RE: Automake/Autoconf and Doxygen

[Oren Ben-Kiki]

I'm working on a parser library for an open-source project 
(www.yaml.org). I'm using Autoconf/Automake. Everything works 
fine (well, I gave up on libtool after a while, but at this 
stage its OK to use a static library; in fact it might make 
sense to keep it static forever).

My biggest hurdle was getting Automake to understand 
generating documentation using Doxygen. What with the 
multiple possible output formats, auto-detecting the required 
programs (doxygen, dot, latex, pdflatex, dvips, etc.) etc. it 
evolved into a mini-project all by itself. I finally bit the 
bullet and created two files, one with macros for Autoconf, 
and one with a Makefile section template for Automake, that 
do a fair job of handling all the subtleties involved. You 
even get configure options that control the type of 
documentation you want to generate (subject to the required 
programs being there, of course). As they are very small, I'm 
attaching them together with a sample doxygen.cfg file that 
uses the environment variables set by 'configure'.

This means I didn't get any work done on my project itself, 
as you can imagine, and I really want to get cracking on it. 
What's the best way to submit my macros to somewhere where 
they may be used by others? It seems rather wasteful not to 
do something with these files. Ideally they would be 
integrated into the Automake/Autoconf distribution.

Certainly I'm not the only one that uses Doxygen for 
generating library documentation. I know Texinfo is supposed 
to be "the" way to document GNU packages, but I (and, it 
seems, many others) find it much more convenient to document 
the code in the code itself, using structured comments. 
Doxygen does allow adding introduction/tutorial pages, so the 
result does not necessarily need to be an incomprehensible 
list of function calls. And yes, I know I could use c2man to 
generate Texinfo directly from my code, but it is a very 
rudimentary tool compared to Doxygen.

At any rate, I did try to follow the Autoconf coding 
standards as much as possible, and commented things to a 
reasonable level. I named everything global 'DX_*' so as not 
to pollute the 'AC_' and 'AM' name spaces. The Automake part 
is pretty rudimentary - it is just a simple "aminclude.am" 
file containing "if @DX_*" that generate the right Makefile 
code. I'm dimly aware there's a way to write Automake macros 
that would do a better job integrating with Automake, but I 
didn't find any documentation on how to do that. I can spend 
another day or so on these files to make them more acceptable 
for inclusion in the distribution, if given a hint on what's required.

So... What's next? Or should I just forget about it and keep 
these files as part of my library's distribution?

Share & Enjoy,

        Oren Ben-Kiki

dx_automake.tar.gz
Description: Binary data