Writing a Converter, Methods

Introduction to Converter Methods

This Tutorial describes the methods that a New Converter

Convert()

The Converter::Convert() method is called by Converter::walk() to process all Converter classes:

• parserData - representation of a file
• parserInclude - representation of include statements
• parserDefine - representation of define statements
• parserFunction - representation of functions
• parserGlobal - representation of global variables
• parserClass - representation of a class
• parserVar - representation of class variables
• parserMethod - representation of class methods
• parserPage - representation of old Package Pages (deprecated)
• parserTutorial - representation of tutorials (like what you are reading now)

Data is passed to the Converter organized by file, procedural elements first followed by class elements, unless Converter::$sort_absolutely_everything is set to true. Then data is passed organized by package, with all files and procedural elements first, followed by all class elements. The PDFdefaultConverter uses $sort_absolutely_everything = true, and HTML converters use it set to false

returnSee()

This method takes a abstractLink class descendant and converts it to an output-format compatible link to an element's documentation. HTML converters convert the link to an <a href=""> tag, the XML converter changes it to a <link linkend=""> tag, etc. This function is also responsible for distinguishing between sections of documentation. All information needed to distinguish between elements is included in the data members of a link class, it is up to the returnSee() method to translate that into a unique string identifier. A good strategy is to write a function that takes a link class and returns a unique identifier as in XMLDocBookConverter::getId(), and then reference this function to grab identification strings for defining anchors in the generated output.

returnLink()

This method takes a URL and converts it to an external link to that URL in the appropriate output format.

Output()

This method is called at the end of the walk() method. It may be used to generate output or do any necessary cleanup. Nothing is required of Output, and it may do nothing as it does in the HTML converters, which write output continuously as converting.

Convert_RIC()

This method is called to format the contents of README, INSTALL, CHANGELOG, NEWS, and FAQ files grabbed from the base parse directory. This function allows standard distribution files to be embedded in generated documentation. A Converter should format these files in a monospace font, if possible.

ConvertErrorLog()

This method is called at the end of parsing to convert the error log into output for viewing later by the developer. Error output is very useful for finding mistakes in documentation comments. A simple solution is to copy the HTMLframesConverter::ConvertErrorLog() function and the errors.tpl template file to the new converter. The error log should not be embedded in generated output, as no end-user wants to see that information.

formatIndex()

This method is called before processing any elements, and is not required to do anything. The intent is to allow processing of a global element index to occur in a separate method, which logically separates activities performed by the Converter. See the HTMLframesConverter::formatIndex() method for details on one possible implementation

formatPkgIndex()

Like formatIndex(), this method is called before processing any elements, and is not required to do anything. The intent is to allow processing of a package-level index to occur in a separate method, which logically separates activities performed by the Converter. See the HTMLframesConverter::formatPkgIndex() method for details on one possible implementation

formatLeftIndex()

Like formatIndex(), this oddly-named method is called before processing any elements, and is not required to do anything. The name comes from the original JavaDoc design of putting an index in the lower left frame of output. The indexes needed by this function are automatically generated based on the value of Converter::$leftindex. These indexes are arrays of links organized by package and subpackage. Left indexes can be generated for files (procedural pages), functions, classes, constants (define statements), and global variables.

formatTutorialTOC()

This method is used to format the automatically generated table of contents from an inline {@toc} in a tutorial. The data structure passed is an array generated by parserTocInlineTag::Convert() that contains each entry. All that formatTutorialTOC needs to do is structure the inherent hierarchy of the original DocBook tutorial source according to the requirements of the output format. This is remarkably simple, and can often be implemented simply by passing the entire array to a template engine, as HTMLframesConverter::formatTutorialTOC() does.

endPage()

endClass()

unmangle()

getFunctionLink()

getClassLink()

getDefineLink()

getGlobalLink()

getMethodLink()

getRootTree()

getVarLink()

checkState()

getState()

type_adjust()

postProcess()

getPPageId()

getSortedClasstreeFromClass()

hasTutorial()

getTutorialTree()

vardump_tree()