[asterisk-dev] Docs converted to TeX?

Russell Bryant russell at digium.com
Tue May 22 09:21:43 MST 2007


Olle E Johansson wrote:
> That means that it is better to go back to doxygen all the way. Doxygen 
> can generate html, windows help files and other formats and
> it's something we already use and want developers and people who 
> contribute documentation to use.

Just because doxygen can generate HTML, it does not mean it is the obvious 
choice for us going forward in creating better Asterisk administrator documentation.

> As I said before, using Tex for the docs breaks the integration we 
> already have between the doxygen docs and the doc/ files.

Well, to be honest, I think we should work toward separating the two.  Doxygen 
is great for API documentation, but using it for a manual is quite a hack in my 
opinion.

> Let's not add another tool, it's already hard enough to get the 
> community to add doxygen.

Developers don't always document their code extremely well?!  I have never heard 
of that before.  :)

> Instead, let's make two doxygen targets - devdocs and admindocs. 
> Admindocs is the READMEs and some of the doc included
> in the source code, but without all the .c and .h files.

This sounds like a more reasonable approach if doxygen was used.  However, if we 
are separating them anyway, using doxygen isn't an obvious choice.  In fact, 
much more people are familiar with TeX markup than doxygen.

I really don't want to get into a documentation format war, but it is going to 
be pretty difficult to convince me that making a manual using a system that is 
intended for API documentation is the right thing to do.

-- 
Russell Bryant
Software Engineer
Digium, Inc.


More information about the asterisk-dev mailing list