[asterisk-dev] Asterisk XML Documentation (Other XML sources)

[Russell Bryant]

Eliel Sardañons wrote:
> Hello list,
>      I am writing here to get some feedback about how to handle other 
> XML documentation sources like "addons" and other extra files where we 
> could be able to find (application/functions) XML documentation. The 
> idea is to add a configuration context inside asterisk.conf of the form:
> 
> [documentation]
> language => en_US
> source => core
> source => addons
> source => anotherextra
> 
> So, asterisk will search inside PATH/core-en_US.xml, 
> PATH/addons-en_US.xml and PATH/anotherextra-en_US.xml to find the XML 
> documentation when needed.
> Right now core is being hardcoded inside the code (uggh), with this form 
> we will be able to add as many sources as needed, then in 
> asterisk-addons we will be able (in the make install) to generate the 
> "addons-language.xml" file. And if we added our application from outside 
> the source tree we will be able to create an xml file and just insert 
> the name in asterisk.conf.

Instead of having anything hard coded like "core", "addons", etc., I 
propose a scheme like the following.  If the documentation language is 
set to en_US, then load documentation from all files that match the 
following patterns:

DOCDIR/*-en_US.xml
      Here in the top level directory, we would have the "core" and 
"addons" files.  Basically, this is where the officially distributed 
documentation would go that comes from us.

DOCDIR/thirdparty/*-en_US.xml
      This is where additional documentation should be installed.  If 
someone installs a backport of an application that has additional 
features, or some custom modules that add new features, the associated 
files that contain their documentation should be installed here.  For 
the case that something is found in this directory that is a duplicate 
of something documented in the top level documentation directory, this 
version should be used.

Using this scheme, we have a way to differentiate between the original 
official documentation, as well as a method for dealing with addons and 
replacements.

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