[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

response on ddp policy, 3.1

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.  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).

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+)

 - since it's simpler, the output is going to be more consistent
 - we're used to it

 - 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)

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.

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.

...Adam Di Carlo..<adam@onshore-devel.com>...<URL:http://www.onshored.com/>

Reply to: