Release-1.2.18-20021030

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 &quot;Perl Module output format&quot;.  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>.
+
+*/