Prepare code directive for inclusion in the core.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@7105 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
author: milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 2011-08-26 22:23:29 +0000
committer: milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 2011-08-26 22:23:29 +0000
commit: b991feb7b06e99b2186fc533733905da9312f5d3 (patch)
tree: 9da9826e25d07a95e86d0f0ed8c711ba13305e92 /sandbox/code-block-directive/docs
parent: 0ffd4b2d58dbf67c4f35be718de8e69de2210c92 (diff)
download: docutils-b991feb7b06e99b2186fc533733905da9312f5d3.tar.gz
8 files changed, 192 insertions, 107 deletions
diff --git a/sandbox/code-block-directive/docs/myfunction.py.htm b/sandbox/code-block-directive/docs/myfunction.py.htm
index 617f4b671..5e180e46e 100644
--- a/sandbox/code-block-directive/docs/myfunction.py.htm
+++ b/sandbox/code-block-directive/docs/myfunction.py.htm
@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.8: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.9: http://docutils.sourceforge.net/" />
 <title></title>
 <link rel="stylesheet" href="../data/pygments-default.css" type="text/css" />
 </head>
@@ -12,19 +12,35 @@
 
 
 <p>This is a test of the new &quot;code&quot; directive:</p>
-<!-- Translate this document to HTML with a pygments enhanced frontend, e.g.
+<!-- Translate this document with a pygments enhanced frontend, e.g.
 
-../rst2html-highlight - -stylesheet=../data/pygments-default.css
+ ../rst2html-highlight.py - -stylesheet=../data/pygments-default.css
+ ../rst2latex-highlight.py - -stylesheet=../data/pygments-docutilsroles.sty
 
-../rst2latex-highlight - -stylesheet=../data/pygments-docutileroles.sty -->
-<pre class="code python silly literal-block">
-<span class="ln">1 </span><span class="k">def</span> <span class="nf">my_function</span><span class="p">():</span>
-<span class="ln">2 </span>    <span class="sd">&quot;&quot;&quot;Test the lexer.
-</span><span class="ln">3 </span><span class="sd">
-</span><span class="ln">4 </span><span class="sd">    just a test&quot;&quot;&quot;</span>
-<span class="ln">5 </span>
-<span class="ln">6 </span>    <span class="c"># and now for something completely different</span>
-<span class="ln">7 </span>    <span class="k">print</span> <span class="mi">8</span><span class="o">/</span><span class="mi">2</span>
+or via the test case in
+
+ ../pygments_code_block_directive.py - -traceback -->
+<p>The example from Docutils TODO list:</p>
+<pre class="code python literal-block">
+<span class="k">print</span> <span class="s">'This is Python code.'</span>
+<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>
+    <span class="k">print</span> <span class="n">i</span>
+</pre>
+<p>Numbered lines:</p>
+<pre class="code python literal-block">
+<span class="ln">1 </span><span class="c"># This is Python code,</span>
+<span class="ln">2 </span><span class="c"># that prints the integers from 0 to 9</span>
+<span class="ln">3 </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span>
+<span class="ln">4 </span>    <span class="k">print</span> <span class="n">i</span>
+</pre>
+<p>Another example:</p>
+<pre class="code python silly literal-block" id="my-function">
+<span class="ln"> 7 </span><span class="k">def</span> <span class="nf">my_function</span><span class="p">():</span>
+<span class="ln"> 8 </span>    <span class="sd">&quot;&quot;&quot;Test the lexer.
+</span><span class="ln"> 9 </span><span class="sd">    &quot;&quot;&quot;</span>
+<span class="ln">10 </span>
+<span class="ln">11 </span>    <span class="c"># and now for something completely different</span>
+<span class="ln">12 </span>    <span class="k">print</span> <span class="mi">8</span><span class="o">/</span><span class="mi">2</span>
 </pre>
 <p>The end.</p>
 </div>
diff --git a/sandbox/code-block-directive/docs/myfunction.py.pdf b/sandbox/code-block-directive/docs/myfunction.py.pdf
index b6624d223..fccaeee8e 100644
--- a/sandbox/code-block-directive/docs/myfunction.py.pdf
+++ b/sandbox/code-block-directive/docs/myfunction.py.pdf
diff --git a/sandbox/code-block-directive/docs/myfunction.py.pseudoxml b/sandbox/code-block-directive/docs/myfunction.py.pseudoxml
index 6a71c2ede..04bd2cb05 100644
--- a/sandbox/code-block-directive/docs/myfunction.py.pseudoxml
+++ b/sandbox/code-block-directive/docs/myfunction.py.pseudoxml
@@ -1,15 +1,25 @@
-<document source="/home/milde/.python/PyLit/trunk/rstdocs/features/myfunction.py.txt">
-    <decoration>
-        <footer>
-            <paragraph>
-                Generated on: 2007-06-05.
+<document source="/home/milde/Code/Python/docutils-svn/sandbox/code-block-directive/docs/myfunction.py.txt">
     <paragraph>
-        This is a test of the new code-block directive:
+        This is a test of the new "code" directive:
     <comment xml:space="preserve">
         Translate this document to HTML with a pygments enhanced frontend, e.g.
         
-        rst2html-highlight --stylesheet=pygments-default.css --link-stylesheet
-    <literal_block classes="code-block python" raw_content="[u'def my_function():', u'    "just a test"', u'    print 8/2']" xml:space="preserve">
+        ../rst2html-highlight.py --stylesheet=../data/pygments-default.css
+        
+        ../rst2latex-highlight.py --stylesheet=../data/pygments-docutilsroles.sty
+        
+        ../rst2pseudoxml-highlight.py
+    <paragraph>
+        The example from Docutils TODO list:
+    <literal_block classes="code pythonsi" xml:space="preserve">
+        print 'This is Python code.'
+           for i in range(10):
+               print i
+    <paragraph>
+        Another example:
+    <literal_block classes="code python silly" ids="my-function" names="my-function" xml:space="preserve">
+        <inline classes="ln">
+             7 
         <inline classes="k">
             def
          
@@ -18,10 +28,31 @@
         <inline classes="p">
             ():
         
+        <inline classes="ln">
+             8 
+            
+        <inline classes="sd">
+            """Test the lexer.
+        <inline classes="ln">
+             9 
+        <inline classes="sd">
+            
+        <inline classes="ln">
+            10 
+        <inline classes="sd">
+                just a test"""
+        
+        <inline classes="ln">
+            11 
+        
+        <inline classes="ln">
+            12 
             
-        <inline classes="s">
-            "just a test"
+        <inline classes="c">
+            # and now for something completely different
         
+        <inline classes="ln">
+            13 
             
         <inline classes="k">
             print
@@ -32,4 +63,5 @@
             /
         <inline classes="mi">
             2
-        
+    <paragraph>
+        The end.
diff --git a/sandbox/code-block-directive/docs/myfunction.py.tex b/sandbox/code-block-directive/docs/myfunction.py.tex
index c72da4eac..5a7721295 100644
--- a/sandbox/code-block-directive/docs/myfunction.py.tex
+++ b/sandbox/code-block-directive/docs/myfunction.py.tex
@@ -44,20 +44,43 @@
 
 This is a test of the new ``code'' directive:
 
-% Translate this document to HTML with a pygments enhanced frontend, e.g.
+% Translate this document with a pygments enhanced frontend, e.g.
 % 
-% ../rst2html-highlight --stylesheet=../data/pygments-default.css
+%  ../rst2html-highlight.py --stylesheet=../data/pygments-default.css
+%  ../rst2latex-highlight.py --stylesheet=../data/pygments-docutilsroles.sty
 % 
-% ../rst2latex-highlight --stylesheet=../data/pygments-docutilsroles.sty
+% or via the test case in
+% 
+%  ../pygments_code_block_directive.py --traceback
+
+The example from Docutils TODO list:
+%
+\begin{quote}{\ttfamily \raggedright \noindent
+\DUrole{k}{print}~\DUrole{s}{'This~is~Python~code.'}~\\
+\DUrole{k}{for}~\DUrole{n}{i}~\DUrole{ow}{in}~\DUrole{nb}{range}\DUrole{p}{(}\DUrole{mi}{10}\DUrole{p}{):}~\\
+~~~~\DUrole{k}{print}~\DUrole{n}{i}
+}
+\end{quote}
+
+Numbered lines:
+%
+\begin{quote}{\ttfamily \raggedright \noindent
+\DUrole{ln}{1~}\DUrole{c}{\#~This~is~Python~code,}~\\
+\DUrole{ln}{2~}\DUrole{c}{\#~that~prints~the~integers~from~0~to~9}~\\
+\DUrole{ln}{3~}\DUrole{k}{for}~\DUrole{n}{i}~\DUrole{ow}{in}~\DUrole{nb}{range}\DUrole{p}{(}\DUrole{mi}{10}\DUrole{p}{):}~\\
+\DUrole{ln}{4~}~~~~\DUrole{k}{print}~\DUrole{n}{i}
+}
+\end{quote}
+
+Another example:
 %
 \begin{quote}{\ttfamily \raggedright \noindent
 \DUrole{ln}{~7~}\DUrole{k}{def}~\DUrole{nf}{my\_function}\DUrole{p}{():}~\\
 \DUrole{ln}{~8~}~~~~\DUrole{sd}{"{}"{}"Test~the~lexer.\\
-}\DUrole{ln}{~9~}\DUrole{sd}{~\\
-}\DUrole{ln}{10~}\DUrole{sd}{~~~~just~a~test"{}"{}"}~\\
-\DUrole{ln}{11~}~\\
-\DUrole{ln}{12~}~~~~\DUrole{c}{\#~and~now~for~something~completely~different}~\\
-\DUrole{ln}{13~}~~~~\DUrole{k}{print}~\DUrole{mi}{8}\DUrole{o}{/}\DUrole{mi}{2}
+}\DUrole{ln}{~9~}\DUrole{sd}{~~~~"{}"{}"}~\\
+\DUrole{ln}{10~}~\\
+\DUrole{ln}{11~}~~~~\DUrole{c}{\#~and~now~for~something~completely~different}~\\
+\DUrole{ln}{12~}~~~~\DUrole{k}{print}~\DUrole{mi}{8}\DUrole{o}{/}\DUrole{mi}{2}
 }
 \end{quote}
 
diff --git a/sandbox/code-block-directive/docs/myfunction.py.txt b/sandbox/code-block-directive/docs/myfunction.py.txt
index b9727e96f..cce27ea52 100644
--- a/sandbox/code-block-directive/docs/myfunction.py.txt
+++ b/sandbox/code-block-directive/docs/myfunction.py.txt
@@ -1,19 +1,43 @@
 This is a test of the new "code" directive:
 
-.. Translate this document to HTML with a pygments enhanced frontend, e.g.
+.. Translate this document with a pygments enhanced frontend, e.g.
 
-    ../rst2html-highlight --stylesheet=../data/pygments-default.css
+    ../rst2html-highlight.py --stylesheet=../data/pygments-default.css
+    ../rst2latex-highlight.py --stylesheet=../data/pygments-docutilsroles.sty
+    
+   or via the test case in
+   
+    ../pygments_code_block_directive.py --traceback
+    
 
-    ../rst2latex-highlight --stylesheet=../data/pygments-docutilsroles.sty
+The example from Docutils TODO list:
+
+.. code:: python
+
+  print 'This is Python code.'
+  for i in range(10):
+      print i
+
+Numbered lines:
+
+.. code:: python
+  :number-lines:
+
+  # This is Python code,
+  # that prints the integers from 0 to 9
+  for i in range(10):
+      print i
+
+Another example:
 
 .. code:: python
   :class: silly
+  :name: my_function
   :number-lines: 7
 
   def my_function():
       """Test the lexer.
-
-      just a test"""
+      """
 
       # and now for something completely different
       print 8/2
diff --git a/sandbox/code-block-directive/docs/myfunction.py.xml b/sandbox/code-block-directive/docs/myfunction.py.xml
index 564e57e17..15e883899 100644
--- a/sandbox/code-block-directive/docs/myfunction.py.xml
+++ b/sandbox/code-block-directive/docs/myfunction.py.xml
@@ -1,10 +1,18 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
+<?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML" "http://docutils.sourceforge.net/docs/ref/docutils.dtd">
-<!-- Generated by Docutils 0.4.1 -->
-<document source="/home/milde/.python/PyLit/trunk/rstdocs/features/myfunction.py.txt"><decoration><footer><paragraph>Generated on: 2007-06-05.
-</paragraph></footer></decoration><paragraph>This is a test of the new code-block directive:</paragraph><comment xml:space="preserve">Translate this document to HTML with a pygments enhanced frontend, e.g.
+<!-- Generated by Docutils 0.9 -->
+<document source="/home/milde/Code/Python/docutils-svn/sandbox/code-block-directive/docs/myfunction.py.txt"><paragraph>This is a test of the new &quot;code&quot; directive:</paragraph><comment xml:space="preserve">Translate this document to HTML with a pygments enhanced frontend, e.g.
 
-rst2html-highlight --stylesheet=pygments-default.css --link-stylesheet</comment><literal_block classes="code-block python" raw_content="[u'def my_function():', u'    &quot;just a test&quot;', u'    print 8/2']" xml:space="preserve"><inline classes="k">def</inline> <inline classes="nf">my_function</inline><inline classes="p">():</inline>
-    <inline classes="s">&quot;just a test&quot;</inline>
-    <inline classes="k">print</inline> <inline classes="mi">8</inline><inline classes="o">/</inline><inline classes="mi">2</inline>
-</literal_block></document>
+../rst2html-highlight.py --stylesheet=../data/pygments-default.css
+
+../rst2latex-highlight.py --stylesheet=../data/pygments-docutilsroles.sty
+
+../rst2pseudoxml-highlight.py</comment><paragraph>The example from Docutils TODO list:</paragraph><literal_block classes="code python" xml:space="preserve"><inline classes="k">print</inline> <inline classes="s">'This is Python code.'</inline>
+   <inline classes="k">for</inline> <inline classes="n">i</inline> <inline classes="ow">in</inline> <inline classes="nb">range</inline><inline classes="p">(</inline><inline classes="mi">10</inline><inline classes="p">):</inline>
+       <inline classes="k">print</inline> <inline classes="n">i</inline></literal_block><paragraph>Another example:</paragraph><literal_block classes="code python ['silly']" ids="my-function" names="my-function" xml:space="preserve"><inline classes="ln"> 7 </inline><inline classes="k">def</inline> <inline classes="nf">my_function</inline><inline classes="p">():</inline>
+<inline classes="ln"> 8 </inline>    <inline classes="sd">&quot;&quot;&quot;Test the lexer.
+</inline><inline classes="ln"> 9 </inline><inline classes="sd">
+</inline><inline classes="ln">10 </inline><inline classes="sd">    just a test&quot;&quot;&quot;</inline>
+<inline classes="ln">11 </inline>
+<inline classes="ln">12 </inline>    <inline classes="c"># and now for something completely different</inline>
+<inline classes="ln">13 </inline>    <inline classes="k">print</inline> <inline classes="mi">8</inline><inline classes="o">/</inline><inline classes="mi">2</inline></literal_block><paragraph>The end.</paragraph></document>
diff --git a/sandbox/code-block-directive/docs/pygments_with_docutils-latex-problems.txt b/sandbox/code-block-directive/docs/pygments_with_docutils-latex-problems.txt
deleted file mode 100644
index 99ca7a48f..000000000
--- a/sandbox/code-block-directive/docs/pygments_with_docutils-latex-problems.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-Now to some of the details (This is rather for LaTeX inclined
-
-> > * latex-output seems even less usable.
-
-This is actually an understatement:
-
-Currently, an inline node with a class unknown to the latex writer like::
-
-  <inline classes="keyword">
-            def
-
-is converted to a function::
-
-  \docutilsroleNone{def}
-
-which is not defined in the preamble and hence leads to an error if the
-documents is translated to PDF.
-
-IMO, the missing feature is a "failsave" handling of class information:
-
-  In HTML, the semantic syntax markup can be simply stored in a class
-  argument to a <span> element. It can be used by the CSS stylesheet for
-  syntax highlight and is simply ignored if no CSS rule for the given
-  class exists.
-
-LaTeX does not have a "class" attribute, so some emulation of this
-concept is needed. Maybe we can use a \newcommand with optional argument?
diff --git a/sandbox/code-block-directive/docs/syntax-highlight.txt b/sandbox/code-block-directive/docs/syntax-highlight.txt
index 10ea6f91b..d87967995 100644
--- a/sandbox/code-block-directive/docs/syntax-highlight.txt
+++ b/sandbox/code-block-directive/docs/syntax-highlight.txt
@@ -43,13 +43,6 @@ State of the art
 
 There are already docutils extensions providing syntax colouring, e.g:
 
-SilverCity_,
-  a C++ library and Python extension that can provide lexical
-  analysis for over 20 different programming languages. A recipe__ for a
-  "code-block" directive provides syntax highlight by SilverCity.
-
-__ http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252170
-
 `listings`_,
   Since Docutils 0.5, the "latex2e" writer supports syntax highlight of
   literal blocks via the `listings` package with the
@@ -57,11 +50,20 @@ __ http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252170
   style sheet. The stylesheets_ repository provides two LaTeX style sheets
   for highlighting literal-blocks with "listings".
 
-Trac_
-  has `reStructuredText support`__ and offers syntax highlighting with
-  a "code-block" directive using GNU Enscript_, SilverCity_, or Pygments_.
+Odtwriter_, experimental writer for Docutils OpenOffice export supports syntax
+  colours using Pygments_. See also the (outdated) section `Odtwriter syntax`_.
 
-__ http://trac.edgewall.org/wiki/WikiRestructuredText
+Pygments_
+  is a generic syntax highlighter written completely in Python.
+
+  * Usable as a command-line tool and as a Python package.
+  * Supports about 200 `languages and markup formats`_ (version 1.4).
+  * Already used by the odtwriter_ and Sphinx.
+  * Support for new languages, formats, and styles is added easily (modular
+    structure, Python code, existing documentation).
+  * Well documented and actively maintained.
+  * The web site provides a recipe for `using Pygments in ReST documents`_
+    (used in the legacy `Pygments enhanced docutils front-ends`_).
 
 rest2web_,
   the "site builder" provides the `colorize`__ macro (using the
@@ -69,6 +71,12 @@ rest2web_,
 
 __ http://www.voidspace.org.uk/python/rest2web/macros.html#colorize
 
+SilverCity_,
+  a C++ library and Python extension that can provide lexical
+  analysis for over 20 different programming languages. A recipe__ for a
+  "code-block" directive provides syntax highlight by SilverCity.
+
+__ http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252170
 
 Sphinx_
   features automatic highlighting using the Pygments_ highlighter.
@@ -80,23 +88,12 @@ Sphinx_
 
   (see http://sphinx.pocoo.org/markup/code.html).
 
-Pygments_
-  is a generic syntax highlighter written completely in Python.
+Trac_
+  has `reStructuredText support`__ and offers syntax highlighting with
+  a "code-block" directive using GNU Enscript_, SilverCity_, or Pygments_.
 
-  * Usable as a command-line tool and as a Python package.
-  * A wide range of common `languages and markup formats`_ is supported.
-  * Additionally, OpenOffice's ``*.odt`` is supported by the odtwriter_.
-  * The layout is configurable by style sheets.
-  * Several built-in styles and an option for line-numbering.
-  * Built-in output formats include HTML, LaTeX, rtf
-  * Support for new languages, formats, and styles is added easily (modular
-    structure, Python code, existing documentation).
-  * Well documented and actively maintained.
-  * The web site provides a recipe for `using Pygments in ReST documents`_.
-    It is used in the `Pygments enhanced docutils front-ends`_ below.
+__ http://trac.edgewall.org/wiki/WikiRestructuredText
 
-Odtwriter_, experimental writer for Docutils OpenOffice export supports syntax
-  colours using Pygments_. (See the (outdated) section `Odtwriter syntax`_.)
 
 Summary
 """""""
@@ -153,7 +150,7 @@ Syntax
 :Directive Type: "code"
 :Doctree Element: literal_block
 :Directive Arguments: One (`language`), optional.
-:Directive Options: name, class.
+:Directive Options: name, class, number-lines.
 :Directive Content: Becomes the body of the literal block.
 
 The "code-block" directive constructs a literal block where the content is
@@ -162,8 +159,19 @@ If syntax rules for `language` are not known to Docutils, a warning is
 issued and the content is rendered as ordinary literal block with
 additional class arguments: "code" and the value of `language`.
 
+  :number-lines: let pygments include line-numbers
+
+
+The following options are recognized:
+
+``number-lines`` : [start line number]
+    Precede every code line with a line number.
+    The optional argument is the number of the first line (defaut 1).
+
+and the common options `:class:`_ and `:name:`_.
+
 Example::
-  The Python code snippet ::
+  The content of the following directive ::
 
    .. code:: python
 
@@ -171,10 +179,12 @@ Example::
         "just a test"
         print 8/2
 
-  will be parsed and marked up as Python source code. The actual rendering
+  is parsed and marked up as Python source code. The actual rendering
   depends on the style-sheet.
 
-Remarks:
+
+Remarks
+"""""""
 
 * Without language argument, the parsing step is skipped. Use cases:
 
@@ -186,14 +196,13 @@ Remarks:
     the listings_ package).
 
   The language's name can be given as `class` option.
-  
-  Alternative: 
-    make the `language` argument compulsory and add a "no-parsing" option.
 
-* Additional arguments might be defined and passed to the pygments_
-  parser.
+  Alternative:
+    make the `language` argument compulsory and add a "no-highlight" option.
+
+* TODO: Pygments_ provides filters like VisibleWhitespaceFilter
+  add options to use them?
 
-  :number-lines: let pygments include line-numbers
 
 
 Include directive option
author	milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>	2011-08-26 22:23:29 +0000
committer	milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>	2011-08-26 22:23:29 +0000
commit	b991feb7b06e99b2186fc533733905da9312f5d3 (patch)
tree	9da9826e25d07a95e86d0f0ed8c711ba13305e92 /sandbox/code-block-directive/docs
parent	0ffd4b2d58dbf67c4f35be718de8e69de2210c92 (diff)
download	docutils-b991feb7b06e99b2186fc533733905da9312f5d3.tar.gz