svn: /phd/trunk/docs/phd-guide/ phd-guide.xml
| From: | Christian Weiske | Date: | Fri, 27 Aug 2010 09:07:36 +0000 |
| Subject: | svn: /phd/trunk/docs/phd-guide/ phd-guide.xml | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-7050@lists.php.net to get a copy of this message | ||
cweiske Fri, 27 Aug 2010 09:07:36 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=302846
Log:
Write about writing own source code highlighters. This fixes bug #47201: use an external highlight
source-code engine
Bug: http://bugs.php.net/47201 (To be documented) use an
external highlight source-code engine
Changed paths:
U phd/trunk/docs/phd-guide/phd-guide.xml
Modified: phd/trunk/docs/phd-guide/phd-guide.xml
===================================================================
--- phd/trunk/docs/phd-guide/phd-guide.xml 2010-08-27 08:50:32 UTC (rev 302845)
+++ phd/trunk/docs/phd-guide/phd-guide.xml 2010-08-27 09:07:36 UTC (rev 302846)
@@ -289,6 +289,7 @@
too.</para>
</section>
+
<section xml:id="render-custom">
<title>Customizing the rendering results</title>
@@ -301,7 +302,8 @@
<para>Part of the documentation of programming languages
is source code examples. PhD is able to colorize the source
- code of many types.</para>
+ 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
@@ -358,7 +360,9 @@
</para>
<para>Apart from using the highlighter shipped with PhD, you
- can build your own highlighters.</para>
+ can
+ <link linkend="phd-extension-highlighter">build your own
highlighters</link>.
+ </para>
</section>
</section>
@@ -590,6 +594,51 @@
</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>pdf</literal>, <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>