Index of /sandbox/code-block-directive/tools/pygments-enhanced-front-ends

[ICO]NameLast modifiedSizeDescription

[PARENTDIR]Parent Directory   -  
[   ]for-else-test.py.pdf 2012-01-03 12:41 76K 
[TXT]for-else-test.py.htm 2012-01-03 12:41 8.8K 
[   ]for-else-test.py.tex 2012-01-03 12:41 4.8K 
[TXT]rst2latex-pygments 2012-01-03 12:41 2.0K 
[TXT]rst2html-pygments 2012-01-03 12:41 2.0K 
[TXT]for-else-test.py 2012-01-03 12:41 1.8K 
[TXT]for-else-test.py.txt 2012-01-03 12:41 1.8K 

Pygments enhanced docutils front-ends

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

The disadvantages lead to the alternative implementation with the demonstrator front ends rst2html-highlight and rst2latex-highlight.

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