[asterisk-dev] Asterisk XML documentation (appdocsxml branch) is ready

[Jared Smith]

On Tue, 2008-10-21 at 12:22 +0200, Vadim Lebedev wrote:  
> Still it seems, that the desired effect can be achieved by using
> doxygen  and post processing resulting HTML  with XSLT to extract
> user-level doc only

While it's certainly *possible* to write the documentation in doxygen
and then convert it to HTML with some post-processing (and I don't think
XSLT would work, as doxygen comments aren't XML), the main problem here
is that doxygen doesn't provide the structure we need to make the
documentation consistent.

Although Doygen does provide some structure (this is a function, it has
these parameters, etc.), the structure doesn't exactly fit what we need
for end-user documentation. If you look closely at the XML docs or the
included DTD, I think you'll see what I mean.

More importantly, however, Doxygen fails two of the major design goals
of this little exercise: first, it doesn't lend itself to being able to
be ready by Asterisk at run-time (for more advanced dialplan parsing and
validation).  Second, documentation in doxygen doesn't lend itself to
translation into other languages nearly as easily as XML in the format
we've developed (somewhat based on a very limited subset of DocBook).  I
posted in another tread last night here in this mailing list that the
existing xml2po/xml2pot tools that large projects like KDE, Gnome, and
Fedora use appear to work fairly well on our XML files, which makes it
easy for translators to use existing translation infrastructure
(programs and services such as KBabel, Rosetta, or Transifex) to help us
translate the documentation.  From what I gather, most translators are
familiar with those tools, and not familiar with Doxygen.  I don't
pretend to be an expert on internationalization or localization issues,
but I've tried to do my homework and make this as easy as possible (but
no easier!) to help get the community involved in the translation of
this documentation.

In short, I think our XML is better suited to the end-user documentation
in the Asterisk source code (for the reasons stated above), and that
Doxygen is a great solution for the documentation of the source code
itself.

-Jared