Class: XMLDocBookConverter

Source Location: /PEAR/PhpDocumentor/phpDocumentor/Converters/XML/DocBook/XMLDocBookConverter.inc

Class XMLDocBookConverter

Class Overview

XML DocBook converter.

This Converter takes output from the Parser and converts it to DocBook output

Located in /PEAR/PhpDocumentor/phpDocumentor/Converters/XML/DocBook/XMLDocBookConverter.inc [line 43]

Converter
   |
   --XMLDocBookConverter

Author(s):

Greg Beaver <cellog@php.net>

API Tags:

See:

parserDocBlock, parserInclude, parserPage, parserClass, parserDefine, parserFunction, parserMethod, parserVar

Information Tags:

Version:	$Id: XMLDocBookConverter.inc,v 1.3 2007/04/19 20:20:57 ashnazg Exp $
Todo:	templates
Todo:	indexes for other DocBook converters not based on peardoc
Since:	1.0

Properties

Methods

[ Top ]

Inherited Properties, Constants, and Methods

Inherited Properties

Inherited Methods

Inherited Constants

Inherited From Converter

Converter::$all_packages

Converter::$classes

Converter::$class_contents

Converter::$class_elements

Converter::$curfile

Converter::$curpage

Converter::$define_elements

Converter::$elements

Converter::$function_elements

Converter::$global_elements

Converter::$highlightingSource

Converter::$package

Converter::$packagecategories

Converter::$package_elements

Converter::$package_output

Converter::$package_parents

Converter::$page_contents

Converter::$page_elements

Converter::$parseprivate

Converter::$pkg_elements

Converter::$processSpecialRoots

Converter::$quietmode

Converter::$smarty_dir

Converter::$sort_absolutely_everything

Converter::$sourcePaths

Converter::$subpackage

Converter::$targetDir

Converter::$templateDir

Converter::$templateName

Converter::$title

Converter::$todoList

Inherited From Converter

Converter::Converter()

Initialize Converter data structures

Converter::AttrToString()

Convert the attribute of a Tutorial docbook tag's attribute list

Converter::Bolden()

Used to convert the contents of <b> in a docblock

Converter::Br()

Used to convert <br> in a docblock

Converter::checkState()

Compare parserStringWithInlineTags::Convert() cache state to $state

Converter::cleanup()

Finish up parsing/cleanup directories

Converter::Convert()

Convert all elements to output format

Converter::convertClass()

Default Class Handler

Converter::convertConst()

Converts class constants for template output.

Converter::convertDefine()

Converts defines for template output

Converter::ConvertErrorLog()

Convert the phpDocumentor parsing/conversion error log

Converter::convertFunction()

Converts function for template output

Converter::convertGlobal()

Converts global variables for template output

Converter::convertInclude()

Converts includes for template output

Converter::convertMethod()

Converts method for template output

Converter::convertPage()

Default Page Handler

Converter::ConvertTitle()

Convert the title of a Tutorial docbook tag section

Converter::ConvertTodoList()

Convert the list of all @todo tags

Converter::convertTutorial()

Default Tutorial Handler

Converter::convertVar()

Converts class variables for template output.

Converter::Convert_RIC()

Convert README/INSTALL/CHANGELOG file contents to output format

Converter::copyFile()

Copies a file from the template directory to the target directory

Converter::createParentDir()

Recursively creates all subdirectories that don't exist in the $dir path

Converter::EncloseList()

Used to convert the contents of <ol> or <ul> in a docblock

Converter::EncloseParagraph()

Used to enclose a paragraph in a docblock

Converter::endClass()

Called by walk() while converting, when the last class element has been parsed.

Converter::endPage()

Called by walk() while converting, when the last procedural page element has been parsed.

Converter::exampleProgramExample()

Used to convert the {@example} inline tag in a docblock.

Converter::flushHighlightCache()

Return the close text for the current token

Converter::formatIndex()

Called by walk() while converting.

Converter::formatLeftIndex()

Called by walk() while converting.

Converter::formatPkgIndex()

Called by walk() while converting.

Converter::formatTutorialTOC()

Creates a table of contents for a {@toc} inline tag in a tutorial

Converter::generateChildClassList()

returns a list of child classes

Converter::generateFormattedClassTree()

returns an array containing the class inheritance tree from the root object to the class.

Converter::getClassesOnPage()

gets a list of all classes declared on a procedural page represented by

Converter::getClassLink()

return false or a classLink to $expr

Converter::getConstLink()

return false or a constLink to $expr in $class

Converter::getConverterDir()

Get the absolute path to the converter's base directory

Converter::getCurrentPageLink()

Converter::getCurrentPageURL()

Return the path to the current

Converter::getDefineLink()

return false or a defineLink to $expr

Converter::getFileSourceName()

Translate the path info into a unique file name for the highlighted source code.

Converter::getFileSourcePath()

Return the fixed path to the source-code file folder.

Converter::getFormattedConflicts()

Converter::getFormattedDescMethods()

Get a list of methods in child classes that override this method

Converter::getFormattedDescVars()

Get a list of vars in child classes that override this var

Converter::getFormattedImplements()

returns an array containing the class inheritance tree from the root object to the class.

Converter::getFormattedInheritedConsts()

Return template-enabled list of inherited class constants

Converter::getFormattedInheritedMethods()

Return template-enabled list of inherited methods

Converter::getFormattedInheritedVars()

Return template-enabled list of inherited variables

Converter::getFormattedMethodImplements()

Get the method this method(s) implemented from an interface, if any

Converter::getFormattedOverrides()

Get the method this method overrides, if any

Converter::getFunctionLink()

return false or a functionLink to $expr

Converter::getGlobalLink()

return false or a globalLink to $expr

Converter::getGlobalValue()

Parse a global variable's default value for class initialization.

Converter::getHighlightState()

Converter::getId()

take abstractLink descendant and text $eltext and return a

Converter::getIncludeValue()

Parse an include's file to see if it is a file documented in this project

Converter::getLink()

The meat of the @see tag and inline {@link} tag

Converter::getMethodLink()

return false or a methodLink to $expr in $class

Converter::getPageLink()

return false or a pageLink to $expr

Converter::getSortedClassTreeFromClass()

Return a tree of all classes that extend this class

Converter::getSourceLink()

Converter::getState()

Return parserStringWithInlineTags::Convert() cache state

Converter::getTutorialId()

Return a converter-specific id to distinguish tutorials and their sections

Converter::getTutorialLink()

The meat of the @tutorial tag and inline {@tutorial} tag

Converter::getTutorialTree()

Get a tree structure representing the hierarchy of tutorials

Converter::getVarLink()

return false or a varLink to $expr in $class

Converter::hasSourceCode()

Determine whether an element's file has generated source code, used for linking to line numbers of source.

Converter::hasTutorial()

Converter::highlightDocBlockSource()

Used to allow converters to format the source code of DocBlocks the way they'd like.

Converter::highlightSource()

Used to allow converters to format the source code the way they'd like.

Converter::highlightTutorialSource()

Used to allow converters to format the source code of Tutorial XML the way they'd like.

Converter::Italicize()

Used to convert the contents of <i> in a docblock

Converter::Kbdize()

Used to convert the contents of <kbd> in a docblock

Converter::ListItem()

Used to convert the contents of <li> in a docblock

Converter::newSmarty()

Return a Smarty template object to operate with

Converter::Output()

do all necessary output

Converter::postProcess()

This version does nothing

Converter::prepareDocBlock()

convert the element's DocBlock for output

Converter::PreserveWhiteSpace()

Used to convert the contents of <pre> in a docblock

Converter::ProgramExample()

Used to convert the <code> tag in a docblock

Converter::returnLink()

take URL $link and text $text and return a link in the format needed for the Converter

Converter::returnSee()

take abstractLink descendant and text $eltext and return a link

Converter::Sampize()

Used to convert the contents of <samp> in a docblock

Converter::setSourcePaths()

Mark a file as having had source code highlighted

Converter::setTargetDir()

Sets the output directory for generated documentation

Converter::setTemplateBase()

Set the template directory with a different template base directory

Converter::setTemplateDir()

sets the template directory based on the $outputformat and $name

Converter::sortPageContentsByElementType()

sorts $page_contents by element type as well as alphabetically

Converter::sourceLine()

Return a line of highlighted source code with formatted line number

Converter::startHighlight()

Initialize highlight caching

Converter::TranslateEntity()

Used to translate an XML DocBook entity like ” from a tutorial by reading the options.ini file for the template.

Converter::TranslateTag()

Used to translate an XML DocBook tag from a tutorial by reading the options.ini file for the template.

Converter::TutorialExample()

Converter::type_adjust()

Called by parserReturnTag::Convert() to allow converters to change type names to desired formatting

Converter::unmangle()

Called by parserSourceInlineTag::stringConvert() to allow converters to format the source code the way they'd like.

Converter::vardump_tree()

Debugging function for dumping $tutorial_tree

Converter::Varize()

Used to convert the contents of <var> in a docblock

Converter::walk()

called by phpDocumentor_IntermediateParser::Convert() to traverse the array of pages and their elements, converting them to the output format

Converter::walk_everything()

walk over elements by package rather than page

Converter::writeExample()

Write out the formatted source code for an example php file

Converter::writeFile()

Writes a file to target dir

Converter::writeSource()

Write out the formatted source code for a php file

Converter::_rmdir()

Completely remove a directory and its contents

Converter::_setHighlightCache()

Converter::_tutorial_path()

Returns the path to this tutorial as a string

[ Top ]

Property Summary

string	$base_dir	target directory passed on the command-line.
string	$category	peardoc2 Category
string	$class	name of current class being converted
Template	$class_data	template for the class currently being processed
string	$class_dir	output directory for the current class being processed
array	$current	contains all of the template procedural page element loop data needed for the current template
array	$currentclass	contains all of the template class element loop data needed for the current template
mixed	$function_data
boolean	$juststarted	controls formatting of parser informative output
array	$leftindex	indexes of elements by package that need to be generated
boolean	$local	whether a @see is going to be in the $base_dir, or in a package/subpackage subdirectory of $base_dir
mixed	$method_data
string	$name
string	$outputformat
array	$package_pages	array of converted package page names.
string	$page	name of current page being converted
Template	$page_data	template for the procedural page currently being processed
string	$page_dir	output directory for the current procedural page being processed
string	$path	path of current page being converted
boolean	$sort_page_contents_by_type	XMLDocBookConverter wants elements sorted by type as well as alphabetically
mixed	$sourceloc
array	$template_options	template options. Currently only 1 recognized option usepear

[ Top ]

Method Summary

XMLDocBookConverter	XMLDocBookConverter()	sets $base_dir to $targetDir
void	convertClass()	Converts class for template output
void	convertDefine()	Converts defines for template output
void	ConvertErrorLog()	Create errors.html template file output
void	convertFunction()	Converts function for template output
void	convertGlobal()	Converts global variables for template output
void	convertInclude()	Converts include elements for template output
void	convertMethod()	Converts method for template output
void	convertPackagePage()	Converts package page and sets its package as used in $package_pages
void	convertPage()	converts procedural pages for template output
void	convertTutorial()
void	convertVar()	Converts class variables for template output.
void	endClass()	Writes out the template file of $class_data and unsets the template to save memory
void	endPage()	Writes out the template file of $page_data and unsets the template to save memory
void	formatIndex()	HTMLdefaultConverter uses this function to format template index.html and packages.html
void	formatLeftIndex()	Generate indexes for li_package.html and classtree output files
void	formatPkgIndex()	HTMLdefaultConverter chooses to format both package indexes and the complete index here
void	generateElementIndex()	Generate alphabetical index of all elements
array	generateFormattedClassTree()	returns an array containing the class inheritance tree from the root object to the class
void	generateFormattedClassTrees()	returns a template-enabled array of class trees
void	generatePkgElementIndex()	Generate alphabetical index of all elements by package and subpackage
void	generatePkgElementIndexes()
void	getCData()
mixed	getClassLink()
mixed	getDefineLink()
mixed	getFunctionLink()
mixed	getGlobalLink()
string	getId()	Get the id value needed to allow linking
void	&getLink()	do that stuff in $template_options
mixed	getMethodLink()
mixed	getPageLink()
void	getPageName()
string	getRootTree()	return formatted class tree for the Class Trees page
void	getTutorialId()
mixed	getVarLink()
void	makeLeft()
void	Output()	This function is not used by HTMLdefaultConverter, but is required by Converter
void	postProcess()
void	prepareDocBlock()
int	rcNatCmp()	does a nat case sort on the specified second level value of the array
int	rcNatCmp1()	does a nat case sort on the specified second level value of the array.
string	returnLink()
void	returnSee()	This function takes an abstractLink descendant and returns an html link
void	setTargetDir()	calls the converter setTargetDir, and then copies any template images and the stylesheet if they haven't been copied
void	setTemplateDir()
void	&SmartyInit()
void	type_adjust()
void	unmangle()
void	writeNewPPage()

[ Top ]

Properties

string $base_dir [line 101]

target directory passed on the command-line.

$targetDir is malleable, always adding package/ and package/subpackage/ subdirectories onto it.

[ Top ]

string $category [line 162]

peardoc2 Category

[ Top ]

string $class [line 82]

name of current class being converted

Redefinition of:

Converter::$class: set to a classname if currently parsing a class, false if not

[ Top ]

Template $class_data [line 113]

template for the class currently being processed

Redefinition of:

Converter::$class_data: template for the class currently being processed

[ Top ]

string $class_dir [line 107]

output directory for the current class being processed

[ Top ]

array $current [line 138]

contains all of the template procedural page element loop data needed for the current template

[ Top ]

array $currentclass [line 144]

contains all of the template class element loop data needed for the current template

[ Top ]

mixed $function_data = array() [line 155]

[ Top ]

boolean $juststarted = false [line 132]

controls formatting of parser informative output

Converter prints: "Converting /path/to/file.php... Procedural Page Elements... Classes..." Since HTMLdefaultConverter outputs files while converting, it needs to send a \n to start a new line. However, if there is more than one class, output is messy, with multiple \n's just between class file output. This variable prevents that and is purely cosmetic

[ Top ]

array $leftindex = array('classes' => true, 'pages' => true, 'functions' => false, 'defines' => false, 'globals' => false) [line 59]

indexes of elements by package that need to be generated

Redefinition of:

Converter::$leftindex: Controls which of the one-element-only indexes are generated.

[ Top ]

boolean $local = true [line 64]

whether a @see is going to be in the $base_dir, or in a package/subpackage subdirectory of $base_dir

[ Top ]

mixed $method_data = array() [line 156]

[ Top ]

string $name = 'DocBook' [line 54]

[ Top ]

string $outputformat = 'XML' [line 52]

Redefinition of:

Converter::$outputformat: output format of this converter

[ Top ]

array $package_pages = array() [line 120]

array of converted package page names.

Used to link to the package page in the left index

[ Top ]

string $page [line 70]

name of current page being converted

Redefinition of:

Converter::$page: name of current page being converted

[ Top ]

Template $page_data [line 88]

template for the procedural page currently being processed

Redefinition of:

Converter::$page_data: template for the procedural page currently being processed

[ Top ]

string $page_dir [line 94]

output directory for the current procedural page being processed

[ Top ]

string $path [line 76]

path of current page being converted

Redefinition of:

Converter::$path: path of current page being converted

[ Top ]

boolean $sort_page_contents_by_type = true [line 50]

XMLDocBookConverter wants elements sorted by type as well as alphabetically

API Tags:

See:

Converter::$sort_page_contents_by_type

Redefinition of:

Converter::$sort_page_contents_by_type: This determines whether the $page_contents array should be sorted by element type as well as alphabetically by name

[ Top ]

mixed $sourceloc = '' [line 157]

[ Top ]

array $template_options = array('usepear' => false) [line 153]

template options. Currently only 1 recognized option usepear

usepear tells the getLink() function to return a package link to PEAR and PEAR_ERROR if possible, and to link directly to the fully-delimited link package#class.method or package#file.method in PEAR style, if possible, even if the package is not parsed. This will allow parsing of separate PEAR packages without parsing the entire thing at once!

Redefinition of:

Converter::$template_options: Options for each template, parsed from the options.ini file in the template base directory

[ Top ]

Methods

Constructor XMLDocBookConverter [line 167]

XMLDocBookConverter XMLDocBookConverter(

&$allp, 
&$packp, 
&$classes, 
&$procpages, 
$po, 
$pp, 
$qm, 
$targetDir, 
$templateDir, 
$title 
)

sets $base_dir to $targetDir

Parameters:

	&$allp:
	&$packp:
	&$classes:
	&$procpages:
	$po:
	$pp:
	$qm:
	$targetDir:
	$templateDir:
	$title:

API Tags:

See:

Converter::Converter()

[ Top ]

convertClass [line 811]

void convertClass(
parserClass
&$element 
)

Converts class for template output

Parameters:

parserClass

&$element:

API Tags:

See:	Converter::getFormattedInheritedMethods(), Converter::getFormattedInheritedVars()
See:	XMLDocBookConverter::prepareDocBlock(), Converter::generateChildClassList(), XMLDocBookConverter::generateFormattedClassTree(), Converter::getFormattedConflicts()

Redefinition of:

Converter::convertClass(): Default Class Handler

[ Top ]

convertDefine [line 1021]

void convertDefine(
parserDefine
&$element 
)

Converts defines for template output

Parameters:

parserDefine

&$element:

API Tags:

See:

XMLDocBookConverter::prepareDocBlock(), Converter::getFormattedConflicts()

Redefinition of:

Converter::convertDefine(): Converts defines for template output

[ Top ]

ConvertErrorLog [line 625]

void ConvertErrorLog(
)

Create errors.html template file output

This method takes all parsing errors and warnings and spits them out ordered by file and line number.

API Tags:

Global:

ErrorTracker $phpDocumentor_errors: We'll be using it's output facility

Redefinition of:

Converter::ConvertErrorLog(): Convert the phpDocumentor parsing/conversion error log

[ Top ]

convertFunction [line 952]

void convertFunction(
parserFunction
&$element 
)

Converts function for template output

Parameters:

parserFunction

&$element:

API Tags:

See:

XMLDocBookConverter::prepareDocBlock(), parserFunction::getFunctionCall(), Converter::getFormattedConflicts()

Redefinition of:

Converter::convertFunction(): Converts function for template output

[ Top ]

convertGlobal [line 1040]

void convertGlobal(
parserGlobal
&$element 
)

Converts global variables for template output

Parameters:

parserGlobal

&$element:

API Tags:

See:

XMLDocBookConverter::prepareDocBlock(), Converter::getFormattedConflicts()

Redefinition of:

Converter::convertGlobal(): Converts global variables for template output

[ Top ]

convertInclude [line 1003]

void convertInclude(
parserInclude
&$element 
)

Converts include elements for template output

Parameters:

parserInclude

&$element:

API Tags:

See:

XMLDocBookConverter::prepareDocBlock()

Redefinition of:

Converter::convertInclude(): Converts includes for template output

[ Top ]

convertMethod [line 873]

void convertMethod(
parserMethod
&$element 
)

Converts method for template output

Parameters:

parserMethod

&$element:

API Tags:

See:

XMLDocBookConverter::prepareDocBlock(), parserMethod::getFunctionCall(), Converter::getFormattedDescMethods(), Converter::getFormattedOverrides()

Redefinition of:

Converter::convertMethod(): Converts method for template output

[ Top ]

convertPackagePage [line 712]

void convertPackagePage(
parserPackagePage
&$element 
)

Converts package page and sets its package as used in $package_pages

Parameters:

parserPackagePage

&$element:

[ Top ]

convertPage [line 1062]

void convertPage(
parserData
&$element 
)

converts procedural pages for template output

Parameters:

parserData

&$element:

API Tags:

See:

XMLDocBookConverter::prepareDocBlock(), Converter::getClassesOnPage()

Redefinition of:

Converter::convertPage(): Default Page Handler

[ Top ]

convertTutorial [line 736]

void convertTutorial(

&$element 
)

Parameters:

&$element:

Redefinition of:

Converter::convertTutorial(): Default Tutorial Handler

[ Top ]

convertVar [line 774]

void convertVar(
parserVar
&$element 
)

Converts class variables for template output.

Parameters:

parserVar

&$element:

API Tags:

See:

XMLDocBookConverter::prepareDocBlock(), Converter::getFormattedOverrides()

	Converters XMLDocBook

[ class tree: Converters ] [ index: Converters ] [ all elements ]