RE: [Doxygen-users] Understanding how Doxygen Documentation is ge nerated.

[Prikryl,Petr <PRI...@sk...>]

Hi Bob,

Bob Stafford wrote...
> I'm trying to use doxygen to generate general documentation,
> in the same way that is appears it is used to generate the
> doxygen documentation itself, but I'm having some problems
> understanding how this documentation is generated.
> 
> In particular I have the following questions.
> 
> 1. How is the doxygen manual divided into 3 parts. For
>    example Part I starts with the following heading
> 
> Part I
> User Manual
> 
> Greping the doc directory in the doxygen source shows that
> the only place this text occurs is in doxygen_manual.tex (A
> latex file I believe). I've found nothing in the doxygen
> documentation about using latex files as part of the source
> for doxygen. So is this file generated by doxygen? If it is 
> generated by doxygen then where is the source that it used
> to get the "Part I User Manual" text?

The doxygen_manual.tex is not generated from doc sources. It
is (probably) a hand-crafted file that can be found at
doxygen/doc/ subdirectory. When you look inside the
doxygen/doc/Makefile, you can see that the
doxygen_manual.tex is processed by sed (replacing the
version mark by the version information), and the result is
placed into doxygen/latex/ subdirectory. The \part{} is the
LaTeX command that produces the "Part I...".

To summarize, the non-HTML documentation (i.e. DVI, PS, PDF)
is generated via LaTeX sources, and the doxygen_manual.tex
is the external file that defines how the pieces of the
documentation should be put together.

> 2. While trying to regenerate the doxygen documentation from
>    the doc directory, if I type make pdf in the ../latex
>    directory I get the following latex error. Do I need a
>    particular version of Latex.
> 
> [59]
> Underfull \vbox (badness 10000) has occurred while \output is active [60]
> Underfull \hbox (badness 10000) in paragraph at lines 167--167

These are only warnings related to the typographical quality
(basically, the line is shorter than it should be -- from
the typography point of view; just ignore this).

> 
> ) [61] (config.tex
> 
> ! LaTeX Error: Environment multicols undefined.
> 
> See the LaTeX manual or LaTeX Companion for explanation.
> Type  H <return>  for immediate help.
>  ...
> 
> l.25 \begin{multicols}
>                       {2}
> ?

This means that you do not have multicols.sty installed in
your LaTeX instalation.  This package is required.


> The make pdf command does work if I type it before doing the
> doxygen Doxyfile command in the doc directory.

I am not sure here, what Makefile is used in your case.  But
generally, the pdf is produced by ps2pdf from PS result, the
PS is produced by dvips from DVI result, the DVI is
produced by LaTeX from LaTeX sources, and the LaTeX sources
are produced by doxygen from your C/C++/Java source files
plus from your doc files (plus also from the
doxygen_manual.tex).  I guess that there may be some problem
in the Makefile that is used in your case.

(There are also alternative ways how PDF can be produced
from LaTeX.)

> 3. How do you generate different chapters. In my
>    documentation each /page ends up being a different
>    section in one big chapter.
[...]

As far as I know, the doxygen \page commands are transformed
to LaTeX \section commands.  This is fine for generating the 
"article" class of the document, which is used by doxygen
when generating LaTeX output (see the \documentclass LaTeX
command at beginning of the doxygen_manual.tex). The
"article" document class knows nothing about chapters.

The sections do not inject pagebreaks.  If you want to
inject a pagebreak into your LaTeX documentation, you can
use the following sequence in your doxygen doc files:

  \latexonly \pagebreak \endlatexonly
  
But you should know what you are doing from the LaTeX point
of view. (The \latexonly and \endlatexonly are doxygen
commands, the \pagebreak is the LaTeX comand.)

On the other hand, doxygen generates refman.tex for your project
documentation (instead of doxygen_manual.tex).  The chapters are
used for higher structure level than your \page level.  In other
words, the refman.tex uses the "book" document class where the
\chapter{} LaTeX command can be used, but doxygen reserves the
chapter level for other things.

Hope this helps,

  Petr

-- 
Petr Prikryl, Skil, spol. s r.o., (pri...@sk...)