reStructuredText "code" role and directive

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@7119 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

4 files changed, 184 insertions, 48 deletions

diff --git a/docutils/docs/howto/security.txt b/docutils/docs/howto/security.txt
index a967dffb4..c6c3b3f62 100644
--- a/docutils/docs/howto/security.txt
+++ b/docutils/docs/howto/security.txt
@@ -49,7 +49,7 @@ features can be disabled by setting "file_insertion_enabled_" to
 
 .. _reStructuredText directives: ../ref/rst/directives.html
 .. _include: ../ref/rst/directives.html#include
-.. _raw: ../ref/rst/directives.html#raw
+.. _raw: ../ref/rst/directives.html#raw-directive
 .. _csv-table: ../ref/rst/directives.html#csv-table
 .. _file_insertion_enabled: ../user/config.html#file-insertion-enabled
 
diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt
index 3a37fb8a6..f570989e6 100644
--- a/docutils/docs/ref/rst/directives.txt
+++ b/docutils/docs/ref/rst/directives.txt
@@ -64,7 +64,7 @@ Specific Admonitions
 :Directive Types: "attention", "caution", "danger", "error", "hint",
                   "important", "note", "tip", "warning", "admonition"
 :Doctree Elements: attention, caution, danger, error, hint, important,
-                   note, tip, warning, admonition, title
+                   note, tip, warning, admonition_, title
 :Directive Arguments: None.
 :Directive Options: `:class:`_, `:name:`_
 :Directive Content: Interpreted as body elements.
@@ -112,13 +112,11 @@ bullet list consisting of two list items::
        - It includes this bullet list.
 
 
-.. _admonition:
-
 Generic Admonition
 ==================
 
 :Directive Type: "admonition"
-:Doctree Elements: admonition, title
+:Doctree Elements: admonition_, title
 :Directive Arguments: One, required (admonition title)
 :Directive Options: Possible, see below.
 :Directive Content: Interpreted as body elements.
@@ -164,7 +162,7 @@ Image
 =====
 
 :Directive Type: "image"
-:Doctree Element: image
+:Doctree Element: image_
 :Directive Arguments: One, required (image URI).
 :Directive Options: Possible.
 :Directive Content: None.
@@ -242,7 +240,7 @@ Figure
 ======
 
 :Directive Type: "figure"
-:Doctree Elements: figure, image, caption, legend
+:Doctree Elements: figure_, image_, caption_, legend_
 :Directive Arguments: One, required (image URI).
 :Directive Options: Possible.
 :Directive Content: Interpreted as the figure caption and an optional
@@ -332,7 +330,7 @@ Topic
 =====
 
 :Directive Type: "topic"
-:Doctree Element: topic
+:Doctree Element: topic_
 :Directive Arguments: 1, required (topic title).
 :Directive Options: `:class:`_, `:name:`_
 :Directive Content: Interpreted as the topic body.
@@ -358,7 +356,7 @@ Sidebar
 =======
 
 :Directive Type: "sidebar"
-:Doctree Element: sidebar
+:Doctree Element: sidebar_
 :Directive Arguments: One, required (sidebar title).
 :Directive Options: Possible (see below).
 :Directive Content: Interpreted as the sidebar body.
@@ -404,7 +402,7 @@ Line Block
    .. _line block syntax: restructuredtext.html#line-blocks
 
 :Directive Type: "line-block"
-:Doctree Element: line_block
+:Doctree Element: line_block_
 :Directive Arguments: None.
 :Directive Options: `:class:`_, `:name:`_
 :Directive Content: Becomes the body of the line block.
@@ -438,7 +436,7 @@ Parsed Literal Block
 ====================
 
 :Directive Type: "parsed-literal"
-:Doctree Element: literal_block
+:Doctree Element: literal_block_
 :Directive Arguments: None.
 :Directive Options: `:class:`_, `:name:`_
 :Directive Content: Becomes the body of the literal block.
@@ -466,17 +464,69 @@ For example, all the element names in this content model are links::
          (docinfo_, transition_?)?,
          `%structure.model;`_ )
 
+Code
+====
+
+:Directive Type: "code"
+:Doctree Element: literal_block_, `inline elements`_
+:Directive Arguments: One, optional (formal language).
+:Directive Options: name, class, number-lines.
+:Directive Content: Becomes the body of the literal block.
+:Configuration Setting: syntax_highlight_.
+
+(New in Docutils 0.9)
+
+The "code" directive constructs a literal block. If the code language is
+specified, the content is parsed by the Pygments_ syntax highlighter and
+tokens are stored in nested `inline elements`_ with class arguments
+according to their syntactic category. The actual highlighting depends on a
+style-sheet (e.g. one `generated by Pygments`__).
+
+The parsing can be turned off with the syntax_highlight_ configuration
+setting and command line option or by specifying the language as `:class:`_
+option (leaveing the directive argument empty). This also avoids warnings
+when Pygments_ is not installed or the language is not amongst the
+`supported languages and markup formats`_.
+
+__   http://pygments.org/docs/cmdline/#generating-styles
+.. _Pygments: http://pygments.org/
+.. _syntax_highlight: ../../user/config.html#syntax-highlight
+.. _supported languages and markup formats: http://pygments.org/languages/
+
+
+The following options are recognized:
+
+``number-lines`` : [start line number]
+    Precede every code line with a line number.
+    The optional argument is the number of the first line (defaut 1).
+
+and the common options `:class:`_ and `:name:`_.
+
+Example::
+  The content of the following directive ::
+
+   .. code:: python
+
+    def my_function():
+        "just a test"
+        print 8/2
+
+  is parsed and marked up as Python source code.
+
 
 Math
 ====
 
 :Directive Type: "math"
-:Doctree Element: math-block
+:Doctree Element: math_block_
 :Directive Arguments: One, optional: prepended to content.
 :Directive Options: `:class:`_, `:name:`_
 :Directive Content: Interpreted as math block(s).
                     Content blocks separated by a blank line are put in
                     separate math-block doctree elements.
+:Configuration Setting: math_output_
+
+(New in Docutils 0.8)
 
 The "math" directive inserts block(s) with mathematical content
 (display formulas, equations) into the document. The input format is
@@ -495,8 +545,6 @@ For HTML, the output format can be set with the `math_output`_
 configuration setting (or the corresponding ``--math-output`` command
 line option).
 
-New in Docutils 0.8.
-
 .. _Short Math Guide: ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
 .. _math role: roles.html#math
 .. _math_output: ../../user/config.html#math-output
@@ -505,7 +553,7 @@ Rubric
 ======
 
 :Directive Type: "rubric"
-:Doctree Element: rubric
+:Doctree Element: rubric_
 :Directive Arguments: 1, required (rubric text).
 :Directive Options: `:class:`_, `:name:`_
 :Directive Content: None.
@@ -527,7 +575,7 @@ Epigraph
 ========
 
 :Directive Type: "epigraph"
-:Doctree Element: block_quote
+:Doctree Element: block_quote_
 :Directive Arguments: None.
 :Directive Options: None.
 :Directive Content: Interpreted as the body of the block quote.
@@ -558,7 +606,7 @@ Highlights
 ==========
 
 :Directive Type: "highlights"
-:Doctree Element: block_quote
+:Doctree Element: block_quote_
 :Directive Arguments: None.
 :Directive Options: None.
 :Directive Content: Interpreted as the body of the block quote.
@@ -574,7 +622,7 @@ Pull-Quote
 ==========
 
 :Directive Type: "pull-quote"
-:Doctree Element: block_quote
+:Doctree Element: block_quote_
 :Directive Arguments: None.
 :Directive Options: None.
 :Directive Content: Interpreted as the body of the block quote.
@@ -587,13 +635,11 @@ The "pull-quote" directive produces a "pull-quote"-class block quote.
 See Epigraph_ above for an analogous example.
 
 
-.. _compound:
-
 Compound Paragraph
 ==================
 
 :Directive Type: "compound"
-:Doctree Element: compound
+:Doctree Element: compound_
 :Directive Arguments: None.
 :Directive Options: `:class:`_, `:name:`_
 :Directive Content: Interpreted as body elements.
@@ -643,7 +689,7 @@ Container
 =========
 
 :Directive Type: "container"
-:Doctree Element: container
+:Doctree Element: container_
 :Directive Arguments: One or more, optional (class names).
 :Directive Options: `:name:`_
 :Directive Content: Interpreted as body elements.
@@ -686,7 +732,7 @@ Table
 =====
 
 :Directive Type: "table"
-:Doctree Element: table
+:Doctree Element: table_
 :Directive Arguments: 1, optional (table title).
 :Directive Options: `:class:`_, `:name:`_
 :Directive Content: A normal reStructuredText table.
@@ -712,7 +758,7 @@ CSV Table
 =========
 
 :Directive Type: "csv-table"
-:Doctree Element: table
+:Doctree Element: table_
 :Directive Arguments: 1, optional (table title).
 :Directive Options: Possible (see below).
 :Directive Content: A CSV (comma-separated values) table.
@@ -818,7 +864,7 @@ List Table
 ==========
 
 :Directive Type: "list-table"
-:Doctree Element: table
+:Doctree Element: table_
 :Directive Arguments: 1, optional (table title).
 :Directive Options: Possible (see below).
 :Directive Content: A uniform two-level bullet list.
@@ -879,7 +925,7 @@ Table of Contents
 =================
 
 :Directive Type: "contents"
-:Doctree Elements: pending, topic
+:Doctree Elements: pending_, topic_
 :Directive Arguments: One, optional: title.
 :Directive Options: Possible.
 :Directive Content: None.
@@ -942,10 +988,11 @@ Automatic Section Numbering
 ===========================
 
 :Directive Type: "sectnum" or "section-autonumbering" (synonyms)
-:Doctree Elements: pending, generated
+:Doctree Elements: pending_, generated_
 :Directive Arguments: None.
 :Directive Options: Possible.
 :Directive Content: None.
+:Configuration Setting: sectnum_xform_
 
 The "sectnum" (or "section-autonumbering") directive automatically numbers
 sections and subsections in a document (if not disabled by the
@@ -997,7 +1044,7 @@ Document Header & Footer
 ========================
 
 :Directive Types: "header" and "footer"
-:Doctree Elements: decoration, header, footer
+:Doctree Elements: decoration_, header, footer
 :Directive Arguments: None.
 :Directive Options: None.
 :Directive Content: Interpreted as body elements.
@@ -1048,7 +1095,7 @@ Target Footnotes
 ================
 
 :Directive Type: "target-notes"
-:Doctree Elements: pending, footnote, footnote_reference
+:Doctree Elements: pending_, footnote_, footnote_reference_
 :Directive Arguments: None.
 :Directive Options: `:class:`_, `:name:`_
 :Directive Options: Possible.
@@ -1067,7 +1114,7 @@ Footnotes
 **NOT IMPLEMENTED YET**
 
 :Directive Type: "footnotes"
-:Doctree Elements: pending, topic
+:Doctree Elements: pending_, topic_
 :Directive Arguments: None?
 :Directive Options: Possible?
 :Directive Content: None.
@@ -1081,7 +1128,7 @@ Citations
 **NOT IMPLEMENTED YET**
 
 :Directive Type: "citations"
-:Doctree Elements: pending, topic
+:Doctree Elements: pending_, topic_
 :Directive Arguments: None?
 :Directive Options: Possible?
 :Directive Content: None.
@@ -1173,7 +1220,7 @@ Replacement Text
 ================
 
 :Directive Type: "replace"
-:Doctree Element: Text & inline elements
+:Doctree Element: Text & `inline elements`_
 :Directive Arguments: None.
 :Directive Options: None.
 :Directive Content: A single paragraph; may contain inline markup.
@@ -1305,6 +1352,7 @@ Including an External Document Fragment
 :Directive Arguments: One, required (path to the file to include).
 :Directive Options: Possible.
 :Directive Content: None.
+:Configuration Setting: file_insertion_enabled_
 
 .. WARNING::
 
@@ -1389,18 +1437,18 @@ Combining ``start/end-line`` and ``start-after/end-before`` is possible. The
 text markers will be searched in the specified lines (further limiting the
 included content).
 
-
-.. _raw:
+.. _raw-directive:
 
 Raw Data Pass-Through
 =====================
 
 :Directive Type: "raw"
-:Doctree Element: raw
+:Doctree Element: raw_
 :Directive Arguments: One or more, required (output format types).
 :Directive Options: Possible.
 :Directive Content: Stored verbatim, uninterpreted.  None (empty) if a
                     "file" or "url" option given.
+:Configuration Setting: raw_enabled_
 
 .. WARNING::
 
@@ -1471,7 +1519,7 @@ Class
 =====
 
 :Directive Type: "class"
-:Doctree Element: pending
+:Doctree Element: pending_
 :Directive Arguments: One or more, required (class names / attribute
                       values).
 :Directive Options: None.
@@ -1709,8 +1757,6 @@ initial default interpreted text role of the standard reStructuredText
 parser is "title-reference".
 
 
-.. _title:
-
 Metadata Document Title
 =======================
 
@@ -1756,19 +1802,19 @@ _`:name:` : text
     Add `text` to the `"names"`_ attribute of the doctree element generated
     by the directive. This allows `hyperlink references`_ to the element
     using `text` as `reference name`_.
-    
+
     Specifying the `name` option of a directive, e.g., ::
-    
+
       .. image:: bild.png
          :name: my picture
-    
+
     is a concise syntax alternative to preceding it with a `hyperlink
     target`_ ::
-    
+
       .. _my picture:
-    
+
       .. image:: bild.png
-    
+
     New in Docutils 0.8.
 
 
@@ -1777,6 +1823,30 @@ _`:name:` : text
 .. _hyperlink references: restructuredtext.html#hyperlink-references
 .. _"classes": ../doctree.html#classes
 .. _"names": ../doctree.html#names
+.. _admonition: ../doctree.html#admonition
+.. _block_quote: ../doctree.html#block-quote
+.. _caption: ../doctree.html#caption
+.. _compound: ../doctree.html#compound
+.. _container: ../doctree.html#container
+.. _decoration: ../doctree.html#decoration
+.. _figure: ../doctree.html#figure
+.. _footnote: ../doctree.html#footnote
+.. _footnote_reference: ../doctree.html#footnote-reference
+.. _generated: ../doctree.html#generated
+.. _image: ../doctree.html#image
+.. _inline elements: ../doctree.html#inline-elements
+.. _literal_block: ../doctree.html#literal-block
+.. _legend: ../doctree.html#legend
+.. _line_block: ../doctree.html#line-block
+.. _math_block: ../doctree.html#math-block
+.. _pending: ../doctree.html#pending
+.. _raw: ../doctree.html#raw
+.. _rubric: ../doctree.html#rubric
+.. _sidebar: ../doctree.html#sidebar
+.. _table: ../doctree.html#table
+.. _title: ../doctree.html#title
+.. _topic: ../doctree.html#topic
+
 
 
 ..
diff --git a/docutils/docs/ref/rst/roles.txt b/docutils/docs/ref/rst/roles.txt
index 7c5fc46cf..b8d7077b5 100644
--- a/docutils/docs/ref/rst/roles.txt
+++ b/docutils/docs/ref/rst/roles.txt
@@ -104,6 +104,43 @@ whereas the backslashes in the second line escape the following
 spaces.
 
 
+``:code:``
+==========
+
+:Aliases: None
+:DTD Element: literal
+:Customization:
+    :Options: class_, language
+    :Content: None.
+
+(New in Docutils 0.9.)
+
+The ``code`` role marks its content as code in a formal language.
+
+For syntax highlight of inline code, the `"role" directive`_ can be used to
+build custom roles with the code language specified in the "language"
+option.
+
+For example, the following creates a LaTeX-specific "latex" role::
+
+  .. role:: latex(code)
+     :language: latex
+
+Content of the new role is parsed and tagged by the Pygments_ syntax
+highlighter. See the `code directive`_ for more info on parsing and display
+of code in reStructuredText.
+
+In addition to "class_", the following option is recognized:
+
+``language`` : text
+    Name of the code's language.
+    See `supported languages and markup formats`_ for recognized values.
+
+.. _code directive: directives.html#code
+.. _Pygments: http://pygments.org/
+.. _supported languages and markup formats: http://pygments.org/languages/
+
+
 ``:math:``
 ==========
 
@@ -113,6 +150,8 @@ spaces.
     :Options: class_
     :Content: None.
 
+(New in Docutils 0.8.)
+
 The ``math`` role marks its content as mathematical notation (inline
 formula).
 
@@ -124,8 +163,6 @@ The input format is LaTeX math syntax without the “math delimiters“
 See the `math directive`_ (producing display formulas) for more info
 on mathematical notation in reStructuredText.
 
-New in Docutils 0.8.
-
 .. _math directive: directives.html#math
 
 
diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
index 6bebf143b..3a46e45df 100644
--- a/docutils/docs/user/config.txt
+++ b/docutils/docs/user/config.txt
@@ -383,8 +383,13 @@ _`record_dependencies`
     Default: None.  Option: ``--record-dependencies``.
 
 _`report_level`
-    Verbosity threshold at or above which system messages are
-    reported.
+    Report system messages at or higher than <level>:
+
+    1  info
+    2  warning
+    3  error
+    4  severe
+    5  none
 
     Default: warning (2).  Options: ``--report, -r, --verbose, -v,
     --quiet, -q``.
@@ -553,6 +558,30 @@ _`trim_footnote_reference_space`
 __ `footnote_references [latex2e writer]`_
 
 
+_`syntax_highlight`
+
+    Token type names used by Pygments_ when parsing contents of the code_
+    directive and role.
+
+    Supported values:
+
+    long
+      Use hierarchy of long token type names.
+    short
+      Use short token type names. (For use with
+      `Pygments-generated stylesheets`_.)
+    none
+      No code parsing. Use this to avoid the "Pygments not
+      found" warning when Pygments is not installed.
+
+    Default: "short".  Option: ``--syntax-highlight``.
+
+.. _Pygments: http://pygments.org/
+.. _code: ../ref/rst/directives.html#code
+.. _Pygments-generated stylesheets:
+   http://pygments.org/docs/cmdline/#generating-styles
+
+
 [readers]
 ---------