This is the mail archive of the
docbook-apps@lists.oasis-open.org
mailing list .
Re: "Abbreviated" DocBook
- From: "Matt G." <matt_g_ at hotmail dot com>
- To: docbook-apps at lists dot oasis-open dot org
- Date: Mon, 14 Jan 2002 03:09:15 +0000
- Subject: DOCBOOK-APPS: Re: "Abbreviated" DocBook
- Bcc:
>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