Perl Module output format documentation

Since version 1.2.18, Doxygen can generate a new output format we have called the "Perl Module output format". 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.

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.

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.

Using the Perl Module output format.

When the 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:

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 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 below for details on how to do this.

Using the Perl Module-based LaTeX generator.

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.

Setting the PERLMOD_LATEX tag to YES in the 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.

The additional generated files are the following:

Simple creation of PDF and DVI output using the Perl Module-based LaTeX generator.

To try this you need to have installed LaTeX, PDFLaTeX and the packages used by doxylatex.tex.

  1. Update your Doxyfile to the latest version using:

    doxygen -u Doxyfile

  2. Set both GENERATE_PERLMOD and PERLMOD_LATEX tags to YES in your Doxyfile.

  3. Run Doxygen on your Doxyfile:

    doxygen Doxyfile

  4. A perlmod/ subdirectory should have appeared in your output directory. Enter the perlmod/ subdirectory and run:

    make pdf

    This should generate a doxylatex.pdf with the documentation in PDF format.

  5. Run:

    make dvi

    This should generate a doxylatex.dvi with the documentation in DVI format.

Perl Module documentation format.

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 assigment 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.

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

As you can see, the documentation contained in $doxydocs does not present any special impediment to be processed by a simple Perl script.

Data structure describing the Perl Module documentation tree.

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.

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.


Generated on Thu Apr 30 23:14:04 2009 for Doxygen manual by  doxygen 1.5.9