.. -*- rst-mode -*-

Pygments enhanced docutils front-ends
-------------------------------------

The example code in "`Using Pygments in ReST documents`_" defines a new
"sourcecode" directive. The directive takes one argument `language` and uses
the `Pygments`_ source highlighter to parse and render its content as a
colourful source code block. 

Combining the pygments_ example code with the standard docutils_ 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 "code-block".

`rst2html-pygments`_ 
  enhances the standard docutils ``rst2html`` front-end to
  generate a HTML rendering with syntax highlight. 
  
`rst2latex-pygments`_ 
  enhances docutils' ``rst2latex`` to generate LaTeX with syntax highlight.

Advantages:
  + Easy implementation with no changes to the stock docutils_. 
  + Separation of code blocks and ordinary literal blocks.

Disadvantages:
  - "code-block" content is formatted by `pygments`_ and inserted in the
    document tree as a "raw" node making the approach writer-dependant.
  - documents are incompatible with the standard docutils because of the
    locally defined directive.
  - more "invasive" markup distracting from content
  - no "minimal" code block marker -- three additional lines per code block


Example
"""""""

Python script:
  :text source: `for-else-test.py.txt`_
  :HTML:   `for-else-test.py.htm`_
  :LaTeX:  `for-else-test.py.tex`_
  :PDF:    `for-else-test.py.pdf`_

Stylesheets:
  :CSS stylesheet:  `pygments-default.css`_
  :LaTeX style:     `pygments-default.sty`_

.. References

.. _pygments: http://pygments.org/
.. _docutils: http://docutils.sourceforge.net/
.. _Using Pygments in ReST documents: http://pygments.org/docs/rstdirective/

.. _rst2html-pygments:    rst2html-pygments
.. _rst2latex-pygments:   rst2latex-pygments
.. _for-else-test:
.. _for-else-test.py.htm: for-else-test.py.htm
.. _for-else-test.py.txt: for-else-test.py.txt
.. _for-else-test.py.tex: for-else-test.py.tex
.. _for-else-test.py.pdf: for-else-test.py.pdf
.. _pygments-default.css: ../data/pygments-default.css
.. _pygments-default.sty: ../data/pygments-default.sty
