summaryrefslogtreecommitdiff
path: root/sandbox/code-block-directive/docs/syntax-highlight.html
diff options
context:
space:
mode:
Diffstat (limited to 'sandbox/code-block-directive/docs/syntax-highlight.html')
-rw-r--r--sandbox/code-block-directive/docs/syntax-highlight.html417
1 files changed, 417 insertions, 0 deletions
diff --git a/sandbox/code-block-directive/docs/syntax-highlight.html b/sandbox/code-block-directive/docs/syntax-highlight.html
new file mode 100644
index 000000000..1591b6777
--- /dev/null
+++ b/sandbox/code-block-directive/docs/syntax-highlight.html
@@ -0,0 +1,417 @@
+<?xml version="1.0" encoding="iso-8859-1" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
+<title>Syntax Highlight</title>
+<link rel="stylesheet" href="../../../../../lib/python2.4/site-packages/docutils/writers/html4css1/html4css1.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="syntax-highlight">
+<h1 class="title">Syntax Highlight</h1>
+<!-- -*- rst-mode -*- -->
+<div class="contents topic">
+<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
+<ul class="auto-toc simple">
+<li><a class="reference" href="#existing-highlighting-additions-to-docutils" id="id9" name="id9">1&nbsp;&nbsp;&nbsp;Existing highlighting additions to docutils</a></li>
+<li><a class="reference" href="#pygments-enhanced-docutils-front-ends" id="id10" name="id10">2&nbsp;&nbsp;&nbsp;Pygments enhanced docutils front-ends</a><ul class="auto-toc">
+<li><a class="reference" href="#example" id="id11" name="id11">2.1&nbsp;&nbsp;&nbsp;Example</a></li>
+</ul>
+</li>
+<li><a class="reference" href="#proposal-for-a-code-block-directive-in-docutils" id="id12" name="id12">3&nbsp;&nbsp;&nbsp;Proposal for a code-block directive in docutils</a><ul class="auto-toc">
+<li><a class="reference" href="#parsing" id="id13" name="id13">3.1&nbsp;&nbsp;&nbsp;Parsing</a></li>
+<li><a class="reference" href="#writing" id="id14" name="id14">3.2&nbsp;&nbsp;&nbsp;Writing</a></li>
+<li><a class="reference" href="#todo" id="id15" name="id15">3.3&nbsp;&nbsp;&nbsp;TODO</a></li>
+</ul>
+</li>
+<li><a class="reference" href="#configurable-literal-block-directive" id="id16" name="id16">4&nbsp;&nbsp;&nbsp;Configurable literal block directive</a><ul class="auto-toc">
+<li><a class="reference" href="#goal" id="id17" name="id17">4.1&nbsp;&nbsp;&nbsp;Goal</a></li>
+<li><a class="reference" href="#inline-analogon" id="id18" name="id18">4.2&nbsp;&nbsp;&nbsp;Inline analogon</a></li>
+<li><a class="reference" href="#proposal-make-the-default-literal-block-role-configurable" id="id19" name="id19">4.3&nbsp;&nbsp;&nbsp;Proposal: make the default &quot;literal block&quot; role configurable.</a><ul class="auto-toc">
+<li><a class="reference" href="#motivation" id="id20" name="id20">4.3.1&nbsp;&nbsp;&nbsp;Motivation</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference" href="#odtwriter" id="id21" name="id21">5&nbsp;&nbsp;&nbsp;Odtwriter</a></li>
+<li><a class="reference" href="#syntax-highlight-with-the-listings-sty-latex-package" id="id22" name="id22">6&nbsp;&nbsp;&nbsp;Syntax highlight with the <tt class="docutils literal"><span class="pre">listings.sty</span></tt> LaTeX package</a></li>
+</ul>
+</div>
+<p>Syntax highlighting significantly enhances the readability of code.
+So it is almost a must for pretty-printing a literate program.</p>
+<p><a class="reference" href="http://pylit.berlios.de">PyLit</a> uses <a class="reference" href="http://docutils.sourceforge.net/">docutils</a> as pretty-printing back end. However, in the current
+version, docutils does not highlight literal blocks. This may change in the
+future, as in a mail on
+<a class="reference" href="http://sourceforge.net/mailarchive/message.php?msg_id=12921194">Questions about writing programming manuals and scientific documents</a>,
+docutils main developer David Goodger wrote:</p>
+<blockquote>
+I'd be happy to include Python source colouring support, and other
+languages would be welcome too. A multi-language solution would be
+useful, of course. My issue is providing support for all output formats
+-- HTML and LaTeX and XML and anything in the future -- simultaneously.
+Just HTML isn't good enough. Until there is a generic-output solution,
+this will be something users will have to put together themselves.</blockquote>
+<div class="section">
+<h1><a class="toc-backref" href="#id9" id="existing-highlighting-additions-to-docutils" name="existing-highlighting-additions-to-docutils">1&nbsp;&nbsp;&nbsp;Existing highlighting additions to docutils</a></h1>
+<p>There are already docutils extensions providing syntax colouring, e.g:</p>
+<ul class="simple">
+<li><a class="reference" href="http://silvercity.sourceforge.net/">SilverCity</a> is a C++ library and Python extension that can provide lexical
+analysis for over 20 different programming languages. A <a class="reference" href="http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252170">recipe</a>
+for a &quot;code-block&quot; directive provides syntax highlight by SilverCity.</li>
+</ul>
+<ul class="simple">
+<li>The <a class="reference" href="http://www.ctan.org/tex-archive/help/Catalogue/entries/listings.html">listings</a> LaTeX package provides highly customisable and advanced
+syntax highlight, though only for LaTeX (and LaTeX derived PS|PDF).
+A <a class="reference" href="http://article.gmane.org/gmane.text.docutils.devel/3914">patch</a> mailed by Gael Varoquaux uses the listings package for a
+&quot;code-block&quot; directive with syntax highlight.</li>
+</ul>
+<ul class="simple">
+<li><a class="reference" href="http://trac.edgewall.org/">Trac</a> has <a class="reference" href="http://trac.edgewall.org/wiki/WikiRestructuredText">reStructuredText support</a> and offers syntax highlighting with
+a &quot;code-block&quot; directive using GNU <a class="reference" href="http://www.gnu.org/software/enscript/enscript.html">Enscript</a>, <a class="reference" href="http://silvercity.sourceforge.net/">SilverCity</a>, or <a class="reference" href="http://pygments.org/">Pygments</a>.</li>
+</ul>
+<ul class="simple">
+<li>The <a class="reference" href="http://www.voidspace.org.uk/python/rest2web/">rest2web</a> site builder provides the <a class="reference" href="http://www.voidspace.org.uk/python/rest2web/macros.html#colorize">colorize</a> macro (using the
+<a class="reference" href="http://www.standards-schmandards.com/2005/fangs-093/">Moin-Moin Python colorizer</a>)</li>
+</ul>
+<ul class="simple">
+<li><a class="reference" href="http://pygments.org/">Pygments</a> a generic syntax highlighter for general use.<ul>
+<li>Written completely in Python, usable as a command-line tool and as a
+Python package.</li>
+<li>A wide range of common <a class="reference" href="http://pygments.org/languages">languages and markup formats</a> is supported.</li>
+<li>Additionally, OpenOffice's <tt class="docutils literal"><span class="pre">*.odt</span></tt> is supported by the <a class="reference" href="http://www.rexx.com/~dkuhlman/odtwriter.html">odtwriter</a>.</li>
+<li>The layout is configurable by style sheets.</li>
+<li>Several built-in styles and an option for line-numbering.</li>
+<li>Built-in output formats include HTML, LaTeX, rtf</li>
+<li>Support for new languages, formats, and styles is added easily (modular
+structure, Python code, existing documentation).</li>
+<li>Well documented and actively maintained.</li>
+<li>The web site provides a recipe for <a class="reference" href="http://pygments.org/docs/rstdirective/">using Pygments in ReST documents</a>.
+It is used in the <a class="reference" href="#pygments-enhanced-docutils-front-ends">Pygments enhanced docutils front-ends</a> below.</li>
+</ul>
+</li>
+<li>The experimental <a class="reference" href="http://www.rexx.com/~dkuhlman/odtwriter.html">Odtwriter</a> for Docutils OpenOffice export supports syntax
+colours using Pygments.</li>
+</ul>
+<p><a class="reference" href="http://pygments.org/">Pygments</a> seems to be the most promising docutils highlighter. For printed
+output, the <a class="reference" href="http://www.ctan.org/tex-archive/help/Catalogue/entries/listings.html">listings</a> package has its advantages too.</p>
+</div>
+<div class="section">
+<h1><a class="toc-backref" href="#id10" id="pygments-enhanced-docutils-front-ends" name="pygments-enhanced-docutils-front-ends">2&nbsp;&nbsp;&nbsp;Pygments enhanced docutils front-ends</a></h1>
+<p>Here comes a working example for syntax highlighting in HTML and LaTeX
+output with <a class="reference" href="http://pygments.org/">pygments</a>.</p>
+<p>The example code in &quot;<a class="reference" href="http://pygments.org/docs/rstdirective/">Using Pygments in ReST documents</a>&quot; defines a new
+&quot;sourcecode&quot; directive. The directive takes one argument <cite>language</cite> and uses
+the <a class="reference" href="http://pygments.org/">Pygments</a> source highlighter to parse and render its content as a
+colourful source code block.</p>
+<p>Combining the <a class="reference" href="http://pygments.org/">pygments</a> example code with the standard <a class="reference" href="http://docutils.sourceforge.net/">docutils</a> front-ends,
+results in front-end scripts generating output documents with syntax colour.
+For consistency with the majority of existing add-ons, the directive is
+renamed to &quot;code-block&quot;.</p>
+<dl class="docutils">
+<dt><a class="reference" href="../tools/rst2html-pygments">rst2html-pygments</a></dt>
+<dd>enhances the standard docutils <tt class="docutils literal"><span class="pre">rst2html</span></tt> front-end to
+generate a HTML rendering with syntax highlight.</dd>
+<dt><a class="reference" href="../tools/rst2latex-pygments">rst2latex-pygments</a></dt>
+<dd>enhances docutils' <tt class="docutils literal"><span class="pre">rst2latex</span></tt> to generate LaTeX with syntax highlight.</dd>
+<dt>Advantages:</dt>
+<dd><ul class="first last simple">
+<li>Easy implementation with no changes to the stock <a class="reference" href="http://docutils.sourceforge.net/">docutils</a>.</li>
+<li>Separation of code blocks and ordinary literal blocks.</li>
+</ul>
+</dd>
+<dt>Disadvantages:</dt>
+<dd><ul class="first last simple">
+<li>&quot;code-block&quot; content is formatted by <a class="reference" href="http://pygments.org/">pygments</a> and inserted in the
+document tree as a &quot;raw&quot; node making the approach writer-dependant.</li>
+<li>documents are incompatible with the standard docutils because of the
+locally defined directive.</li>
+<li>more &quot;invasive&quot; markup distracting from content</li>
+<li>no &quot;minimal&quot; code block marker -- three additional lines per code block</li>
+</ul>
+</dd>
+</dl>
+<p>The later disadvantages become an issue in literate programming where a code
+block is the most used block markup (see the proposal for a <a class="reference" href="#configurable-literal-block-directive">configurable
+literal block directive</a> below).</p>
+<p>To support the <tt class="docutils literal"><span class="pre">..</span> <span class="pre">code-block::</span></tt> directive, the PyLit converter would need
+a configurable &quot;code block marker&quot; instead of the hard coded <tt class="docutils literal"><span class="pre">::</span></tt>
+presently in use. (See also the <a class="reference" href="../examples/pylit.py.html#code-block-directive">code-block directive</a> section in
+pylit.py.)</p>
+<div class="section">
+<h2><a class="toc-backref" href="#id11" id="example" name="example">2.1&nbsp;&nbsp;&nbsp;Example</a></h2>
+<dl class="docutils">
+<dt>Python script:</dt>
+<dd><table class="first last docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">text source:</th><td class="field-body"><a class="reference" href="for-else-test.py.txt">for-else-test.py.txt</a></td>
+</tr>
+<tr class="field"><th class="field-name">HTML:</th><td class="field-body"><a class="reference" href="for-else-test.py.html">for-else-test.py.html</a></td>
+</tr>
+<tr class="field"><th class="field-name">LaTeX:</th><td class="field-body"><a class="reference" href="for-else-test.py.tex">for-else-test.py.tex</a></td>
+</tr>
+<tr class="field"><th class="field-name">PDF:</th><td class="field-body"><a class="reference" href="for-else-test.py.pdf">for-else-test.py.pdf</a></td>
+</tr>
+</tbody>
+</table>
+</dd>
+<dt>Stylesheets:</dt>
+<dd><table class="first last docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">CSS stylesheet:</th><td class="field-body"><a class="reference" href="../tools/pygments-default.css">pygments-default.css</a></td>
+</tr>
+<tr class="field"><th class="field-name">LaTeX style:</th><td class="field-body"><a class="reference" href="../tools/pygments-default.sty">pygments-default.sty</a></td>
+</tr>
+</tbody>
+</table>
+</dd>
+</dl>
+</div>
+</div>
+<div class="section">
+<h1><a class="toc-backref" href="#id12" id="proposal-for-a-code-block-directive-in-docutils" name="proposal-for-a-code-block-directive-in-docutils">3&nbsp;&nbsp;&nbsp;Proposal for a code-block directive in docutils</a></h1>
+<p>In a <a class="reference" href="http://article.gmane.org/gmane.text.docutils.user/3923">post to the docutils users list</a>, David Goodger wrote (after an all
+too long discussion):</p>
+<blockquote>
+<p>Here are my pronouncements:</p>
+<ul class="simple">
+<li>If reST is to grow a code-block (or sourcecode or syntax-highlight
+or whatever) directive, it must be independent of the output format.</li>
+<li>The result will be stored in a literal_block node in the document
+tree. There will be no new element.</li>
+<li>There will be no &quot;unparsed&quot; code-block. It would make no sense.</li>
+<li>There will be no special pass-through support for LaTeX to do its
+own syntax highlighting.</li>
+</ul>
+</blockquote>
+<p>On 7.06.07, David Goodger wrote:</p>
+<blockquote>
+<p>On 6/7/07, G. Milde suggested:</p>
+<ol class="arabic" start="3">
+<li><p class="first">Docutils will support optional features that are only available if
+a recommended package or module is installed.</p>
+<p>-&gt; code-block directive content would be</p>
+<blockquote>
+<ul class="simple">
+<li>rendered with syntax highlight if <tt class="docutils literal"><span class="pre">import</span> <span class="pre">pygments</span></tt> works,</li>
+<li>output as &quot;ordinary&quot; literal-block (preserve space, mono-coloured
+fixed-width font) if <tt class="docutils literal"><span class="pre">import</span> <span class="pre">pygments</span></tt> fails.</li>
+</ul>
+</blockquote>
+</li>
+</ol>
+<p>+1 on number 3.</p>
+</blockquote>
+<p>Implemented 2007-06-08.</p>
+<div class="section">
+<h2><a class="toc-backref" href="#id13" id="parsing" name="parsing">3.1&nbsp;&nbsp;&nbsp;Parsing</a></h2>
+<p>Felix Wiemann provided a <a class="reference" href="http://article.gmane.org/gmane.text.docutils.user/3689">proof of concept</a> script that utilizes the
+<a class="reference" href="http://pygments.org/">pygments</a> parser to parse a source code string and store the result in
+the document tree.</p>
+<p>This concept is used in <a class="reference" href="pygments_code_block_directive.py.html">pygments_code_block_directive</a>, (source:
+<a class="reference" href="../pygments_code_block_directive.py">pygments_code_block_directive.py</a>), to define and register a &quot;code-block&quot;
+directive.</p>
+<ul class="simple">
+<li>The <cite>DocutilsInterface</cite> class uses <a class="reference" href="http://pygments.org/">pygments</a> to parse the content of the
+directive and classify the tokens using short CSS class names identical to
+pygments HTML output. If pygments is not available, the unparsed code is
+returned.</li>
+<li>The <cite>code_block_directive</cite> function inserts the tokens in a &quot;rich&quot;
+&lt;literal_block&gt; element with &quot;classified&quot; &lt;inline&gt; nodes.</li>
+</ul>
+<p>The XML rendering of the small example file <a class="reference" href="myfunction.py.txt">myfunction.py.txt</a> looks like
+<a class="reference" href="myfunction.py.xml">myfunction.py.xml</a>.</p>
+</div>
+<div class="section">
+<h2><a class="toc-backref" href="#id14" id="writing" name="writing">3.2&nbsp;&nbsp;&nbsp;Writing</a></h2>
+<p>The writers can use the class information in the &lt;inline&gt; elements to render
+the tokens. They should ignore the class information if they are unable to
+use it or to pass it on.</p>
+<dl class="docutils">
+<dt>HTML</dt>
+<dd><p class="first">The &quot;html&quot; writer works out of the box.</p>
+<ul class="simple">
+<li>The <a class="reference" href="../tools/rst2html-highlight">rst2html-highlight</a> front end registers the &quot;code-block&quot; directive and
+converts an input file to html.</li>
+<li>Styling is done with the adapted CSS style sheet <a class="reference" href="../tools/pygments-default.css">pygments-default.css</a>
+based on docutils' default stylesheet and the output of
+<tt class="docutils literal"><span class="pre">pygmentize</span> <span class="pre">-S</span> <span class="pre">default</span> <span class="pre">-f</span> <span class="pre">html</span></tt>.</li>
+<li>The result looks like <a class="reference" href="myfunction.py.html">myfunction.py.html</a>.</li>
+</ul>
+<p class="last">The &quot;s5&quot; and &quot;pep&quot; writers are not tested yet.</p>
+</dd>
+<dt>XML</dt>
+<dd>&quot;xml&quot; and &quot;pseudoxml&quot; work out of the box, too. See <a class="reference" href="myfunction.py.xml">myfunction.py.xml</a>
+and <a class="reference" href="myfunction.py.pseudoxml">myfunction.py.pseudoxml</a></dd>
+<dt>LaTeX</dt>
+<dd><p class="first">Latex writers must be updated to handle the &quot;rich&quot; &lt;literal_block&gt; element
+correct.</p>
+<ul class="last">
+<li><p class="first">The &quot;latex&quot; writer currently fails to handle &quot;classified&quot; &lt;inline&gt;
+doctree elements. The output <a class="reference" href="myfunction.py.tex">myfunction.py.tex</a> contains undefined
+control sequences <tt class="docutils literal"><span class="pre">\docutilsroleNone</span></tt>.</p>
+</li>
+<li><p class="first">The &quot;newlatex2e&quot; writer produces a valid LaTeX document
+(<a class="reference" href="myfunction.py.newlatex2e.tex">myfunction.py.newlatex2e.tex</a>). However the <cite>pdflatex</cite> output looks
+mixed up a bit (<a class="reference" href="myfunction.py.newlatex2e.pdf">myfunction.py.newlatex2e.pdf</a>).</p>
+<p>The pygments-produced style file will not currently work with
+&quot;newlatex2e&quot; output.</p>
+</li>
+</ul>
+</dd>
+<dt>OpenOffice</dt>
+<dd>The non-official &quot;odtwriter&quot; provides syntax highlight with
+pygments but uses a different syntax.</dd>
+</dl>
+</div>
+<div class="section">
+<h2><a class="toc-backref" href="#id15" id="todo" name="todo">3.3&nbsp;&nbsp;&nbsp;TODO</a></h2>
+<ul class="simple">
+<li>fix the &quot;latex&quot; writer.</li>
+<li>think about an interface for pygments' options (like &quot;encoding&quot; or
+&quot;linenumbers&quot;).</li>
+</ul>
+</div>
+</div>
+<div class="section">
+<h1><a class="toc-backref" href="#id16" id="configurable-literal-block-directive" name="configurable-literal-block-directive">4&nbsp;&nbsp;&nbsp;Configurable literal block directive</a></h1>
+<div class="section">
+<h2><a class="toc-backref" href="#id17" id="goal" name="goal">4.1&nbsp;&nbsp;&nbsp;Goal</a></h2>
+<p>A clean and simple syntax for highlighted code blocks -- preserving the
+space saving feature of the &quot;minimised&quot; literal block marker (<tt class="docutils literal"><span class="pre">::</span></tt> at the
+end of a text paragraph). This is especially desirable in literate programs
+with many code blocks.</p>
+</div>
+<div class="section">
+<h2><a class="toc-backref" href="#id18" id="inline-analogon" name="inline-analogon">4.2&nbsp;&nbsp;&nbsp;Inline analogon</a></h2>
+<p>The <em>role</em> of inline <cite>interpreted text</cite> can be customised with the
+&quot;default-role&quot; directive. This allows the use of the concise &quot;backtick&quot;
+syntax for the most often used role, e.g. in a chemical paper, one could
+use:</p>
+<pre class="literal-block">
+.. default-role:: subscript
+
+The triple point of H`2`O is at 0°C.
+</pre>
+<p>This customisation is currently not possible for block markup.</p>
+</div>
+<div class="section">
+<h2><a class="toc-backref" href="#id19" id="proposal-make-the-default-literal-block-role-configurable" name="proposal-make-the-default-literal-block-role-configurable">4.3&nbsp;&nbsp;&nbsp;Proposal: make the default &quot;literal block&quot; role configurable.</a></h2>
+<ul>
+<li><p class="first">Define a new &quot;literal&quot; directive for an ordinary literal block.
+This would insert the block content into the document tree as
+&quot;literal-block&quot; element with no parsing.</p>
+</li>
+<li><p class="first">Define a &quot;literal-block&quot; setting that controls which directive is called
+on a block following <tt class="docutils literal"><span class="pre">::</span></tt>. Default would be the &quot;literal&quot; directive.</p>
+<p>Alternatively, define a new &quot;default-literal-block&quot; directive instead of
+a settings key.</p>
+</li>
+<li><p class="first">From a syntax view, this would be analog to the behaviour of the <a class="reference" href="http://www.rexx.com/~dkuhlman/odtwriter.html">odtwriter</a>.
+(I am not sure about the representation in the document tree, though.)</p>
+</li>
+</ul>
+<div class="section">
+<h3><a class="toc-backref" href="#id20" id="motivation" name="motivation">4.3.1&nbsp;&nbsp;&nbsp;Motivation</a></h3>
+<p>Analogue to customising the default role of &quot;interpreted text&quot; with the
+&quot;default-role&quot; directive, the concise <tt class="docutils literal"><span class="pre">::</span></tt> literal-block markup could be
+used for e.g.</p>
+<ul class="simple">
+<li>a &quot;code-block&quot; or &quot;sourcecode&quot; directive for colourful code
+(analog to the one in the <a class="reference" href="#pygments-enhanced-docutils-front-ends">pygments enhanced docutils front-ends</a>)</li>
+<li>the &quot;line-block&quot; directive for poems or addresses</li>
+<li>the &quot;parsed-literal&quot; directive</li>
+</ul>
+<p>Example (using the upcoming &quot;settings&quot; directive):</p>
+<pre class="literal-block">
+ordinary literal block::
+
+ some text typeset in monospace
+
+.. settings::
+ :literal-block: code-block python
+
+colourful Python code::
+
+ def hello():
+ print &quot;hello world&quot;
+</pre>
+<p>In the same line, a &quot;default-block-quote&quot; setting or directive could be
+considered to configure the role of a block quote.</p>
+</div>
+</div>
+</div>
+<div class="section">
+<h1><a class="toc-backref" href="#id21" id="odtwriter" name="odtwriter">5&nbsp;&nbsp;&nbsp;Odtwriter</a></h1>
+<p>Dave Kuhlman's <a class="reference" href="http://www.rexx.com/~dkuhlman/odtwriter.html">odtwriter</a> extension can add syntax highlighting
+to ordinary literal blocks.</p>
+<p>The <tt class="docutils literal"><span class="pre">--add-syntax-highlighting</span></tt> command line flag activates syntax
+highlighting in literal blocks. By default, the &quot;python&quot; lexer is used.</p>
+<p>You can change this within your reST document with the <cite>sourcecode</cite>
+directive:</p>
+<pre class="literal-block">
+.. sourcecode:: off
+
+ordinary literal block::
+
+ content set in teletype
+
+.. sourcecode:: on
+.. sourcecode:: python
+
+colourful Python code::
+
+ def hello():
+ print &quot;hello world&quot;
+</pre>
+<p>The &quot;sourcecode&quot; directive defined by the odtwriter is principally
+different from the &quot;code-block&quot; directive of <tt class="docutils literal"><span class="pre">rst2html-pygments</span></tt>:</p>
+<ul>
+<li><p class="first">The odtwriter directive does not have content. It is a switch.</p>
+</li>
+<li><p class="first">The syntax highlighting state and language/lexer set by this directive
+remain in effect until the next sourcecode directive is encountered in the
+reST document.</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">..</span> <span class="pre">sourcecode::</span> <span class="pre">&lt;newstate&gt;</span></tt></dt>
+<dd><p class="first last">make highlighting active or inactive.
+&lt;newstate&gt; is either <tt class="docutils literal"><span class="pre">on</span></tt> or <tt class="docutils literal"><span class="pre">off</span></tt>.</p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">..</span> <span class="pre">sourcecode::</span> <span class="pre">&lt;lexer&gt;</span></tt></dt>
+<dd><p class="first last">change the lexer parsing literal code blocks.
+&lt;lexer&gt; should be one of aliases listed at pygment's <a class="reference" href="http://pygments.org/languages">languages and
+markup formats</a>.</p>
+</dd>
+</dl>
+</li>
+</ul>
+<p>I.e. the odtwriter implements a <a class="reference" href="#configurable-literal-block-directive">configurable literal block directive</a>
+(but with a slightly different syntax than my proposal below).</p>
+</div>
+<div class="section">
+<h1><a class="toc-backref" href="#id22" id="syntax-highlight-with-the-listings-sty-latex-package" name="syntax-highlight-with-the-listings-sty-latex-package">6&nbsp;&nbsp;&nbsp;Syntax highlight with the <tt class="docutils literal"><span class="pre">listings.sty</span></tt> LaTeX package</a></h1>
+<p>Using the <a class="reference" href="http://www.ctan.org/tex-archive/help/Catalogue/entries/listings.html">listings</a> LaTeX package for syntax highlight is currently not
+possible with the standard latex writer output.</p>
+<p>Support for the use of <a class="reference" href="http://www.ctan.org/tex-archive/help/Catalogue/entries/listings.html">listings</a> with docutils is an issue that must be
+settled separate from the <a class="reference" href="#proposal-for-a-code-block-directive-in-docutils">proposal for a code-block directive in
+docutils</a>. It would need</p>
+<ul class="simple">
+<li>a new, specialized docutils latex writer, or</li>
+<li>a new option (and behaviour) to the existing latex writer.</li>
+</ul>
+<!-- External links -->
+<!-- Internal links -->
+</div>
+</div>
+<div class="footer">
+<hr class="footer" />
+<a class="reference" href="syntax-highlight.txt">View document source</a>.
+Generated on: 2007-06-08.
+
+</div>
+</body>
+</html>