cvs: peardoc /en/package/text text-highlighter.xml /en/package/text/text-highlighter intro.xml oc.xml usage.xml
[email protected] ("Brett Bieber")
| Newsgroups | php.pear.doc |
|---|---|
| Message-ID | <cvssaltybeagle1200092757@cvsserver> |
saltybeagle Fri Jan 11 23:05:57 2008 UTC
Added files:
/peardoc/en/package/text/text-highlighter usage.xml oc.xml
Modified files:
/peardoc/en/package/text/text-highlighter intro.xml
/peardoc/en/package/text text-highlighter.xml
Log:
Separate output customization and usage into separate sections. Each file should have one root node - this is needed for the docbook 5 conversion. All others need to have this corrected... some are in the list on http://wiki.pear.php.net/index.php/PEARDocMoveToDocbook5#Conversion_problems
saltybeagle-20080111230557.txt
(text/plain, 15 KB)
http://cvs.php.net/viewvc.cgi/peardoc/en/package/text/text-highlighter/intro.xml?r1=1.7&r2=1.8&diff_format=u
Index: peardoc/en/package/text/text-highlighter/intro.xml
diff -u peardoc/en/package/text/text-highlighter/intro.xml:1.7 peardoc/en/package/text/text-highlighter/intro.xml:1.8
--- peardoc/en/package/text/text-highlighter/intro.xml:1.7 Wed Jan 2 00:47:48 2008
+++ peardoc/en/package/text/text-highlighter/intro.xml Fri Jan 11 23:05:57 2008
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='ISO-8859-1' ?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
<sect2 id="package.text.text-highlighter.intro">
<title>Introduction</title>
@@ -95,183 +95,3 @@
</itemizedlist>
</sect2>
-
- <sect2 id="package.text.text-highlighter.usage">
- <title>Usage</title>
-
- <para>
- The class <classname>Text_Highlighter</classname> contains all
- necessary functionality to perform the syntax highlighting
- except for the actual highlighting rules for the different formats.
- These rules are defined in subclasses of <classname>Text_Highlighter</classname>,
- but one must not directly instantiate these subclasses. Instead the
- object-oriented factory pattern is used to create a highlighter object
- depending on the format:
- </para>
-
- <example>
- <title>Highlighting a SQL query</title>
-
- <programlisting role="php">
- <![CDATA[
-require_once "Text/Highlighter.php";
-
-$hlSQL =& Text_Highlighter::factory("SQL");
-echo $hlSQL->highlight("SELECT * FROM some_table WHERE id = 12");
- ]]>
- </programlisting>
-
- <para>
- This code generates a highlighted version of the SQL SELECT-query
- that is passed to <methodname>Text_Highlighter::highlight</methodname>
- in HTML. It is possible to customize the output to e.g. instead
- generate output suitable for usage on a console. This is
- described in the section <link linkend="package.text.text-highlighter.oc">
- Output Customization</link>.
- </para>
- </example>
-
- <para>
- In order to produce syntax highlighting for other formats, one must
- replace the argument value <literal>SQL</literal> of <methodname>Text_Highlighter::factory</methodname>
- with one of <literal>ABAP</literal>, <literal>CPP</literal>, <literal>CSS</literal>, <literal>DIFF</literal>,
- <literal>DTD</literal>, <literal>HTML</literal>, <literal>JAVA</literal>,
- <literal>JAVASCRIPT</literal>, <literal>MYSQL</literal>,
- <literal>PERL</literal>, <literal>PHP</literal>,
- <literal>PYTHON</literal>, <literal>RUBY</literal>, <literal>SQL</literal>,
- or <literal>XML</literal>.
- </para>
- </sect2>
-
- <sect2 id="package.text.text-highlighter.oc">
- <title>Output Customization</title>
-
- <para>
- The default behaviour of <classname>Text_Highlighter</classname>
- is to generate a syntax highlighted HTML version of the input.
- </para>
-
- <para>
- It is possible to instead generate output that is suitable for
- being displayed on color-capable terminals such as
- <command>xterm</command> or through <command>less(1)</command>
- by telling <classname>Text_Highlighter</classname> to use
- another renderer:
- </para>
-
- <example>
- <title>Using the console renderer</title>
-
- <programlisting role="php">
- <![CDATA[
-require_once "Text/Highlighter.php";
-require_once "Text/Highlighter/Renderer/Console.php";
-
-$hlSQL =& Text_Highlighter::factory("SQL");
-$hlSQL->setRenderer(new Text_Highlighter_Renderer_Console);
-echo $hlSQL->highlight("SELECT * FROM some_table WHERE id = 12");
- ]]>
- </programlisting>
- </example>
-
- <para>
- Also it is possible to further customize the output of both the HTML-
- and the console-renderer by passing an associative array of options
- to the constructor:
- </para>
-
- <example>
- <title>Options for the HTML renderer</title>
-
- <programlisting role="php">
- <![CDATA[
-require_once "Text/Highlighter.php";
-require_once "Text/Highlighter/Renderer/Html.php";
-
-$renderer = new Text_Highlighter_Renderer_Html(array("numbers" => HL_NUMBERS_LI, "tabsize" => 4));
-
-$hlJava =& Text_Highlighter::factory("JAVA");
-$hlJava->setRenderer($renderer);
-
-echo $hlJava->highlight('class JavaProgram {
- public static void main(String args[]) {
- System.out.println("Hello World!");
- }
-}');
- ]]>
- </programlisting>
-
- <para>
- The above example configures a HTML renderer with two options:
- The first one tells it to number the lines in the output
- using the <literal><ol /></literal> HTML tag and the
- second one instructs the renderer to use a tab width of 4
- spaces for indentation.
- </para>
- </example>
-
- <para>
- The following options are applicable:
- </para>
-
- <table>
- <title>Possible options for the renderer classes</title>
-
- <tgroup cols="5">
- <colspec colname="option" />
- <colspec colname="description" />
- <colspec colname="inHTML" />
- <colspec colname="inConsole" />
- <colspec colname="hints"/>
-
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Description</entry>
- <entry>Available in HTML renderer</entry>
- <entry>Available in console renderer</entry>
- <entry>Hints</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry align="center"><literal>numbers</literal></entry>
- <entry>Line numbering style</entry>
- <entry align="center">yes</entry>
- <entry align="center">yes</entry>
- <entry>
- In the console renderer, this option takes just
- &true; or &false; in order to denote if line numbers
- should be displayed or not. The HTML rendered accepts
- three different values: <constant>HL_NUMBERS_LI</constant>
- instructs the class to number the lines using the
- <literal><ol /></literal> HTML tag, while
- <constant>HL_NUMBERS_TABLE</constant> uses a two-column
- table with the line numbers in the first and the source code
- in the second column. Setting the value to &false; turns
- line numbering off in the HTML renderer.
- </entry>
- </row>
- <row>
- <entry align="center"><literal>tabsize</literal></entry>
- <entry>Tab width</entry>
- <entry align="center">yes</entry>
- <entry align="center">yes</entry>
- <entry />
- </row>
- <row>
- <entry align="center"><literal>colors</literal></entry>
- <entry>Additional colors</entry>
- <entry align="center">no</entry>
- <entry align="center">yes</entry>
- <entry>
- An associate array of additional colors for color-enabled
- consoles. The key of each array entry must be the name of
- the color and the corresponding value must be the escape
- sequence for it. (Example: <literal>\033[1;31mRed</literal>.)
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect2>
http://cvs.php.net/viewvc.cgi/peardoc/en/package/text/text-highlighter.xml?r1=1.3&r2=1.4&diff_format=u
Index: peardoc/en/package/text/text-highlighter.xml
diff -u peardoc/en/package/text/text-highlighter.xml:1.3 peardoc/en/package/text/text-highlighter.xml:1.4
--- peardoc/en/package/text/text-highlighter.xml:1.3 Mon Apr 10 15:44:21 2006
+++ peardoc/en/package/text/text-highlighter.xml Fri Jan 11 23:05:57 2008
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='ISO-8859-1' ?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<sect1 id="package.text.text-highlighter">
<title>Text_Highlighter</title>
@@ -9,6 +9,8 @@
</para>
&package.text.text-highlighter.intro;
+ &package.text.text-highlighter.usage;
+ &package.text.text-highlighter.oc;
</sect1>
<!-- Keep this comment at the end of the file
http://cvs.php.net/viewvc.cgi/peardoc/en/package/text/text-highlighter/usage.xml?view=markup&rev=1.1
Index: peardoc/en/package/text/text-highlighter/usage.xml
+++ peardoc/en/package/text/text-highlighter/usage.xml
<?xml version="1.0" encoding="UTF-8"?>
<sect2 id="package.text.text-highlighter.usage">
<title>Usage</title>
<para>
The class <classname>Text_Highlighter</classname> contains all
necessary functionality to perform the syntax highlighting
except for the actual highlighting rules for the different formats.
These rules are defined in subclasses of <classname>Text_Highlighter</classname>,
but one must not directly instantiate these subclasses. Instead the
object-oriented factory pattern is used to create a highlighter object
depending on the format:
</para>
<example>
<title>Highlighting a SQL query</title>
<programlisting role="php">
<![CDATA[
require_once "Text/Highlighter.php";
$hlSQL =& Text_Highlighter::factory("SQL");
echo $hlSQL->highlight("SELECT * FROM some_table WHERE id = 12");
]]>
</programlisting>
<para>
This code generates a highlighted version of the SQL SELECT-query
that is passed to <methodname>Text_Highlighter::highlight</methodname>
in HTML. It is possible to customize the output to e.g. instead
generate output suitable for usage on a console. This is
described in the section <link linkend="package.text.text-highlighter.oc">
Output Customization</link>.
</para>
</example>
<para>
In order to produce syntax highlighting for other formats, one must
replace the argument value <literal>SQL</literal> of <methodname>Text_Highlighter::factory</methodname>
with one of <literal>ABAP</literal>, <literal>CPP</literal>, <literal>CSS</literal>, <literal>DIFF</literal>,
<literal>DTD</literal>, <literal>HTML</literal>, <literal>JAVA</literal>,
<literal>JAVASCRIPT</literal>, <literal>MYSQL</literal>,
<literal>PERL</literal>, <literal>PHP</literal>,
<literal>PYTHON</literal>, <literal>RUBY</literal>, <literal>SQL</literal>,
or <literal>XML</literal>.
</para>
</sect2>
http://cvs.php.net/viewvc.cgi/peardoc/en/package/text/text-highlighter/oc.xml?view=markup&rev=1.1
Index: peardoc/en/package/text/text-highlighter/oc.xml
+++ peardoc/en/package/text/text-highlighter/oc.xml
<?xml version="1.0" encoding="UTF-8"?>
<sect2 id="package.text.text-highlighter.oc">
<title>Output Customization</title>
<para>
The default behaviour of <classname>Text_Highlighter</classname>
is to generate a syntax highlighted HTML version of the input.
</para>
<para>
It is possible to instead generate output that is suitable for
being displayed on color-capable terminals such as
<command>xterm</command> or through <command>less(1)</command>
by telling <classname>Text_Highlighter</classname> to use
another renderer:
</para>
<example>
<title>Using the console renderer</title>
<programlisting role="php">
<![CDATA[
require_once "Text/Highlighter.php";
require_once "Text/Highlighter/Renderer/Console.php";
$hlSQL =& Text_Highlighter::factory("SQL");
$hlSQL->setRenderer(new Text_Highlighter_Renderer_Console);
echo $hlSQL->highlight("SELECT * FROM some_table WHERE id = 12");
]]>
</programlisting>
</example>
<para>
Also it is possible to further customize the output of both the HTML-
and the console-renderer by passing an associative array of options
to the constructor:
</para>
<example>
<title>Options for the HTML renderer</title>
<programlisting role="php">
<![CDATA[
require_once "Text/Highlighter.php";
require_once "Text/Highlighter/Renderer/Html.php";
$renderer = new Text_Highlighter_Renderer_Html(array("numbers" => HL_NUMBERS_LI, "tabsize" => 4));
$hlJava =& Text_Highlighter::factory("JAVA");
$hlJava->setRenderer($renderer);
echo $hlJava->highlight('class JavaProgram {
public static void main(String args[]) {
System.out.println("Hello World!");
}
}');
]]>
</programlisting>
<para>
The above example configures a HTML renderer with two options:
The first one tells it to number the lines in the output
using the <literal><ol /></literal> HTML tag and the
second one instructs the renderer to use a tab width of 4
spaces for indentation.
</para>
</example>
<para>
The following options are applicable:
</para>
<table>
<title>Possible options for the renderer classes</title>
<tgroup cols="5">
<colspec colname="option" />
<colspec colname="description" />
<colspec colname="inHTML" />
<colspec colname="inConsole" />
<colspec colname="hints"/>
<thead>
<row>
<entry>Name</entry>
<entry>Description</entry>
<entry>Available in HTML renderer</entry>
<entry>Available in console renderer</entry>
<entry>Hints</entry>
</row>
</thead>
<tbody>
<row>
<entry align="center"><literal>numbers</literal></entry>
<entry>Line numbering style</entry>
<entry align="center">yes</entry>
<entry align="center">yes</entry>
<entry>
In the console renderer, this option takes just
&true; or &false; in order to denote if line numbers
should be displayed or not. The HTML rendered accepts
three different values: <constant>HL_NUMBERS_LI</constant>
instructs the class to number the lines using the
<literal><ol /></literal> HTML tag, while
<constant>HL_NUMBERS_TABLE</constant> uses a two-column
table with the line numbers in the first and the source code
in the second column. Setting the value to &false; turns
line numbering off in the HTML renderer.
</entry>
</row>
<row>
<entry align="center"><literal>tabsize</literal></entry>
<entry>Tab width</entry>
<entry align="center">yes</entry>
<entry align="center">yes</entry>
<entry />
</row>
<row>
<entry align="center"><literal>colors</literal></entry>
<entry>Additional colors</entry>
<entry align="center">no</entry>
<entry align="center">yes</entry>
<entry>
An associate array of additional colors for color-enabled
consoles. The key of each array entry must be the name of
the color and the corresponding value must be the escape
sequence for it. (Example: <literal>\033[1;31mRed</literal>.)
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>