path: root/doc/perlmod.doc

/*! \page perlmod Perl Module Output

\addindex perlmod

<p>Since version 1.2.18, doxygen can generate a new output format we 
have called the &quot;Perl Module output format&quot;.  It has been 
designed as an intermediate format that can be used to generate new 
and customized output without having to modify the doxygen source. 
Therefore, its purpose is similar to the XML output format that can be 
also generated by doxygen.  The XML output format is more standard, 
but the Perl Module output format is possibly simpler and easier to 
use.

<p>The Perl Module output format is still experimental at the moment 
and could be changed in incompatible ways in future versions, although 
this should not be very probable.  It is also lacking some features of 
other doxygen backends.  However, it can be already used to generate 
useful output, as shown by the Perl Module-based \LaTeX generator.

<p>Please report any bugs or problems you find in the Perl Module 
backend or the Perl Module-based \LaTeX generator to the 
doxygen-develop mailing list.  Suggestions are welcome as well.

\section using_perlmod_fmt Usage

<p>When the \ref cfg_generate_perlmod "GENERATE_PERLMOD" tag is enabled in the Doxyfile, 
running doxygen generates a number of files in the `perlmod/` 
subdirectory of your output directory.  These files are the following:

<ul>

<li>`DoxyDocs.pm`:  This is the Perl module that actually
contains the documentation, in the Perl Module format described 
\ref doxydocs_format "below".

<li>`DoxyModel.pm`:  This Perl module describes the structure of
`DoxyDocs.pm`, independently of the actual documentation.  See 
\ref doxymodel_format "below" for details.

<li>`doxyrules.make`:  This file contains the make rules to build 
and clean the files that are generated from the Doxyfile.  Also 
contains the paths to those files and other relevant information. This 
file is intended to be included by your own Makefile.

<li>`Makefile`:  This is a simple Makefile including 
`doxyrules.make`.

</ul>

<p>To make use of the documentation stored in DoxyDocs.pm you can use
one of the default Perl Module-based generators provided by doxygen
(at the moment this includes the Perl Module-based \LaTeX generator,
see \ref perlmod_latex "below") or write your own customized
generator.  This should not be too hard if you have some knowledge of
Perl and it's the main purpose of including the Perl Module backend in
doxygen.  See \ref doxydocs_format "below" for details on how
to do this.

<-- want to use \LaTeX but not possible in headings -->
\section perlmod_latex Using the LaTeX generator.

<p>The Perl Module-based \LaTeX generator is pretty experimental and
incomplete at the moment, but you could find it useful nevertheless.
It can generate documentation for functions, typedefs and variables
within files and classes and can be customized quite a lot by
redefining \TeX macros.  However, there is still no documentation on
how to do this.

<p>Setting the \ref cfg_perlmod_latex "PERLMOD_LATEX" tag to \c YES in the 
\c Doxyfile enables the creation of some additional files in the `perlmod/` 
subdirectory of your output directory.  These files contain the Perl 
scripts and \LaTeX code necessary to generate PDF and DVI output from 
the Perl Module output, using `pdflatex` and `latex` respectively.  Rules 
to automate the use of these files are also added to 
`doxyrules.make` and the `Makefile`.

<p>The additional generated files are the following:

<ul>

<li>`doxylatex.pl`: This Perl script uses `DoxyDocs.pm` and 
DoxyModel.pm to generate `doxydocs.tex`, a \TeX file containing 
the documentation in a format that can be accessed by \LaTeX code. This 
file is not directly LaTeXable.

<li>`doxyformat.tex`: This file contains the \LaTeX code that 
transforms the documentation from doxydocs.tex into \LaTeX text 
suitable to be \LaTeX'ed and presented to the user.

<li>`doxylatex-template.pl`:  This Perl script uses `DoxyModel.pm` 
to generate `doxytemplate.tex`, a \TeX file defining default 
values for some macros.  doxytemplate.tex is included by 
doxyformat.tex to avoid the need of explicitly defining some macros.

<li>`doxylatex.tex`:  This is a very simple \LaTeX document that 
loads some packages and includes doxyformat.tex and doxydocs.tex. This 
document is \LaTeX'ed to produce the PDF and DVI documentation by the 
rules added to `doxyrules.make`.

</ul>

\subsection pm_pdf_gen Creation of PDF and DVI output 

<p>To try this you need to have installed `latex`, `pdflatex` and the 
packages used by `doxylatex.tex`.

<ol>

<li>Update your `Doxyfile` to the latest version using:

<pre>doxygen -u Doxyfile</pre>

<li>Set both \ref cfg_generate_perlmod "GENERATE_PERLMOD" and 
\ref cfg_perlmod_latex "PERLMOD_LATEX" tags to 
\c YES in your Doxyfile.

<li>Run doxygen on your Doxyfile:

<pre>doxygen Doxyfile</pre>

<li>A `perlmod/` subdirectory should have appeared in your output 
directory.  Enter the `perlmod/` subdirectory and run:

<pre>make pdf</pre>

<p>This should generate a `doxylatex.pdf` with the documentation 
in PDF format.

<li>Run:

<pre>make dvi</pre>

<p>This should generate a `doxylatex.dvi` with the documentation 
in DVI format.

</ol>

\section doxydocs_format Documentation format.

<p>The Perl Module documentation generated by doxygen is stored in 
`DoxyDocs.pm`.  This is a very simple Perl module that contains 
only two statements: an assignment to the variable `$doxydocs` and 
the customary `1;` statement which usually ends Perl modules.  
The documentation is stored in the variable `$doxydocs`, which 
can then be accessed by a Perl script using `DoxyDocs.pm`.

<p>`$doxydocs` contains a tree-like structure composed of three 
types of nodes: strings, hashes and lists.

<ul>

<li>`Strings`: These are normal Perl strings.  They can be of 
any length can contain any character.  Their semantics depends on 
their location within the tree.  This type of node has no children.

<li>`Hashes`:  These are references to anonymous Perl hashes.  A 
hash can have multiple fields, each with a different key.  The value 
of a hash field can be a string, a hash or a list, and its semantics 
depends on the key of the hash field and the location of the hash 
within the tree.  The values of the hash fields are the children of 
the node.

<li>`Lists`:  These are references to anonymous Perl lists.  A 
list has an undefined number of elements, which are the children of 
the node.  Each element has the same type (string, hash or list) and 
the same semantics, depending on the location of the list within the 
tree.

</ul>

<p>As you can see, the documentation contained in `$doxydocs`
does not present any special impediment to be processed by a simple
Perl script.  
<!--
To be able to generate meaningful output using the
documentation contained in `$doxydocs` you'll probably need to
know the semantics of the nodes of the documentation tree, which we
present in \ref perlmod_tree "this page".
-->

\section doxymodel_format Data structure

<p>You might be interested in processing the documentation contained
in `DoxyDocs.pm` without needing to take into account the
semantics of each node of the documentation tree.  For this purpose,
doxygen generates a `DoxyModel.pm` file which contains a data
structure describing the type and children of each node in the
documentation tree.

<p>The rest of this section is to be written yet, but in the meantime
you can look at the Perl scripts generated by doxygen (such as
`doxylatex.pl` or `doxytemplate-latex.pl`) to get an idea on
how to use `DoxyModel.pm`.


\htmlonly
Go to the <a href="perlmod_tree.html">next</a> section or return to the
 <a href="index.html">index</a>.
\endhtmlonly

*/