[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