diff options
Diffstat (limited to 'doc/perlmod.doc')
| -rw-r--r-- | doc/perlmod.doc | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/doc/perlmod.doc b/doc/perlmod.doc new file mode 100644 index 0000000..becbdf2 --- /dev/null +++ b/doc/perlmod.doc @@ -0,0 +1,190 @@ +/*! \page perlmod Perl Module output format documentation + +\addindex perlmod + +<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>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 LaTeX generator. + +<p>Please report any bugs or problems you find in the Perl Module +backend or the Perl Module-based LaTeX generator to the +doxygen-develop mailing list. Suggestions are welcome as well. + +\section using_perlmod_fmt Using the Perl Module output format. + +<p>When the <b>GENERATE_PERLMOD</b> tag is enabled in the Doxyfile, +running Doxygen generates a number of files in the <b>perlmod/</b> +subdirectory of your output directory. These files are the following: + +<ul> + +<li><b>DoxyDocs.pm</b>. This is the Perl module that actually +contains the documentation, in the Perl Module format described +\ref doxydocs_format "below". + +<li><b>DoxyModel.pm</b>. This Perl module describes the structure of +<b>DoxyDocs.pm</b>, independently of the actual documentation. See +\ref doxymodel_format "below" for details. + +<li><b>doxyrules.make</b>. 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. + +<li><b>Makefile</b>. This is a simple Makefile including +<b>doxyrules.make</b>. + +</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 LaTeX generator, +see \ref perlmod_latex "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 +Doxygen. See \ref doxydocs_format "below" for details on how +to do this. + +\section perlmod_latex Using the Perl Module-based LaTeX generator. + +<p>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. + +<p>Setting the <b>PERLMOD_LATEX</b> tag to <b>YES</b> in the Doxyfile +enables the creation of some additional files in the <b>perlmod/</b> +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 +<b>doxyrules.make</b> and the <b>Makefile</b>. + +<p>The additional generated files are the following: + +<ul> + +<li><b>doxylatex.pl</b>. This Perl script uses DoxyDocs.pm and +DoxyModel.pm to generate <b>doxydocs.tex</b>, a TeX file containing +the documentation in a format that can be accessed by LaTeX code. This +file is not directly LaTeXable. + +<li><b>doxyformat.tex</b>. This file contains the LaTeX code that +transforms the documentation from doxydocs.tex into LaTeX text +suitable to be LaTeX'ed and presented to the user. + +<li><b>doxylatex-template.pl</b>. This Perl script uses DoxyModel.pm +to generate <b>doxytemplate.tex</b>, a TeX file defining default +values for some macros. doxytemplate.tex is included by +doxyformat.tex to avoid the need of explicitly defining some macros. + +<li><b>doxylatex.tex</b>. This is a very simple LaTeX document that +loads some packages and includes doxyformat.tex and doxydocs.tex. This +document is LaTeX'ed to produce the PDF and DVI documentation by the +rules added to <b>doxyrules.make</b>. + +</ul> + +\subsection pm_pdf_gen Simple creation of PDF and DVI output using the Perl Module-based LaTeX generator. + +<p>To try this you need to have installed LaTeX, PDFLaTeX and the +packages used by <b>doxylatex.tex</b>. + +<ol> + +<li>Update your Doxyfile to the latest version using: + +<pre>doxygen -u Doxyfile</pre> + +<li>Set both <b>GENERATE_PERLMOD</b> and <b>PERLMOD_LATEX</b> tags to +YES in your Doxyfile. + +<li>Run Doxygen on your Doxyfile: + +<pre>doxygen Doxyfile</pre> + +<li>A <b>perlmod/</b> subdirectory should have appeared in your output +directory. Enter the <b>perlmod/</b> subdirectory and run: + +<pre>make pdf</pre> + +<p>This should generate a <b>doxylatex.pdf</b> with the documentation +in PDF format. + +<li>Run: + +<pre>make dvi</pre> + +<p>This should generate a <b>doxylatex.dvi</b> with the documentation +in DVI format. + +</ol> + +\section doxydocs_format Perl Module documentation format. + +<p>The Perl Module documentation generated by Doxygen is stored in +<b>DoxyDocs.pm</b>. This is a very simple Perl module that contains +only two statements: an assigment to the variable <b>$doxydocs</b> and +the customary <b>1;</b> statement which usually ends Perl modules. +The documentation is stored in the variable <b>$doxydocs</b>, which +can then be accessed by a Perl script using <b>DoxyDocs.pm</b>. + +<p><b>$doxydocs</b> contains a tree-like structure composed of three +types of nodes: strings, hashes and lists. + +<ul> + +<li><b>Strings</b>. 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. + +<li><b>Hashes</b>. 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. + +<li><b>Lists</b>. 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. + +</ul> + +<p>As you can see, the documentation contained in <b>$doxydocs</b> +does not present any special impediment to be processed by a simple +Perl script. To be able to generate meaningful output using the +documentation contained in <b>$doxydocs</b> you'll probably need to +know the semantics of the nodes of the documentation tree, which we +present in \ref perlmod_tree "this page". + +\section doxymodel_format Data structure describing the Perl Module documentation tree. + +<p>You might be interested in processing the documentation contained +in <b>DoxyDocs.pm</b> without needing to take into account the +semantics of each node of the documentation tree. For this purpose, +Doxygen generates a <b>DoxyModel.pm</b> file which contains a data +structure describing the type and children of each node in the +documentation tree. + +<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 +<b>doxylatex.pl</b> or <b>doxytemplate-latex.pl</b>) to get an idea on +how to use <b>DoxyModel.pm</b>. + +*/ |