discuss: LinuxDoc vs. DocBook, was Re: part of the review?
Subject:
Re: LinuxDoc vs. DocBook, was Re: part of the review?
From:
"Anthony E. Greene" ####@####.####
Date:
21 Jul 2001 06:25:41 -0000
Message-Id: <Pine.LNX.4.21.0107210209040.13325-100000@cp5340.localdomain>
On Fri, 20 Jul 2001, David Lawyer wrote:
>On Mon, Jul 16, 2001 at 07:20:00PM -0400, David Merrill wrote:
>> Even if linuxdoc is simpler, it has nothing else going for it. It is
>> technically inferior.
>
>I agree, but I claim that the simplicity outweighs the disadvantage of
>technical inferiority. Consider the case of someone writing in
>DocBook and using a minimal number of tags. That same doc could have
>been written in LinuxDoc with even fewer and shorter tags. In this
>case the resulting html, etc. is about the same and LinuxDoc is not
>technically inferior.
What exactly is the point of using fewer tags? The few keystrokes saved
become a liability when it comes time to manage the document database. If
you start with the sample doc, it's easy to insert the content and cut out
the unused sections. You don't have to learn a lot about what tags are
allowed in what contexts because its already done for you. The tags
themselves are verbose enough that anyone with a fair grasp of English
should have no problem putting content where it belongs.
>Ask yourself the question of what is wrong with the present LDP
>documents. The major things that are wrong is that many of them are
>out-of-date, not clearly written, mainly pertain to how things work in
>a particular distribution, have omitted important info on the topic,
>etc. In addition, there are often no docs at all for certain topics.
One of the reasons this is so is because LinuxDoc does not make it easy
for the LDP to manage the docs. That is one reason why LinuxDoc is
technically inferior.
>So if one were to make a list of the things wrong in order of
>importance to the user, the fact that many are not in linuxdoc would
>be far down on the list.
That is a strawman argument. Nobody is arguing that the authoring format
has any significance to readers.
> Another point is just how important are
>additional tags?
One look at the current document database should answer that question. It
is missing lots of data, primarily because it needs to be manually
input. Some of this data would have been in the DocBook tags had the docs
been authored in that format. As someone who has volunteered to input some
of this data, I have no problem recognizing the utility of the additional
tags.
>What I see as a big advantage of LinuxDoc is getting new people to
>write for us. It's easier to recruit them if you can show them just
>how simple it is.
I consider the high quality of the example doc and the existence of the
email-based DocBook validator as good marketing tools. The author does not
have to install any DocBook tools, does not need to know anything about
dsssl or dtd's, does not need to memorize dozens of tags, and does not
need to read a lengthy LAG (although it is advisable to read some of it).
They can take the example, fill in the content, and send it off to be
validated.
Tony
--
Anthony E. Greene ####@####.#### <http://www.pobox.com/~agreene/>
PGP Key: 0x6C94239D/7B3D BD7D 7D91 1B44 BA26 C484 A42A 60DD 6C94 239D
Chat: AOL/Yahoo: TonyG05
Linux. The choice of a GNU Generation. <http://www.linux.org/>
