DOCBOOK-APPS: Re: "Abbreviated" DocBook

["Matt G." <matt_g_@hotmail.com>]

>From: Kevin Atkinson <kevin@atkinson.dhs.org>
>Subject: DOCBOOK-APPS: "Abbreviated" DocBook
>Date: Wed, 09 Jan 2002 23:46:43 -0500 (EST)
>
>I am strongly considering using DocBook for documentation of Aspell

A spell checking program?  Then you ought to appreciate the value of the 
explicit markup, which would allow you not to check for spelling errors the 
content of such tags as command, arg, computeroutput, filename, function, 
parameter, screen, surname, varname, etc.

I use an XSLT script to output the PCDATA of all the elements I care to 
spell check, then feed this through ispell.  The problem with this approach 
is that I have to manually integrate the corrected spellings back into the 
source document.  It would be nice to have an XML-aware spell-checker, that 
could accept a parameter specifying a file listing what elements to check 
and which to ignore.  :)

(Of course, the hard part is that you don't *really* want to use a standard 
XML parser to read in the document, since you may not care about validation, 
and definitely wouldn't want default attribute values applied to elements or 
entities to be expanded.)


>however there is one major problem. DocBook is too dam verbose,
>providing an entry for just about everything under the sun.

You don't *have* to use all of the markup.  It's a tradeoff between whether 
you want the advantages of a semantically rich representation of your 
document, or not.  If you weren't writing program implementation/API 
documentation (since DocBook has such rich structure for such things, yours 
is a slighly extreme example), I'd say you might consider just sticking with 
the structural elements (<book>, <section>, etc.), if you find the inline 
tags to be more effort to use than they're worth, for you.


>Although you may disagree with me

This *is* a docbook mailing list, after all.  :)


>it is so verbose that just reading a DocBook source document
>becomes rather difficult

First of all, I liken it to coding conventions in any programming language - 
ease of reading has a lot to do with what you're used to looking at.  It 
won't be so bad, after you get more experience with it.

Secondly, I use indentation.  This is a little bit more work, especially 
since I write all my XML with vi, however I'm convinced it's worth the 
effort.

Third, you raise a point that the SGML community understood, which is why 
they have all sorts of minimizations to reduce verbosity and redundancy.  
But SGML didn't seem to catch on so well, and many people feel its success 
was compromised by the complexity of specifying and allowing such 
minimizations, among other things.  So, we now have XML.

A DTD-aware editors allow you to write XML with nearly the same ease, but 
you still end up looking at XML.  If looking at the XML DocBook source is 
too troublesome for you, then consider using an editor with folding 
capabilities (i.e. the content of an element can be "collapsed" and 
"expanded" at will).


>So, I was wondering if there exists any tools which will allow me
>to enter in documents in a more terse and human readable form with
>the minimal amount of tags and then have it expand it into full
>DocBook form with all the special purpose tags in place.

In the general case, see my comments about editors.

In the specific case of API or program documentation, I think the far 
greater crime in writing the XML DocBook, directly, is not its verbosity, 
but the duplication of information.  From the outset, manual translation of 
the API introduces numerous opportunities for human error.  It also presents 
an ongoing burden to keep the API doc in synch with the sources.  For this 
reason, I'm a big fan of tools like doxygen.  Keep in mind that with source 
code, in a high-level language, you *have* a semantically rich source, which 
uses a terse, specialized syntax.  Add to this mix some structured embedded 
comments, and you end up with reliable, manageable, and thorough program 
documentation.


Good luck!


Matt Gruenke


_________________________________________________________________
MSN Photos is the easiest way to share and print your photos: 
http://photos.msn.com/support/worldwide.aspx