discuss: DocBook vs LinuxDoc (was LDP Incorporate ...)
Subject:
DocBook vs LinuxDoc (was LDP Incorporate ...)
From:
David Lawyer ####@####.####
Date:
5 Nov 2007 03:52:06 +0000
Message-Id: <20071105035126.GA1875@davespc>
> Jean-Philippe Gu??rard writes:
> >Having LDP documents published in a single source format (preferably
> >something compatible with Unicode, like XML DocBook) would really help a
> >lot the translation of LDP documents.
>
On Sun, Nov 04, 2007 at 08:13:20PM -0500, Sam Varshavchik wrote:
> I'll throw my two cents in favor of Docbook XML.
>
> Since it's XML-based, when you're doing documentation with Docbook, you
> have a huge assortment of various XML tools available to you.
But LinuxDoc sgml is a lot easier to write. Also, the LDP converts
all LinuxDoc to DocBook (but retains the LinuxDoc version also).
XML is more difficult to write since you can't omit tags. LinuxDoc is
normally written with omission of most end-tags and omission of most
start-end tag pairs, like using double spacing to denote paragraphs,
omitting title tag-pairs in section headings and omitting paragraph
tag-pairs in items. Most users of LinuxDoc are not even aware that
tag pairs like this exist (or have been omitted). The seldom-used
tag-pairs have different names, etc. in Linuxdoc but it doesn't matter
since few people learn them.
Thus going from a powerful and user friendly sgml to xml was in my
opinion a bad mistake. Xml is of course a lot easier for programs to
parse (and to write programs to parse them) but it's a lot harder on
the users that have to write documents in xml. Machine created xml
docs are an exception. See my "Comparing LinuxDoc to DocBook":
http://www.lafn.org/~dave/linux/ld_vs_db.txt
A very important project would be to merge LinuxDoc sgml and DocBook
sgml which would have a subset just as easy to use as LinuxDoc. It's
use would go far beyond the bounds of LDP. It's a big task including
new software smart enough to find and add all the missing tags (but
don't show them to the user unless the user wants to see
them).
David Lawyer
