rstdocs/features/syntax-highlight.txt

   1 .. -*- rst-mode -*-
   2 ..
   3   restindex
   4       crumb: Highlights
   5       page-title: Pylit - Features - Syntax Highlight
   6       file: rst2html-pygments
   7       file: rst2latex-pygments
   8       file: for-else-test.py.txt
   9       file: for-else-test.py.tex
  10       file: for-else-test.py.pdf
  11       file: for-else-test.py.html
  12       file: pygments-default.css
  13   /restindex
  14
  15 .. sectnum::
  16 .. contents::
  17
  18 Syntax Highlight
  19 ----------------
  20
  21 Syntax highlighting significantly enhances the readability of code.
  22 So it is almost a must for pretty-printing a literate program.
  23
  24 PyLit uses docutils_ as pretty-printing back end. However, in the current
  25 version, docutils does not highlight literal blocks. This may change in the
  26 future, as in a mail on
  27 `Questions about writing programming manuals and scientific documents`__,
  28 docutils main developer David Goodger wrote:
  29
  30    I'd be happy to include Python source colouring support, and other
  31    languages would be welcome too. A multi-language solution would be
  32    useful, of course. My issue is providing support for all output formats
  33    -- HTML and LaTeX and XML and anything in the future -- simultaneously.
  34    Just HTML isn't good enough. Until there is a generic-output solution,
  35    this will be something users will have to put together themselves.
  36
  37 __ http://sourceforge.net/mailarchive/message.php?msg_id=12921194
  38
  39
  40 There are already such add-ons providing syntax colouring. E.g
  41
  42 * the rest2web_ site builder provides the `colorize`__ macro (using the
  43   `Moin-Moin Python colorizer`_)
  44
  45 * the Odtwriter_ for Docutils supports syntax colours via the pygments_
  46   generic syntax highlighter.
  47
  48 __ http://www.voidspace.org.uk/python/rest2web/macros.html#colorize
  49
  50 * the `listings`_ LaTeX package provides highly customisable and advanced
  51   syntax highlight, though only for the LaTeX (and LaTeX derived PS|PDF)
  52   rendering.
  53
  54 * `Pygments`_ a generic syntax highlighter for general use.
  55
  56   * It is written completely in Python, usable as a command-line tool and as a
  57     Python package.
  58   * A wide range of common `languages and markup formats`_ is supported.
  59   * The layout is configurable by style sheets.
  60   * Several built-in styles and an option for line-numbering.
  61   * Built-in output formats include HTML, LaTeX, and rtf.
  62   * Support for new languages, formats, and styles is added easily (modular
  63     structure, Python code, existing documentation).
  64   * Well documented and actively maintained.
  65   * There is a recipe for `using Pygments in ReST documents`_.
  66
  67 Pygments seems to be the most promising docutils highlighter.
  68
  69
  70 Pygments enhanced docutils front-ends
  71 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  72
  73 The example code in "`Using Pygments in ReST documents`_" defines a new
  74 "sourcecode" directive.  The directive takes one argument `language` and
  75 uses the `Pygments`_ source highlighter to parse and render its content as a
  76 literal block with syntax colour.
  77
  78 Example::
  79
  80   .. sourcecode:: python
  81
  82      def hello():
  83          print "hello world"
  84
  85 Combining the pygments_ example code with the standard docutils_ front-ends,
  86 results in front-end scripts generating pretty-print with syntax highlight:
  87
  88 `rst2html-pygments`_
  89   enhances the standard docutils ``rst2html`` front-end to
  90   generate a HTML rendering with syntax highlight.
  91
  92 `rst2latex-pygments`_
  93   enhances docutils' ``rst2latex`` to generate LaTeX with syntax highlight.
  94
  95 Advantages:
  96   + Easy implementation with no changes needed for the stock docutils_.
  97   + Separation of code blocks and ordinary literal blocks.
  98
  99 Disadvantage:
 100   - more "invasive" markup distracting from content
 101   - no "minimal" code block marker -- three additional lines per code block
 102
 103 The disadvantages become a real issue in literate programming where a code
 104 block is expected to be the most used block markup.
 105
 106 Examples
 107 """"""""
 108
 109 example Python script:
 110   `for-else-test`_ investigates the command flow in a Python
 111   ``for ... else`` construct.
 112
 113   :text source: `for-else-test.py.txt`_
 114   :HTML:   `for-else-test.py.html`_
 115   :LaTeX:  `for-else-test.py.tex`_
 116   :PDF:    `for-else-test.py.pdf`_
 117
 118 Stylesheets:
 119   :CSS stylesheet:  `pygments-default.css`_
 120   :LaTeX style:     `pygments-default.sty`_
 121
 122
 123 To support this way of syntax highlight, the PyLit converter would need a
 124 configurable "code block marker" instead of the hard coded double colon
 125 (``::``) presently in use. (See also the `sourcecode directive`__ section in
 126 pylit.py.)
 127
 128 __ ../examples/pylit.py.html#sourcecode-directive
 129
 130
 131 Odtwriter syntax
 132 ~~~~~~~~~~~~~~~~
 133
 134 Dave Kuhlmans odtwriter_ extension can add Python syntax highlighting
 135 to ordinary literal blocks.
 136
 137 The ``--add-syntax-highlighting`` command line flag activates syntax
 138 highlighting in literal blocks. By default, the "python" lexer is used.
 139
 140 You can change this within your reST document with the `sourcecode`
 141 directive::
 142
 143   .. sourcecode:: off
 144
 145   ordinary literal block::
 146
 147      content set in teletype
 148
 149   .. sourcecode:: on
 150   .. sourcecode:: python
 151
 152   colourful Python code::
 153
 154      def hello():
 155          print "hello world"
 156
 157
 158 The "sourcecode" directive defined by the odtwriter is principally
 159 different from the "sourcecode" directive of ``rst2html-pygments``:
 160
 161 * The odtwriter directive does not have content. It is a switch.
 162
 163 * The syntax highlighting state and language/lexer set by this directive
 164   remain in effect until the next sourcecode directive is encountered in the
 165   reST document.
 166
 167   ``.. sourcecode:: <newstate>``
 168        make highlighting active or inactive.
 169        <newstate> is either ``on`` or ``off``.
 170
 171   ``.. sourcecode:: <lexer>``
 172        change the lexer parsing literal code blocks.
 173        <lexer> should be one of aliases listed at pygment's `languages and
 174        markup formats`_.
 175
 176
 177 The advantage of this approach is the clean and simple syntax for code
 178 blocks -- preserving the space saving feature of the "minimised" literal
 179 block marker (``::`` at the end of a text paragraph). This is especially
 180 handy in literate programs where there are many sourcecode blocks!
 181
 182
 183 Alternative syntax proposal
 184 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 185
 186 Ideas for a revised highlighting syntax based on the one in the
 187 odtwriter:
 188
 189 * A *command line option* ``--syntax-highlight=LEXER``
 190   tells the writer to apply syntax highlight to literal blocks.
 191
 192 * Turn of syntax highlight with ``--syntax-highlight=off`` or
 193   ``--no-syntax-highlight``.
 194
 195 * The corresponding *directive* should also be named "syntax-highlight"
 196   (instead of "sourcecode") because:
 197
 198   * it makes the relationship of command line option and directive more
 199     transparent,
 200
 201   * The name "sourcecode" leads me to assume that the directive
 202     contains source code that should be treated specially. It's a
 203     surprise to realise that the odtwriter's "sourcecode" directive
 204     is a switch without content.
 205
 206   * it disambiguates from the name proposed in `Using Pygments in ReST
 207     documents`_.
 208
 209   * with Pygments you can highlight not only source code but also
 210     config files and markup languages,
 211
 212   Example::
 213
 214     .. syntax-highlight:: off
 215
 216     ordinary literal block::
 217
 218        typeset in monospace
 219
 220     .. syntax-highlight:: python
 221
 222     colourful Python code::
 223
 224        def hello():
 225            print "hello world"
 226
 227
 228   Instead of a dedicated "syntax-highlight" directive, a settings
 229   key could be employed together with the upcoming "settings" directive.
 230
 231   Example::
 232
 233     .. settings::
 234        :syntax-highlight: bash
 235
 236
 237 * The syntax highlighting state and language/lexer set by this
 238   directive remain in effect until the next "syntax-highlight" directive
 239   is encountered in the reST document.
 240
 241 * In contrast to the current odtwriter, there is no "on" argument:
 242
 243   ``.. syntax-highlight:: LEXER``
 244        makes highlighting active and sets the Pygments lexer to use.
 245
 246   ``.. syntax-highlight:: off``
 247        turns off highlighting of literal blocks
 248
 249   In order to turn syntax highlighting on and set the
 250   lexer, you will need to use this directive only once.
 251
 252
 253
 254 Configurable literal block directive
 255 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 256
 257 An even more flexible alternative would be to make the default "literal block"
 258 role configurable.
 259
 260 * Define a new "literal" directive for an ordinary literal block
 261   (doctree element "literal-block" with no parsing)
 262
 263 * Define a "literal-block" setting that controls which directive is called
 264   on a block following ``::``. Default would be the "literal" directive.
 265
 266   Alternatively, define a new "default-literal-block" directive instead of
 267   a settings key.
 268
 269 Analogue to customising the default role of "interpreted text" with
 270 the "default-role" directive, the concise literal-block markup could be
 271 used for e.g.
 272
 273 * the "line-block" directive for poems or addresses
 274
 275 * the "parsed-literal" directive
 276
 277 * a "sourcecode" directive for colourful code
 278   (analog to the one in the `pygments enhanced docutils front-ends`_)
 279
 280 * a "listing" directive for the `listings`_ environment in LaTeX
 281
 282 Example::
 283
 284   ordinary literal block::
 285
 286      some text typeset in monospace
 287
 288   .. settings::
 289      :literal-block:  sourcecode python
 290
 291   colourful Python code::
 292
 293      def hello():
 294          print "hello world"
 295
 296
 297 In the same line, a "default-block-quote" setting or directive could be
 298 considered to configure the role of a block quote.
 299
 300
 301 .. _docutils: http://docutils.sourceforge.net/
 302 .. _rest2web: http://www.voidspace.org.uk/python/rest2web/
 303 .. _Moin-Moin Python colorizer:
 304      http://www.standards-schmandards.com/2005/fangs-093/
 305 .. _odtwriter: http://www.rexx.com/~dkuhlman/odtwriter.html
 306 .. _pygments: http://pygments.org/
 307 .. _listings: http://tug.ctan.org/tex-archive/macros/latex/contrib/listings/
 308 .. _languages and markup formats: http://pygments.org/languages
 309 .. _Using Pygments in ReST documents: http://pygments.org/docs/rstdirective/
 310
 311 .. _rst2html-pygments: rst2html-pygments
 312 .. _rst2latex-pygments: rst2latex-pygments
 313 .. _for-else-test:
 314 .. _for-else-test.py.html: for-else-test.py.html
 315 .. _for-else-test.py.txt: for-else-test.py.txt
 316 .. _for-else-test.py.tex: for-else-test.py.tex
 317 .. _for-else-test.py.pdf: for-else-test.py.pdf
 318 .. _pygments-default.css: pygments-default.css
 319 .. _pygments-default.css.txt: pygments-default.css.txt
 320 .. _pygments-default.css.html: pygments-default.css.html
 321 .. _pygments-default.sty: pygments-default.sty