Linuxdoc Linux Questions
Click here to ask our community of linux experts!
Custom Search
Next Previous Contents

4. Comparing LinuxDoc to DocBook

Before reading this section it's best to have at least an elementary knowledge of tags in markup languages. So if you don't know much about this, you may first want to look at Example 1 for LinuxDoc markup.

One way to compare is to inspect real HOWTOs at the LDP site. Click on either DocBook Index or LinuxDoc Index to find them. You'll notice that the DocBook docs are cluttered with tags while the LinuxDoc docs have far fewer tags and are thus more readable and easier to write and modify. Some documents at LDP are marked up much more clearly than others so you should inspect at least a few documents.

You may at first think that DocBook is more advanced since there are so many more tags but this isn't necessarily so. If you create a document in LinuxDoc and convert it to DocBook (by computer) there will be many more tags in the DocBook version, including new tags that were not in the LinuxDoc version. Why? Because LinuxDoc permits the omission of tags while DocBook doesn't. And in this way LinuxDoc is more flexible and advanced than DocBook. Not only does LinuxDoc often allow the omission of end-tags like </title> but allows the omission of both start and end tag pairs. For example, in LinuxDoc paragraphs are normally separated by blank lines instead of pairs of paragraph tags <p> (<para> in DocBook) so that paragraph tags are seldom needed. Another example is just after the start of a new section of a LinuxDoc document. You just type in the title of the section after the <sect> tag while DocBook requires one to also enclose the title in a pair of <title> tags.

When one runs a program to convert LinuxDoc to say HTML, the first thing the program does is to find all the omitted tags and add them to the document. For example, a pair of tags are added which are equivalent to the pair of <title> tags after a <sect> tag (including the cases of <sect1> tags, etc.). So in a sense, LinuxDoc also has a lot of tags, but they are hidden from the user to make the document both much easier to write and read. In most cases, the author writing a document in LinuxDoc is unaware of the existence of most of the missing tags. There's no need (in most cases) for the author to know about them since they exist only in the computer memory (or a temporary file) when the PC is converting LinuxDoc to some other format (like to HTML). Well, it is possible to save a file showing the added tags but that is done mainly by programmers debugging the LinuxDoc computer code (or by people like me that are curious about how it works).

The DocBook tags are often longer than the equivalent LinuxDoc tags such as <em> instead of <emphasis>. For a short comparison see the author's website Comparison of DocBook to LinuxDoc

However, the fact that many tags are omitted when writing LinuxDoc (but are found by the software) is only one reason why LinuxDoc documents have fewer tags. Another reason is that DocBook actually has many more tags to use than LinuxDoc does. For example, LinuxDoc has just one tag for the author's name while DocBook has separate tags for the first middle and last names. So in this sense DocBook is more powerful than LinuxDoc but in another sense it's weaker since it can't find missing tags. The solution to this dilemma would be to merge LinuxDoc with DocBook so as to retain the advantages of each. DocBook would then need to abandon it's current status as a "xml" language since xml prohibits the omission of tags, etc. while sgml allows it.

One reason why omitted tags are not allowed in DocBook is that it makes it easier for programmers to write software to parse it and convert it to other formats. There is no need for software capable of finding and adding missing tags. But making it easier for programmers, makes it more difficult for the much large number of writers that have to use DocBook.

There are special editors or word processors like Lyx and Bluefish that make it easier to type DocBook documents. For example, Bluefish automatically adds end tags. But for people who don't want to learn a new editor or word processor, LinuxDoc is a lot easier since one can type in the tags by hand or create a set of macros to insert the (<emphasis> tags. I use the vim editor and if I type ;s it inserts the <sect1> tag. ;r does <sect>, ;i does <item>, etc. For the header tags on the first several lines of the document, I just copy them from another document and change the words after the tags. Of course I don't need to change the author's name or email. So a major advantage of LinuxDoc is that one can easily use it with the same editor or word processor that they currently use and know.

Some people who don't understand the situation have advocated making DocBook about as easy as LinuxDoc by just using a subset of the DocBook tags. This doesn't work because DocBook will still require a few times as many tags to get the same results due to the requirement of DocBook to not permit any omitted tags.

In spite of the advantages of LinuxDoc, the number of people who use DocBook greatly exceeds the number using LinuxDoc partly because Linuxdoc was promoted by book publishers. There's a program by Reuben Thomas (ld2db) which can convert LinuxDoc documents to DocBook. It's not perfect and you will likely need to do some manual editing. The LDP also automatically converts a LinuxDoc HOWTO to DocBook after you submit it. It would be nice to have another program to automatically convert DocBook docs to LinuxDoc so they can be modified by people using the simpler LinuxDoc markup.


Next Previous Contents