[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Linux.com Newsletter: SGML Tools]

Please do not spread disinformation about Linux documentation.

In Living Linux 05/23/2000, Michael Stutz writes:

"And since the Linux HOWTOs are still written in linuxdoc,..."

This is incorrect.  The LDP has been standardized on DocBook 3.1 for
over a month and all our documents have now been converted from
LinuxDoc to DocBook.  Most other documentation projects have also
abandoned LinuxDoc and while most will still graciously accept a new
document submitted in any format, including LinuxDoc, they will
grumble and curse you when you leave.

For the LDP, submitting your docs in LinuxDoc means we must find a
volunteer to translate your file to DocBook, which is not a trivial
task.  For example, the illustration in the above cited article shows
a <p> tag which is not closed; this is just one of many items which
cannot be translated reliably by any script at our disposal.  LinuxDoc
is a better fit than HTML, but the looseness of the parser (and
LinuxDoc editors such as older versions of LyX) encourage bad coding
and do not provide for the essential element attributes needed by the
LDP for document cross referencing and cataloging.

Sending people to use the SGMLtools will also cause no end of
heartache; that package is horribly broken and as soon as you
complain, the answer comes back "fetch DocBook and OpenJade from their
respective websites" SGMLTools-lite is being actively developed
(re-invented) and now mostly works.  All of this is covered in the
newly re-released HOWTO-HOWTO, and that paper should always be the
first reference when inviting people to contribute to the LDP.

It is also misleading to say "For smaller documents written by
individual authors, such as a multi-part essay, FAQ, or white paper,
the linuxdoc DTD still works fine." because it belittles the work we
do with the LDP and other similar documentation projects: No document
is an island. To be effective, all our documents must integrate to
form a coherent whole.  All the documentation projects are realizing
this, and this is the primary motivation for our shift to DocBook.

All that said, however, very few of the projects are talking about
updating to DocBook 4.0, and for the long-term, SGML will probably
lose out to XML as the XML tools mature over the next two years.

Gary Lawrence Murphy <garym@linux.ca>: office voice/fax: 01 519 4222723
TCI - Business Innovations through Open Source : http://www.teledyn.com
Canadian Co-ordinators for Bynari International : http://ca.bynari.net/
Free Internet for a Free O/S? - http://www.teledyn.com/products/FreeWWW/

To unsubscribe from the emacspeak list or change your address on the
emacspeak list send mail to "emacspeak-request@cs.vassar.edu" with a
subject of "unsubscribe" or "help"

Emacspeak Files | Subscribe | Unsubscribe