Bring the syntax-highlight proposal up to date

latex2e writer now supports listings, 
alternative "high level" and "low level" implementation proposals.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@5662 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 79 insertions, 57 deletions

diff --git a/sandbox/code-block-directive/docs/syntax-highlight.txt b/sandbox/code-block-directive/docs/syntax-highlight.txt
index 7f7d1a1e2..ba7c3599e 100644
--- a/sandbox/code-block-directive/docs/syntax-highlight.txt
+++ b/sandbox/code-block-directive/docs/syntax-highlight.txt
@@ -38,12 +38,16 @@ SilverCity_,
 __ http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252170
 
 `listings`_,
-  a LaTeX package providing highly customisable and advanced
-  syntax highlight, though only for LaTeX (and LaTeX derived PS|PDF). 
-  See also section `listings.sty`_ and a proposal__ Gael Varoquaux.
+  a LaTeX package providing highly customisable and advanced syntax
+  highlight, though only for LaTeX (and LaTeX derived PS|PDF).  
+  
+  Since Docutils 0.5, the latex2e writer (and rst2latex.py) support
+  syntax highlight of literal blocks by `listings` with the
+  ``--literal-block-env=listings`` option. You need to provide a
+  stylesheet (see also `Pylit Examples`_)
+  
+.. _Pylit Examples: http://pylit.berlios.de/examples/index.html#latex-packages
   
-__ http://article.gmane.org/gmane.text.docutils.devel/3914
-
 Trac_ 
   has `reStructuredText support`__ and offers syntax highlighting with
   a "code-block" directive using GNU Enscript_, SilverCity_, or Pygments_.
@@ -72,7 +76,7 @@ Pygments_
     It is used in the `Pygments enhanced docutils front-ends`_ below.
 
 Odtwriter_, experimental writer for Docutils OpenOffice export supports syntax
-  colours using Pygments. (See section `Odtwriter syntax`_.)
+  colours using Pygments_. (See (the outdated) section `Odtwriter syntax`_.)
 
 Pygments_ seems to be the most promising docutils highlighter. For printed
 output, the listings_ package has its advantages too.
@@ -97,10 +101,11 @@ Disadvantages:
      (no "minimal" code block marker -- three additional lines per code block)
 
 
-Point 1 and 2 lead to the `code-block directive proposal`_. Point 3
-becomes an issue in literate programming where a code block is the most used
-block markup. It is addressed in the proposal for a `configurable literal
-block directive`_).
+Point 1 and 2 lead to the `code-block directive proposal`_. 
+
+Point 3 becomes an issue in literate programming where a code block is
+the most used block markup. It is addressed in the proposal for a
+`configurable literal block directive`_).
 
 
 `code-block` directive proposal
@@ -109,19 +114,19 @@ block directive`_).
 Syntax
 """"""
 
-This is the first draft for the definition analogue to other directives in 
-``directives.txt``. Comments welcome.
+This is the first draft for a reStructuredText definition, analogue to
+other directives in ``directives.txt``.
 
 :Directive Type: "code-block"
 :Doctree Element: literal_block
-:Directive Arguments: One or more, optional (class names).
+:Directive Arguments: One (`language`) or more (class names), optional.
 :Directive Options: None.
 :Directive Content: Becomes the body of the literal block.
 
-Unlike an ordinary literal block, the "code-block" directive constructs a
-literal block where the text is parsed as source code and syntax highlight
-rules for `language` are applied. If syntax rules for `language` are not
-known to docutils, it is rendered like an ordinary literal block.
+The "code-block" directive constructs a literal block where the content is
+parsed as source code and syntax highlight rules for `language` are
+applied. If syntax rules for `language` are not known to docutils, it
+is rendered like an ordinary literal block.
 
 For example, the following snipped is parsed and marked up as python source 
 code. The actual rendering depends on the style-sheet. ::
@@ -137,8 +142,37 @@ Additional arguments might be used and e.g. passed to the pygments_ parser
 or (as class arguments) the output document.
 
 
+Implementation
+""""""""""""""
+
+Alternatives
+''''''''''''
+
+There are 2 alternatives for the implementation of a code-block directive:
+
+hight level markup
+   modeled on the ideas for the planned math-mode directive:
+   
+   * Store the content as-is in the doctree and tag it as source code of
+     lanugage `language` (i.e. store a literal-block element with
+     "code-block" and "`language`" classes).
+   
+   * Write according to the writers possibilities and user settings
+     (parse and mark-up by the writer (or backend) or render as
+     monospaced).
+
+low level markup:
+   result of the past discussion for the planned source-code directive:
+
+   * Parse the content while reading and store as "rich" literal block.
+     
+   * Write similar to a "parsed-literal" block. Styling via style-sheet
+     is possible.
+
+The following concept implements "low level markup".
+
 Reading
-"""""""
+'''''''
 
 Felix Wiemann provided a `proof of concept`_ script that utilizes the
 pygments_ parser to parse a source code string and store the result in
@@ -160,7 +194,7 @@ The XML rendering of the small example file `myfunction.py.txt`_ looks like
 `myfunction.py.xml`_.
 
 Writing
-"""""""
+'''''''
 
 The writers can use the class information in the <inline> elements to render
 the tokens. They should ignore the class information if they are unable to
@@ -196,16 +230,22 @@ LaTeX
     
     The pygments-produced style file will not currently work with
     "newlatex2e" output. 
+    
+  The "high level markup" alternative would be easier to implement in
+  LaTeX.
   
 OpenOffice 
   The non-official "odtwriter" provides syntax highlight with
-  pygments but uses a different syntax.
+  pygments but uses a different syntax and implementation.
 
 
 TODO
 """"
 
-* fix the "latex" writers.
+* decide on "low level" or "high level" markup.
+
+* fix the "latex" writers (difficult for "low level markup" as LaTeX
+  has no concept of "object classes").
 
 * think about an interface for pygments' options (like "encoding" or
   "linenumbers").
@@ -250,56 +290,49 @@ use::
 
   .. default-role:: subscript
   
-  The triple point of H\ `2`\O is at 0°C.
+  The triple point of H\ `2`\O is at 0°C.
 
 .. default-role:: subscript
 
 to produce 
   
-  The triple point of H\ `2`\O is at 0°C.
+  The triple point of H\ `2`\O is at 0°C.
 
 This customisation is currently not possible for block markup.
 
 Proposal
 """"""""
 
-* Define a new "literal" directive for an ordinary literal block.
-  This would insert the block content into the document tree as
-  "literal-block" element with no parsing.
-
-* Define a "literal-block" setting that controls which directive is called
-  on a block following ``::``. Default would be the "literal" directive.
-  
-  Alternatively, define a new "default-literal-block" directive instead of
-  a settings key.
+* Define a new "literal-block" directive syntax for an ordinary literal
+  block. This would simply insert the block content into the document
+  tree as "literal-block" element.
 
-* From a syntax view, this would be analog to the behaviour of the odtwriter_.
-  (I am not sure about the representation in the document tree, though.)
+* Define a "default-literal-block" setting that controls which
+  directive is called on a block following ``::``. Default would be the
+  "literal-block" directive (backwards compatible).
 
-Motive
-""""""
+Motivation
+""""""""""
 
 Analogue to customising the default role of "interpreted text" with the
 "default-role" directive, the concise ``::`` literal-block markup could be
 used for e.g.
 
-* a "code-block" or "sourcecode" directive for colourful code 
-  (analog to the one in the `pygments enhanced docutils front-ends`_)
+* a "code-block" directive for syntax highight
 
 * the "line-block" directive for poems or addresses
 
 * the "parsed-literal" directive
 
-Example (using the upcoming "settings" directive)::
+Example::
 
   ordinary literal block::
   
      some text typeset in monospace
 
-  .. settings::
-     :literal-block:  code-block python
+  .. default-literal-block::  code-block python
      
-  colourful Python code::
+  this is colourful Python code::
      
      def hello():
          print "hello world"
@@ -314,6 +347,10 @@ Odtwriter syntax
 Dave Kuhlman's odtwriter_ extension can add syntax highlighting
 to ordinary literal blocks.
 
+.. attention:: 
+   The following might no longer be true for the current version of
+   the odtwriter_.
+
 The ``--add-syntax-highlighting`` command line flag activates syntax
 highlighting in literal blocks. By default, the "python" lexer is used.
 
@@ -357,21 +394,6 @@ I.e. the odtwriter implements a `configurable literal block directive`_
 (but with a slightly different syntax than my proposal below).
 
 
-``listings.sty``
-----------------
-
-Using the listings_ LaTeX package for syntax highlight is currently not
-possible with the standard latex writer output. 
-
-Support for the use of listings_ with docutils is an issue that must be
-settled separate from the `code-block directive proposal`_. It needs
-
-* a new, specialized docutils latex writer, or
-* a new option (and behaviour) to the existing latex writer.
-
-Ideas and experimental code is in the Sandbox under `latex-variants`_.
-
-
 .. External links 
 .. _pylit: http://pylit.berlios.de
 .. _docutils: http://docutils.sourceforge.net/