Re: response on ddp policy, 3.1
On Mon, Dec 09, 2002 at 01:39:52AM -0600, Adam DiCarlo wrote:
> Javier Fernández-Sanguino Peña <jfs@computer.org> writes:
>
> > On Sat, Dec 07, 2002 at 06:13:36PM +0100, Josip Rodin wrote:
> > > Besides, that DDP policy is outdated, we've all realized in the meantime how
> > > DebianDoc SGML is not the holy cow it was supposed to be...
> > >
> >
> > _And_ there is a draft (unpublished) which is trying to fix this policy
> > issues. Just to remember to those that did not comment about it:
> >
> > http://www.debian.org/doc/manuals/ddp-policy/ddp-policy.en.html
> >
> > Discussion on source file formats is here:
> >
> > http://www.debian.org/doc/manuals/ddp-policy/ch-manuals.en.html#s3.1
>
> Comments follow.
>
> In 3.1 we read: "SGML is used as the source format for all
> manuals. Currently, SGML format compatible with the debiandoc-sgml
> tool chain is chosen as the document format. [4]"
>
> But you contradict both of those below.
>
> Cut to the chase; drop the historical references; drop the
> justificiation. It should simply state the debiandoc-sgml and
> docbook-xml are the recommended formats.
OK. How about "debiandoc-sgml, docbook-sgml, and docbook-xml are the
recommended formats."
> It should further clarify
> which version of DocBook, e.g., 4.1.2 or better or whatever (4.2 is
> latest, quite recent); and which version of Debiandoc (DTD version 1
> or better, clearly).
OK. Let's follow you "4.1.2 or better".
> I would also suggest a more balanced approach. I've worked with
> DocBook now for 3+ years, and believe me, debiandoc-sgml has
> significant things to recommend it:
>
> - its tons easier to learn then DocBook (46 elements vs 300+)
It was discussed on this mailing list. In short, the answer given was
"we do not need to use all the tags". I guess converting current
debiandocsgml-doc into docbook-sgml or docbook-xml with content adjusted
shall give nice tutorials and/or "best practice document".
Just add table and figure support HOWTO, it should be in good shape.
> - since it's simpler, the output is going to be more consistent
I think the existence of "best practice document" shall fix this issue.
Also, making some debian customized stylesheet maybe an good option.
> - we're used to it
I agree and I am feeling pain. When I raised this when importing HTML
version of "progeny users' guide", some people flamed me because I
converted it into debiandoc-sgml citing this reason.
> - it can also be argued that the output is actually better than
> DocBook output for our purposes (tho this just points to the need
> for a DocBook-XML stylesheet, I'm sure we could bring them to
> relative parity if we want to)
I agree. I think plain text output is nicer with debiandoc-sgml. Ardo
did a good job.
> The i18n bugs in particular don't deserve mention; I think could be
> fixed easily.
>
> I think we should recommend that if people don't *need* the DocBook
> features, they should stick with debiandoc. Folks should only use
> DocBook if they need tables, figures, optional framed output and such.
With existence of tutorial to let people use subset of DocBook, I think
this should not be too much of issue.
> In fact, I would go even further and state that we should make this
> change, and Ardo should close most of the wishlists for new tags and
> features in debiandoc-sgml. DebianDoc should explicitly be a
> *simple*, 80% solution. If folks want bells and whistles, use
> DocBook. This way, both have a place in our galaxy and Ardo doesn't
> have to feel bad about all the things he doesn't do that DocBook does.
Sure but Ardo's time may be better spent on improving text output of
docbook or debian customization of docbook output. That up to him to
decide, I guess.
As I posted separately, Philippe Batailler's script may require some
iteration of optimization before becoming version 1.0 :-)
Osamu
--
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +++++
Osamu Aoki <osamu@debian.org> Cupertino CA USA, GPG-key: A8061F32
.''`. Debian Reference: post-installation user's guide for non-developers
: :' : http://qref.sf.net and http://people.debian.org/~osamu
`. `' "Our Priorities are Our Users and Free Software" --- Social Contract
Reply to: