diff options
Diffstat (limited to 'sandbox/code-block-directive/docs/syntax-highlight.txt')
| -rw-r--r-- | sandbox/code-block-directive/docs/syntax-highlight.txt | 91 |
1 files changed, 48 insertions, 43 deletions
diff --git a/sandbox/code-block-directive/docs/syntax-highlight.txt b/sandbox/code-block-directive/docs/syntax-highlight.txt index a5d6ffc34..a71cc5b77 100644 --- a/sandbox/code-block-directive/docs/syntax-highlight.txt +++ b/sandbox/code-block-directive/docs/syntax-highlight.txt @@ -3,11 +3,15 @@ Syntax Highlight ================ -:Author: Günter Milde -:Contact: milde@users.berlios.de -:Date: $Date$ -:Abstract: Proposal to add syntax highlight of code blocks to the - capabilities of Docutils_. +:Author: Günter Milde +:Contact: milde@users.berlios.de +:Date: $Date$ +:Copyright: © 2007, 2009 G. Milde, + Released without warranties or conditions of any kind + under the terms of the Apache License, Version 2.0 + http://www.apache.org/licenses/LICENSE-2.0 +:Abstract: Proposal to add syntax highlight of code blocks to the + capabilities of Docutils_. .. sectnum:: .. contents:: @@ -47,10 +51,11 @@ __ http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252170 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 supports - syntax highlight of literal blocks by `listings` with the - ``--literal-block-env=lstlistings`` option. You need to provide a - stylesheet (see also `PyLit Examples`_). + Since Docutils 0.5, the "latex2e" writer supports syntax highlight of + literal blocks by `listings` with the ``--literal-block-env=lstlistings`` + option. You need to provide a custom 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 @@ -67,12 +72,12 @@ __ http://www.voidspace.org.uk/python/rest2web/macros.html#colorize Sphinx_ features automatic highlighting using the Pygments_ highlighter. - It introduces the custom directives - + It introduces the custom directives + :code-block: similar to the proposal below, :sourcecode: an alias to "code-block", and :highlight: configre highlight of "literal blocks". - + (see http://sphinx.pocoo.org/markup/code.html). Pygments_ @@ -93,8 +98,13 @@ Pygments_ Odtwriter_, experimental writer for Docutils OpenOffice export supports 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. +Summary +""""""" + +Pygments_ seems to be the most promising Docutils highlighter. + +For printed output and PDFs via LaTeX, the listings_ package is a viable +alternative. Pygments enhanced docutils front-ends @@ -199,9 +209,6 @@ directive. * The ``code_block_directive`` function inserts the tokens in a "rich" <literal_block> element with "classified" <inline> nodes. -The XML rendering of the small example file `<myfunction.py.txt>`_ looks like -`<myfunction.py.xml>`_. - Writing ''''''' @@ -209,53 +216,51 @@ 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 use it or to pass it on. +Running the test script `<../tools/test_pygments_code_block_directive.py>`_ +produces example output for a set of writers. + HTML The "html" writer works out of the box. * The rst2html-highlight_ front end registers the "code-block" directive and converts an input file to html. + * Styling is done with the adapted CSS style sheet `pygments-default.css`_ based on docutils' default stylesheet and the output of ``pygmentize -S default -f html``. - + The conversion of `myfunction.py.txt`_ looks like `<myfunction.py.htm>`_. The "s5" and "pep" writers are not tested yet. XML - "xml" and "pseudoxml" work out of the box. - + "xml" and "pseudoxml" work out of the box. + The conversion of `myfunction.py.txt`_ looks like - `<myfunction.py.xml>`_ and `<myfunction.py.pseudoxml>`_ + `<myfunction.py.xml>`_ respective `<myfunction.py.pseudoxml>`_ LaTeX - "latex2e" (SVN version) works out of the box. - - * A style file is required to actually highlight the code in the - output. (As with HTML, the pygments-produced style file will not work - with docutils' output.) - + "latex2e" (SVN version) works out of the box. + + * A style file, e.g. `pygments-docutilsroles.sty`_, is required to actually + highlight the code in the output. (As with HTML, the pygments-produced + style file will not work with docutils' output.) + * Alternatively, the latex writer could reconstruct the original - content and pass it to a ``lstlistings`` environment. - + content and pass it to a ``lstlistings`` environment. + TODO: This should be the default behaviour with ``--literal-block-env=lstlistings``. - - The conversion of `myfunction.py.txt`_ looks like - `<myfunction.py.tex>`_ and converted with pdflatex (without style - sheet) like `<myfunction.py.pdf>`_ - "newlatex2e" produces a valid LaTeX document - (`<myfunction.py.newlatex2e.tex>`_). There is some garbage in the - pdflatex output (`<myfunction.py.newlatex2e.pdf>`_) but this might be - unrelated to the code-block directive. + The LaTeX output of `myfunction.py.txt`_ looks like `<myfunction.py.tex>`_ + and corresponding PDF like `<myfunction.py.pdf>`_. OpenOffice The sandbox project `odtwriter` provided syntax highlight with pygments but used a different syntax and implementation. - - (What is the status of the official `odtwriter` now included in the + + (What is the status of the `odtwriter` now included in the standard distribution?) @@ -268,7 +273,7 @@ TODO place". * add the CSS rules to the default style-sheet (see pygments-default.css_) - + * provide a LaTeX style. 2. Write functional test case and sample. @@ -354,10 +359,10 @@ Odtwriter syntax ---------------- .. attention:: - The content of this section relates to an old version of the + The content of this section relates to an old version of the `odtwriter`. Things changed with the inclusion of the `odtwriter` into standard Docutils. - + This is only kept for historical reasons. Dave Kuhlman's odtwriter_ extension can add syntax highlighting @@ -438,4 +443,4 @@ I.e. the odtwriter implements a `configurable literal block directive`_ .. _pygments_code_block_directive: pygments_code_block_directive-bunt.py.htm .. _rst2html-highlight: ../rst2html-highlight .. _pygments-long.css: ../data/pygments-long.css - +.. _stylesheets: ../../stylesheets/ |