1 /*! \page perlmod Perl Module Output
5 <p>Since version 1.2.18, doxygen can generate a new output format we
6 have called the "Perl Module output format". It has been
7 designed as an intermediate format that can be used to generate new
8 and customized output without having to modify the doxygen source.
9 Therefore, its purpose is similar to the XML output format that can be
10 also generated by doxygen. The XML output format is more standard,
11 but the Perl Module output format is possibly simpler and easier to
14 <p>The Perl Module output format is still experimental at the moment
15 and could be changed in incompatible ways in future versions, although
16 this should not be very probable. It is also lacking some features of
17 other doxygen backends. However, it can be already used to generate
18 useful output, as shown by the Perl Module-based \LaTeX generator.
20 <p>Please report any bugs or problems you find in the Perl Module
21 backend or the Perl Module-based \LaTeX generator to the
22 doxygen-develop mailing list. Suggestions are welcome as well.
24 \section using_perlmod_fmt Usage
26 <p>When the \ref cfg_generate_perlmod "GENERATE_PERLMOD" tag is enabled in the Doxyfile,
27 running doxygen generates a number of files in the `perlmod/`
28 subdirectory of your output directory. These files are the following:
32 <li>`DoxyDocs.pm`: This is the Perl module that actually
33 contains the documentation, in the Perl Module format described
34 \ref doxydocs_format "below".
36 <li>`DoxyModel.pm`: This Perl module describes the structure of
37 `DoxyDocs.pm`, independently of the actual documentation. See
38 \ref doxymodel_format "below" for details.
40 <li>`doxyrules.make`: This file contains the make rules to build
41 and clean the files that are generated from the Doxyfile. Also
42 contains the paths to those files and other relevant information. This
43 file is intended to be included by your own Makefile.
45 <li>`Makefile`: This is a simple Makefile including
50 <p>To make use of the documentation stored in DoxyDocs.pm you can use
51 one of the default Perl Module-based generators provided by doxygen
52 (at the moment this includes the Perl Module-based \LaTeX generator,
53 see \ref perlmod_latex "below") or write your own customized
54 generator. This should not be too hard if you have some knowledge of
55 Perl and it's the main purpose of including the Perl Module backend in
56 doxygen. See \ref doxydocs_format "below" for details on how
59 <-- want to use \LaTeX but not possible in headings -->
60 \section perlmod_latex Using the LaTeX generator.
62 <p>The Perl Module-based \LaTeX generator is pretty experimental and
63 incomplete at the moment, but you could find it useful nevertheless.
64 It can generate documentation for functions, typedefs and variables
65 within files and classes and can be customized quite a lot by
66 redefining \TeX macros. However, there is still no documentation on
69 <p>Setting the \ref cfg_perlmod_latex "PERLMOD_LATEX" tag to \c YES in the
70 \c Doxyfile enables the creation of some additional files in the `perlmod/`
71 subdirectory of your output directory. These files contain the Perl
72 scripts and \LaTeX code necessary to generate PDF and DVI output from
73 the Perl Module output, using `pdflatex` and `latex` respectively. Rules
74 to automate the use of these files are also added to
75 `doxyrules.make` and the `Makefile`.
77 <p>The additional generated files are the following:
81 <li>`doxylatex.pl`: This Perl script uses `DoxyDocs.pm` and
82 DoxyModel.pm to generate `doxydocs.tex`, a \TeX file containing
83 the documentation in a format that can be accessed by \LaTeX code. This
84 file is not directly LaTeXable.
86 <li>`doxyformat.tex`: This file contains the \LaTeX code that
87 transforms the documentation from doxydocs.tex into \LaTeX text
88 suitable to be \LaTeX'ed and presented to the user.
90 <li>`doxylatex-template.pl`: This Perl script uses `DoxyModel.pm`
91 to generate `doxytemplate.tex`, a \TeX file defining default
92 values for some macros. doxytemplate.tex is included by
93 doxyformat.tex to avoid the need of explicitly defining some macros.
95 <li>`doxylatex.tex`: This is a very simple \LaTeX document that
96 loads some packages and includes doxyformat.tex and doxydocs.tex. This
97 document is \LaTeX'ed to produce the PDF and DVI documentation by the
98 rules added to `doxyrules.make`.
102 \subsection pm_pdf_gen Creation of PDF and DVI output
104 <p>To try this you need to have installed `latex`, `pdflatex` and the
105 packages used by `doxylatex.tex`.
109 <li>Update your `Doxyfile` to the latest version using:
111 <pre>doxygen -u Doxyfile</pre>
113 <li>Set both \ref cfg_generate_perlmod "GENERATE_PERLMOD" and
114 \ref cfg_perlmod_latex "PERLMOD_LATEX" tags to
115 \c YES in your Doxyfile.
117 <li>Run doxygen on your Doxyfile:
119 <pre>doxygen Doxyfile</pre>
121 <li>A `perlmod/` subdirectory should have appeared in your output
122 directory. Enter the `perlmod/` subdirectory and run:
126 <p>This should generate a `doxylatex.pdf` with the documentation
133 <p>This should generate a `doxylatex.dvi` with the documentation
138 \section doxydocs_format Documentation format.
140 <p>The Perl Module documentation generated by doxygen is stored in
141 `DoxyDocs.pm`. This is a very simple Perl module that contains
142 only two statements: an assignment to the variable `$doxydocs` and
143 the customary `1;` statement which usually ends Perl modules.
144 The documentation is stored in the variable `$doxydocs`, which
145 can then be accessed by a Perl script using `DoxyDocs.pm`.
147 <p>`$doxydocs` contains a tree-like structure composed of three
148 types of nodes: strings, hashes and lists.
152 <li>`Strings`: These are normal Perl strings. They can be of
153 any length can contain any character. Their semantics depends on
154 their location within the tree. This type of node has no children.
156 <li>`Hashes`: These are references to anonymous Perl hashes. A
157 hash can have multiple fields, each with a different key. The value
158 of a hash field can be a string, a hash or a list, and its semantics
159 depends on the key of the hash field and the location of the hash
160 within the tree. The values of the hash fields are the children of
163 <li>`Lists`: These are references to anonymous Perl lists. A
164 list has an undefined number of elements, which are the children of
165 the node. Each element has the same type (string, hash or list) and
166 the same semantics, depending on the location of the list within the
171 <p>As you can see, the documentation contained in `$doxydocs`
172 does not present any special impediment to be processed by a simple
175 To be able to generate meaningful output using the
176 documentation contained in `$doxydocs` you'll probably need to
177 know the semantics of the nodes of the documentation tree, which we
178 present in \ref perlmod_tree "this page".
181 \section doxymodel_format Data structure
183 <p>You might be interested in processing the documentation contained
184 in `DoxyDocs.pm` without needing to take into account the
185 semantics of each node of the documentation tree. For this purpose,
186 doxygen generates a `DoxyModel.pm` file which contains a data
187 structure describing the type and children of each node in the
190 <p>The rest of this section is to be written yet, but in the meantime
191 you can look at the Perl scripts generated by doxygen (such as
192 `doxylatex.pl` or `doxytemplate-latex.pl`) to get an idea on
193 how to use `DoxyModel.pm`.
197 Go to the <a href="perlmod_tree.html">next</a> section or return to the
198 <a href="index.html">index</a>.