sandbox/code-block-directive/tools/pygments-enhanced-front-ends/README.txt

   1 .. -*- rst-mode -*-
   2
   3 Pygments enhanced docutils front-ends
   4 -------------------------------------
   5
   6 The example code in "`Using Pygments in ReST documents`_" defines a new
   7 "sourcecode" directive. The directive takes one argument `language` and uses
   8 the `Pygments`_ source highlighter to parse and render its content as a
   9 colourful source code block.
  10
  11 Combining the pygments_ example code with the standard docutils_ front-ends,
  12 results in front-end scripts generating output documents with syntax colour.
  13 For consistency with the majority of existing add-ons, the directive is
  14 renamed to "code-block".
  15
  16 `rst2html-pygments`_
  17   enhances the standard docutils ``rst2html`` front-end to
  18   generate a HTML rendering with syntax highlight.
  19
  20 `rst2latex-pygments`_
  21   enhances docutils' ``rst2latex`` to generate LaTeX with syntax highlight.
  22
  23 Advantages:
  24   + Easy implementation with no changes to the stock docutils_.
  25   + Separation of code blocks and ordinary literal blocks.
  26
  27 Disadvantages:
  28   - "code-block" content is formatted by `pygments`_ and inserted in the
  29     document tree as a "raw" node making the approach writer-dependant.
  30   - documents are incompatible with the standard docutils because of the
  31     locally defined directive.
  32   - more "invasive" markup distracting from content
  33   - no "minimal" code block marker -- three additional lines per code block
  34
  35
  36 The disadvantages lead to the alternative implementation with the
  37 demonstrator front ends `rst2html-highlight`_ and `rst2latex-highlight`_.
  38
  39
  40 Example
  41 """""""
  42
  43 Python script:
  44   :text source: `for-else-test.py.txt`_
  45   :HTML:   `for-else-test.py.htm`_
  46   :LaTeX:  `for-else-test.py.tex`_
  47   :PDF:    `for-else-test.py.pdf`_
  48
  49 Stylesheets:
  50   :CSS stylesheet:  `pygments-default.css`_
  51   :LaTeX style:     `pygments-default.sty`_
  52
  53 .. References
  54
  55 .. _pygments: http://pygments.org/
  56 .. _docutils: http://docutils.sourceforge.net/
  57 .. _Using Pygments in ReST documents: http://pygments.org/docs/rstdirective/
  58
  59 .. _rst2html-pygments:    rst2html-pygments
  60 .. _rst2latex-pygments:   rst2latex-pygments
  61 .. _rst2html-highlight:    ../../rst2html-highlight
  62 .. _rst2latex-highlight:   ../../rst2latex-highlight
  63 .. _for-else-test:
  64 .. _for-else-test.py.htm: for-else-test.py.htm
  65 .. _for-else-test.py.txt: for-else-test.py.txt
  66 .. _for-else-test.py.tex: for-else-test.py.tex
  67 .. _for-else-test.py.pdf: for-else-test.py.pdf
  68 .. _pygments-default.css: ../../data/pygments-default.css
  69 .. _pygments-default.sty: ../../data/pygments-default.sty