[PPL-devel] Doxygen bug report: (pdf)latex is not run as many times as necessary

[Roberto Bagnara]

Doxygen writes, in the LATEX_OUTPUT a Makefile that is very useful
in order not to run (pdf)latex and makeindex by hand.
Here is one of the make rules I am talking about

refman.dvi: refman.tex doxygen.sty
        echo "Running latex..."
        latex refman.tex
        echo "Running makeindex..."
        makeindex refman.idx
        echo "Rerunning latex...."
        latex refman.tex

The problem is that (pdf)latex may have to be run multiple times
to get cross-references right.  Sometimes running it once after
makeindex is indeed enough, but must often you need to run it
twice (this is the case for the project I am working on).
In rare cases you need to run it three or more times (even though
I have never seen more than three runs to be necessary).
That is why I propose to replace the above rule by the following
and to provide a similar rule for pdflatex when USE_PDFLATEX is set
to YES:

refman.dvi: refman.tex doxygen.sty
	echo "Running latex..."
	latex refman.tex
	echo "Running makeindex..."
	makeindex refman.idx
	echo "Rerunning latex...."
	latex refman.tex
	latex_count=5
	while egrep -s 'Rerun (LaTeX|to get cross-references right)' refman.log && [ $latex_count -gt 0 ] ;\
	do \
	  echo "Rerunning latex...." ;\
	  latex refman.tex ;\
	  latex_count=`expr $latex_count - 1` ;\
	done

Notice that latex is run only if necessary and at most five times
after makeindex. This is done because (pdf)latex is not guaranteed
to be able to stabilize the cross-references.  While this happens only
in extremely pathological cases, it is better to take measures
against it.  That is what latex_count is used for.

All the best,

    Roberto

-- 
Roberto Bagnara
Computer Science Group
Department of Mathematics, University of Parma, Italy
http://www.cs.unipr.it/~bagnara/
mailto:bagnara at cs.unipr.it