[asterisk-dev] documentation to docbook

[Tzafrir Cohen]

On Sun, Mar 09, 2008 at 04:11:19AM -0400, Jay R. Ashworth wrote:
> On Sat, Mar 08, 2008 at 11:06:07PM -0600, Tilghman Lesher wrote:
> > > For sufficiently small values of "easier", I guess.
> > >
> > > My intuition is that so *many* projects switch their doco sources for a
> > > reason, which is likely that the toolchain that converts it into other
> > > formats (HTML, HTML tree, flat text, PDF, etc) is so well tuned.
> > >
> > > I would vote for it, and since I've just taken a new job that is
> > > *heavy* on Asterisk, and I'm a copy/editor type anyway, I expect to
> > > have a vested interest in the results.  I'm therefore pleased that
> > > someone volunteered to convert it, and Jared thinks that's a good idea.
> > 
> > My main concern with "format du jour" is that we've had close to 100 people
> > volunteer to contribute documentation, in their own format.  Who are they?
> > Mostly people we haven't heard from again.  Yes, documentation is good.
> > Maintained documentation is even better.
> > 
> > I prefer plain text, because I don't need a fancy editor to view it, edit it,
> > correct it.  I prefer LaTeX because at least two of the core developers can
> > write LaTeX markup and could maintain it in a pinch.  Fancy documentation
> > is all well and good, until it's wrong, and the developer who changes
> > something doesn't fix the documentation, because it takes too much of his
> > time to start up a graphical editor.
> > 
> > In summary, if the documentation is easy to use (and fix), you're much more
> > likely to get maintained documentation.
> 
> You're not all that familiar with docbook, are you?
> 
> I'm not either, but I still know that vi is enough editor to maintain
> docbook sources reasonably.

Docbook is a very verbose format. 

LaTeX will simply do the right thing with text formmated as my mail
message (paragraphs seperated by an empty line). Other formatters do the
same. DocBook doesn't.

> 
> LaTeX is, IMHO, *too* powerful; it puts in the hands of writers things
> that properly are the domain of designers, and belong in the style
> sheets that the translation programs call out to.

Fine. Here's something nice and useful I do with asciidoc. Now go and
implement this with LaTeX or DocBook:

The Zaptel documentation now includes the sample config inline. This is
after processing it through a simple filter that does the following:

* A line that begins with '# ' [1] is considered documentation. The '# ' 
  will be stripped from it.
* Other lines are considered non-documentation. Those are typically
  configuration directives or commented-out configuration directives.
  This should be printed verbatim. For asciidoc verbatim is simply by
  indentation.
* When starting a block of documentation or non-documentation, I add an
  empty line.

So the following sample config text:

-------------------------------------
# this example is a single tone DCS transmit and receive
#
# specify the transmit tone (in DCS mode this stays constant):
#tx=D371
#
# specify the receive DCS code:
#dcsrx=223
-------------------------------------

Becomes:

-------------------------------------
this example is a single tone DCS transmit and receive
 
specify the transmit tone (in DCS mode this stays constant):

  #tx=D371


specify the receive DCS code:

  #dcsrx=223
-------------------------------------

In the rest of the configuration file I can freely use asciidoc syntax.
Luckily asciidoc syntax is quite usable as plain text. And if all else
fails, I resort to verbatim formatting. Check the text of this message.

To apply this to Asterisk' configuration, simply s/#/;/g

[1] A line that consists of a single '#' or is empty is also considered
documentation.

-- 
               Tzafrir Cohen
icq#16849755              jabber:tzafrir.cohen at xorcom.com
+972-50-7952406           mailto:tzafrir.cohen at xorcom.com
http://www.xorcom.com  iax:guest at local.xorcom.com/tzafrir