discuss: Thread: Linuxdoc vs Docbook. Was:Re: LAG changes, multiple formats; DocBook 5.0 was [ My rejected "replacement" for the Author Guide

> 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

I'm with Mark on this. We need quality documentation not good quality
markup. Moreover, the latter you can sort of automate provided
sufficient background. The former is much more difficult to achieve.

I've been working on search engine and data mining technologies of late...

One thing I would be curious about is whether there is somewhat of a
market for specialised search for Linux Documentation and FOSS
material in general. If you think about this carefully, you just index
those sites with the most relevant material (lots of FOSS search
engines we can use code from) or else build a proxy style website to
access this material from other search engines which already index
them and provide those results back to the end user... You instantly
have the basis for what I believe would be a pretty worthwhile
project. Obviously, the backend, bandwidth, infrastructure, and other
support issues are the big problem though...


On Wed, Feb 10, 2016 at 8:59 AM, Mark Komarinski ####@####.#### wrote:
> (Sorry for top-posting.  I'm at a client site today and thus using my phone for personal mail)
> I have a variety of reasons I prefer Docbook and XML.  You're not going to convince me otherwise.  I can accept other people don't share my view and am open to have the LDP accept other formats for submissions.  Can we PLEASE let this drop and get on with the work of getting quality documentation out, no matter what markup format it's using?
> -Mark
>
> -------- Original message --------
> From: David Lawyer ####@####.####
> Date: 2/10/2016  3:40 AM  (GMT-05:00)
> To: ####@####.####
> Subject: Linuxdoc vs Docbook. Was:Re: LAG changes, multiple formats; DocBook
>   5.0 was [ My rejected "replacement" for the Author Guide
>
>> 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
>
> ______________________
> http://lists.tldp.org/
>