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

[Michiel van Baak]

On 20:02, Tue 08 Jul 08, Tzafrir Cohen wrote:
> On Tue, Jul 08, 2008 at 06:30:42PM +0200, Michiel van Baak wrote:
> > Hi all,
> > 
> > Olle already mentioned it briefly, but I wanted to devote a whole post
> > to it:
> > We are currently working on defining and implementing an XML format for
> > apps/function/etc documentation.
> > 
> > The goal of this project is to convert the static documentation in the
> > sourcecode into a parseable format that will be loaded at runtime.
> > Right now, the apps for example, have a static char description that
> > documents all the options etc. This info can only be used inside
> > asterisk on the CLI with 'core show application FOO'
> 
> It's easy to make it extractable at build time without any major
> changes.
> 
> See the macros in http://svn.digium.com/view/asterisk/team/tzafrir/docs/
> http://svn.digium.com/view/asterisk/team/tzafrir/docs/?view=log

Yeah.
There's a target in the Makefile called 'documentation'
This will extract the blob from all the files in apps/functions/res etc

All those blocks will be stored in documentation.xml.
On install, this file will be installed in
/var/lib/asterisk/documentation.xml
> 
> One unrelated thing I learned from there: extracting text from the whole
> of the Asterisk source tree is not so expensive. At least if you do it
> in a single sed/awk/perl script. The first time may take a bit longer to
> get the text in the cache. But the following runs are much faster.

We dont see a noticable increase in build time at the moment.
We do use the same method for this as menuselect does for that info.

> 
> > 
> > With this new XML setup we can still do that, but the documentation will
> > be structured and parseable.
> > One thing that comes to mind is some webbased documentation.
> > 
> > We defined the format in:
> > http://svn.digium.com/view/asterisk/team/group/appdocsxml/doc/xmldocumentation.txt?view=markup
> > and the TODO list in:
> > http://svn.digium.com/view/asterisk/team/group/appdocsxml/TODO_appdocsxml?view=markup
> 
> http://svn.digium.com/svn/asterisk/team/group/appdocsxml/doc/xmldocumentation.txt
> http://svn.digium.com/svn/asterisk/team/group/appdocsxml/TODO_appdocsxml
> 
> That's the format.
> 
> Where is the documentation stored? How is it generated? What about
> external modules? What about modules of which an original version exists
> in the tree but I load a different version from elsewhere?

On compile time, an awk script will collect all the info into
documentation.xml. This file will also be installed in
${ASTVARLIBDIR}/documentation.xml

Every function that has it's documentation moved to this new format well
grab it's info from that file on load time.

besides the ast_register_application we now have an
ast_register_application_xml
This function will honor a flag in /etc/asterisk/asterisk.conf called
documentation_language.
This way we can have localized help on the CLI.

External modules can have a small addition to their makefile to add
nodes to the documentation.xml

The last question seems tricky to me anyways.
What if the original version and outside version are compiled against
another version of asterisk ?
If they all have some logic in the build process to add info to the
documentation.xml I think it should just work.
> 
> -- 
>                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
> 
> _______________________________________________
> --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

-- 

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