[Doxygen-develop] PDF index errors and proposed fix

[Simon G. <sim...@at...>]

Hi Doxygenators,

I wish to propose a small fix for a problem that
I have encountered and hope I have corrected.
Since this is the first change I've proposed for
Doxygen, and I'm still finding my way around
it, either my analysis or the cure may be faulty,
but I'm not the only user who has noticed the
problem (it cropped up once, embarrassingly,
when I demonstrated Doxygen to my boss,
and another Doxygen advocate here at ATD
spotted the problem but couldn't work out
a fix). I wonder if others here have seen this?

Problem:

Index references in PDF documentation are
sometimes incorrect, typically by a small
amount (a page or so).

Analysis:

This appears to be because latex needs to
be run several times to resolve references.
It needs to do this because when the index
is generated it changes the document and
so the document needs to be re-indexed.
This process terminates eventually, but it
seems Doxygen does not persue it enough
when generating files with pdflatex (only).

It appears that the ps2pdf process, which
goes via DVI format, does not suffer the same
problem, though its output quality is inferior.
The latex/Makefile 'make dvi' code uses egrep
and a loop to force repeat runs, but no such
loop appears in the makefile section that runs
pdflatex, yet the refman.log indicates that a
repeat run is expected.

Fix:

Modify the 'make pdf' case to rerun pdflatex
essentially as 'make ps' already does: 

$ make pdf
pdflatex refman.tex
makeindex refman.idx
pdflatex 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...." ;\
      pdflatex refman.tex ;\
      latex_count=`expr $latex_count - 1` ;\
    done

Yields:

	LaTeX Warning: Label(s) may have changed. Rerun to get 
	cross-references right.

	Rerunning latex....

and (as far as I can tell, so far) a correct index.

The fix is to replace line 176 of latexgen.cpp with this:

    /* Changes by Simon N Goodwin 2002-6-5 */
      t << "\tpdflatex refman.tex" << endl ;
	  t << "\tlatex_count=5 ; \\" << endl
    << "\twhile egrep -s 'Rerun (LaTeX|to get cross-references right)' refman.log && [ $$latex_count -gt 0 ] ;\\" << endl
    << "\t    do \\" << endl
    << "\t      echo \"Rerunning pdflatex....\" ;\\" << endl
    << "\t      pdflatex refman.tex ;\\" << endl
    << "\t      latex_count=`expr $$latex_count - 1` ;\\" << endl
    << "\t    done" << endl << endl;
    /* End of changes by Simon N Goodwin */

I welcome comments. You can check if this might
help you by looking through your own refman.log
for the string "to get cross-references right". If it
is present, I think you need the fix.

-- 
Simon Goodwin <sim...@at...>