Previous Next
inline {@tutorial} Converter Default Template Variables

Writing a New Converter

Overview of how to write a new Converter


Joshua Eichorn Gregory Beaver

Introduction to Converters

This documentation deals only with the advanced programming topic of creating a new output converter. To learn how to use phpDocumentor, read the phpDocumentor Guide to Creating Fantastic Documentation. To learn how to extend an existing Converter, read Converter Manual

Basic Concepts

Abstract Parsing Data

Source Code Elements

A Converter's job is to take abstract data from parsing and create documentation. What is the abstract data? phpDocumentor is capable of documenting tutorials, and a php file and its re-usable or structurally important contents. In other words, phpDocumentor can document:

  • A XML DocBook-based tutorial (see phpDocumentor Tutorials)

  • Procedural Page (PHP source file)

  • Include Statements

  • Define Statements

  • Global Variables

  • Functions

  • Classes

  • Class Variables

  • Class Methods

phpDocumentor represents these PHP elements using classes:

This relationship between the source code and abstract data is quite clear, and very simple. The data members of each abstract representation correspond with the information needed to display the documentation. All PHP elements contain a DocBlock, and this is represented by a class as well, parserDocBlock. The elements of a DocBlock are simple:

  • Short Description, containing any number of inline tags

  • Long Description, containing any number of inline tags

  • Tags, some containing any number of inline tags in their general description field

phpDocumentor represents these elements using classes as well:

HTML-specific issues

There are some other issues that Converters solve. In HTML, a link is represented by an <a> tag, but in the PDF Converter, it is represented by a <c:ilink> tag. How can we handle both cases? Through another abstract class, the abstractLink and its descendants:

Note the absence of an "includeLink" class - this is intentional, as only re-usable elements need to be linked. An include statement is always attached to the file that it is in, and cannot be anywhere else.

These abstract linking classes contain the information necessary to differentiate between the location of any of the element's documentation. They are only used to allow linking to documentation, and not to source code. A link is then converted to the appropriate text representation for the output format by Converter::returnSee() (a href=link for html, c:ilink:link for pdf, link linkend=link in xml:docbook, and so on).

The other issues solved by a converter involves html in a DocBlock. To allow better documentation, html is allowed in DocBlocks to format the output. Unfortunately, this complicates output in other formats. To solve this issue, phpDocumentor also parses out all allowed HTML (see phpDocumentor Tutorial for more detailed information) into abstract structures:

  • <b> -- emphasize/bold text

  • <br> -- hard line break, may be ignored by some converters

  • <code> -- Use this to surround php code, some converters will highlight it

  • <i> -- italicize/mark as important

  • <li> -- list item

  • <ol> -- ordered list

  • <p> -- If used to enclose all paragraphs, otherwise it will be considered text

  • <pre> -- Preserve line breaks and spacing, and assume all tags are text (like XML's CDATA)

  • <ul> -- unordered list

is mapped to classes: <p> is represented by partitioning text into an array, where each array item is a new paragraph. (as in parserDocBlock::$processed_desc)

With these simple structures and a few methods to handle them, the process of writing a new converter is straightforward.

Separation of data from display formatting

phpDocumentor has been designed to keep as much formatting out of the source code as possible. For many converters, there need be no new code written to support the conversion, as all output-specific information can be placed in template files. However, the complexity of generating class trees does require the insertion of some code into the source, so at the bare minimum, the getRootTree() method must be overridden.

Methods that must be overridden

Creating a new converter can be challenging, but should not be too complicated. You need to override one data structure, Converter::$leftindex, to tell the Converter which of the individual element indexes your Converter will use. You will also need to override a few methods for the Converter to work. The most important relate to linking and output.

A Converter must override these core methods:

A Converter may optionally implement these abstract methods:

The following methods may need to be overridden for proper functionality, and are for advanced situations.

Converter methods an extended converter should use

  • getSortedClassTreeFromClass() -- generating class trees by package

  • hasTutorial() -- use this to retrieve a tutorial, or determine if it exists

  • getTutorialTree() -- use this to retrieve a hierarchical tree of tutorials that can be used to generate a table of contents for all tutorials

  • vardump_tree() -- use this to assist in debugging large tree structures of tutorials

Previous Next
inline {@tutorial} Converter Default Template Variables

Documentation generated on Mon, 05 Dec 2011 21:01:59 -0600 by phpDocumentor 1.4.4