DoxyPress  1.6.0
Perl Module Output

DoxyPress can generate an output format 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 DoxyPress source. Therefore, its purpose is similar to the XML output format that can be also generated by DoxyPress. 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 DoxyPress backends. However, it can be already used to generate useful output, as shown by the Perl Module-based LaTeX generator.

Usage

When the generate-perl tag is enabled in the project file, running DoxyPress generates a number of files in the perlmod directory in your project output.

DoxyDocs.pm
This is the Perl module that contains the documentation, in the Perl Module format described in Documentation Format
DoxyModel.pm
This Perl module describes the structure of DoxyDocs.pm, independently of the actual documentation. See below for details.
doxyrules.make
This file contains the make rules to build and clean the files which are generated by your DoxyPress project. This file is intended to be included by your own Makefile.
Makefile
This is a simple Makefile including doxyrules.make.

To make use of the documentation stored in DoxyDocs.pm you can use one of the default Perl Module-based generators provided by DoxyPress (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 DoxyPress. Refer to below for details on how to do this.

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 perl-latex tag to YES in your project file 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:

  • 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 LaTeX.
  • doxyformat.tex: This file contains the LaTeX code that transforms the documentation from doxydocs.tex into LaTeX text suitable to be LaTeX and presented to the user.
  • doxylatex-template.pl: This Perl script uses DoxyModel.pm to generate doxytemplate.tex, a TeX file defining default values for some macros. The file doxytemplate.tex is included by doxyformat.tex to avoid the need of explicitly defining some macros.
  • doxylatex.tex: This is a very simple LaTeX document that loads some packages and includes doxyformat.tex and doxydocs.tex. This document is LaTeX to produce the PDF and DVI documentation by the rules added to doxyrules.make.

PDF and DVI Output

You will need to install latex, pdflatex, and the packages used by doxylatex.tex.

  1. Set generate-perl and perl-latex tags to YES in your project file.
  2. Run DoxyPress using your project file
  3. Run
    make pdf
    from the perlmod directory in your project output. This will generate a a doxylatex.pdf with the documentation in PDF format.
  4. Run
    make dvi
    . This will generate a doxylatex.dvi with the documentation in DVI format.

Documentation Format

The Perl Module documentation generated by DoxyPress 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.

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

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

The documentation contained in $doxydocs does not present any special impediment to be processed by a simple Perl script.

Data Structure

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, DoxyPress 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 DoxyPress (such as doxylatex.pl or doxytemplate-latex.pl) to get an idea on how to use DoxyModel.pm.