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

[BJ Weschke]

Eliel Sardañons wrote:
> +1
>
> Right now we are using ASTVARDIR /var/lib/asterisk/ to store the 
> documentation XML, is this the right place? actually the XML 
> documentation is not variable data, and we could use 
> /usr/lib/asterisk/documentation to store there the XMLs (default).
>
>
> On Thu, Oct 16, 2008 at 4:34 PM, Russell Bryant <russell at digium.com 
> <mailto:russell at digium.com>> wrote:
>
>     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.
>
>
>
>
 I am more partial to /usr/lib/asterisk/documentation as well. It implies that this content is indeed static with the deploy of that build of the code and it won't be changing.

--
Bird's The Word Technologies, Inc.
http://www.btwtech.com/