[prev in list] [next in list] [prev in thread] [next in thread] 

List:       php-doc-cvs
Subject:    [DOC-CVS] =?utf-8?q?svn:_/phd/trunk/docs/phd-guide/_phd-guide.xml?=
From:       Christian_Weiske <cweiske () php ! net>
Date:       2010-08-27 9:07:36
Message-ID: svn-cweiske-1282900056-302846-1502354643 () svn ! php ! net
[Download RAW message or body]

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>&lt;programlisting&gt;</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>



-- 
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[prev in list] [next in list] [prev in thread] [next in thread]