Subject:
Re: TLDP DocBook pages need work - Start there!
From:
David Lawyer ####@####.####
Date:
25 Nov 2003 23:19:54 -0000
Message-Id: <20031125231918.GE504@lafn.org>
On Tue, Nov 25, 2003 at 09:05:51AM -0600, Rodolfo J. Paiz wrote:
> At 23:03 11/24/2003, David Lawyer wrote:
> >Here's an example of some differences:
> >----------------------------------------------------------------------
> > Comparison of DocBook to LinuxDoc (short).
> > by David Lawyer, June 23, 2000, revised July 2001
> >
> >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 harder to read. Thus DocBook is not nearly as easy to
> >do by hand. Even with an editor that supports it, there is a lot
> >more complexity to DocBook.
>
> David,
>
> I find your "example of some differences" biased, subjective, and
> irrelevant. You have not noted any specific differences (not one!), and
Well, there's a difference in ease of writing and reading. It's
functional is a sense :-)
> only made comparative statements that were _all_ favorable to Linuxdoc, of
> which you are an open advocate. Now, it's fine that you have your opinion,
> and it's fine that you state your opinion clearly, but these are not
> differences, these are not examples, and the entire text achieves exactly
> nothing when attempting to answer the original question:
Sorry, that I didn't read your question over more closely. But the
non-functional differences that I showed are important too.
>
> On Sun, Nov 23, 2003 at 01:51:16PM -0500, John R. Daily wrote:
> > What is the functional difference between LinuxDoc and a
> > comparable subset of DocBook tags[1] with a well-defined toolchain?
One major functional difference is that DocBook will not let the author
specify fonts, such as italic, bold, typewriter etc. Linuxdoc has these
but DocBook doesn't. They're presentation tags, not content tags.
That's both bad and good. Presentation tags may promote standard
translations from content to presentation, at least if there are some
rules for this. Content tags allow anyone to create their own rendering
of a certain type of content and thus create their own rules. If all
writers could agree on a standard presentation for certain content, then
linuxdoc has advantages. Otherwise, the docbook concept of only-content
tags is better.
One can "overload" a presentation tag such as <tt> (typewriter font) to
include a number of content tags such as computer code, command line
entry, email, etc. This cuts down on the number of tags one needs to
learn (and program as a macro in say vim). Of course it makes it more
difficult to search for a certain type of content, but few need to make
such searches, in my opinion.
> That question has not been answered. Personally, I like DocBook as being
> more flexible and more scalable (things that come along with the increased
> complexity you decry). However, I do not care about either my subjective
> opinion or yours on this matter.
The increased complexity is a fact, not an opinion as is the fact that
DocBook is more flexible and scalable (at too high of a price for some
in my opinion). What I posted was intended to demonstrate it's
increased complexity.
> What I _would_ like to see, if someone more knowledgeable cares to offer
I admit that I'm just not very knowledgeable about docbook so I don't feel
insulted.
> it, is an answer to John Daily's actual question: What is the FUNCTIONAL
> DIFFERENCE between LinuxDoc and a COMPARABLE SUBSET of DocBook tags with a
> WELL-DEFINED TOOLCHAIN? (Emphasis mine, of course.)
Well fonts are one difference I've already mentioned. Another is the
overloading by former LDP rules/suggestions of linuxdoc tags for
example:
<author>David S.Lawyer
<tt><url ####@####.####
<date>v3.17 July 2004
Note that the <author> tag takes both the name and email. The <date>
tag takes both version and date. So translation to DocBook (as done by
LDP) seems to lose both the email address and the version number. Not
only that, but the translation to docbooks results in:
<FirstName>David S.Lawyer
It looks like the <author> tag in docbook requires subtags like
<FirstName>.
I think that linuxdoc could be improved upon by adding a few more tags
for the header since one often uses a template for this and doesn't need
to type it. For example <version> and <email>. There are likely still
more differences.
David Lawyer
