[<<] [<] Page 1 of 1 [>] [>>] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Subject:
RE: Linuxdoc vs Docbook. Was:Re: LAG changes, multiple formats; DocBook
5.0 was [ My rejected "replacement" for the Author Guide
From: Mark Komarinski ####@####.#### Date: 10 Feb 2016 13:58:50 +0000 Message-Id: <4o2dk3qitxbs9mx1wsout98l.1455112728964@email.android.com> (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/ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[<<] [<] Page 1 of 1 [>] [>>] |