[asterisk-dev] XML Documentation of Dialplan Applications and Functions

[Russell Bryant]

Greetings,

As you may know from various discussions that have occurred on this mailing list, there has been a project going on to re-work the way that documentation is maintained for dialplan applications and dialplan functions.  The project has been very successful so far, and I would like to thank everyone that has helped out along the way, including Eliel Sardañons, Michiel van Baak, Brandon Kruse, Bradley Latus (snuffy), and a number of others for their efforts.  (If I forgot to include your name, please accept my advance apologies.)

At this point, I would like to make a last call for feedback before the first phase of this work is merged into Asterisk trunk.  Given the invasiveness of the changes, I would like to get it merged in as soon as we can.  Keeping the documentation conversions up to date would be a tiresome task.

===== Project Background =====

Writing documentation is a huge job.  Every time that someone has gone to write documentation on Asterisk, part of the task is always to take the information from "core show application <foo>" or "core show function <bar>" and convert it to some other format.  This documentation has been maintained in the source code in a raw string format, and there has been no programmatic way to extract it from the source.  This project aimed to improve that situation.

===== Current Status =====

A good amount of work has been done, and the current code can be found in the following branch:

http://svn.digium.com/svn/asterisk/team/group/appdocsxml

The best place to look for information on the XML format being used is the examples of applications and functions that have already been converted.  Looking at the diff on reviewboard is an easy place to see these examples.  Visit the review request and click "View Diff" in the upper right.

http://reviewboard.digium.com/r/9/

Another useful reference on the format is the DTD:

http://svn.digium.com/view/asterisk/team/group/appdocsxml/doc/appdocsxml.dtd?view=markup

Of course, one of the best things to do is to check out the code, install it, and look at the displayed documentation.  A lot of applications and functions have been converted.  However, not all of them have been.  The code supports both methods of registering documentation for the sake of backwards compatibility.

===== Third Party Documentation =====

One of the issues that came up while discussing this functionality was how to handle documentation for modules not included in Asterisk.  A similar issue was how to handle documentation for a custom module that replaces one distributed with Asterisk, such as a backport that contains additional features.  The current code makes provisions for this situation.

Documentation is loaded from two different places.  First, it loads from ${AST_DATA_DIR}/documentation/thirdparty, and second, ${AST_DATA_DIR}/documenatation.  What this does is let us install the core documentation that we distribute in the documentation dir.  When someone installs a third party module, or a newer version of a module that we distribute, the associated documentation can be installed into the thirdparty directory, and it will take precedence.

There have been a number of discussions about various methods for having tighter integration between module versions and documentation versions.  However, this task has been deferred to a later phase of this project.

===== Internationalization =====

The current code takes language into account.  All of the documentation currently included in Asterisk is marked as "en_US".  The preferred documentation language can be configured in asterisk.conf.  One of the next phases of this project will be to figure out a plan for maintaining documentation translations.  Keeping the translations in sync will be quite a task, but other large projects have been doing this for a long time, and have many of the technical and logistical issues sorted out.

===== Other Future Development =====

While the current code only handles applications and dialplan functions, it certainly makes sense to extend this functionality to other Asterisk interfaces, as well.  Once these are settled, we can improve the documentation format for CLI commands, AGI, and the manager interface.

===== Final Thoughts =====

Take a look, and please post any feedback that you may have.  If there is no opposition, I would like to move forward with merging this work into trunk in the near future.  Then, we'll unleash a janitor project to finish the conversions of all applications and functions to the new documentation format.

Thanks,

-- 
Russell Bryant
Senior Software Engineer
Open Source Team Lead
Digium, Inc.