Slashdot Mirror

How about DocBook? It's cross-platform and it is structure based, not presentation based. From a docbook source, you can render to various presentation formats (html, ps, rtf). The only problem I have been having with it is finding a nice authoring tool.

There is an XML/SGML alternative to LaTeX. It is already used by LinuxDoc and it is called DocBook.

This XML/SGML solution will not give you power to specify exact inches/cm like LaTeX but the goal is to tag everything to use with stylesheets. With the use of MathML, one can get the formula writing powers of LaTeX.

Alot of work has been done by Norman Walsh and he has some nice stylesheets for making slides and even a website.

This is not for the person interested in flashy webpages, but for people interested in using the power of XML to document anything.

If you are working with writing technical documentation this is something that is worth looking into.

alfadir
--
"A witty quote proves nothing." - Signature Etiquette

The problem is that in mandating that every single construction be inserted in a way that maintains the document status as "valid HTML," this leaves the problem that the UI has to build pages as a sort of "tree" into which you insert nodes. It may look "WYSIWYG," but the input side is hairy to actually use.

I mostly compose web material by writing DocBook which then transforms to HTML; that provides quite decent guarantees of well-formedness and validity. Mind you, I start with something that may not be valid SGML.

It seems to me that a more usable approach, if composing HTML, is to write it however you like, perhaps a tad messy, and then use tools like Dave Raggett's HTML Tidy utility.

Amaya is well and interesting; I suspect that it is only of practical interest to people that are working specifically on HTML standardization, and of limited interest to anyone else.

I agree that XHTML is probably a good starting point for unified Linux documentation.

FWIW, XHTML is not the same as XML. XHTML is "a reformulation of HTMLÊ4 as an XML 1.0 application" (to quote the W3C's take on it ... and they should know. XHTML can be displayed by ordinary HTML browsers like the one you're using now, but it can also be parsed by an XML parser. It's basically a transitional form ... getting people used to writing formally correct XMLish markup while there aren't yet enough XML tools out there.

(In other words, XML is not a markup language; it is a markup metalanguage. XML applications, of which XHTML is one, are markup languages.)

XHTML, because it is HTML, is the Wrong Thing for documentation, because HTML has insufficient structure, and the wrong sorts of what it's got. DocBook may or may not be the Right Thing for manpages, but the Linux Documentation Project folks seem to get along with it for HOWTOs, and they seem to be okay at rendering it into text or HTML or various other formats. DocBook is an SGML system and not XML, but that will be changing with the next major revision, and presumably LDP will be keeping up.

The other problem is that there are all sorts of possible pathological cases.

For instance, Postscript is described as an "Opaque" format, but supposing someone follows the dictums of TINYDICT, and writes their documents in raw Postscript, then despite the fact that Postscript is usually considered "Opaque," it is, in fact, the "Transparent" form.

That's probably the most pathological (and perverse-sounding) case, and is one that I brought up in some discussions on the license last year.

HTML is a necessarily ambiguous form.

• Many people do write documentation directly in HTML.

  In such a case, HTML is the "most transparent form available."

• On the other hand, if I write documentation using DocBook/SGML, and generate HTML from that, the "transparent" form is quite clearly DocBook.

In practice, I don't think this will be a big problem. After all, am I likely to sue someone for releasing "freely," under the "GDL," some documentation in a form that I don't much like? I think not...

Did you look? How about Open Sources? Or Using Samba? Don't forget Learning Debian GNU/Linux. Maybe even Docbook: The Definitive Guide? (The latter is an O'Reilly book, but the downloadable version is hosted elsewhere.)

--

I'd like to point out that those of you that struggled with LinuxDoc, either getting it installed or running, will have fewer problems with DocBook, mostly because it is so well documented. One excellent resource is the DocBook: The Difinitive Guide from ORA, available at your local dead tree store and online at www.docbook.org.

Unfortunately, they are still no further in the transition from qwertz to DocBook than they were three months ago.

There is not going to be a substantial change in the quality of the material until that happens.

You meant to say docbook.org not docbook.com. Also DocBook is an SGML DTD, not an XML DTD (I guess you knew this already). Interestingly Normal Walsh has written DocBk XML DTD, an XML DTD based on DocBook. DocBook 5.0 will be XML compatible. Btw, if you want to use XML extensively checkout task-xml and task-xml-dev in Debian potato. Ganesan

Thanks for that info, that's very useful.

Will somebody please moderate this post up?

Here are the hyperlinks:

• http://www.docbook.org
• http://www.bruceeckel.com
• http://www.software.u-net.com (the tutorial is here)