[Cppunit-devel] Problems with TeX documentation

[CppUnit d. m. l. <cpp...@li...>]

Dear List,
                     although the machinery for setting using LaTeX (via 
doxygen)
is still in place (featured in the options to 'configure', for instance) 
it's not
been given a place in the top-level Makefile (whereas the HTML documentation
has).  This may reflect a recognition that the documentation is in fact
broken... but it may as well be repaired.

There are essentially three problems.
(a) The Doxyfile[.in] file has an out-of-date format.  This can be
worked around by invoking doxygen -u <path to Doxyfile>: I think
this may as well happen in the sources (unless there is some especial
reason to keep on using old versions of doxygen - mine is 1.4.7).

(b) The \brief tags for TOC entries are not quite consistent.  They
mostly suppose that entries are single lines.  This is NOT the
default behaviour of Doxygen, and I can't see a way of over-riding
it.  The end of the enclosing comment or a "blank" line (not counting
'*' in block comments) is needed.  This mostly doesn't break the
TeX, though I suspect it leads to extra tags being adjoined into the
ToC entry which don't belong there.  What DOES break TeX is
constructions like that near the start of AdditionalMessage.h:

/*! \brief An additional Message for assertions.
 *
 * \ingroup CreatingNewAssertions
 *
 * Provides a implicit constructor that takes a single string. This 
allow this
 * class to be used as the message arguments in macros.
 *
 * The constructed object is either a Message with a single detail string if
 * a string was passed to the macro, or a copy of the Message passed to 
the macro.
 *
 * Here is an example of usage:
 * \code

Doxygen thinks the first "blank" ('*' only) line terminates the TOC entry,
and then gets very confused, because it's split the multi-paragraph
\ingroup block.

The cure is to put in a "blank" line after the \brief tag in each case, 
which
is plainly "safe".  I'm reasonably confident that this is ALMOST always
correct, though in a few cases it could be intended that subsequent
lines be part of the TOC entry.  In just ONE case that I've noticed,
near lines 230-231 in include/cppunit/TestAssert.h, there is DEFINITELY
a run-on past a line-break.

This then allows TeX to pick up another set of problems.
I haven't unravelled the exact cause of the problem, but
'Implemented' and 'Reimplemented' remarks on classes produce broken
\doxyref blocks in which what should be the cross-reference anchor is
simply set out in bold-face (\bf{name}) followed by the \doxyref block,
but this time with the reference target omitted.  Unsurprisingly, this
too produces some thoroughly confused error messages.

A work-around (I don't say it's elegant, or even correct,
but it stops TeX from gagging) is to perform the following substitution
on the output .tex files from the run which generates the HTML
documentation:

(change directory to <builddir>/doc/latex)

sed -i 's/\\bf\({[^}]\+}\) *\\doxyref *{p/\\doxyref\1{p/g' '-`' grep -rl 
'\\\\bf\({[^}]\+}\) *\\\\doxyref *{p' *.tex '-`' ';' \

That is, get a list of files to be modified from 'grep -rl' (this can be 
omitted: one can
be simple-minded and lazy and just zap all the *.tex files in sight), 
and use 'sed' to
reconstruct the \doxyref properly.

There seems no point to expressing this as a patch: what's needed is to 
stop Doxygen
creating the bad \doxyref entries in the first place, which is beyond me 
in my present
stage of ignorance.

I attach a bzipped version of a patch which worked for the 1.12.0 
release (I haven't
tried it against the CVS sources, nor even checked whether they have 
changed).
It represents the combined effect of updating Doxyfile.in  for 
doxygen-1.4.7 and
the extra "blank" lines inserted in the doxyfile comments after \brief 
TOC entries.
For the foreseeable future this should also be available at
http://www.brenda-arkle.demon.co.uk/patches/cppunit/cppunit-1.12.0-bl12_doxygen-1.patch 
.

I note (slightly to my surprise) that there don't seem to be any working 
hyperlinks
in the PDF documentation resulting, though it looks OK.  It's also 
littered with
errors of one sort or another (I especially liked the claim that the 
PlugInManager
"manges" TestPlugIn).  I may get back to these some other day.  But at 
least it
*exists* now...
                                                  Yours exhaustedly,
                                                                                   
Bernard Leak