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