Re: [Audacity-devel] Documentation updates

[Alexandre P. <ale...@gm...>]

On 9/22/05, Dominic Mazzoni <do...@au...> wrote:
> Richard Ash wrote:
> > Short of creating a custom converter to get from one to the other, or
> > maintaining two completely different documents, does anyone have any
> > suggestions?
>
> We should look into DocBook.  It's a relatively simple XML format for
> describing technical documentation, with a whole suite of converters for
> turning it into MSHelp (which is exactly what wxHTML is), full HTML,
> PDF, and more:
>
>    http://www.docbook.org/
>    http://wiki.docbook.org/topic/formats
>    http://www.xml-dev.com/blog/test.php
>    http://docbook.sourceforge.net/
>    http://en.wikipedia.org/wiki/DocBook
>
> We could write a one-time converter to convert what we have into
> DocBook, fixing things by hand, and from then on we'd have an open,
> well-supported, and flexible system for generating documentation in all
> forms.

Okay, 3 eurocents from a docbook zealot (obviously, me :))

1. "relatively simple XML format". DocBook/XML is considered as
difficult by many technical writers. Due to XML nature of this format
no company in the market has succeded in creating one good usable XML
editor (in WYSIWYM style), though there are tens of them. And not so
many people have fun editing it in text editors with syntax highlight.
This is one of the reasons DocBook is not accepted as widely as it
could be yet.

2. You can't create complete HTML Help file (.chm). Htmlhelp styles
from Norman Walsh create a project file for HTML Help Workshop only.
Workshop is freely downloadable though.

2. "One-time converter" is a good joke :) Basically it means regexp
magic like 's/p/para/n', followed by more complicated substitution
like "<h1>some text</h1>" to "<section><title>Some
text</title></section>". I even used to write one myself in the early
days of my work at ALT Linux. Someone will have a good time fixing
unclosed tags and structure of dicuments. Actually, I could volunteer
for this.

My 1,5 year old book on Audacity is available in DocBook/XML, btw.

Alexandre