--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Orb/Doxygen/doc/perlmod.doc Thu Jan 21 17:29:01 2010 +0000
@@ -0,0 +1,193 @@
+/*! \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>.
+
+*/