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

[Brandon Kruse]

>----- Original Message -----
>From: "Michiel van Baak" <michiel at vanbaak.info>
>To: asterisk-dev at lists.digium.com
>Sent: Wednesday, July 9, 2008 2:40:28 AM GMT -06:00 US/Canada Central
>Subject: Re: [asterisk-dev] XML documentation of apps/functions/the_rest_of_the_world
>
>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 ?
>

I think I see what you mean tzafrir, and the answer is yes. XML, in it's raw
format in schema is as good as the parsers implementation.

For example, we can make each specific tag it's own document.

I will add the ability to do this in the contrib php file.

The end goal being documentation.php?app=Dial&option=Timeout
Or just html reference tags eg:
documentation.php#Dial.Timeout

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

-Brandon