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

[Jared Smith]

On Thu, 2008-10-16 at 14:34 -0500, Russell Bryant wrote:
> 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.

I agree with Russell here that this should be the correct course of
action.  As it stands right now, however, it doesn't seem that docs in
the thirdparty directory override the documentation in the top-level
documentation directory... it only seems to be used if top-level
documentation *doesn't* exist for that application for function.

I didn't spend too much time looking at this (it's late), but I thought
I'd throw this out there.  I've been looking at how we can put together
the infrastructure to make translation of these docs easier, and I'm
pretty sure we can use xml2po/xml2pot to generate .pot and .po files
from our XML docs, and merge the translated results back into
per-language XML files.  (From what I understand, those utilities were
originally designed for DocBook, but they appear at first glance to work
just fine with our XML format as well.)

-Jared