Re: debiandoc vs. docbook
On Sat, 2002-09-21 at 02:03, Osamu Aoki wrote:
> Hi, Susan
>
> These topics have been somewhat emotional flame wars and I want this
> thread to be productive one ;-)
>
> In short, as an author of one of the longer debiandoc documents, I am,
> to your surprise, for the XML format provided infrastructures (including
> nice best practice guide lines) are there for me.
>
> I see many "programmer types" argue strongly about XML and
> "documentation authors" are not to excited about "complicated" XML and
> very reluctant to the changes. But this stereotype needs to be
> considered where it came from. For me, the only way to change document
> format is not through argument with hostilities nor by put-downs to the
> authors "who does not learn" but by the persuasion with helping hands ;-)
>
> For me, as long as Debian use reasonable subset of XML tags, it ain't too
> different.
>
> Please provide following resources, then this conversion will happen
> without much fuss.
>
> 1. provide debiandoc-to-XML converter (include SGML normalizer).
> 2. provide XML usage manual with subset of tags (best practice guide).
> 3. provide nice small subset tag style-sheet.
> 4. provide wrapper scripts to build many formats easily.
>
> If these are ready, I will not hesitate to move to XML. as far as I
> know, I hear loud call for XML but not completed program packages to
> support above 3 items. It looks like 1 and 3 are done.
>
> Please point to me to information leading to 2 and 4.
There are some nice wrapper scripts out there for DocBook called xmlto
and are made by Tim Waugh for RedHat. There is a Debian package for
xmlto in Debian unstable. You might want to check it out.
As for a XML usage manual I don't believe there is any guide solely
describing the best practices to use for tags because there are a number
of ways to use tags. The GNOME Documentation Project and the FreeBSD
Documentation Project both have guides to using DocBook which give some
standard uses of the tags specific to both projects. Also The
Definitive Guide by Norman Walsh gives example usage for every tag. I
would suggest the Debian Doc Project make a best use guide for DocBook
based on the common tags the DDP uses.
Some DocBook guides which you can look over are:
GDP Handbook, specifically the DocBook chapter
http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/
FreeBSD Documentation Primer, specifically the DocBook chapter
http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/index.html
The Definitive Guide
http://www.docbook.org/tdg/en/html/docbook.html
Eric Baudais
Reply to: