doc/perlmod.doc

   1 /*! \page perlmod Perl Module Output
   2
   3 \addindex perlmod
   4
   5 <p>Since version 1.2.18, Doxygen can generate a new output format we
   6 have called the &quot;Perl Module output format&quot;.  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 Usage
  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 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 Creation of PDF and DVI output
 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 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 assignment 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
 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 */