mirror of
https://github.com/php/phd.git
synced 2026-03-23 22:52:05 +01:00
690 lines
22 KiB
XML
690 lines
22 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<book version="5.0" xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:svg="http://www.w3.org/2000/svg"
|
|
xmlns:mml="http://www.w3.org/1998/Math/MathML"
|
|
xmlns:html="http://www.w3.org/1999/xhtml"
|
|
xmlns:db="http://docbook.org/ns/docbook"
|
|
xml:id="index">
|
|
<title>PhD: The definitive guide to PHP's DocBook Rendering System</title>
|
|
|
|
<preface xml:id="preface">
|
|
<title>About PhD</title>
|
|
|
|
<para>PhD is PHP's very own DocBook 5 rendering system. It is used to
|
|
convert the <acronym>PHP</acronym> Manual and PEAR Documentation into
|
|
different output formats like XHTML, Man pages and CHM.</para>
|
|
|
|
<para>The goal of PhD is to become a fast, general DocBook rendering
|
|
system. At the moment of writing, PhD is already very fast: It can create
|
|
the chunked version of PEAR's manual (some 3000 files) in less than a
|
|
minute on a 2GHz system. It also renders the PHP and PEAR manual
|
|
flawlessly. It does not support every DocBook 5 tag yet, and using it to
|
|
render own DocBook files may need some tweaks.</para>
|
|
</preface>
|
|
|
|
<chapter xml:id="getting-phd">
|
|
<title>Getting PhD</title>
|
|
|
|
<para>You might find some other tutorials in the <link
|
|
linkend="links">links</link> section.</para>
|
|
|
|
<section xml:id="installation">
|
|
<title>Installation</title>
|
|
|
|
<para>PhD is distributed via an own PEAR channel,
|
|
<uri>doc.php.net</uri>. Using it is also the most easy way to get
|
|
it.</para>
|
|
|
|
<section xml:id="installation-pear">
|
|
<title>Installation via PEAR</title>
|
|
|
|
<note>
|
|
<para>You need a working <link
|
|
xlink:href="http://pear.php.net/manual/en/installation.php">PEAR
|
|
installation</link>.</para>
|
|
</note>
|
|
|
|
<para>To install the latest version of PhD:</para>
|
|
|
|
<screen>
|
|
<![CDATA[
|
|
$ pear install doc.php.net/phd
|
|
|
|
... downloading
|
|
|
|
$ phd --version
|
|
PhD Version: 1.0.0-stable
|
|
PHP Version: 5.3.3
|
|
Copyright(c) 2007-2010 The PHP Documentation Group
|
|
]]>
|
|
</screen>
|
|
|
|
<para>Installing the PhD Packages:</para>
|
|
|
|
<screen>
|
|
<![CDATA[
|
|
$ pear install doc.php.net/phd_php
|
|
Starting to download PhD_PHP-1.0.0.tgz (18,948 bytes)
|
|
[...]
|
|
install ok: channel://doc.php.net/PhD_PHP-1.0.0
|
|
|
|
$ pear install doc.php.net/phd_pear
|
|
downloading PhD_PEAR-1.0.0.tgz ...
|
|
[...]
|
|
install ok: channel://doc.php.net/PhD_PEAR-1.0.0
|
|
]]>
|
|
</screen>
|
|
|
|
<para>That's it!</para>
|
|
</section>
|
|
|
|
<section xml:base="" xml:id="installation-git">
|
|
<title>Installation from Git</title>
|
|
|
|
<para>To get the latest and greatest features that have not been
|
|
released yet, you can use PhD from Git.</para>
|
|
|
|
<screen>
|
|
<![CDATA[
|
|
$ git clone https://github.com/php/phd.git
|
|
... output
|
|
|
|
pear install package.xml package_generic.xml package_php.xml package_pear.xml
|
|
[...]
|
|
install ok: channel://doc.php.net/PhD-1.0.1
|
|
install ok: channel://doc.php.net/PhD_Generic-1.0.1
|
|
install ok: channel://doc.php.net/PhD_PHP-1.0.1
|
|
install ok: channel://doc.php.net/PhD_PEAR-1.0.1
|
|
|
|
$ cd phd
|
|
$ phd --version
|
|
PhD Version: phd-from-git
|
|
PHP Version: 5.3.3-dev
|
|
Copyright(c) 2007-2010 The PHP Documentation Group
|
|
]]>
|
|
</screen>
|
|
|
|
<para>And now you're done.</para>
|
|
</section>
|
|
</section>
|
|
</chapter>
|
|
|
|
<chapter xml:id="using-phd">
|
|
<title>Using PhD to render documentation</title>
|
|
<note>
|
|
<para>
|
|
Earlier versions of the PHP documentation infrastructure used Subversion (SVN).
|
|
All PHP documentation repositories are now maintained using Git.
|
|
</para>
|
|
</note>
|
|
<section xml:id="render-phpdoc">
|
|
<title>Rendering the PHP Documentation Sources</title>
|
|
|
|
<sidebar>
|
|
<title>Getting the PHP Documentation Sources</title>
|
|
<para>To get the PHP documentation sources, simply clone them from the
|
|
official Git repository with the following command.</para>
|
|
<screen>
|
|
<![CDATA[
|
|
$ git clone https://github.com/php/doc-en.git phpdoc
|
|
... output
|
|
]]>
|
|
</screen>
|
|
|
|
<para>To prepare the documentation, <command>cd</command> to the
|
|
phpdoc directory, and run configure.php.</para>
|
|
|
|
<screen><![CDATA[$ php doc-base/configure.php]]></screen>
|
|
|
|
<para>This process will generate a .manual.xml file in the current
|
|
directory, which is what we need for building the docs. Now we're
|
|
ready to proceed with running PhD to generate the PHP docs.</para>
|
|
</sidebar>
|
|
|
|
<para>To quickly become familiar with using PhD, you can download the
|
|
PHP documentation sources and render those. Running PhD to render the
|
|
docs is surprisingly simple, so we'll start with that.</para>
|
|
|
|
<screen>
|
|
<![CDATA[
|
|
$ phd -d doc-base/.manual.xml -P PHP
|
|
... status messages
|
|
]]>
|
|
</screen>
|
|
|
|
<para>After a running for a few moments, PhD will generate all the
|
|
output formats of the PHP Package into <literal>output/</literal>.</para>
|
|
|
|
<para>So now that you've seen the fruits of your labor, let's take a
|
|
closer look at PhD and see what capabilities are available to us.</para>
|
|
|
|
<screen>
|
|
<![CDATA[
|
|
$ phd --help
|
|
PhD version: 1.1.6
|
|
Copyright(c) 2007-2013 The PHP Documentation Group
|
|
|
|
-v
|
|
--verbose <int> Adjusts the verbosity level
|
|
-f <formatname>
|
|
--format <formatname> The build format to use
|
|
-P <packagename>
|
|
--package <packagename> The package to use
|
|
-I
|
|
--noindex Do not index before rendering but load from cache
|
|
(default: false)
|
|
-M
|
|
--memoryindex Do not save indexing into a file, store it in memory.
|
|
(default: false)
|
|
-r
|
|
--forceindex Force re-indexing under all circumstances
|
|
(default: false)
|
|
-t
|
|
--notoc Do not rewrite TOC before rendering but load from
|
|
cache (default: false)
|
|
-d <filename>
|
|
--docbook <filename> The Docbook file to render from
|
|
-x
|
|
--xinclude Process XML Inclusions (XInclude)
|
|
(default: false)
|
|
-p <id[=bool]>
|
|
--partial <id[=bool]> The ID to render, optionally skipping its children
|
|
chunks (default to true; render children)
|
|
-s <id[=bool]>
|
|
--skip <id[=bool]> The ID to skip, optionally skipping its children
|
|
chunks (default to true; skip children)
|
|
-l
|
|
--list Print out the supported packages and formats
|
|
-o <directory>
|
|
--output <directory> The output directory (default: .)
|
|
-F filename
|
|
--outputfilename filename Filename to use when writing standalone formats
|
|
(default: <packagename>-<formatname>.<formatext>)
|
|
-L <language>
|
|
--lang <language> The language of the source file (used by the CHM
|
|
theme). (default: en)
|
|
-c <bool>
|
|
--color <bool> Enable color output when output is to a terminal
|
|
(default: true)
|
|
-C <filename>
|
|
--css <filename> Link for an external CSS file.
|
|
-g <classname>
|
|
--highlighter <classname> Use custom source code highlighting php class
|
|
-V
|
|
--version Print the PhD version information
|
|
-h
|
|
--help This help
|
|
-e <extension>
|
|
--ext <extension> The alternative filename extension to use,
|
|
including the dot. Use 'false' for no extension.
|
|
-S <bool>
|
|
--saveconfig <bool> Save the generated config (default: false).
|
|
|
|
-Q
|
|
--quit Don't run the build. Use with --saveconfig to
|
|
just save the config.
|
|
-k
|
|
--packagedir Use an external package directory.
|
|
|
|
|
|
Most options can be passed multiple times for greater effect.
|
|
]]>
|
|
</screen>
|
|
|
|
<para>As you can see, there are plenty of options to look into in PhD.
|
|
The most important options are those which allow you to select a format
|
|
and package to output your documentation to.</para>
|
|
|
|
<screen>
|
|
<![CDATA[
|
|
$ phd --list
|
|
Supported packages:
|
|
Generic
|
|
xhtml
|
|
bigxhtml
|
|
manpage
|
|
IDE
|
|
xml
|
|
funclist
|
|
json
|
|
php
|
|
phpstub
|
|
PEAR
|
|
xhtml
|
|
bigxhtml
|
|
php
|
|
chm
|
|
tocfeed
|
|
PHP
|
|
xhtml
|
|
bigxhtml
|
|
php
|
|
howto
|
|
manpage
|
|
kdevelop
|
|
chm
|
|
tocfeed
|
|
epub
|
|
enhancedchm
|
|
]]>
|
|
</screen>
|
|
|
|
<note>
|
|
<para>The format packages are provided by separate PEAR packages
|
|
(doc.php.net/PhD_Generic, doc.php.net/PhD_IDE, doc.php.net/PhD_PEAR and
|
|
doc.php.net/PhD_PHP) where only the Generic is installed by default.
|
|
</para>
|
|
</note>
|
|
|
|
|
|
<para>You can tell by the output of the <literal>--list</literal> option
|
|
that PhD can also be used to render the docs as Unix
|
|
Man Pages.</para>
|
|
|
|
<para>To select a format and package, you must use the <literal>-f
|
|
[formatName]</literal> and <literal>-P [packageName]</literal> options.</para>
|
|
|
|
<screen><![CDATA[$ phd -f manpage -P PHP -d .manual.xml]]></screen>
|
|
|
|
<para>This command will output the documentation for PHP functions in
|
|
the Unix Man page format.</para>
|
|
</section>
|
|
|
|
<section xml:id="render-phd-guide">
|
|
<title>Compiling the PhD guide</title>
|
|
|
|
<para>The PhD guide is this manual you are reading currently. It lives
|
|
in <acronym>PhD</acronym>'s Git repository under
|
|
<filename>docs/phd-guide/phd-guide.xml</filename>. If you installed PhD
|
|
from Git, you already have it. Otherwise, get it:</para>
|
|
|
|
<screen>
|
|
<![CDATA[
|
|
$ git clone https://github.com/php/phd.git
|
|
$ cd phd/docs/phd-guide
|
|
]]>
|
|
</screen>
|
|
|
|
<para>Now you have everything you need. Just type</para>
|
|
|
|
<screen>
|
|
<![CDATA[
|
|
$ cd phd/docs/phd-guide/
|
|
$ phd -f bigxhtml -d phd-guide.xml
|
|
]]>
|
|
</screen>
|
|
|
|
<para>There should be an .html file in the directory now. View it with a
|
|
browser!</para>
|
|
|
|
<para>That's all to say. This way you can render your own docbook files,
|
|
too.</para>
|
|
</section>
|
|
|
|
|
|
<section xml:id="render-custom">
|
|
<title>Customizing the rendering results</title>
|
|
|
|
<para>PhD lets you specify a number of options to customize the
|
|
generated documentation files. The following sections describe
|
|
some of them.</para>
|
|
|
|
<section xml:id="render-custom-highlighter">
|
|
<title>Source code highlighter</title>
|
|
|
|
<para>Part of the documentation of programming languages
|
|
is source code examples. PhD is able to colorize the source
|
|
code of many types of source code with the help of
|
|
<emphasis>highlighters</emphasis>.</para>
|
|
|
|
<para>To utilize syntax highlighting, your opening
|
|
<literal><programlisting></literal> tags need a
|
|
<literal>role</literal> attribute describing the type
|
|
of source code. Examples are <literal>php</literal>,
|
|
<literal>html</literal> and <literal>python</literal>.</para>
|
|
|
|
<note>
|
|
<para>PhD currently only highlights the code if it is embedded
|
|
in a <literal>CDATA</literal> section.</para>
|
|
</note>
|
|
|
|
<example>
|
|
<title>A programlisting tag with a role</title>
|
|
<programlisting role="xml"><![CDATA[<programlisting role="php"><![CDATA[
|
|
<?php
|
|
echo "Hello world!";
|
|
?>
|
|
]]>]]></programlisting>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>By default, PhD uses the source code highlighter that
|
|
is built into PHP itself. It is only able to highlight PHP code
|
|
and nothing else.</para>
|
|
|
|
<para>If your documentation contains other types of source code
|
|
or markup, like XML, HTML, Javascript or any other language,
|
|
you should try the
|
|
<link xlink:href="http://qbnz.com/highlighter/">GeSHi</link>
|
|
highlighter that is shipped with PhD:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Install GeSHi from the MediaWiki PEAR channel:
|
|
</para>
|
|
<screen><![CDATA[$ pear channel-discover mediawiki.googlecode.com/svn
|
|
$ pear install mediawiki/geshi]]></screen>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Use the GeSHi syntax highlighting class when rendering your
|
|
documentation:
|
|
<screen><![CDATA[$ phd -g 'phpdotnet\phd\Highlighter_GeSHi' -d phd-guide.xml]]></screen>
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>If you have GeSHi version 1.1.x installed, you should use
|
|
the <literal>phpdotnet\phd\Highlighter_GeSHi11x</literal> highlighter,
|
|
which is adapted to GeSHi's new API.
|
|
</para>
|
|
|
|
<para>Apart from using the highlighter shipped with PhD, you
|
|
can
|
|
<link linkend="phd-extension-highlighter">build your own highlighters</link>.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</chapter>
|
|
|
|
|
|
<chapter xml:id="docbook-extensions">
|
|
<title>DocBook extensions</title>
|
|
|
|
<para>PhD has been tailored for PHP and PEAR manuals. To make writing
|
|
documentation as easy as possible, some own tags have been added to the
|
|
DTD.</para>
|
|
|
|
<para>All extensions live in their own XML namespace
|
|
"<literal>phd:</literal>" which resolves to
|
|
<uri>http://www.php.net/ns/phd</uri>. When using one of the attributes or
|
|
tags described here, remember to set the namespace:</para>
|
|
|
|
<programlisting>xmlns:phd="http://www.php.net/ns/phd"</programlisting>
|
|
|
|
<section xml:id="ext-general">
|
|
<title>General DocBook extensions</title>
|
|
|
|
<para>The extensions listed here are available in all PhD themes and
|
|
formats.</para>
|
|
|
|
<section xml:id="ext-phd-chunk">
|
|
<title>Manual chunking with "phd:chunk" (Attribute)</title>
|
|
|
|
<para>PhD automatically chooses which sections, chapters or other tags
|
|
get their own file (chunk) when using a chunked theme. Sometimes the
|
|
result of this automatism is not optimal and you want to fine-tune it.
|
|
The attribute "phd:chunk" is offered as solution by PhD.</para>
|
|
|
|
<section>
|
|
<title>Allowed values</title>
|
|
|
|
<para><literal>phd:chunk</literal> may have values
|
|
<literal>true</literal> and <literal>false</literal>. They force the
|
|
element to be chunked or not.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Allowed in</title>
|
|
|
|
<para><literal>phd:chunk</literal> may be used in every tag that
|
|
accepts <link
|
|
xlink:href="http://www.docbook.org/tdg5/en/html/ref-elements.html#common.attributes">db.common.attributes</link>.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Example</title>
|
|
|
|
<programlisting role="xml">
|
|
<![CDATA[
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<preface xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:phd="http://www.php.net/ns/phd"
|
|
xml:id="preface"
|
|
phd:chunk="false"
|
|
>
|
|
<info>
|
|
<title>Preface</title>
|
|
..
|
|
</info>
|
|
..
|
|
</preface>
|
|
]]>
|
|
</programlisting>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="ext-phd-toc">
|
|
<title>Generating Table Of Contents: <phd:toc> (Tag)</title>
|
|
|
|
<para>To manually insert a Table Of Contents (TOC) that creates a list
|
|
of links to children elements of a specified tag.</para>
|
|
|
|
<para>phd:toc-depth</para>
|
|
|
|
<section>
|
|
<title>Allowed in</title>
|
|
|
|
<para><literal><phd:toc></literal> is can be used everywhere
|
|
<literal><para></literal> is allowed.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Children</title>
|
|
|
|
<para>You can add a title with
|
|
<literal><title></literal>.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Attributes</title>
|
|
|
|
<table>
|
|
<title>Attributes for <phd:toc></title>
|
|
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Attribute name</entry>
|
|
|
|
<entry>Description</entry>
|
|
|
|
<entry>Default value</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry>phd:element</entry>
|
|
|
|
<entry>ID of the element whose children shall be
|
|
linked</entry>
|
|
|
|
<entry><emphasis>none</emphasis></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>phd:toc-depth</entry>
|
|
|
|
<entry>Depth of the TOC/Number of levels</entry>
|
|
|
|
<entry><literal>1</literal></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="ext-pear">
|
|
<title>PEAR specific DocBook extensions</title>
|
|
|
|
<para>The DocBook extensions listed here are only available when using a
|
|
PEAR theme.</para>
|
|
|
|
<section xml:id="ext-phd-pearapi" xml:lang="">
|
|
<title>Linking to PEAR API documentation: <phd:pearapi>
|
|
(Tag)</title>
|
|
|
|
<para>A large part of the PEAR manual is about packages and how to use
|
|
them. Package authors often find they need to link to the API
|
|
documentation of a specific method, variable or class of their
|
|
package. To ease the linking process, the
|
|
<literal><phd:pearapi></literal> tag was introduced.</para>
|
|
|
|
<para>You can let PhD automatically create the link text by just
|
|
closing the tag, or specify the tag text via the tag's content.</para>
|
|
|
|
<section>
|
|
<title>Package links</title>
|
|
|
|
<para><literal>phd:package</literal> name is put into the attribute,
|
|
any text:</para>
|
|
|
|
<programlisting role="xml">
|
|
<![CDATA[
|
|
<phd:pearapi phd:package="HTML_QuickForm"/>
|
|
<phd:pearapi phd:package="HTML_QuickForm">some text</phd:pearapi>
|
|
]]>
|
|
</programlisting>
|
|
|
|
<screen><link
|
|
xlink:href="http://pear.php.net/package/HTML_QuickForm/docs/latest/li_HTML_QuickForm.html">HTML_QuickForm</link>
|
|
<link xlink:href="http://pear.php.net/package/HTML_QuickForm/docs/latest/li_HTML_QuickForm.html">some text</link></screen>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Class links</title>
|
|
|
|
<para>Class name as <literal>phd:linkend</literal> attribute
|
|
value.</para>
|
|
|
|
<programlisting role="xml">
|
|
<![CDATA[
|
|
<phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm_element"/>
|
|
<phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm_element">some text</phd:pearapi>
|
|
]]>
|
|
</programlisting>
|
|
|
|
<screen><link
|
|
xlink:href="http://pear.php.net/package/HTML_QuickForm/docs/latest/HTML_QuickForm/HTML_QuickForm_element.html">HTML_QuickForm_element</link>
|
|
<link xlink:href="http://pear.php.net/package/HTML_QuickForm/docs/latest/HTML_QuickForm/HTML_QuickForm_element.html">some text</link></screen>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Class method links</title>
|
|
|
|
<para>Class and method name as <literal>phd:linkend</literal> text,
|
|
separated by a double colon.</para>
|
|
|
|
<programlisting role="xml">
|
|
<![CDATA[
|
|
<phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm_element::setName"/>
|
|
<phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm_element::setName">some text</phd:pearapi>
|
|
]]>
|
|
</programlisting>
|
|
|
|
<screen><link
|
|
xlink:href="http://pear.php.net/package/HTML_QuickForm/docs/latest/HTML_QuickForm/HTML_QuickForm_element.html#methodsetName">HTML_QuickForm_element::setName()</link>
|
|
<link xlink:href="http://pear.php.net/package/HTML_QuickForm/docs/latest/HTML_QuickForm/HTML_QuickForm_element.html#methodsetName">some text</link></screen>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Class variable links</title>
|
|
|
|
<para>Class and variable name as <literal>phd:linkend</literal>
|
|
text, separated by a double colon and a dollar sign before the
|
|
variable name.</para>
|
|
|
|
<programlisting role="xml">
|
|
<![CDATA[
|
|
<phd:pearapi phd:package="Net_Geo" phd:linkend="Net_Geo::$cache_ttl"/>
|
|
<phd:pearapi phd:package="Net_Geo" phd:linkend="Net_Geo::$cache_ttl">some text</phd:pearapi>
|
|
]]>
|
|
</programlisting>
|
|
|
|
<screen><link
|
|
xlink:href="http://pear.php.net/package/Net_Geo/docs/latest/Net_Geo/Net_Geo.html#var$cache_ttl">Net_Geo::$cache_ttl</link>
|
|
<link xlink:href="http://pear.php.net/package/Net_Geo/docs/latest/Net_Geo/Net_Geo.html#var$cache_ttl">some text</link></screen>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
</chapter>
|
|
|
|
|
|
|
|
<chapter xml:id="phd-extension">
|
|
<title>Extending PhD</title>
|
|
|
|
<para>Written in PHP, PhD is easy to hack on and easy to extend.
|
|
It provides command line parameters to use custom code
|
|
without changing PhD internals, like source code highlighters.</para>
|
|
|
|
<section xml:id="phd-extension-highlighter">
|
|
<title>Writing an own syntax highlighter</title>
|
|
|
|
<para>A syntax highlighter for PhD is nothing more than a simple
|
|
PHP class that has two methods, a <literal>factory</literal>
|
|
and <literal>highlight</literal>.</para>
|
|
|
|
<para><literal>factory</literal> is static and takes the format name
|
|
(i.e. <literal>xhtml</literal>,
|
|
<literal>troff</literal>) as only parameter. It returns
|
|
the highlighter instance object for the given format.
|
|
The method is called for each output format the documentation
|
|
is rendered to.</para>
|
|
|
|
<para><literal>highlight</literal> takes three parameters,
|
|
<literal>text</literal>, <literal>role</literal> and
|
|
<literal>format</literal>.
|
|
It is called whenever a piece of source code needs to be highlighted
|
|
and expects the highlighted source code to be returned in whatever
|
|
format the current rendering format is expected to be.</para>
|
|
|
|
<para>Take a look at the provided highlighters,
|
|
<literal>phpdotnet\phd\Highlighter</literal>,
|
|
<literal>phpdotnet\phd\Highlighter_GeSHi</literal> and
|
|
<literal>phpdotnet\phd\Highlighter_GeSHi11x</literal>.
|
|
They will serve as good examples how to implement your own
|
|
highlighter.</para>
|
|
|
|
<para>Once you wrote your custom source code highlighting
|
|
class, it's time to
|
|
<link linkend="render-custom-highlighter">try it out</link>.</para>
|
|
</section>
|
|
</chapter>
|
|
|
|
|
|
|
|
<appendix xml:id="links">
|
|
<title>Links</title>
|
|
|
|
<para>Some other articles for further reading. Latest are on top.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><link
|
|
xlink:href="http://bjori.blogspot.com/2007/10/phd-php-based-docbook-renderer-rc1.html">PhD
|
|
0.1RC1 released</link> by Hannes Magnusson (PhD 0.1RC1)</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</appendix>
|
|
</book>
|