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

[Brandon Kruse]

>----- Original Message -----
>From: "Caio Begotti" <caio at ueberalles.net>
>To: "Asterisk Developers Mailing List" <asterisk-dev at lists.digium.com>
>Sent: Tuesday, July 8, 2008 12:55:42 PM GMT -06:00 US/Canada Central
>Subject: Re: [asterisk-dev] XML documentation of apps/functions/the_rest_of_the_world
>
>On Tue, 8 Jul 2008 19:42:41 +0200
>Michiel van Baak <michiel at vanbaak.info> wrote:
>
>> Instead of having a single *descrip in the source we can now define
>> multiple blocks of documentation for an application.
>> As an example I added dutch documentation to the ChanIsAvail
>> application:
>>  /*** DOCUMENTATION
>>           <application name="ChanIsAvail" language="en">
>> 		  ...
>> 		  ...
>> 		  <application name="ChanIsAvail" language="nl">
>> 		  ...
>>  ***/
>> 
>[...]
>> If set, it will look for a node with the specified language once the
>> application is loaded. If that language node exists, it will use
>> that for the documentation. If not, it will fall back to english.
>
>Instead of a node for each language what about merging different XML
>files for each one of them? Too hackish? Let's say there are 7 amazing
>Asterisk local groups out there looking forward to send their massive
>translations :)
>

That wouldn't be a problem in the sense that it's XML, it is still parsed
by the language= attribute, after the nodes are parsed into a group by
application/function name. We are still defining the spec/schema, but 
I think that a few more languages would not be bad at all.

It is important to remember that in doing this, the only thing that grows
is the external documentation.xml (which can be trimmed on build time based
on a specific language), and the source. The modules/resources/application no longer
have that const char *, which does decrease the size of the modules compiled.

I would also suggest that this move isn't just for a new cool way to get
the documentation out, but rather that it can be used for so much more.

One thing russell mentioned is the extensions.conf validiation, and the
easy way to add new language support for specific things.

The other major advantage IS having all this in XML, which can be easily
converted and manipulated in docbook, and other applications that can find
use for this specific XML blob that ALSO defines exactly what the application
is.

>[]'s
>
>-- 
>Caio Begotti
>http://caio.ueberalles.net/asterisk/faq/
>
>_______________________________________________
>--Bandwidth and Colocation Provided by http://www.api-digital.com--
>
>AstriCon 2008 - September 22 - 25 Phoenix, Arizona
>Register Now: http://www.astricon.net
>
>asterisk-dev mailing list
>To UNSUBSCRIBE or update options visit:
>   http://lists.digium.com/mailman/listinfo/asterisk-dev
>


-bkruse