1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.12"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Doxygen: Perl Module Output</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen_manual.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Doxygen
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.12 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('perlmod.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Perl Module Output </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a name="aperlmod"></a></p>
<p>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.</p>
<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 <img class="formulaInl" alt="$\mbox{\LaTeX}$" src="form_0.png"/> generator.</p>
<p>Please report any bugs or problems you find in the Perl Module backend or the Perl Module-based <img class="formulaInl" alt="$\mbox{\LaTeX}$" src="form_0.png"/> generator to the doxygen-develop mailing list. Suggestions are welcome as well.</p>
<h1><a class="anchor" id="using_perlmod_fmt"></a>
Usage</h1>
<p>When the <a class="el" href="config.html#cfg_generate_perlmod">GENERATE_PERLMOD</a> tag is enabled in the Doxyfile, running doxygen generates a number of files in the <code>perlmod/</code> subdirectory of your output directory. These files are the following:</p>
<ul>
<li>
<p class="startli"><code>DoxyDocs.pm</code>: This is the Perl module that actually contains the documentation, in the Perl Module format described <a class="el" href="perlmod.html#doxydocs_format">below</a>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>DoxyModel.pm</code>: This Perl module describes the structure of <code>DoxyDocs.pm</code>, independently of the actual documentation. See <a class="el" href="perlmod.html#doxymodel_format">below</a> for details.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>doxyrules.make</code>: 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.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>Makefile</code>: This is a simple Makefile including <code>doxyrules.make</code>.</p>
<p class="endli"></p>
</li>
</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 <img class="formulaInl" alt="$\mbox{\LaTeX}$" src="form_0.png"/> generator, see <a class="el" href="perlmod.html#perlmod_latex">below</a>) 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 <a class="el" href="perlmod.html#doxydocs_format">below</a> for details on how to do this.</p>
<p><– want to use <img class="formulaInl" alt="$\mbox{\LaTeX}$" src="form_0.png"/> but not possible in headings –> </p>
<h1><a class="anchor" id="perlmod_latex"></a>
Using the LaTeX generator.</h1>
<p>The Perl Module-based <img class="formulaInl" alt="$\mbox{\LaTeX}$" src="form_0.png"/> 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 <img class="formulaInl" alt="$\mbox{\TeX}$" src="form_12.png"/> macros. However, there is still no documentation on how to do this.</p>
<p>Setting the <a class="el" href="config.html#cfg_perlmod_latex">PERLMOD_LATEX</a> tag to <code>YES</code> in the <code>Doxyfile</code> enables the creation of some additional files in the <code>perlmod/</code> subdirectory of your output directory. These files contain the Perl scripts and <img class="formulaInl" alt="$\mbox{\LaTeX}$" src="form_0.png"/> code necessary to generate PDF and DVI output from the Perl Module output, using <code>pdflatex</code> and <code>latex</code> respectively. Rules to automate the use of these files are also added to <code>doxyrules.make</code> and the <code>Makefile</code>.</p>
<p>The additional generated files are the following:</p>
<ul>
<li>
<p class="startli"><code>doxylatex.pl</code>: This Perl script uses <code>DoxyDocs.pm</code> and DoxyModel.pm to generate <code>doxydocs.tex</code>, a <img class="formulaInl" alt="$\mbox{\TeX}$" src="form_12.png"/> file containing the documentation in a format that can be accessed by <img class="formulaInl" alt="$\mbox{\LaTeX}$" src="form_0.png"/> code. This file is not directly LaTeXable.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>doxyformat.tex</code>: This file contains the <img class="formulaInl" alt="$\mbox{\LaTeX}$" src="form_0.png"/> code that transforms the documentation from doxydocs.tex into <img class="formulaInl" alt="$\mbox{\LaTeX}$" src="form_0.png"/> text suitable to be <img class="formulaInl" alt="$\mbox{\LaTeX}$" src="form_0.png"/>'ed and presented to the user.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>doxylatex-template.pl</code>: This Perl script uses <code>DoxyModel.pm</code> to generate <code>doxytemplate.tex</code>, a <img class="formulaInl" alt="$\mbox{\TeX}$" src="form_12.png"/> file defining default values for some macros. doxytemplate.tex is included by doxyformat.tex to avoid the need of explicitly defining some macros.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>doxylatex.tex</code>: This is a very simple <img class="formulaInl" alt="$\mbox{\LaTeX}$" src="form_0.png"/> document that loads some packages and includes doxyformat.tex and doxydocs.tex. This document is <img class="formulaInl" alt="$\mbox{\LaTeX}$" src="form_0.png"/>'ed to produce the PDF and DVI documentation by the rules added to <code>doxyrules.make</code>.</p>
<p class="endli"></p>
</li>
</ul>
<h2><a class="anchor" id="pm_pdf_gen"></a>
Creation of PDF and DVI output</h2>
<p>To try this you need to have installed <code>latex</code>, <code>pdflatex</code> and the packages used by <code>doxylatex.tex</code>.</p>
<ol>
<li>
<p class="startli">Update your <code>Doxyfile</code> to the latest version using:</p>
<pre>doxygen -u Doxyfile</pre><p class="endli"></p>
</li>
<li>
<p class="startli">Set both <a class="el" href="config.html#cfg_generate_perlmod">GENERATE_PERLMOD</a> and <a class="el" href="config.html#cfg_perlmod_latex">PERLMOD_LATEX</a> tags to <code>YES</code> in your Doxyfile.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">Run doxygen on your Doxyfile:</p>
<pre>doxygen Doxyfile</pre><p class="endli"></p>
</li>
<li>
<p class="startli">A <code>perlmod/</code> subdirectory should have appeared in your output directory. Enter the <code>perlmod/</code> subdirectory and run:</p>
<pre>make pdf</pre><p></p>
<p>This should generate a <code>doxylatex.pdf</code> with the documentation in PDF format.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">Run:</p>
<pre>make dvi</pre><p></p>
<p>This should generate a <code>doxylatex.dvi</code> with the documentation in DVI format.</p>
<p class="endli"></p>
</li>
</ol>
<h1><a class="anchor" id="doxydocs_format"></a>
Documentation format.</h1>
<p>The Perl Module documentation generated by doxygen is stored in <code>DoxyDocs.pm</code>. This is a very simple Perl module that contains only two statements: an assignment to the variable <code>$doxydocs</code> and the customary <code>1;</code> statement which usually ends Perl modules. The documentation is stored in the variable <code>$doxydocs</code>, which can then be accessed by a Perl script using <code>DoxyDocs.pm</code>.</p>
<p><code>$doxydocs</code> contains a tree-like structure composed of three types of nodes: strings, hashes and lists.</p>
<ul>
<li>
<p class="startli"><code>Strings</code>: 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.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>Hashes</code>: 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.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><code>Lists</code>: 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.</p>
<p class="endli"></p>
</li>
</ul>
<p>As you can see, the documentation contained in <code>$doxydocs</code> does not present any special impediment to be processed by a simple Perl script.</p>
<h1><a class="anchor" id="doxymodel_format"></a>
Data structure</h1>
<p>You might be interested in processing the documentation contained in <code>DoxyDocs.pm</code> without needing to take into account the semantics of each node of the documentation tree. For this purpose, doxygen generates a <code>DoxyModel.pm</code> file which contains a data structure describing the type and children of each node in the documentation tree.</p>
<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 <code>doxylatex.pl</code> or <code>doxytemplate-latex.pl</code>) to get an idea on how to use <code>DoxyModel.pm</code>.</p>
<p>
Go to the <a href="perlmod_tree.html">next</a> section or return to the
<a href="index.html">index</a>.
</p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.12 </li>
</ul>
</div>
</body>
</html>
|
