[prev in list] [next in list] [prev in thread] [next in thread] 

List:       asterisk-dev
Subject:    [asterisk-dev] XML Documentation of Dialplan Applications and
From:       Russell Bryant <russell () digium ! com>
Date:       2008-10-29 4:38:01
Message-ID: 4909563.560051225255081238.JavaMail.root () jupiler ! digium ! com
[Download RAW message or body]

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.

_______________________________________________
--Bandwidth and Colocation Provided by http://www.api-digital.com--

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev


[prev in list] [next in list] [prev in thread] [next in thread]