sandbox/code-block-directive/docs/syntax-highlight.txt

   1 .. -*- rst-mode -*-
   2
   3 Syntax Highlight
   4 ================
   5
   6 :Author:    Günter Milde
   7 :Contact:   milde@users.berlios.de
   8 :Date:      $Date$
   9 :Copyright: © 2007, 2009, 2012 G. Milde,
  10 :License: Released under the terms of the `2-Clause BSD license`_, in short:
  11
  12    Copying and distribution of this file, with or without modification,
  13    are permitted in any medium without royalty provided the copyright
  14    notice and this notice are preserved.
  15    This file is offered as-is, without any warranty.
  16
  17 .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause
  18
  19 :Abstract:  Proposal to add syntax highlight of code blocks to the
  20             capabilities of Docutils_.
  21
  22 .. sectnum::
  23 .. contents::
  24
  25 Syntax highlighting significantly enhances the readability of code.
  26 Since version 0.9, docutils supports this with a `code` directive and role
  27 as well as a `code` option to the `include` directive using the Pygments_
  28 syntax highlighter.
  29
  30 Example::
  31   The content of the following directive ::
  32
  33    .. code:: python
  34
  35     def my_function():
  36         "just a test"
  37         print 8/2
  38
  39   is parsed and marked up as Python source code. The actual rendering
  40   depends on the style-sheet.
  41
  42 TODO
  43 ====
  44
  45 * TODO: Pygments_ provides filters like VisibleWhitespaceFilter
  46   add options to use them?
  47
  48
  49 * Use syntax-highlight=long as default and add basic highlight rules
  50   (keyword, comment, string?) to the default CSS stylesheet to get syntax
  51   highlight out-of-the-box?
  52
  53   Let the latex2e writer write basic rules in the document preamble if
  54   "code" is used in the document?
  55
  56 * The latex writer should pass the original content and options to a
  57   ``lstlistings`` environment. with ``--literal-block-env=lstlistings``.
  58
  59 * Check the `odtwriter`, use common syntax and implementation.
  60
  61 * Provide more sample stylesheets in an official stylesheet library.
  62
  63
  64 Configurable literal block directive
  65 ------------------------------------
  66
  67 Goal
  68 """"
  69
  70 A clean and simple syntax for highlighted code blocks -- preserving the
  71 space saving feature of the "minimised" literal block marker (``::`` at the
  72 end of a text paragraph). This is especially desirable in documents with
  73 many code blocks like tutorials or literate programs.
  74
  75 Inline analogon
  76 """""""""""""""
  77
  78 The *role* of inline `interpreted text` can be customised with the
  79 "default-role" directive. This allows the use of the concise "backtick"
  80 syntax for the most often used role, e.g. in a chemical paper, one could
  81 use::
  82
  83   .. default-role:: subscript
  84
  85   The triple point of H\ `2`\O is at 0°C.
  86
  87 .. default-role:: subscript
  88
  89 to produce
  90
  91   The triple point of H\ `2`\O is at 0°C.
  92
  93 This customisation is currently not possible for block markup.
  94
  95 Proposal
  96 """"""""
  97
  98 * Define a new "literal-block" directive syntax for an ordinary literal
  99   block. This would simply insert the block content into the document
 100   tree as "literal-block" element.
 101
 102 * Define a "default-literal-block" setting that controls which
 103   directive is called on a block following ``::``. Default would be the
 104   "literal-block" directive (backwards compatible).
 105
 106 Motivation
 107 """"""""""
 108
 109 Analogue to customising the default role of "interpreted text" with the
 110 "default-role" directive, the concise ``::`` literal-block markup could be
 111 used for e.g.
 112
 113 * a "code-block" directive for syntax highight
 114
 115 * the "line-block" directive for poems or addresses
 116
 117 * the "parsed-literal" directive
 118
 119 Example::
 120
 121   ordinary literal block::
 122
 123      some text typeset in monospace
 124
 125   .. default-literal-block::  code-block python
 126
 127   this is colourful Python code::
 128
 129      def hello():
 130          print "hello world"
 131
 132
 133 In the same line, a "default-block-quote" setting or directive could be
 134 considered to configure the role of a block quote.
 135
 136
 137
 138 .. External links
 139 .. _odtwriter: http://www.rexx.com/~dkuhlman/odtwriter.html
 140 .. _Sphinx: http://sphinx.pocoo.org
 141 .. _listings:
 142     http://www.ctan.org/tex-archive/help/Catalogue/entries/listings.html
 143 .. _Pygments: http://pygments.org/
 144 .. _Docutils: http://docutils.sourceforge.net/
 145 .. _Docutils Document Tree:
 146     http://docutils.sf.net/docs/ref/doctree.html#classes
 147
 148 .. Internal links
 149 .. _stylesheets:       ../../stylesheets/