<refentry id="{@id}">
 <refnamediv>
  <refname>Converter Manual</refname>
  <refpurpose>Learn how to use and extend a Converter</refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <author>
   Gregory Beaver
   <authorblurb>
    {@link mailto:cellog@sourceforge.com cellog@sourceforge.com}
   </authorblurb>
  </author>
 </refsynopsisdiv>
 <refsect1 id="{@id intro}">
  <title>{@link http://pear.php.net/package/PhpDocumentor phpDocumentor} Converters Documentation</title>
  <para>Detailed Documentation of the tag specification is available at {@tutorial phpDocumentor/tags.pkg}.  Detailed information on phpDocumentor and a tutorial on basic usage is at: {@tutorial phpDocumentor/phpDocumentor.howto.pkg}</para>
  <para>If you are wondering how to extend the capabilities of phpDocumentor's output, this is the documentation you need.  This documentation does not discuss how to document your code or project, and only deals with the specific requirements of extending phpDocumentor.</para>
 </refsect1>
 <refsect1 id="{@id internals}">
  <title>Internals: how phpDocumentor takes source code and generates documentation</title>
  <para>phpDocumentor is divided into three logical components: {@link Parser}, {@link IntermediateParser} and {@link Converter}.  These three divisions communicate through special method interfaces.</para>
  <refsect2 id="{@id parser}">
   <title>Parser internals</title>
   <para>The Parser component does the work of reading the actual files, both source code and tutorial/manual files.  For a detailed discussion of how to write a tutorial, see {@tutorial phpDocumentor/tutorials.pkg}, or read the source files for phpDocumentor's manual in the tutorials/ subdirectory.  The Parser encapsulates input into abstract classes, all of which are defined in seven files:
    <itemizedlist>
     <listitem><para>{@link phpDocumentor#DescHTML.inc}</para></listitem>
     <listitem><para>{@link phpDocumentor#DocBlockTags.inc}</para></listitem>
     <listitem><para>{@link phpDocumentor#InlineTags.inc}</para></listitem>
     <listitem><para>{@link phpDocumentor#ParserData.inc}</para></listitem>
     <listitem><para>{@link phpDocumentor#ParserElements.inc}</para></listitem>
     <listitem><para>{@link phpDocumentor#ParserDocBlock.inc}</para></listitem>
     <listitem><para>{@link phpDocumentor#PackagePageElements.inc}</para></listitem>
    </itemizedlist>
    The abstract classes are then passed to the Intermediate Parser.
   </para>
  </refsect2>
  <refsect2 id="{@id intermediateparser}">
   <para>The {@link IntermediateParser} class organizes and processes abstract data passed in with the assistance of the {@link ProceduralPages} and {@link Classes} classes.  All data is sorted alphabetically and then passed to the converters specified on the command-line one by one.  Traditionally, the next step would be to generate output by passing the abstract data to a template engine.  phpDocumentor has one more layer of separation to accomodate different output formats called &quot;Converters.&quot;</para>
  </refsect2>
  <refsect2 id="{@id converters}">
   <para>What is a Converter?  To understand this, one must first understand the problem that Converters solve.  Documentation is not always best viewed as a web page.  Sometimes a user may want to print it out, or view it in XML with an interface program that can search or perform other advanced functions.  Printing html does not work very well, and may look very different on different user's screens.  To solve this problem, we need an interface between the parser and the template engine, hence the Converter.</para>
   <para>On an even more basic level, the linking performed by phpDocumentor requires that the program pass over the data at least twice to set up relationships and create the @see, @tutorial, {@}tutorial} and {@}link} hyperlinks that make it such an effective tool.  In earlier versions of phpDocumentor, the parser passed over the data twice, with significant redundancy and slow parsing times.  In addition, the linking pass had to be first, and the order of parsing was important.  In other words, if file A contains class B extends foo, and file B contains class foo, if file A is parsed before file B, no inheritance occurs between the classes (you can try this with phpDocumentor 0.4.2a and earlier, it breaks the parser).  The Converter works with temporary data structures (all defined in ParserData.inc, ParserElements.inc, and ParserDocBlock.inc if you want a peek), and allows the linking pass to occur in-memory after parsing, with a significant speedup (almost twice as fast as earlier versions).</para>
  </refsect2>
 </refsect1>
 <refsect1 id="{@id templates}">
  <title>Adding a template</title>
  <para>In most cases, it is possible to leverage the existing code to create spectacular output simply by writing a new set of templates for one of the existing Converters.  To learn how to write templates for each specific converter, choose from the list below:
   <itemizedlist>
    <listitem><para>{@tutorial Converters/HTMLframes/HTMLframesConverter.cls}</para></listitem>
    <listitem><para>{@tutorial Converters/HTMLSmarty/HTMLSmartyConverter.cls}</para></listitem>
    <listitem><para>{@tutorial Converters/PDFdefault/PDFdefaultConverter.cls}</para></listitem>
    <listitem><para>{@tutorial Converters/XMLDocBook/XMLDocBookConverter.cls}</para></listitem>
    <listitem><para>{@tutorial Converters/CHMdefault/CHMdefaultConverter.cls}</para></listitem>
   </itemizedlist>
  </para>
 </refsect1>
 <refsect1 id="{@id extending}">
  <title>Extending an existing Converter by writing your own Converter Class</title>
  <para>If the existing converters work except for a small detail that could be fixed by adding a small patch to the source code of an output converter, then you need to extend a Converter.  There are several straightforward rules that allow you to easily extend a Converter.</para>
  <refsect2 id="{@id rules}">
   <title>Rules for extending a Converter</title>
   <para>First, the extended converter must be defined by a single word that would work as a valid filename.  For an example, if the Converter extends the HTMLframesConverter, and provides search functionality in the generated documentation through the insertion of special php code into the generated files, it might be named &quot;Search.&quot;</para>
   <para>Once a name has been chosen, a subdirectory of the parent converter (HTMLframesConverter is in phpDocumentor/Converters/HTML/frames/) must be created with the same name as the child converter.  So, for our &quot;Search&quot; Converter, the directory phpDocumentor/Converters/HTML/frames/Search/ must be created.  Put your new Converter in a file called <emphasis>&quot;HTMLframes<important>Search</important>Converter.inc&quot;</emphasis>.  Note the insertion of our new Converter's name before the word &quot;Converter&quot; in the filename.</para>
   <para>Next, create a class declaration in the new HTMLframesSearchConverter.inc file as below:</para>
   <para>
    <programlisting role="php">
<![CDATA[
/**
 * HTML output converter.
 *
 * This Converter takes output from the {@}link Parser} and converts it to HTML-ready output for use with {@}link Smarty}.
 * Add any extra documentation about the search capabilities here
 * @package Converters
 * @subpackage HTMLframes
 * @author Your Name <example@example.com>
 */
class HTMLframesSearchConverter extends Converter
{
    /**
     * frames/Search Converter wants elements sorted by type as well as alphabetically
     * @see Converter::$sort_page_contents_by_type
     * @var boolean
     */
    var $sort_page_contents_by_type = true;
    /** @var string */
    var $outputformat = 'HTML';
    /** @var string */
    var $name = 'frames/Search';
]]>
    </programlisting>
   </para>
   <para>Note the var $name is set to the relative subdirectory.  This is very important.  Do not set the name to be &quot;framesSearch&quot;, as the {@link Converter::setTemplateDir()} method uses this variable to set the template directory.</para>
   <para>If the existing templates work fine, and there is some other change needed, set the name to be the same as the parent, and phpDocumentor will use the parent templates.</para>
   <para>After extending the methods the new Search Converter will need, place the templates in a subdirectory named templates/ (as in phpDocumentor/Converters/HTML/frames/Search/templates/), just as they are used in the converters that come with phpDocumentor.</para>
  </refsect2>
  <refsect2 id="{@id using}">
   <title>Using an extended Converter with phpDocumentor</title>
   <para>After all this complexity of setting up the Converter, using it is straightforward.  simply pass <screen>-o HTML:frames/Search:templatename</screen> to phpDocumentor's web interface or commandline!</para>
  </refsect2>
 </refsect1>
 <refsect1 id="{@id newconverter}">
  <title>Writing a Converter for a new output format</title>
  <para>This topic is very large, and a separate manual entry is devoted entirely to this subject, {@tutorial Converters/Converter.cls}</para>
 </refsect1>
</refentry>