[asterisk-dev] documentation to MediaWiki?

[Jay R. Ashworth]

On Sun, Mar 09, 2008 at 12:13:55PM +0200, Tzafrir Cohen wrote:
> > 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.

Yes; I see your point.

> > 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
> -------------------------------------

I see where you're going, and I like that, but I'm not sure I'd
overload, specifically, "# "; that's the common introducer in such
files, and you *want* it to come through, no?

But yes, for my part (which is probably not worth much, yet :-), I
don't object philosophically to lightweight markup sources, as long as
they render into something as flexible as docbook, which asciidoc does
(as do other lightweight markup languages, such as YAML, reST, and --
very shortly -- MediaWikitext -- Steve Gerard has created a grammar in
ANTLR for a parser which can render, I think, something like 95% of
wikitext, and there are a couple of other WTtoXML converters).

I'm inclined, at this point, to toss my *next* standard suggestion
against the wall: given the ability to transform wikitext into docbook
sources, why not put the doco in a wiki, with registration required to
edit?

It could be maintained in realtime, and pinched off into source files
for transformation into the usual suspect formats at release time as
well.

Cheers,
-- jra
-- 
Jay R. Ashworth                   Baylink                      jra at baylink.com
Designer                     The Things I Think                       RFC 2100
Ashworth & Associates     http://baylink.pitas.com                     '87 e24
St Petersburg FL USA      http://photo.imageinc.us             +1 727 647 1274

	     Those who cast the vote decide nothing.
	     Those who count the vote decide everything.
	       -- (Joseph Stalin)