|
1 /*! \page perlmod Perl Module output format documentation |
|
2 |
|
3 \addindex perlmod |
|
4 |
|
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 |
|
12 use. |
|
13 |
|
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. |
|
19 |
|
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. |
|
23 |
|
24 \section using_perlmod_fmt Using the Perl Module output format. |
|
25 |
|
26 <p>When the <b>GENERATE_PERLMOD</b> tag is enabled in the Doxyfile, |
|
27 running Doxygen generates a number of files in the <b>perlmod/</b> |
|
28 subdirectory of your output directory. These files are the following: |
|
29 |
|
30 <ul> |
|
31 |
|
32 <li><b>DoxyDocs.pm</b>. This is the Perl module that actually |
|
33 contains the documentation, in the Perl Module format described |
|
34 \ref doxydocs_format "below". |
|
35 |
|
36 <li><b>DoxyModel.pm</b>. This Perl module describes the structure of |
|
37 <b>DoxyDocs.pm</b>, independently of the actual documentation. See |
|
38 \ref doxymodel_format "below" for details. |
|
39 |
|
40 <li><b>doxyrules.make</b>. 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. |
|
44 |
|
45 <li><b>Makefile</b>. This is a simple Makefile including |
|
46 <b>doxyrules.make</b>. |
|
47 |
|
48 </ul> |
|
49 |
|
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 |
|
57 to do this. |
|
58 |
|
59 \section perlmod_latex Using the Perl Module-based LaTeX generator. |
|
60 |
|
61 <p>The Perl Module-based LaTeX generator is pretty experimental and |
|
62 incomplete at the moment, but you could find it useful nevertheless. |
|
63 It can generate documentation for functions, typedefs and variables |
|
64 within files and classes and can be customized quite a lot by |
|
65 redefining TeX macros. However, there is still no documentation on |
|
66 how to do this. |
|
67 |
|
68 <p>Setting the <b>PERLMOD_LATEX</b> tag to <b>YES</b> in the Doxyfile |
|
69 enables the creation of some additional files in the <b>perlmod/</b> |
|
70 subdirectory of your output directory. These files contain the Perl |
|
71 scripts and LaTeX code necessary to generate PDF and DVI output from |
|
72 the Perl Module output, using PDFLaTeX and LaTeX respectively. Rules |
|
73 to automate the use of these files are also added to |
|
74 <b>doxyrules.make</b> and the <b>Makefile</b>. |
|
75 |
|
76 <p>The additional generated files are the following: |
|
77 |
|
78 <ul> |
|
79 |
|
80 <li><b>doxylatex.pl</b>. This Perl script uses DoxyDocs.pm and |
|
81 DoxyModel.pm to generate <b>doxydocs.tex</b>, a TeX file containing |
|
82 the documentation in a format that can be accessed by LaTeX code. This |
|
83 file is not directly LaTeXable. |
|
84 |
|
85 <li><b>doxyformat.tex</b>. This file contains the LaTeX code that |
|
86 transforms the documentation from doxydocs.tex into LaTeX text |
|
87 suitable to be LaTeX'ed and presented to the user. |
|
88 |
|
89 <li><b>doxylatex-template.pl</b>. This Perl script uses DoxyModel.pm |
|
90 to generate <b>doxytemplate.tex</b>, a TeX file defining default |
|
91 values for some macros. doxytemplate.tex is included by |
|
92 doxyformat.tex to avoid the need of explicitly defining some macros. |
|
93 |
|
94 <li><b>doxylatex.tex</b>. This is a very simple LaTeX document that |
|
95 loads some packages and includes doxyformat.tex and doxydocs.tex. This |
|
96 document is LaTeX'ed to produce the PDF and DVI documentation by the |
|
97 rules added to <b>doxyrules.make</b>. |
|
98 |
|
99 </ul> |
|
100 |
|
101 \subsection pm_pdf_gen Simple creation of PDF and DVI output using the Perl Module-based LaTeX generator. |
|
102 |
|
103 <p>To try this you need to have installed LaTeX, PDFLaTeX and the |
|
104 packages used by <b>doxylatex.tex</b>. |
|
105 |
|
106 <ol> |
|
107 |
|
108 <li>Update your Doxyfile to the latest version using: |
|
109 |
|
110 <pre>doxygen -u Doxyfile</pre> |
|
111 |
|
112 <li>Set both <b>GENERATE_PERLMOD</b> and <b>PERLMOD_LATEX</b> tags to |
|
113 YES in your Doxyfile. |
|
114 |
|
115 <li>Run Doxygen on your Doxyfile: |
|
116 |
|
117 <pre>doxygen Doxyfile</pre> |
|
118 |
|
119 <li>A <b>perlmod/</b> subdirectory should have appeared in your output |
|
120 directory. Enter the <b>perlmod/</b> subdirectory and run: |
|
121 |
|
122 <pre>make pdf</pre> |
|
123 |
|
124 <p>This should generate a <b>doxylatex.pdf</b> with the documentation |
|
125 in PDF format. |
|
126 |
|
127 <li>Run: |
|
128 |
|
129 <pre>make dvi</pre> |
|
130 |
|
131 <p>This should generate a <b>doxylatex.dvi</b> with the documentation |
|
132 in DVI format. |
|
133 |
|
134 </ol> |
|
135 |
|
136 \section doxydocs_format Perl Module documentation format. |
|
137 |
|
138 <p>The Perl Module documentation generated by Doxygen is stored in |
|
139 <b>DoxyDocs.pm</b>. This is a very simple Perl module that contains |
|
140 only two statements: an assigment to the variable <b>$doxydocs</b> and |
|
141 the customary <b>1;</b> statement which usually ends Perl modules. |
|
142 The documentation is stored in the variable <b>$doxydocs</b>, which |
|
143 can then be accessed by a Perl script using <b>DoxyDocs.pm</b>. |
|
144 |
|
145 <p><b>$doxydocs</b> contains a tree-like structure composed of three |
|
146 types of nodes: strings, hashes and lists. |
|
147 |
|
148 <ul> |
|
149 |
|
150 <li><b>Strings</b>. These are normal Perl strings. They can be of |
|
151 any length can contain any character. Their semantics depends on |
|
152 their location within the tree. This type of node has no children. |
|
153 |
|
154 <li><b>Hashes</b>. These are references to anonymous Perl hashes. A |
|
155 hash can have multiple fields, each with a different key. The value |
|
156 of a hash field can be a string, a hash or a list, and its semantics |
|
157 depends on the key of the hash field and the location of the hash |
|
158 within the tree. The values of the hash fields are the children of |
|
159 the node. |
|
160 |
|
161 <li><b>Lists</b>. These are references to anonymous Perl lists. A |
|
162 list has an undefined number of elements, which are the children of |
|
163 the node. Each element has the same type (string, hash or list) and |
|
164 the same semantics, depending on the location of the list within the |
|
165 tree. |
|
166 |
|
167 </ul> |
|
168 |
|
169 <p>As you can see, the documentation contained in <b>$doxydocs</b> |
|
170 does not present any special impediment to be processed by a simple |
|
171 Perl script. |
|
172 <!-- |
|
173 To be able to generate meaningful output using the |
|
174 documentation contained in <b>$doxydocs</b> you'll probably need to |
|
175 know the semantics of the nodes of the documentation tree, which we |
|
176 present in \ref perlmod_tree "this page". |
|
177 --> |
|
178 |
|
179 \section doxymodel_format Data structure describing the Perl Module documentation tree. |
|
180 |
|
181 <p>You might be interested in processing the documentation contained |
|
182 in <b>DoxyDocs.pm</b> without needing to take into account the |
|
183 semantics of each node of the documentation tree. For this purpose, |
|
184 Doxygen generates a <b>DoxyModel.pm</b> file which contains a data |
|
185 structure describing the type and children of each node in the |
|
186 documentation tree. |
|
187 |
|
188 <p>The rest of this section is to be written yet, but in the meantime |
|
189 you can look at the Perl scripts generated by Doxygen (such as |
|
190 <b>doxylatex.pl</b> or <b>doxytemplate-latex.pl</b>) to get an idea on |
|
191 how to use <b>DoxyModel.pm</b>. |
|
192 |
|
193 */ |