[asterisk-dev] XML documentation of apps/functions/the_rest_of_the_world

[Michiel van Baak]

On 10:14, Wed 09 Jul 08, Tzafrir Cohen wrote:
> Hi
> 
> Is it simple to write documentation?

Yes.
It's not harder then what we have now.
Only difference is that you have to structure the documentation instead
of putting it all in a large char variable.

> 
> How can I refer to other parts of the documentation in a specific
> document? e.g.: (let me dream for a minute) "for other parameters of this 
> application, see doc:apps/app_dial#options").

The description is a text field.
If you add some special string in it your script that generates
html/pdf/whatever output has to interpret it.
It's probably a good idea to agree on a format for those markers, so
everyone is adding it the same way.

> 
> Refering to "something in the middle of a docuemnt" is actually more of
> an HTML-like implementation detail. Refering to an arbitrary "label" is
> something that could be of great use. I consider this a major
> requirement. Otherwise we'll have to waste much space later on on
> copy&paste.
> 
> We already have a generated "Asterisk book". Can module documentation 
> refer to specific labels in it? How can it be integrated into it?

I'm not sure I understand clearly what you mean here.
The generated book is using some kind of script to generate it right ?
It wouldn't be that hard to make that script use the core-$lang.xml file
for module documentation right ?

> 
> (In my suggestion: module documentation is asciidoc, and may generate
> latex and/or docbook for integration with the rest of the documentation)

It's an XML file.
You can parse it into whatever format you need.

-- 

Michiel van Baak
michiel at vanbaak.eu
http://michiel.vanbaak.eu
GnuPG key: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x71C946BD

"Why is it drug addicts and computer aficionados are both called users?"