Subject:
Re: LinuxDoc vs. DocBook, was Re: part of the review? (fwd)
From:
Poet/Joshua Drake ####@####.####
Date:
18 Jul 2001 16:42:08 -0000
Message-Id: <Pine.LNX.4.30.0107180940260.12790-100000@commandprompt.com>
--
--
<COMPANY>CommandPrompt - http://www.commandprompt.com </COMPANY>
<PROJECT>OpenDocs, LLC. - http://www.opendocs.org </PROJECT>
<PROJECT>LinuxPorts - http://www.linuxports.com </PROJECT>
<WEBMASTER>LDP - http://www.linuxdoc.org </WEBMASTER>
--
Instead of asking why a piece of software is using "1970s technology,"
start asking why software is ignoring 30 years of accumulated wisdom.
--
---------- Forwarded message ----------
Date: Wed, 18 Jul 2001 08:42:42 -0700
From: Robert S. Dubinski ####@####.####
To: ####@####.####
Subject: Re: LinuxDoc vs. DocBook, was Re: part of the review?
Hi,
I tried to get into this thread, but for some reason I can't post to
the list. Any chance you can cc this to the list? I think it's
important to be heard. The whole notion of linuxdoc being superior
to docbook is absurd.
Thanks,
-Robb
On Sun, Jul 15, 2001 at 10:11:57PM -0700, David Lawyer wrote:
> Some things are facts: Here is a comparison of LinuxDoc vs DocBook:
<snip>
> 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.
Those are more opinions than facts.
I've done the conversion on my docs from linuxdoc -> docbook SGML ->
docbook XML, and would like to add my 2 cents to this thread:
One thing your comparison is lacking is in noting the procedure for future
maintenance. Because docbook, particularly with the XML route, is a
"well-formed" grammar, it means from now on we can make tools that will
translate our docs automatically to any future revs of docbook or to any
alternate markup languages, and do it _correctly_ all the time.
This is in stark contrast to the linuxdoc->docbook tools, which do an
approximation but always need some manual work afterwards. I recall
when I wanted to move from linuxdoc to docbook, the tools then did such a
lousy job that I spent the time reworking the doc as a whole. This time
would have been much better spent updating my doc's content. The move from
docbook sgml to docbook xml, by contrast took a couple minutes. And it
should take no more effort to move to future formats. This same argument
can be applied when considering HTML as your source language.
Now that it's in XML, I can try all the generic XML processors out there
that are used for other fields of work, and not be stuck to one particular
set of tools. And, with XSLT added to the mix, it becomes very easy to
transform the doc into something completely different. I'm not yet using
XSLT on my HOWTO, but I am using it on other XML source docs I have, and
the ease-of-use and flexibility in transformations is tremendous.
For those doing a few page document, I fail to see how docbook the _language_
can be such a big deal. Take a template, change and add. If you'd like a
template, I've got a minimalistic one for both Article and Book type I can
send you.
The _tools_ on the other hand, have always been a pain. All Linux
distributions seem to do it differently (and even with the LSB now available,
distros like Debian aren't following it exactly.) On the flip side though,
I can easily get docbook running on my Solaris machine, but not linuxdoc.
This traditional tools crutch for docbook should go away when you move
to docbook XML, because, as I said earlier, you can technically use
any XML parser on it, and there's plenty to choose from. If you don't
like that, one fellow on this list had a mechanism where by you send your
docbook source doc to an email address, and get the results returned to you.
Now you don't even need the tools!
As for GUI tools, I'd say it's simply a matter of time before they catch
up. Consider Abiword. As Abiword's native document format is based on
XML, there should be no problem converting it to Docbook, or Docbook to
it. It's a matter of implementation of the proper transformation, and
how rich the Abiword's format is right now versus Docbook. Such
functionality will serve the GUI users who don't want to learn markup.
For the rest of us, there's always vim/emacs/whatever text editor.
In short, I feel LDP should be promoting Docbook over Linuxdoc. I would
also go so far as to recommend Docbook XML over Docbook SGML. The switch
is minimal effort, and you'll save yourself tremendous time over the long
run, should a new and different markup language come on the horizon. I
look forward to being able to conveniently process my source to a new
source markup format as easily as I post-process it to its HTML/PDF/TXT/PS
output formats today.
-Robert
