discuss: Linuxdoc vs Docbook. Was:Re: LAG changes, multiple formats; DocBook 5.0 was [ My rejected "replacement" for the Author Guide
Subject:
Linuxdoc vs Docbook. Was:Re: LAG changes, multiple formats; DocBook
5.0 was [ My rejected "replacement" for the Author Guide
From:
David Lawyer ####@####.####
Date:
10 Feb 2016 08:40:47 +0000
Message-Id: <20160210084037.GA18499@daveslinux>
> Mark Komarinski wrote:
> > I started the LAG after trying to figure out how DocBook worked.
> > I'll admit my bias towards a cleaner and richer format, but not
> > everyone shares my opinion and I'll have to deal with it ;)
>
On Tue, Feb 09, 2016 at 08:38:49AM -0800, Martin A. Brown wrote:
> I, personally, prefer the richness of DocBook, so I share your
> preference. However, I think David's point is right, especially,
> since we have heard questions in the past about supporting X, Y and
> Z formats. So, yeah, I'll have to deal with it, too! :)
It turns out that linuxdoc has a cleaner format. The source is about as
easy to read as a wiki. I wish the creators of docbook had used the
linuxdoc format as a base and retained all the features of linuxdoc sgml
which allows omission of tags (such as using blank lines for paragraph
separators). For my docs, to use docbook with the same tags would require
a few times as many tags since docbook requires both opening and closing
tags in all cases. But in spite of the pluses of Linuxdoc, it hasn't had
modern features added: it doesn't support unicode and adding images is
tedious. Here's an example comparison I have on my website:
Comparison of DocBook to LinuxDoc (short).
by David Lawyer, June 23, 2000, revised Mar. 2005
Using DocBook instead of LinuxDoc requires many more tags and the tags
tend to be longer. DocBook tags tend to be nested. The tag clutter
makes DocBook both harder to read and harder to write. Thus DocBook
is not nearly as easy to do by hand or by using macros in a text
editor. Even with an editor that supports it, there is a lot more
complexity to writing in DocBook.
LinuxDoc is quoted with LD; DocBook with DB.
----------------------------------------------------------------------
Example 1, A section with 2 paragraphs
DB <Sect>
DB <title>Introduction</title>
DB <Para>First paragraph contents
DB </Para>
DB <Para>Second paragraph contents
DB </Para>
DB </Sect>
LD <sect>Introduction
LD <p>First paragraph contents
LD
LD Second paragraph contents
----------------------------------------------------------------------
Example 2, emphasis
DB <emphasis>release</emphasis>
LD <em>release</em>
----------------------------------------------------------------------
Example 3, Itemized lists
DB <ItemizedList>
DB <ListItem> <Para>
DB This is the first item
DB </Para> </ListItem>
DB
DB <ListItem> <Para>
DB This is the second item
DB </Para> </ListItem>
DB
DB <ListItem> <Para>
DB This is the third item
DB </Para> </ListItem>
DB </ItemizedList>
LD <itemize>
LD <item> This is the first item
LD <item> This is the second item
LD <item> This is the third item
LD </itemize>
----------------------------------------------------------------------------
Example 4, Author
DB <author>
DB <firstname>David</firstname>
DB <surname>Lawyer</surname>
DB <affiliation>
DB ####@####.####
DB </affiliation>
DB </author>
LD <author>David Lawyer
LD <url ####@####.####
----------------------------------------------------------------------------
One may use the linux "grep -c" command to help count the number of
tags in a doc. Converting a linuxdoc document to docbook increased
the number of tags by about a factor of 3. Linuxdoc usually doesn't
require both start and end tags like <title>My report</title>. One
can just use <title>My report. Also, in several cases both start and
end tags may be omitted and authors usually don't even realize that
such tags exist. So the first step in machine conversion of linuxdoc
to other formats is to find and insert the missing tags. Doing only
this step (as a test) resulted in about twice as many tags.
The conclusion is that a document in docbook will require a few times
as many tags and may require several times the effort due to more
tags, longer tags, tagging objects that would not need tagging in
linuxdoc, and a more complex structure of nested tags that the user
needs to deal with. Linuxdoc has an underlying structure almost as
complex as docbook but it's mostly hidden from the writer of
documentation.
All of this makes Linuxdoc much easier to utilize than Docbook, but
potentially just as powerful if it were developed further.
David Lawyer
