|
Packit Service |
50c9f2 |
/*! \page perlmod Perl Module Output
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\addindex perlmod
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Since version 1.2.18, doxygen can generate a new output format we
|
|
Packit Service |
50c9f2 |
have called the "Perl Module output format". It has been
|
|
Packit Service |
50c9f2 |
designed as an intermediate format that can be used to generate new
|
|
Packit Service |
50c9f2 |
and customized output without having to modify the doxygen source.
|
|
Packit Service |
50c9f2 |
Therefore, its purpose is similar to the XML output format that can be
|
|
Packit Service |
50c9f2 |
also generated by doxygen. The XML output format is more standard,
|
|
Packit Service |
50c9f2 |
but the Perl Module output format is possibly simpler and easier to
|
|
Packit Service |
50c9f2 |
use.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The Perl Module output format is still experimental at the moment
|
|
Packit Service |
50c9f2 |
and could be changed in incompatible ways in future versions, although
|
|
Packit Service |
50c9f2 |
this should not be very probable. It is also lacking some features of
|
|
Packit Service |
50c9f2 |
other doxygen backends. However, it can be already used to generate
|
|
Packit Service |
50c9f2 |
useful output, as shown by the Perl Module-based \LaTeX generator.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Please report any bugs or problems you find in the Perl Module
|
|
Packit Service |
50c9f2 |
backend or the Perl Module-based \LaTeX generator to the
|
|
Packit Service |
50c9f2 |
doxygen-develop mailing list. Suggestions are welcome as well.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section using_perlmod_fmt Usage
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
When the \ref cfg_generate_perlmod "GENERATE_PERLMOD" tag is enabled in the Doxyfile,
|
|
Packit Service |
50c9f2 |
running doxygen generates a number of files in the `perlmod/`
|
|
Packit Service |
50c9f2 |
subdirectory of your output directory. These files are the following:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
`DoxyDocs.pm`: This is the Perl module that actually
|
|
Packit Service |
50c9f2 |
contains the documentation, in the Perl Module format described
|
|
Packit Service |
50c9f2 |
\ref doxydocs_format "below".
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
`DoxyModel.pm`: This Perl module describes the structure of
|
|
Packit Service |
50c9f2 |
`DoxyDocs.pm`, independently of the actual documentation. See
|
|
Packit Service |
50c9f2 |
\ref doxymodel_format "below" for details.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
`doxyrules.make`: This file contains the make rules to build
|
|
Packit Service |
50c9f2 |
and clean the files that are generated from the Doxyfile. Also
|
|
Packit Service |
50c9f2 |
contains the paths to those files and other relevant information. This
|
|
Packit Service |
50c9f2 |
file is intended to be included by your own Makefile.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
`Makefile`: This is a simple Makefile including
|
|
Packit Service |
50c9f2 |
`doxyrules.make`.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
To make use of the documentation stored in DoxyDocs.pm you can use
|
|
Packit Service |
50c9f2 |
one of the default Perl Module-based generators provided by doxygen
|
|
Packit Service |
50c9f2 |
(at the moment this includes the Perl Module-based \LaTeX generator,
|
|
Packit Service |
50c9f2 |
see \ref perlmod_latex "below") or write your own customized
|
|
Packit Service |
50c9f2 |
generator. This should not be too hard if you have some knowledge of
|
|
Packit Service |
50c9f2 |
Perl and it's the main purpose of including the Perl Module backend in
|
|
Packit Service |
50c9f2 |
doxygen. See \ref doxydocs_format "below" for details on how
|
|
Packit Service |
50c9f2 |
to do this.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
<-- want to use \LaTeX but not possible in headings -->
|
|
Packit Service |
50c9f2 |
\section perlmod_latex Using the LaTeX generator.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The Perl Module-based \LaTeX generator is pretty experimental and
|
|
Packit Service |
50c9f2 |
incomplete at the moment, but you could find it useful nevertheless.
|
|
Packit Service |
50c9f2 |
It can generate documentation for functions, typedefs and variables
|
|
Packit Service |
50c9f2 |
within files and classes and can be customized quite a lot by
|
|
Packit Service |
50c9f2 |
redefining \TeX macros. However, there is still no documentation on
|
|
Packit Service |
50c9f2 |
how to do this.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Setting the \ref cfg_perlmod_latex "PERLMOD_LATEX" tag to \c YES in the
|
|
Packit Service |
50c9f2 |
\c Doxyfile enables the creation of some additional files in the `perlmod/`
|
|
Packit Service |
50c9f2 |
subdirectory of your output directory. These files contain the Perl
|
|
Packit Service |
50c9f2 |
scripts and \LaTeX code necessary to generate PDF and DVI output from
|
|
Packit Service |
50c9f2 |
the Perl Module output, using `pdflatex` and `latex` respectively. Rules
|
|
Packit Service |
50c9f2 |
to automate the use of these files are also added to
|
|
Packit Service |
50c9f2 |
`doxyrules.make` and the `Makefile`.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The additional generated files are the following:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
`doxylatex.pl`: This Perl script uses `DoxyDocs.pm` and
|
|
Packit Service |
50c9f2 |
DoxyModel.pm to generate `doxydocs.tex`, a \TeX file containing
|
|
Packit Service |
50c9f2 |
the documentation in a format that can be accessed by \LaTeX code. This
|
|
Packit Service |
50c9f2 |
file is not directly LaTeXable.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
`doxyformat.tex`: This file contains the \LaTeX code that
|
|
Packit Service |
50c9f2 |
transforms the documentation from doxydocs.tex into \LaTeX text
|
|
Packit Service |
50c9f2 |
suitable to be \LaTeX'ed and presented to the user.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
`doxylatex-template.pl`: This Perl script uses `DoxyModel.pm`
|
|
Packit Service |
50c9f2 |
to generate `doxytemplate.tex`, a \TeX file defining default
|
|
Packit Service |
50c9f2 |
values for some macros. doxytemplate.tex is included by
|
|
Packit Service |
50c9f2 |
doxyformat.tex to avoid the need of explicitly defining some macros.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
`doxylatex.tex`: This is a very simple \LaTeX document that
|
|
Packit Service |
50c9f2 |
loads some packages and includes doxyformat.tex and doxydocs.tex. This
|
|
Packit Service |
50c9f2 |
document is \LaTeX'ed to produce the PDF and DVI documentation by the
|
|
Packit Service |
50c9f2 |
rules added to `doxyrules.make`.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\subsection pm_pdf_gen Creation of PDF and DVI output
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
To try this you need to have installed `latex`, `pdflatex` and the
|
|
Packit Service |
50c9f2 |
packages used by `doxylatex.tex`.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Update your `Doxyfile` to the latest version using:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
doxygen -u Doxyfile
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Set both \ref cfg_generate_perlmod "GENERATE_PERLMOD" and
|
|
Packit Service |
50c9f2 |
\ref cfg_perlmod_latex "PERLMOD_LATEX" tags to
|
|
Packit Service |
50c9f2 |
\c YES in your Doxyfile.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Run doxygen on your Doxyfile:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
doxygen Doxyfile
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
A `perlmod/` subdirectory should have appeared in your output
|
|
Packit Service |
50c9f2 |
directory. Enter the `perlmod/` subdirectory and run:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
make pdf
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
This should generate a `doxylatex.pdf` with the documentation
|
|
Packit Service |
50c9f2 |
in PDF format.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Run:
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
make dvi
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
This should generate a `doxylatex.dvi` with the documentation
|
|
Packit Service |
50c9f2 |
in DVI format.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section doxydocs_format Documentation format.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The Perl Module documentation generated by doxygen is stored in
|
|
Packit Service |
50c9f2 |
`DoxyDocs.pm`. This is a very simple Perl module that contains
|
|
Packit Service |
50c9f2 |
only two statements: an assignment to the variable `$doxydocs` and
|
|
Packit Service |
50c9f2 |
the customary `1;` statement which usually ends Perl modules.
|
|
Packit Service |
50c9f2 |
The documentation is stored in the variable `$doxydocs`, which
|
|
Packit Service |
50c9f2 |
can then be accessed by a Perl script using `DoxyDocs.pm`.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
`$doxydocs` contains a tree-like structure composed of three
|
|
Packit Service |
50c9f2 |
types of nodes: strings, hashes and lists.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
`Strings`: These are normal Perl strings. They can be of
|
|
Packit Service |
50c9f2 |
any length can contain any character. Their semantics depends on
|
|
Packit Service |
50c9f2 |
their location within the tree. This type of node has no children.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
`Hashes`: These are references to anonymous Perl hashes. A
|
|
Packit Service |
50c9f2 |
hash can have multiple fields, each with a different key. The value
|
|
Packit Service |
50c9f2 |
of a hash field can be a string, a hash or a list, and its semantics
|
|
Packit Service |
50c9f2 |
depends on the key of the hash field and the location of the hash
|
|
Packit Service |
50c9f2 |
within the tree. The values of the hash fields are the children of
|
|
Packit Service |
50c9f2 |
the node.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
`Lists`: These are references to anonymous Perl lists. A
|
|
Packit Service |
50c9f2 |
list has an undefined number of elements, which are the children of
|
|
Packit Service |
50c9f2 |
the node. Each element has the same type (string, hash or list) and
|
|
Packit Service |
50c9f2 |
the same semantics, depending on the location of the list within the
|
|
Packit Service |
50c9f2 |
tree.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
As you can see, the documentation contained in `$doxydocs`
|
|
Packit Service |
50c9f2 |
does not present any special impediment to be processed by a simple
|
|
Packit Service |
50c9f2 |
Perl script.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
To be able to generate meaningful output using the
|
|
Packit Service |
50c9f2 |
documentation contained in `$doxydocs` you'll probably need to
|
|
Packit Service |
50c9f2 |
know the semantics of the nodes of the documentation tree, which we
|
|
Packit Service |
50c9f2 |
present in \ref perlmod_tree "this page".
|
|
Packit Service |
50c9f2 |
-->
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section doxymodel_format Data structure
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
You might be interested in processing the documentation contained
|
|
Packit Service |
50c9f2 |
in `DoxyDocs.pm` without needing to take into account the
|
|
Packit Service |
50c9f2 |
semantics of each node of the documentation tree. For this purpose,
|
|
Packit Service |
50c9f2 |
doxygen generates a `DoxyModel.pm` file which contains a data
|
|
Packit Service |
50c9f2 |
structure describing the type and children of each node in the
|
|
Packit Service |
50c9f2 |
documentation tree.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The rest of this section is to be written yet, but in the meantime
|
|
Packit Service |
50c9f2 |
you can look at the Perl scripts generated by doxygen (such as
|
|
Packit Service |
50c9f2 |
`doxylatex.pl` or `doxytemplate-latex.pl`) to get an idea on
|
|
Packit Service |
50c9f2 |
how to use `DoxyModel.pm`.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\htmlonly
|
|
Packit Service |
50c9f2 |
Go to the next section or return to the
|
|
Packit Service |
50c9f2 |
index.
|
|
Packit Service |
50c9f2 |
\endhtmlonly
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
*/
|