diff options
| author | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2011-09-02 13:00:23 +0000 |
|---|---|---|
| committer | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2011-09-02 13:00:23 +0000 |
| commit | ea2a368467d1ca9410beaf287a28e930972a3055 (patch) | |
| tree | c2ae7d8bf38a463b9664fd1ab72a686ba9c60c18 | |
| parent | 813025811c1f1a377b1c0c70bd851e895898afe8 (diff) | |
| download | docutils-ea2a368467d1ca9410beaf287a28e930972a3055.tar.gz | |
reStructuredText "code" role and directive
git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@7119 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
41 files changed, 1519 insertions, 325 deletions
diff --git a/HISTORY.txt b/HISTORY.txt index a9348312f..0196adbb0 100644 --- a/HISTORY.txt +++ b/HISTORY.txt @@ -17,6 +17,16 @@ Changes Since 0.8.1 =================== +* General: + + - reStructuredText "code" role and directive with syntax highlighting + by Pygments_. + +.. _Pygments: http://pygments.org/ + +* docutils/writers/latex2e/__init__.py + + - Support the `abbreviation` and `acronym` standard roles. Release 0.8.1 (2011-08-30) ========================== diff --git a/docs/howto/security.txt b/docs/howto/security.txt index a967dffb4..c6c3b3f62 100644 --- a/docs/howto/security.txt +++ b/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/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 3a37fb8a6..f570989e6 100644 --- a/docs/ref/rst/directives.txt +++ b/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/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 7c5fc46cf..b8d7077b5 100644 --- a/docs/ref/rst/roles.txt +++ b/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/docs/user/config.txt b/docs/user/config.txt index 6bebf143b..3a46e45df 100644 --- a/docs/user/config.txt +++ b/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] --------- diff --git a/docutils/parsers/code_analyzer.py b/docutils/parsers/code_analyzer.py new file mode 100644 index 000000000..bee4e65cf --- /dev/null +++ b/docutils/parsers/code_analyzer.py @@ -0,0 +1,133 @@ +#!/usr/bin/python +# coding: utf-8 + +"""Lexical analysis of formal languages (i.e. code) using Pygments.""" + +# :Author: Georg Brandl; Felix Wiemann; Günter Milde +# :Date: $Date$ +# :Copyright: This module has been placed in the public domain. + +from docutils import ApplicationError +try: + import pygments + from pygments.lexers import get_lexer_by_name + from pygments.formatters.html import _get_ttype_class + with_pygments = True +except ImportError: + with_pygments = False + +# Filter the following token types from the list of class arguments: +unstyled_tokens = ['token', # Token (base token type) + 'text', # Token.Text + ''] # short name for Token and Text +# (Add, e.g., Token.Punctuation with ``unstyled_tokens += 'punctuation'``.) + +class LexerError(ApplicationError): + pass + +class Lexer(object): + """Parse `code` lines and yield "classified" tokens. + + Arguments + + code -- list of source code lines to parse, + language -- formal language the code is written in, + tokennames -- either 'long', 'short', or '' (see below). + + Merge subsequent tokens of the same token-type. + + Iterating over an instance yields the tokens as ``(tokentype, value)`` + tuples. The value of `tokennames` configures the naming of the tokentype: + + 'long': downcased full token type name, + 'short': short name defined by pygments.token.STANDARD_TYPES + (= class argument used in pygments html output), + 'none': skip lexical analysis. + """ + + def __init__(self, code, language, tokennames='short'): + """ + Set up a lexical analyzer for `code` in `language`. + """ + self.code = code + self.language = language + self.tokennames = tokennames + self.lexer = None + # get lexical analyzer for `language`: + if language in ('', 'text') or tokennames == 'none': + return + if not with_pygments: + raise LexerError('Cannot analyze code. ' + 'Pygments package not found.') + try: + self.lexer = get_lexer_by_name(self.language) + except pygments.util.ClassNotFound: + raise LexerError('Cannot analyze code. ' + 'No Pygments lexer found for "%s".' % language) + + # Since version 1.2. (released Jan 01, 2010) Pygments has a + # TokenMergeFilter. However, this requires Python >= 2.4. When Docutils + # requires same minimal version, ``self.merge(tokens)`` in __iter__ can + # be replaced by ``self.lexer.add_filter('tokenmerge')`` in __init__. + def merge(self, tokens): + """Merge subsequent tokens of same token-type. + + Also strip the final newline (added by pygments). + """ + tokens = iter(tokens) + (lasttype, lastval) = tokens.next() + for ttype, value in tokens: + if ttype is lasttype: + lastval += value + else: + yield(lasttype, lastval) + (lasttype, lastval) = (ttype, value) + if lastval != '\n': + yield(lasttype, lastval) + + def __iter__(self): + """Parse self.code and yield "classified" tokens. + """ + codestring = u'\n'.join(self.code) + if self.lexer is None: + yield ([], codestring) + return + tokens = pygments.lex(codestring, self.lexer) + for tokentype, value in self.merge(tokens): + if self.tokennames == 'long': # long CSS class args + classes = str(tokentype).lower().split('.') + else: # short CSS class args + classes = [_get_ttype_class(tokentype)] + classes = [cls for cls in classes if cls not in unstyled_tokens] + yield (classes, value) + + +class NumberLines(object): + """Insert linenumber-tokens at the start of every code line. + + Arguments + + tokens -- iterable of ``(classes, value)`` tuples + startline -- first line number + endline -- last line number + + Iterating over an instance yields the tokens with a + ``(['ln'], '<the line number>')`` token added for every code line. + Multi-line tokens are splitted.""" + + def __init__(self, tokens, startline, endline): + self.tokens = tokens + self.startline = startline + # pad linenumbers, e.g. endline == 100 -> fmt_str = '%3d ' + self.fmt_str = '%%%dd ' % len(str(endline)) + + def __iter__(self): + lineno = self.startline + yield ('ln', self.fmt_str % lineno) + for ttype, value in self.tokens: + lines = value.split('\n') + for line in lines[:-1]: + yield (ttype, line + '\n') + lineno += 1 + yield (['ln'], self.fmt_str % lineno) + yield (ttype, lines[-1]) diff --git a/docutils/parsers/rst/__init__.py b/docutils/parsers/rst/__init__.py index 328ebd9ed..68c3d8d71 100644 --- a/docutils/parsers/rst/__init__.py +++ b/docutils/parsers/rst/__init__.py @@ -131,7 +131,12 @@ class Parser(docutils.parsers.Parser): 'validator': frontend.validate_boolean}), ('Enable the "raw" directive. Enabled by default.', ['--raw-enabled'], - {'action': 'store_true'}),)) + {'action': 'store_true'}), + ('Token name set for parsing code with Pygments: one of ' + '"long", "short", or "none (no parsing)". Default is "short".', + ['--syntax-highlight'], + {'choices': ['long', 'short', 'none'], + 'default': 'short', 'metavar': '<format>'}),)) config_section = 'restructuredtext parser' config_section_dependencies = ('parsers',) diff --git a/docutils/parsers/rst/directives/__init__.py b/docutils/parsers/rst/directives/__init__.py index 64c97c153..b00a67683 100644 --- a/docutils/parsers/rst/directives/__init__.py +++ b/docutils/parsers/rst/directives/__init__.py @@ -17,6 +17,7 @@ from docutils.parsers.rst.languages import en as _fallback_language_module _directive_registry = { 'attention': ('admonitions', 'Attention'), 'caution': ('admonitions', 'Caution'), + 'code': ('body', 'CodeBlock'), 'danger': ('admonitions', 'Danger'), 'error': ('admonitions', 'Error'), 'important': ('admonitions', 'Important'), @@ -222,7 +223,7 @@ def get_measure(argument, units): Check for a positive argument of one of the units and return a normalized string of the form "<value><unit>" (without space in between). - + To be called from directive option conversion functions. """ match = re.match(r'^([0-9.]+) *(%s)$' % '|'.join(units), argument) diff --git a/docutils/parsers/rst/directives/body.py b/docutils/parsers/rst/directives/body.py index 90b7ce1ca..c3ee1e172 100644 --- a/docutils/parsers/rst/directives/body.py +++ b/docutils/parsers/rst/directives/body.py @@ -16,7 +16,7 @@ from docutils import nodes from docutils.parsers.rst import Directive from docutils.parsers.rst import directives from docutils.parsers.rst.roles import set_classes - +from docutils.parsers.code_analyzer import Lexer, LexerError, NumberLines class BasePseudoSection(Directive): @@ -115,6 +115,66 @@ class ParsedLiteral(Directive): return [node] + messages +class CodeBlock(Directive): + """Parse and mark up content of a code block. + + Configuration setting: syntax_highlight + Highlight Code content with Pygments? + Possible values: ('long', 'short', 'none') + + """ + optional_arguments = 1 + option_spec = {'class': directives.class_option, + 'name': directives.unchanged, + 'number-lines': directives.unchanged # integer or None + } + has_content = True + + def run(self): + self.assert_has_content() + if self.arguments: + language = self.arguments[0] + else: + language = '' + set_classes(self.options) + classes = ['code'] + if language: + classes.append(language) + if 'classes' in self.options: + classes.extend(self.options['classes']) + + # set up lexical analyzer + try: + tokens = Lexer(self.content, language, + self.state.document.settings.syntax_highlight) + except LexerError, error: + raise self.warning(error) + + if 'number-lines' in self.options: + # optional argument `startline`, defaults to 1 + try: + startline = int(self.options['number-lines'] or 1) + except ValueError: + raise self.error(':number-lines: with non-integer start value') + endline = startline + len(self.content) + # add linenumber filter: + tokens = NumberLines(tokens, startline, endline) + + node = nodes.literal_block('\n'.join(self.content), classes=classes) + self.add_name(node) + + # analyze content and add nodes for every token + for classes, value in tokens: + # print (classes, value) + if classes: + node += nodes.inline(value, value, classes=classes) + else: + # insert as Text to decrease the verbosity of the output + node += nodes.Text(value, value) + + return [node] + + class MathBlock(Directive): option_spec = {'class': directives.class_option, diff --git a/docutils/parsers/rst/languages/af.py b/docutils/parsers/rst/languages/af.py index 4774a9084..792bfca21 100644 --- a/docutils/parsers/rst/languages/af.py +++ b/docutils/parsers/rst/languages/af.py @@ -18,6 +18,7 @@ __docformat__ = 'reStructuredText' directives = { 'aandag': 'attention', 'versigtig': 'caution', + 'code (translation required)': 'code', 'gevaar': 'danger', 'fout': 'error', 'wenk': 'hint', @@ -73,6 +74,7 @@ roles = { 'ab': 'abbreviation', 'akroniem': 'acronym', 'ac': 'acronym', + u'code (translation required)': 'code', 'indeks': 'index', 'i': 'index', 'voetskrif': 'subscript', diff --git a/docutils/parsers/rst/languages/ca.py b/docutils/parsers/rst/languages/ca.py index cd06e9202..78159ec05 100644 --- a/docutils/parsers/rst/languages/ca.py +++ b/docutils/parsers/rst/languages/ca.py @@ -19,6 +19,7 @@ directives = { # language-dependent: fixed u'atenci\u00F3': 'attention', u'compte': 'caution', + u'code (translation required)': 'code', u'perill': 'danger', u'error': 'error', u'suggeriment': 'hint', @@ -84,6 +85,7 @@ roles = { u'ab': 'abbreviation', u'acr\u00F2nim': 'acronym', u'ac': 'acronym', + u'code (translation required)': 'code', u'\u00EDndex': 'index', u'i': 'index', u'sub\u00EDndex': 'subscript', diff --git a/docutils/parsers/rst/languages/cs.py b/docutils/parsers/rst/languages/cs.py index a8cddc573..55e037cfa 100644 --- a/docutils/parsers/rst/languages/cs.py +++ b/docutils/parsers/rst/languages/cs.py @@ -19,6 +19,7 @@ directives = { # language-dependent: fixed u'pozor': 'attention', u'caution (translation required)': 'caution', # jak rozlisit caution a warning? + u'code (translation required)': 'code', u'nebezpe\u010D\u00ED': 'danger', u'chyba': 'error', u'rada': 'hint', @@ -75,6 +76,7 @@ roles = { u'ab (translation required)': 'abbreviation', u'acronym (translation required)': 'acronym', u'ac (translation required)': 'acronym', + u'code (translation required)': 'code', u'index (translation required)': 'index', u'i (translation required)': 'index', u'subscript (translation required)': 'subscript', diff --git a/docutils/parsers/rst/languages/de.py b/docutils/parsers/rst/languages/de.py index c4b733d86..28e9bafcb 100644 --- a/docutils/parsers/rst/languages/de.py +++ b/docutils/parsers/rst/languages/de.py @@ -19,6 +19,7 @@ __docformat__ = 'reStructuredText' directives = { 'achtung': 'attention', 'vorsicht': 'caution', + 'code': 'code', 'gefahr': 'danger', 'fehler': 'error', 'hinweis': 'hint', @@ -75,6 +76,7 @@ mapping.""" roles = { u'abk\xfcrzung': 'abbreviation', 'akronym': 'acronym', + u'code': 'code', 'index': 'index', 'tiefgestellt': 'subscript', 'hochgestellt': 'superscript', diff --git a/docutils/parsers/rst/languages/en.py b/docutils/parsers/rst/languages/en.py index 60b50c13d..755cbc282 100644 --- a/docutils/parsers/rst/languages/en.py +++ b/docutils/parsers/rst/languages/en.py @@ -19,6 +19,7 @@ directives = { # language-dependent: fixed 'attention': 'attention', 'caution': 'caution', + 'code': 'code', 'danger': 'danger', 'error': 'error', 'hint': 'hint', @@ -75,6 +76,7 @@ roles = { 'ab': 'abbreviation', 'acronym': 'acronym', 'ac': 'acronym', + 'code': 'code', 'index': 'index', 'i': 'index', 'subscript': 'subscript', diff --git a/docutils/parsers/rst/languages/eo.py b/docutils/parsers/rst/languages/eo.py index c8c28d0ac..b47240c80 100644 --- a/docutils/parsers/rst/languages/eo.py +++ b/docutils/parsers/rst/languages/eo.py @@ -19,6 +19,7 @@ directives = { # language-dependent: fixed u'atentu': 'attention', u'zorgu': 'caution', + u'code (translation required)': 'code', u'dangxero': 'danger', u'dan\u011dero': 'danger', u'eraro': 'error', @@ -82,6 +83,7 @@ roles = { u'mall': 'abbreviation', u'komenclitero': 'acronym', u'kl': 'acronym', + u'code (translation required)': 'code', u'indekso': 'index', u'i': 'index', u'subskribo': 'subscript', diff --git a/docutils/parsers/rst/languages/es.py b/docutils/parsers/rst/languages/es.py index 8d37c50cb..16d3a1c49 100644 --- a/docutils/parsers/rst/languages/es.py +++ b/docutils/parsers/rst/languages/es.py @@ -20,6 +20,7 @@ directives = { u'atenci\u00f3n': 'attention', u'atencion': 'attention', u'precauci\u00f3n': 'caution', + u'code (translation required)': 'code', u'precaucion': 'caution', u'peligro': 'danger', u'error': 'error', @@ -87,6 +88,7 @@ roles = { u'acronimo': 'acronym', u'acronimo': 'acronym', u'ac': 'acronym', + u'code (translation required)': 'code', u'indice': 'index', u'i': 'index', u'subindice': 'subscript', diff --git a/docutils/parsers/rst/languages/fi.py b/docutils/parsers/rst/languages/fi.py index 5309bd48f..cdc8c33ff 100644 --- a/docutils/parsers/rst/languages/fi.py +++ b/docutils/parsers/rst/languages/fi.py @@ -1,3 +1,4 @@ +# -*- coding: utf-8 -*- # $Id$ # Author: Asko Soukka <asko.soukka@iki.fi> # Copyright: This module has been placed in the public domain. @@ -19,6 +20,7 @@ directives = { # language-dependent: fixed u'huomio': u'attention', u'varo': u'caution', + u'code (translation required)': 'code', u'vaara': u'danger', u'virhe': u'error', u'vihje': u'hint', @@ -70,6 +72,7 @@ roles = { u'lyhennys': u'abbreviation', u'akronyymi': u'acronym', u'kirjainsana': u'acronym', + u'code (translation required)': 'code', u'hakemisto': u'index', u'luettelo': u'index', u'alaindeksi': u'subscript', diff --git a/docutils/parsers/rst/languages/fr.py b/docutils/parsers/rst/languages/fr.py index 8d4f05a6b..8328e542a 100644 --- a/docutils/parsers/rst/languages/fr.py +++ b/docutils/parsers/rst/languages/fr.py @@ -18,6 +18,7 @@ __docformat__ = 'reStructuredText' directives = { u'attention': 'attention', u'pr\u00E9caution': 'caution', + u'code': 'code', u'danger': 'danger', u'erreur': 'error', u'conseil': 'hint', @@ -76,6 +77,7 @@ roles = { u'abr\u00E9viation': 'abbreviation', u'acronyme': 'acronym', u'sigle': 'acronym', + u'code': 'code', u'index': 'index', u'indice': 'subscript', u'ind': 'subscript', diff --git a/docutils/parsers/rst/languages/gl.py b/docutils/parsers/rst/languages/gl.py index 7d4fb457a..53d52c9c8 100644 --- a/docutils/parsers/rst/languages/gl.py +++ b/docutils/parsers/rst/languages/gl.py @@ -22,6 +22,7 @@ directives = { # language-dependent: fixed u'atenci\u00f3n': 'attention', u'advertencia': 'caution', + u'code (translation required)': 'code', u'perigo': 'danger', u'erro': 'error', u'pista': 'hint', @@ -78,6 +79,7 @@ roles = { u'ab': 'abbreviation', u'acr\u00f3nimo': 'acronym', u'ac': 'acronym', + u'code (translation required)': 'code', u'\u00edndice': 'index', u'i': 'index', u'sub\u00edndice': 'subscript', diff --git a/docutils/parsers/rst/languages/he.py b/docutils/parsers/rst/languages/he.py index b343a5c2a..c23f677e4 100644 --- a/docutils/parsers/rst/languages/he.py +++ b/docutils/parsers/rst/languages/he.py @@ -19,6 +19,7 @@ directives = { # language-dependent: fixed u'\u05ea\u05e9\u05d5\u05de\u05ea \u05dc\u05d1': 'attention', u'\u05d6\u05d4\u05d9\u05e8\u05d5\u05ea': 'caution', + u'code (translation required)': 'code', u'\u05e1\u05db\u05e0\u05d4': 'danger', u'\u05e9\u05d2\u05d9\u05d0\u05d4' : 'error', u'\u05e8\u05de\u05d6': 'hint', @@ -75,6 +76,7 @@ roles = { 'ab': 'abbreviation', 'acronym': 'acronym', 'ac': 'acronym', + u'code (translation required)': 'code', 'index': 'index', 'i': 'index', u'\u05ea\u05d7\u05ea\u05d9': 'subscript', diff --git a/docutils/parsers/rst/languages/it.py b/docutils/parsers/rst/languages/it.py index 1fe610777..79bf12163 100644 --- a/docutils/parsers/rst/languages/it.py +++ b/docutils/parsers/rst/languages/it.py @@ -19,6 +19,7 @@ __docformat__ = 'reStructuredText' directives = { 'attenzione': 'attention', 'cautela': 'caution', + 'code (translation required)': 'code', 'pericolo': 'danger', 'errore': 'error', 'suggerimento': 'hint', @@ -73,6 +74,7 @@ mapping.""" roles = { 'abbreviazione': 'abbreviation', 'acronimo': 'acronym', + u'code (translation required)': 'code', 'indice': 'index', 'deponente': 'subscript', 'esponente': 'superscript', diff --git a/docutils/parsers/rst/languages/ja.py b/docutils/parsers/rst/languages/ja.py index 56364f32c..c87bf59ca 100644 --- a/docutils/parsers/rst/languages/ja.py +++ b/docutils/parsers/rst/languages/ja.py @@ -22,6 +22,7 @@ directives = { # language-dependent: fixed u'注目': 'attention', u'注意': 'caution', + u'code (translation required)': 'code', u'危険': 'danger', u'エラー': 'error', u'ヒント': 'hint', @@ -88,6 +89,7 @@ roles = { # language-dependent: fixed u'略': 'abbreviation', u'頭字語': 'acronym', + u'code (translation required)': 'code', u'インデックス': 'index', u'索引': 'index', u'添字': 'subscript', diff --git a/docutils/parsers/rst/languages/lt.py b/docutils/parsers/rst/languages/lt.py index 20b469f83..233792a1f 100644 --- a/docutils/parsers/rst/languages/lt.py +++ b/docutils/parsers/rst/languages/lt.py @@ -20,6 +20,7 @@ directives = { # language-dependent: fixed u'dėmesio': 'attention', u'atsargiai': 'caution', + u'code (translation required)': 'code', u'pavojinga': 'danger', u'klaida': 'error', u'užuomina': 'hint', @@ -76,6 +77,7 @@ roles = { 'sa': 'abbreviation', 'akronimas': 'acronym', 'ak': 'acronym', + u'code (translation required)': 'code', 'indeksas': 'index', 'i': 'index', u'apatinis-indeksas': 'subscript', diff --git a/docutils/parsers/rst/languages/nl.py b/docutils/parsers/rst/languages/nl.py index 6a8c13b28..3538e9de2 100644 --- a/docutils/parsers/rst/languages/nl.py +++ b/docutils/parsers/rst/languages/nl.py @@ -19,6 +19,7 @@ directives = { # language-dependent: fixed 'attentie': 'attention', 'let-op': 'caution', + 'code (translation required)': 'code', 'gevaar': 'danger', 'fout': 'error', 'hint': 'hint', @@ -77,6 +78,7 @@ roles = { # 'ab': 'abbreviation', 'acroniem': 'acronym', 'ac': 'acronym', + u'code (translation required)': 'code', 'index': 'index', 'i': 'index', 'inferieur': 'subscript', diff --git a/docutils/parsers/rst/languages/pl.py b/docutils/parsers/rst/languages/pl.py index 563326cec..9cd7ddbf6 100644 --- a/docutils/parsers/rst/languages/pl.py +++ b/docutils/parsers/rst/languages/pl.py @@ -19,6 +19,7 @@ directives = { # language-dependent: fixed u'uwaga': 'attention', u'ostro\u017cnie': 'caution', + u'code (translation required)': 'code', u'niebezpiecze\u0144stwo': 'danger', u'b\u0142\u0105d': 'error', u'wskaz\u00f3wka': 'hint', @@ -73,6 +74,7 @@ roles = { # language-dependent: fixed u'skr\u00f3t': 'abbreviation', u'akronim': 'acronym', + u'code (translation required)': 'code', u'indeks': 'index', u'indeks-dolny': 'subscript', u'indeks-g\u00f3rny': 'superscript', diff --git a/docutils/parsers/rst/languages/pt_br.py b/docutils/parsers/rst/languages/pt_br.py index 201010bd3..b0b116759 100644 --- a/docutils/parsers/rst/languages/pt_br.py +++ b/docutils/parsers/rst/languages/pt_br.py @@ -19,6 +19,7 @@ directives = { # language-dependent: fixed u'aten\u00E7\u00E3o': 'attention', 'cuidado': 'caution', + u'code (translation required)': 'code', 'perigo': 'danger', 'erro': 'error', u'sugest\u00E3o': 'hint', @@ -75,6 +76,7 @@ roles = { 'ab': 'abbreviation', u'acr\u00F4nimo': 'acronym', 'ac': 'acronym', + u'code (translation required)': 'code', u'\u00EDndice-remissivo': 'index', 'i': 'index', 'subscrito': 'subscript', diff --git a/docutils/parsers/rst/languages/ru.py b/docutils/parsers/rst/languages/ru.py index 557485be6..dc437d2d8 100644 --- a/docutils/parsers/rst/languages/ru.py +++ b/docutils/parsers/rst/languages/ru.py @@ -1,3 +1,4 @@ +# -*- coding: utf-8 -*- # $Id$ # Author: Roman Suzi <rnd@onego.ru> # Copyright: This module has been placed in the public domain. @@ -14,14 +15,16 @@ reStructuredText. __docformat__ = 'reStructuredText' +# TODO: use utf-8 encoded literal Cyrillic characters directives = { u'\u0431\u043b\u043e\u043a-\u0441\u0442\u0440\u043e\u043a': u'line-block', u'meta': u'meta', - 'math (translation required)': 'math', + u'math (translation required)': 'math', u'\u043e\u0431\u0440\u0430\u0431\u043e\u0442\u0430\u043d\u043d\u044b\u0439-\u043b\u0438\u0442\u0435\u0440\u0430\u043b': u'parsed-literal', u'\u0432\u044b\u0434\u0435\u043b\u0435\u043d\u043d\u0430\u044f-\u0446\u0438\u0442\u0430\u0442\u0430': u'pull-quote', + u'code (translation required)': 'code', u'compound (translation required)': 'compound', u'container (translation required)': 'container', u'table (translation required)': 'table', @@ -72,6 +75,7 @@ mapping.""" roles = { u'\u0430\u043a\u0440\u043e\u043d\u0438\u043c': 'acronym', + u'code (translation required)': 'code', u'\u0430\u043d\u043e\u043d\u0438\u043c\u043d\u0430\u044f-\u0441\u0441\u044b\u043b\u043a\u0430': 'anonymous-reference', u'\u0431\u0443\u043a\u0432\u0430\u043b\u044c\u043d\u043e': 'literal', diff --git a/docutils/parsers/rst/languages/sk.py b/docutils/parsers/rst/languages/sk.py index 649e00bec..15a72bf49 100644 --- a/docutils/parsers/rst/languages/sk.py +++ b/docutils/parsers/rst/languages/sk.py @@ -18,6 +18,7 @@ __docformat__ = 'reStructuredText' directives = { u'pozor': 'attention', u'opatrne': 'caution', + u'code (translation required)': 'code', u'nebezpe\xe8enstvo': 'danger', u'chyba': 'error', u'rada': 'hint', @@ -71,6 +72,7 @@ mapping.""" roles = { u'abbreviation (translation required)': 'abbreviation', u'acronym (translation required)': 'acronym', + u'code (translation required)': 'code', u'index (translation required)': 'index', u'subscript (translation required)': 'subscript', u'superscript (translation required)': 'superscript', diff --git a/docutils/parsers/rst/languages/sv.py b/docutils/parsers/rst/languages/sv.py index cfc564cf4..da9c93ded 100644 --- a/docutils/parsers/rst/languages/sv.py +++ b/docutils/parsers/rst/languages/sv.py @@ -17,6 +17,7 @@ __docformat__ = 'reStructuredText' directives = { u'observera': 'attention', u'caution (translation required)': 'caution', + u'code (translation required)': 'code', u'fara': 'danger', u'fel': 'error', u'v\u00e4gledning': 'hint', @@ -70,6 +71,7 @@ mapping.""" roles = { u'abbreviation (translation required)': 'abbreviation', u'acronym (translation required)': 'acronym', + u'code (translation required)': 'code', u'index (translation required)': 'index', u'subscript (translation required)': 'subscript', u'superscript (translation required)': 'superscript', diff --git a/docutils/parsers/rst/languages/zh_cn.py b/docutils/parsers/rst/languages/zh_cn.py index c071eb92f..7aa4ea338 100644 --- a/docutils/parsers/rst/languages/zh_cn.py +++ b/docutils/parsers/rst/languages/zh_cn.py @@ -20,6 +20,7 @@ directives = { # language-dependent: fixed u'注意': 'attention', u'小心': 'caution', + u'code (translation required)': 'code', u'危险': 'danger', u'错误': 'error', u'提示': 'hint', @@ -73,6 +74,7 @@ roles = { # language-dependent: fixed u'缩写': 'abbreviation', u'简称': 'acronym', + u'code (translation required)': 'code', u'index (translation required)': 'index', u'i (translation required)': 'index', u'下标': 'subscript', diff --git a/docutils/parsers/rst/languages/zh_tw.py b/docutils/parsers/rst/languages/zh_tw.py index a259eab3b..84fe5d79d 100644 --- a/docutils/parsers/rst/languages/zh_tw.py +++ b/docutils/parsers/rst/languages/zh_tw.py @@ -20,6 +20,7 @@ directives = { # language-dependent: fixed 'attention (translation required)': 'attention', 'caution (translation required)': 'caution', + 'code (translation required)': 'code', 'danger (translation required)': 'danger', 'error (translation required)': 'error', 'hint (translation required)': 'hint', @@ -76,6 +77,7 @@ roles = { 'ab (translation required)': 'abbreviation', 'acronym (translation required)': 'acronym', 'ac (translation required)': 'acronym', + u'code (translation required)': 'code', 'index (translation required)': 'index', 'i (translation required)': 'index', 'subscript (translation required)': 'subscript', diff --git a/docutils/parsers/rst/roles.py b/docutils/parsers/rst/roles.py index 1d79badde..0b7fc9467 100644 --- a/docutils/parsers/rst/roles.py +++ b/docutils/parsers/rst/roles.py @@ -75,6 +75,7 @@ __docformat__ = 'reStructuredText' from docutils import nodes, utils from docutils.parsers.rst import directives from docutils.parsers.rst.languages import en as _fallback_language_module +from docutils.parsers.code_analyzer import Lexer, LexerError DEFAULT_INTERPRETED_ROLE = 'title-reference' """ @@ -314,6 +315,41 @@ raw_role.options = {'format': directives.unchanged} register_canonical_role('raw', raw_role) +def code_role(role, rawtext, text, lineno, inliner, options={}, content=[]): + set_classes(options) + language = options.get('language', '') + classes = ['code'] + if language: + classes.append(language) + if 'classes' in options: + classes.extend(options['classes']) + + try: + tokens = Lexer([utils.unescape(text, 1)], language, + inliner.document.settings.syntax_highlight) + except LexerError, error: + msg = inliner.reporter.warning(error) + prb = inliner.problematic(rawtext, rawtext, msg) + return [prb], [msg] + + node = nodes.literal(rawtext, '', classes=classes) + + # analyze content and add nodes for every token + for classes, value in tokens: + # print (classes, value) + if classes: + node += nodes.inline(value, value, classes=classes) + else: + # insert as Text to decrease the verbosity of the output + node += nodes.Text(value, value) + + return [node], [] + +code_role.options = {'class': directives.class_option, + 'language': directives.unchanged} + +register_canonical_role('code', code_role) + def math_role(role, rawtext, text, lineno, inliner, options={}, content=[]): i = rawtext.find('`') text = rawtext.split('`')[1] diff --git a/test/functional/expected/standalone_rst_html4css1.html b/test/functional/expected/standalone_rst_html4css1.html index 49d8efa7c..adfb9bec6 100644 --- a/test/functional/expected/standalone_rst_html4css1.html +++ b/test/functional/expected/standalone_rst_html4css1.html @@ -2,7 +2,7 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8" /> <meta name="generator" content="Docutils 0.9: http://docutils.sourceforge.net/" /> <title>reStructuredText Test Document</title> <meta name="author" content="David Goodger" /> @@ -85,74 +85,75 @@ They are transformed from section titles after parsing. --> <div class="contents topic" id="table-of-contents"> <p class="topic-title first">Table of Contents</p> <ul class="auto-toc simple"> -<li><a class="reference internal" href="#structural-elements" id="id32">1 Structural Elements</a><ul class="auto-toc"> -<li><a class="reference internal" href="#section-title" id="id33">1.1 Section Title</a></li> -<li><a class="reference internal" href="#empty-section" id="id34">1.2 Empty Section</a></li> -<li><a class="reference internal" href="#transitions" id="id35">1.3 Transitions</a></li> +<li><a class="reference internal" href="#structural-elements" id="id34">1 Structural Elements</a><ul class="auto-toc"> +<li><a class="reference internal" href="#section-title" id="id35">1.1 Section Title</a></li> +<li><a class="reference internal" href="#empty-section" id="id36">1.2 Empty Section</a></li> +<li><a class="reference internal" href="#transitions" id="id37">1.3 Transitions</a></li> </ul> </li> -<li><a class="reference internal" href="#body-elements" id="id36">2 Body Elements</a><ul class="auto-toc"> -<li><a class="reference internal" href="#paragraphs" id="id37">2.1 Paragraphs</a><ul class="auto-toc"> -<li><a class="reference internal" href="#inline-markup" id="id38">2.1.1 Inline Markup</a></li> +<li><a class="reference internal" href="#body-elements" id="id38">2 Body Elements</a><ul class="auto-toc"> +<li><a class="reference internal" href="#paragraphs" id="id39">2.1 Paragraphs</a><ul class="auto-toc"> +<li><a class="reference internal" href="#inline-markup" id="id40">2.1.1 Inline Markup</a></li> </ul> </li> -<li><a class="reference internal" href="#bullet-lists" id="id39">2.2 Bullet Lists</a></li> -<li><a class="reference internal" href="#enumerated-lists" id="id40">2.3 Enumerated Lists</a></li> -<li><a class="reference internal" href="#definition-lists" id="id41">2.4 Definition Lists</a></li> -<li><a class="reference internal" href="#field-lists" id="id42">2.5 Field Lists</a></li> -<li><a class="reference internal" href="#option-lists" id="id43">2.6 Option Lists</a></li> -<li><a class="reference internal" href="#literal-blocks" id="id44">2.7 Literal Blocks</a></li> -<li><a class="reference internal" href="#line-blocks" id="id45">2.8 Line Blocks</a></li> -<li><a class="reference internal" href="#block-quotes" id="id46">2.9 Block Quotes</a></li> -<li><a class="reference internal" href="#doctest-blocks" id="id47">2.10 Doctest Blocks</a></li> -<li><a class="reference internal" href="#footnotes" id="id48">2.11 Footnotes</a></li> -<li><a class="reference internal" href="#citations" id="id49">2.12 Citations</a></li> -<li><a class="reference internal" href="#targets" id="id50">2.13 Targets</a><ul class="auto-toc"> -<li><a class="reference internal" href="#duplicate-target-names" id="id51">2.13.1 Duplicate Target Names</a></li> -<li><a class="reference internal" href="#id21" id="id52">2.13.2 Duplicate Target Names</a></li> +<li><a class="reference internal" href="#bullet-lists" id="id41">2.2 Bullet Lists</a></li> +<li><a class="reference internal" href="#enumerated-lists" id="id42">2.3 Enumerated Lists</a></li> +<li><a class="reference internal" href="#definition-lists" id="id43">2.4 Definition Lists</a></li> +<li><a class="reference internal" href="#field-lists" id="id44">2.5 Field Lists</a></li> +<li><a class="reference internal" href="#option-lists" id="id45">2.6 Option Lists</a></li> +<li><a class="reference internal" href="#literal-blocks" id="id46">2.7 Literal Blocks</a></li> +<li><a class="reference internal" href="#line-blocks" id="id47">2.8 Line Blocks</a></li> +<li><a class="reference internal" href="#block-quotes" id="id48">2.9 Block Quotes</a></li> +<li><a class="reference internal" href="#doctest-blocks" id="id49">2.10 Doctest Blocks</a></li> +<li><a class="reference internal" href="#footnotes" id="id50">2.11 Footnotes</a></li> +<li><a class="reference internal" href="#citations" id="id51">2.12 Citations</a></li> +<li><a class="reference internal" href="#targets" id="id52">2.13 Targets</a><ul class="auto-toc"> +<li><a class="reference internal" href="#duplicate-target-names" id="id53">2.13.1 Duplicate Target Names</a></li> +<li><a class="reference internal" href="#id21" id="id54">2.13.2 Duplicate Target Names</a></li> </ul> </li> -<li><a class="reference internal" href="#directives" id="id53">2.14 Directives</a><ul class="auto-toc"> -<li><a class="reference internal" href="#document-parts" id="id54">2.14.1 Document Parts</a></li> -<li><a class="reference internal" href="#images-and-figures" id="id55">2.14.2 Images and Figures</a></li> -<li><a class="reference internal" href="#admonitions" id="id56">2.14.3 Admonitions</a></li> -<li><a class="reference internal" href="#topics-sidebars-and-rubrics" id="id57">2.14.4 Topics, Sidebars, and Rubrics</a></li> -<li><a class="reference internal" href="#target-footnotes" id="id58">2.14.5 Target Footnotes</a></li> -<li><a class="reference internal" href="#replacement-text" id="id59">2.14.6 Replacement Text</a></li> -<li><a class="reference internal" href="#compound-paragraph" id="id60">2.14.7 Compound Paragraph</a></li> -<li><a class="reference internal" href="#parsed-literal-blocks" id="id61">2.14.8 Parsed Literal Blocks</a></li> +<li><a class="reference internal" href="#directives" id="id55">2.14 Directives</a><ul class="auto-toc"> +<li><a class="reference internal" href="#document-parts" id="id56">2.14.1 Document Parts</a></li> +<li><a class="reference internal" href="#images-and-figures" id="id57">2.14.2 Images and Figures</a></li> +<li><a class="reference internal" href="#admonitions" id="id58">2.14.3 Admonitions</a></li> +<li><a class="reference internal" href="#topics-sidebars-and-rubrics" id="id59">2.14.4 Topics, Sidebars, and Rubrics</a></li> +<li><a class="reference internal" href="#target-footnotes" id="id60">2.14.5 Target Footnotes</a></li> +<li><a class="reference internal" href="#replacement-text" id="id61">2.14.6 Replacement Text</a></li> +<li><a class="reference internal" href="#compound-paragraph" id="id62">2.14.7 Compound Paragraph</a></li> +<li><a class="reference internal" href="#parsed-literal-blocks" id="id63">2.14.8 Parsed Literal Blocks</a></li> +<li><a class="reference internal" href="#code" id="id64">2.14.9 Code</a></li> </ul> </li> -<li><a class="reference internal" href="#substitution-definitions" id="id62">2.15 Substitution Definitions</a></li> -<li><a class="reference internal" href="#comments" id="id63">2.16 Comments</a></li> -<li><a class="reference internal" href="#raw-text" id="id64">2.17 Raw text</a></li> -<li><a class="reference internal" href="#container" id="id65">2.18 Container</a></li> -<li><a class="reference internal" href="#colspanning-tables" id="id66">2.19 Colspanning tables</a></li> -<li><a class="reference internal" href="#rowspanning-tables" id="id67">2.20 Rowspanning tables</a></li> -<li><a class="reference internal" href="#complex-tables" id="id68">2.21 Complex tables</a></li> -<li><a class="reference internal" href="#list-tables" id="id69">2.22 List Tables</a></li> -<li><a class="reference internal" href="#custom-roles" id="id70">2.23 Custom Roles</a></li> -<li><a class="reference internal" href="#svg-images" id="id71">2.24 SVG Images</a></li> -<li><a class="reference internal" href="#swf-images" id="id72">2.25 SWF Images</a></li> +<li><a class="reference internal" href="#substitution-definitions" id="id65">2.15 Substitution Definitions</a></li> +<li><a class="reference internal" href="#comments" id="id66">2.16 Comments</a></li> +<li><a class="reference internal" href="#raw-text" id="id67">2.17 Raw text</a></li> +<li><a class="reference internal" href="#container" id="id68">2.18 Container</a></li> +<li><a class="reference internal" href="#colspanning-tables" id="id69">2.19 Colspanning tables</a></li> +<li><a class="reference internal" href="#rowspanning-tables" id="id70">2.20 Rowspanning tables</a></li> +<li><a class="reference internal" href="#complex-tables" id="id71">2.21 Complex tables</a></li> +<li><a class="reference internal" href="#list-tables" id="id72">2.22 List Tables</a></li> +<li><a class="reference internal" href="#custom-roles" id="id73">2.23 Custom Roles</a></li> +<li><a class="reference internal" href="#svg-images" id="id74">2.24 SVG Images</a></li> +<li><a class="reference internal" href="#swf-images" id="id75">2.25 SWF Images</a></li> </ul> </li> -<li><a class="reference internal" href="#error-handling" id="id73">3 Error Handling</a></li> +<li><a class="reference internal" href="#error-handling" id="id76">3 Error Handling</a></li> </ul> </div> <div class="section" id="structural-elements"> -<h1><a class="toc-backref" href="#id32">1 Structural Elements</a></h1> +<h1><a class="toc-backref" href="#id34">1 Structural Elements</a></h1> <div class="section" id="section-title"> -<h2 class="with-subtitle"><a class="toc-backref" href="#id33">1.1 Section Title</a></h2> +<h2 class="with-subtitle"><a class="toc-backref" href="#id35">1.1 Section Title</a></h2> <h2 class="section-subtitle" id="section-subtitle"><span class="section-subtitle">Section Subtitle</span></h2> <p>Lone subsections are converted to a section subtitle by a transform activated with the <tt class="docutils literal"><span class="pre">--section-subtitles</span></tt> command line option or the <tt class="docutils literal"><span class="pre">sectsubtitle-xform</span></tt> configuration value.</p> </div> <div class="section" id="empty-section"> -<h2><a class="toc-backref" href="#id34">1.2 Empty Section</a></h2> +<h2><a class="toc-backref" href="#id36">1.2 Empty Section</a></h2> </div> <div class="section" id="transitions"> -<h2><a class="toc-backref" href="#id35">1.3 Transitions</a></h2> +<h2><a class="toc-backref" href="#id37">1.3 Transitions</a></h2> <p>Here's a transition:</p> <hr class="docutils" /> <p>It divides the section. Transitions may also occur between sections:</p> @@ -160,18 +161,18 @@ activated with the <tt class="docutils literal"><span class="pre">--section-subt </div> <hr class="docutils" /> <div class="section" id="body-elements"> -<h1><a class="toc-backref" href="#id36">2 Body Elements</a></h1> +<h1><a class="toc-backref" href="#id38">2 Body Elements</a></h1> <div class="section" id="paragraphs"> -<h2><a class="toc-backref" href="#id37">2.1 Paragraphs</a></h2> +<h2><a class="toc-backref" href="#id39">2.1 Paragraphs</a></h2> <p>A paragraph.</p> <div class="section" id="inline-markup"> -<h3><a class="toc-backref" href="#id38">2.1.1 Inline Markup</a></h3> +<h3><a class="toc-backref" href="#id40">2.1.1 Inline Markup</a></h3> <p>Paragraphs contain text and may contain inline markup: <em>emphasis</em>, <strong>strong emphasis</strong>, <tt class="docutils literal">inline literals</tt>, standalone hyperlinks (<a class="reference external" href="http://www.python.org">http://www.python.org</a>), external hyperlinks (<a class="reference external" href="http://www.python.org/">Python</a> <a class="footnote-reference" href="#id25" id="id26">[5]</a>), internal cross-references (<a class="reference internal" href="#example">example</a>), external hyperlinks with embedded URIs (<a class="reference external" href="http://www.python.org">Python web site</a>), <a class="reference external" href="http://www.python.org/">anonymous hyperlink -references</a> <a class="footnote-reference" href="#id25" id="id29">[5]</a> (<a class="reference external" href="http://docutils.sourceforge.net/">a second reference</a> <a class="footnote-reference" href="#id30" id="id31">[6]</a>), footnote references (manually +references</a> <a class="footnote-reference" href="#id25" id="id31">[5]</a> (<a class="reference external" href="http://docutils.sourceforge.net/">a second reference</a> <a class="footnote-reference" href="#id32" id="id33">[7]</a>), footnote references (manually numbered <a class="footnote-reference" href="#id8" id="id1">[1]</a>, anonymous auto-numbered <a class="footnote-reference" href="#id12" id="id2">[3]</a>, labeled auto-numbered <a class="footnote-reference" href="#label" id="id3">[2]</a>, or symbolic <a class="footnote-reference" href="#id13" id="id4">[*]</a>), citation references (<a class="citation-reference" href="#cit2002" id="id5">[CIT2002]</a>), substitution references (<img alt="EXAMPLE" src="../../../docs/user/rst/images/biohazard.png" />), and <span class="target" id="inline-hyperlink-targets">inline hyperlink targets</span> @@ -181,9 +182,10 @@ inline markup is also possible (although exceedingly ugly!) in <em>re</em><tt cl reference to the <a class="reference internal" href="#doctitle">doctitle</a> and the <a class="reference internal" href="#subtitle">subtitle</a>.</p> <p>The default role for interpreted text is <cite>Title Reference</cite>. Here are some explicit interpreted text roles: a PEP reference (<a class="reference external" href="http://www.python.org/dev/peps/pep-0287">PEP 287</a>); an -RFC reference (<a class="reference external" href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>); a <sub>subscript</sub>; a <sup>superscript</sup>; -and explicit roles for <em>standard</em> <strong>inline</strong> -<tt class="docutils literal">markup</tt>.</p> +RFC reference (<a class="reference external" href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>); an abbreviation (<abbr>abb.</abbr>), an acronym +(<acronym>reST</acronym>), code (<tt class="code docutils literal">print "hello world"</tt>); a <sub>subscript</sub>; +a <sup>superscript</sup> and explicit roles for <cite>Docutils</cite>' +<em>standard</em> <strong>inline</strong> <tt class="docutils literal">markup</tt>.</p> <!-- DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! --> <p>Let's test wrapping and whitespace significance in inline literals: <tt class="docutils literal">This is an example of <span class="pre">--inline-literal</span> <span class="pre">--text,</span> <span class="pre">--including</span> <span class="pre">some--</span> @@ -196,7 +198,7 @@ live link to PEP 258 here.</p> </div> </div> <div class="section" id="bullet-lists"> -<h2><a class="toc-backref" href="#id39">2.2 Bullet Lists</a></h2> +<h2><a class="toc-backref" href="#id41">2.2 Bullet Lists</a></h2> <ul> <li><p class="first">A bullet list</p> <ul class="simple"> @@ -221,7 +223,7 @@ live link to PEP 258 here.</p> </ul> </div> <div class="section" id="enumerated-lists"> -<h2><a class="toc-backref" href="#id40">2.3 Enumerated Lists</a></h2> +<h2><a class="toc-backref" href="#id42">2.3 Enumerated Lists</a></h2> <ol class="arabic"> <li><p class="first">Arabic numerals.</p> <ol class="loweralpha simple"> @@ -254,7 +256,7 @@ live link to PEP 258 here.</p> </ol> </div> <div class="section" id="definition-lists"> -<h2><a class="toc-backref" href="#id41">2.4 Definition Lists</a></h2> +<h2><a class="toc-backref" href="#id43">2.4 Definition Lists</a></h2> <dl class="docutils"> <dt>Term</dt> <dd>Definition</dd> @@ -269,7 +271,7 @@ live link to PEP 258 here.</p> </dl> </div> <div class="section" id="field-lists"> -<h2><a class="toc-backref" href="#id42">2.5 Field Lists</a></h2> +<h2><a class="toc-backref" href="#id44">2.5 Field Lists</a></h2> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> @@ -293,7 +295,7 @@ doesn't get stripped away.)</p> </table> </div> <div class="section" id="option-lists"> -<h2><a class="toc-backref" href="#id43">2.6 Option Lists</a></h2> +<h2><a class="toc-backref" href="#id45">2.6 Option Lists</a></h2> <p>For listing command-line options:</p> <table class="docutils option-list" frame="void" rules="none"> <col class="option" /> @@ -339,7 +341,7 @@ regardless of where it starts.</p> description.</p> </div> <div class="section" id="literal-blocks"> -<h2><a class="toc-backref" href="#id44">2.7 Literal Blocks</a></h2> +<h2><a class="toc-backref" href="#id46">2.7 Literal Blocks</a></h2> <p>Literal blocks are indicated with a double-colon ("::") at the end of the preceding paragraph (over there <tt class="docutils literal"><span class="pre">--></span></tt>). They can be indented:</p> <pre class="literal-block"> @@ -356,7 +358,7 @@ if literal_block: </pre> </div> <div class="section" id="line-blocks"> -<h2><a class="toc-backref" href="#id45">2.8 Line Blocks</a></h2> +<h2><a class="toc-backref" href="#id47">2.8 Line Blocks</a></h2> <p>This section tests line blocks. Line blocks are body elements which consist of lines and other line blocks. Nested line blocks cause indentation.</p> @@ -430,7 +432,7 @@ also be centre-aligned:</p> </div> </div> <div class="section" id="block-quotes"> -<h2><a class="toc-backref" href="#id46">2.9 Block Quotes</a></h2> +<h2><a class="toc-backref" href="#id48">2.9 Block Quotes</a></h2> <p>Block quotes consist of indented body elements:</p> <blockquote> <p>My theory by A. Elk. Brackets Miss, brackets. This theory goes @@ -448,7 +450,7 @@ ReStructuredText est un langage de balisage léger utilisé notamment dans la documentation du langage Python.</blockquote> </div> <div class="section" id="doctest-blocks"> -<h2><a class="toc-backref" href="#id47">2.10 Doctest Blocks</a></h2> +<h2><a class="toc-backref" href="#id49">2.10 Doctest Blocks</a></h2> <pre class="doctest-block"> >>> print 'Python-specific usage examples; begun with ">>>"' Python-specific usage examples; begun with ">>>" @@ -457,7 +459,7 @@ Python-specific usage examples; begun with ">>>" </pre> </div> <div class="section" id="footnotes"> -<h2><a class="toc-backref" href="#id48">2.11 Footnotes</a></h2> +<h2><a class="toc-backref" href="#id50">2.11 Footnotes</a></h2> <table class="docutils footnote" frame="void" id="id8" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> @@ -503,12 +505,12 @@ Here's a reference to the next footnote: <a class="footnote-reference" href="#id <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> <tr><td class="label">[4]</td><td>Here's an unreferenced footnote, with a reference to a -nonexistent footnote: <a href="#id82"><span class="problematic" id="id83"><span id="id17"></span>[5]_</span></a>.</td></tr> +nonexistent footnote: <a href="#id86"><span class="problematic" id="id87"><span id="id17"></span>[5]_</span></a>.</td></tr> </tbody> </table> </div> <div class="section" id="citations"> -<h2><a class="toc-backref" href="#id49">2.12 Citations</a></h2> +<h2><a class="toc-backref" href="#id51">2.12 Citations</a></h2> <table class="docutils citation" frame="void" id="cit2002" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> @@ -516,11 +518,11 @@ nonexistent footnote: <a href="#id82"><span class="problematic" id="id83"><span rendered separately and differently from footnotes.</td></tr> </tbody> </table> -<p>Here's a reference to the above, <a class="citation-reference" href="#cit2002" id="id18">[CIT2002]</a>, and a <a href="#id84"><span class="problematic" id="id85"><span id="id19"></span>[nonexistent]_</span></a> +<p>Here's a reference to the above, <a class="citation-reference" href="#cit2002" id="id18">[CIT2002]</a>, and a <a href="#id88"><span class="problematic" id="id89"><span id="id19"></span>[nonexistent]_</span></a> citation.</p> </div> <div class="section" id="targets"> -<span id="another-target"></span><h2><a class="toc-backref" href="#id50">2.13 Targets</a></h2> +<span id="another-target"></span><h2><a class="toc-backref" href="#id52">2.13 Targets</a></h2> <p id="example">This paragraph is pointed to by the explicit "example" target. A reference can be found under <a class="reference internal" href="#inline-markup">Inline Markup</a>, above. <a class="reference internal" href="#inline-hyperlink-targets">Inline hyperlink targets</a> are also possible.</p> @@ -530,46 +532,47 @@ hyperlink targets</a> are also possible.</p> "<a class="reference external" href="http://www.python.org/">Python</a> <a class="footnote-reference" href="#id25" id="id27">[5]</a>".</p> <p>Targets may be indirect and anonymous. Thus <a class="reference internal" href="#targets">this phrase</a> may also refer to the <a class="reference internal" href="#targets">Targets</a> section.</p> -<p>Here's a <a href="#id86"><span class="problematic" id="id87">`hyperlink reference without a target`_</span></a>, which generates an +<p>Here's a <a href="#id90"><span class="problematic" id="id91">`hyperlink reference without a target`_</span></a>, which generates an error.</p> <div class="section" id="duplicate-target-names"> -<h3><a class="toc-backref" href="#id51">2.13.1 Duplicate Target Names</a></h3> +<h3><a class="toc-backref" href="#id53">2.13.1 Duplicate Target Names</a></h3> <p>Duplicate names in section headers or other implicit targets will generate "info" (level-1) system messages. Duplicate names in explicit targets will generate "warning" (level-2) system messages.</p> </div> <div class="section" id="id21"> -<h3><a class="toc-backref" href="#id52">2.13.2 Duplicate Target Names</a></h3> +<h3><a class="toc-backref" href="#id54">2.13.2 Duplicate Target Names</a></h3> <p>Since there are two "Duplicate Target Names" section headers, we cannot uniquely refer to either of them by name. If we try to (like -this: <a href="#id88"><span class="problematic" id="id89">`Duplicate Target Names`_</span></a>), an error is generated.</p> +this: <a href="#id92"><span class="problematic" id="id93">`Duplicate Target Names`_</span></a>), an error is generated.</p> </div> </div> <div class="section" id="directives"> -<h2><a class="toc-backref" href="#id53">2.14 Directives</a></h2> +<h2><a class="toc-backref" href="#id55">2.14 Directives</a></h2> <div class="contents local topic" id="contents"> <ul class="auto-toc simple"> -<li><a class="reference internal" href="#document-parts" id="id74">2.14.1 Document Parts</a></li> -<li><a class="reference internal" href="#images-and-figures" id="id75">2.14.2 Images and Figures</a></li> -<li><a class="reference internal" href="#admonitions" id="id76">2.14.3 Admonitions</a></li> -<li><a class="reference internal" href="#topics-sidebars-and-rubrics" id="id77">2.14.4 Topics, Sidebars, and Rubrics</a></li> -<li><a class="reference internal" href="#target-footnotes" id="id78">2.14.5 Target Footnotes</a></li> -<li><a class="reference internal" href="#replacement-text" id="id79">2.14.6 Replacement Text</a></li> -<li><a class="reference internal" href="#compound-paragraph" id="id80">2.14.7 Compound Paragraph</a></li> -<li><a class="reference internal" href="#parsed-literal-blocks" id="id81">2.14.8 Parsed Literal Blocks</a></li> +<li><a class="reference internal" href="#document-parts" id="id77">2.14.1 Document Parts</a></li> +<li><a class="reference internal" href="#images-and-figures" id="id78">2.14.2 Images and Figures</a></li> +<li><a class="reference internal" href="#admonitions" id="id79">2.14.3 Admonitions</a></li> +<li><a class="reference internal" href="#topics-sidebars-and-rubrics" id="id80">2.14.4 Topics, Sidebars, and Rubrics</a></li> +<li><a class="reference internal" href="#target-footnotes" id="id81">2.14.5 Target Footnotes</a></li> +<li><a class="reference internal" href="#replacement-text" id="id82">2.14.6 Replacement Text</a></li> +<li><a class="reference internal" href="#compound-paragraph" id="id83">2.14.7 Compound Paragraph</a></li> +<li><a class="reference internal" href="#parsed-literal-blocks" id="id84">2.14.8 Parsed Literal Blocks</a></li> +<li><a class="reference internal" href="#code" id="id85">2.14.9 Code</a></li> </ul> </div> <p>These are just a sample of the many reStructuredText Directives. For others, please see <a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/directives.html">http://docutils.sourceforge.net/docs/ref/rst/directives.html</a>.</p> <div class="section" id="document-parts"> -<h3><a class="toc-backref" href="#id74">2.14.1 Document Parts</a></h3> +<h3><a class="toc-backref" href="#id77">2.14.1 Document Parts</a></h3> <p>An example of the "contents" directive can be seen above this section (a local, untitled table of <a class="reference internal" href="#contents">contents</a>) and at the beginning of the document (a document-wide <a class="reference internal" href="#table-of-contents">table of contents</a>).</p> </div> <div class="section" id="images-and-figures"> -<h3><a class="toc-backref" href="#id75">2.14.2 Images and Figures</a></h3> +<h3><a class="toc-backref" href="#id78">2.14.2 Images and Figures</a></h3> <p>An image directive (also clickable -- a hyperlink reference):</p> <a class="reference internal image-reference" href="#directives"><img alt="../../../docs/user/rst/images/title.png" class="class1 class2" src="../../../docs/user/rst/images/title.png" /></a> <p>Image with multiple IDs:</p> @@ -660,7 +663,7 @@ rendering software used.</p> upon the style sheet and the browser or rendering software used.</p> </div> <div class="section" id="admonitions"> -<h3><a class="toc-backref" href="#id76">2.14.3 Admonitions</a></h3> +<h3><a class="toc-backref" href="#id79">2.14.3 Admonitions</a></h3> <div class="attention"> <p class="first admonition-title">Attention!</p> <p class="last">Directives at large.</p> @@ -709,7 +712,7 @@ Reader discretion is strongly advised.</p> </div> </div> <div class="section" id="topics-sidebars-and-rubrics"> -<h3><a class="toc-backref" href="#id77">2.14.4 Topics, Sidebars, and Rubrics</a></h3> +<h3><a class="toc-backref" href="#id80">2.14.4 Topics, Sidebars, and Rubrics</a></h3> <p><em>Sidebars</em> are like miniature, parallel documents.</p> <div class="sidebar"> <p class="first sidebar-title">Sidebar Title</p> @@ -733,26 +736,32 @@ document's structure. It is typically highlighted in red (hence the name).</p> allowed (e.g. inside a directive).</p> </div> <div class="section" id="target-footnotes"> -<h3><a class="toc-backref" href="#id78">2.14.5 Target Footnotes</a></h3> +<h3><a class="toc-backref" href="#id81">2.14.5 Target Footnotes</a></h3> <table class="docutils footnote" frame="void" id="id25" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> -<tr><td class="label">[5]</td><td><em>(<a class="fn-backref" href="#id26">1</a>, <a class="fn-backref" href="#id27">2</a>, <a class="fn-backref" href="#id28">3</a>, <a class="fn-backref" href="#id29">4</a>)</em> <a class="reference external" href="http://www.python.org/">http://www.python.org/</a></td></tr> +<tr><td class="label">[5]</td><td><em>(<a class="fn-backref" href="#id26">1</a>, <a class="fn-backref" href="#id27">2</a>, <a class="fn-backref" href="#id28">3</a>, <a class="fn-backref" href="#id31">4</a>)</em> <a class="reference external" href="http://www.python.org/">http://www.python.org/</a></td></tr> </tbody> </table> -<table class="docutils footnote" frame="void" id="id30" rules="none"> +<table class="docutils footnote" frame="void" id="id29" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id31">[6]</a></td><td><a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a></td></tr> +<tr><td class="label"><a class="fn-backref" href="#id30">[6]</a></td><td><a class="reference external" href="http://pygments.org/">http://pygments.org/</a></td></tr> +</tbody> +</table> +<table class="docutils footnote" frame="void" id="id32" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id33">[7]</a></td><td><a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a></td></tr> </tbody> </table> </div> <div class="section" id="replacement-text"> -<h3><a class="toc-backref" href="#id79">2.14.6 Replacement Text</a></h3> +<h3><a class="toc-backref" href="#id82">2.14.6 Replacement Text</a></h3> <p>I recommend you try <a class="reference external" href="http://www.python.org/">Python, <em>the</em> best language around</a> <a class="footnote-reference" href="#id25" id="id28">[5]</a>.</p> </div> <div class="section" id="compound-paragraph"> -<h3><a class="toc-backref" href="#id80">2.14.7 Compound Paragraph</a></h3> +<h3><a class="toc-backref" href="#id83">2.14.7 Compound Paragraph</a></h3> <div class="some-class compound"> <p class="compound-first">Compound 1, paragraph 1.</p> <p class="compound-middle">Compound 1, paragraph 2.</p> @@ -820,7 +829,7 @@ paragraph.</td> </div> </div> <div class="section" id="parsed-literal-blocks"> -<h3><a class="toc-backref" href="#id81">2.14.8 Parsed Literal Blocks</a></h3> +<h3><a class="toc-backref" href="#id84">2.14.8 Parsed Literal Blocks</a></h3> <pre class="literal-block"> This is a parsed literal block. This line is indented. The next line is blank. @@ -829,14 +838,38 @@ Inline markup is supported, e.g. <em>emphasis</em>, <strong>strong</strong>, <tt text</tt>, footnotes <a class="footnote-reference" href="#id8" id="id22">[1]</a>, <span class="target" id="hyperlink-targets">hyperlink targets</span>, and <a class="reference external" href="http://www.python.org/">references</a>. </pre> </div> +<div class="section" id="code"> +<h3><a class="toc-backref" href="#id85">2.14.9 Code</a></h3> +<p>Blocks of source code can be set with the <cite>code</cite> directive. If the +code language is specified, the content is parsed and tagged by the +<a class="reference external" href="http://pygments.org/">Pygments</a> <a class="footnote-reference" href="#id29" id="id30">[6]</a> syntax highlighter and can be formatted with a style sheet:</p> +<pre class="code python literal-block"> +<span class="k">print</span> <span class="s">'This is Python code.'</span> +</pre> +<p>There is an option for line numbers with optional start value:</p> +<pre class="code python literal-block"> +<span class="l n"> 8 </span><span class="c"># print integers from 0 to 9:</span> +<span class="ln"> 9 </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">):</span> +<span class="ln">10 </span> <span class="k">print</span> <span class="n">i</span> +</pre> +<p>For inline code snippets, there is the <cite>code</cite> role, which can be used +directly (the code will not be parsed/tagged, as the language is not +known) or as base for special code roles, e.g.,</p> +<!-- --> +<blockquote> +Docutils uses LaTeX syntax for math directives and roles: +<tt class="code latex tex docutils literal">\alpha = f(x) +</tt> prints <math xmlns="http://www.w3.org/1998/Math/MathML"> +<mrow><mi>α</mi><mo>=</mo><mi>f</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow></math>.</blockquote> +</div> </div> <div class="section" id="substitution-definitions"> -<h2><a class="toc-backref" href="#id62">2.15 Substitution Definitions</a></h2> +<h2><a class="toc-backref" href="#id65">2.15 Substitution Definitions</a></h2> <p>An inline image (<img alt="EXAMPLE" src="../../../docs/user/rst/images/biohazard.png" />) example:</p> <p>(Substitution definitions are not visible in the HTML source.)</p> </div> <div class="section" id="comments"> -<h2><a class="toc-backref" href="#id63">2.16 Comments</a></h2> +<h2><a class="toc-backref" href="#id66">2.16 Comments</a></h2> <p>Here's one:</p> <!-- Comments begin with two dots and a space. Anything may follow, except for the syntax of footnotes, hyperlink @@ -848,20 +881,20 @@ Comments may contain non-ASCII characters: ä ö ü æ ø å --> <p>(View the HTML source to see the comment.)</p> </div> <div class="section" id="raw-text"> -<h2><a class="toc-backref" href="#id64">2.17 Raw text</a></h2> +<h2><a class="toc-backref" href="#id67">2.17 Raw text</a></h2> <p>This does not necessarily look nice, because there may be missing white space.</p> <p>It's just there to freeze the behavior.</p> A test.Second test.<div class="myclass">Another test with myclass set.</div><p>This is the <span class="myrawroleclass">fourth test</span> with myrawroleclass set.</p> Fifth test in HTML.<br />Line two.</div> <div class="section" id="container"> -<h2><a class="toc-backref" href="#id65">2.18 Container</a></h2> +<h2><a class="toc-backref" href="#id68">2.18 Container</a></h2> <div class="custom container"> <p>paragraph 1</p> <p>paragraph 2</p> </div> </div> <div class="section" id="colspanning-tables"> -<h2><a class="toc-backref" href="#id66">2.19 Colspanning tables</a></h2> +<h2><a class="toc-backref" href="#id69">2.19 Colspanning tables</a></h2> <p>This table has a cell spanning two columns:</p> <table border="1" class="docutils"> <colgroup> @@ -899,7 +932,7 @@ Fifth test in HTML.<br />Line two.</div> </table> </div> <div class="section" id="rowspanning-tables"> -<h2><a class="toc-backref" href="#id67">2.20 Rowspanning tables</a></h2> +<h2><a class="toc-backref" href="#id70">2.20 Rowspanning tables</a></h2> <p>Here's a table with cells spanning several rows:</p> <table border="1" class="docutils"> <colgroup> @@ -932,7 +965,7 @@ cell.</td> </table> </div> <div class="section" id="complex-tables"> -<h2><a class="toc-backref" href="#id68">2.21 Complex tables</a></h2> +<h2><a class="toc-backref" href="#id71">2.21 Complex tables</a></h2> <p>Here's a complex table, which should test all features.</p> <table border="1" class="docutils"> <colgroup> @@ -981,7 +1014,7 @@ empty: <tt class="docutils literal"><span class="pre">--></span></tt></td> </table> </div> <div class="section" id="list-tables"> -<h2><a class="toc-backref" href="#id69">2.22 List Tables</a></h2> +<h2><a class="toc-backref" href="#id72">2.22 List Tables</a></h2> <p>Here's a list table exercising all features:</p> <table border="1" class="test docutils"> <caption>list table with integral header</caption> @@ -1014,7 +1047,7 @@ crunchy, now would it?</td> </table> </div> <div class="section" id="custom-roles"> -<h2><a class="toc-backref" href="#id70">2.23 Custom Roles</a></h2> +<h2><a class="toc-backref" href="#id73">2.23 Custom Roles</a></h2> <ul> <li><p class="first">A role based on an existing role.</p> <p><tt class="custom docutils literal">one</tt> <tt class="custom docutils literal">two</tt> <tt class="custom docutils literal">three</tt></p> @@ -1044,7 +1077,7 @@ crunchy, now would it?</td> </ul> </div> <div class="section" id="svg-images"> -<h2><a class="toc-backref" href="#id71">2.24 SVG Images</a></h2> +<h2><a class="toc-backref" href="#id74">2.24 SVG Images</a></h2> <object data="../../../docs/user/rst/images/biohazard.svg" style="width: 48px; height: 48px;" type="image/svg+xml"> ../../../docs/user/rst/images/biohazard.svg</object> <p>Scalable vector graphics (SVG) images are not supported by all backends. @@ -1080,7 +1113,7 @@ reStructuredText, the markup syntax</object> </div> </div> <div class="section" id="swf-images"> -<h2><a class="toc-backref" href="#id72">2.25 SWF Images</a></h2> +<h2><a class="toc-backref" href="#id75">2.25 SWF Images</a></h2> <p>Shockwave Flash is an image/movie format that most modern web browsers support via a plugin. It is sometimes blocked due to privacy/security concerns.</p> @@ -1093,7 +1126,7 @@ For complete control over display options use raw HTML.</p> </div> </div> <div class="section" id="error-handling"> -<h1><a class="toc-backref" href="#id73">3 Error Handling</a></h1> +<h1><a class="toc-backref" href="#id76">3 Error Handling</a></h1> <p>Any errors caught during processing will generate system messages.</p> <p>There should be five messages in the following, auto-generated section, "Docutils System Messages":</p> @@ -1104,17 +1137,17 @@ section, "Docutils System Messages":</p> <div class="system-message" id="id23"> <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/standard.txt</tt>, line 104); <em><a href="#id24">backlink</a></em></p> Undefined substitution referenced: "problematic".</div> -<div class="system-message" id="id82"> -<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/standard.txt</tt>, line 390); <em><a href="#id83">backlink</a></em></p> +<div class="system-message" id="id86"> +<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/standard.txt</tt>, line 391); <em><a href="#id87">backlink</a></em></p> Unknown target name: "5".</div> -<div class="system-message" id="id84"> -<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/standard.txt</tt>, line 399); <em><a href="#id85">backlink</a></em></p> +<div class="system-message" id="id88"> +<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/standard.txt</tt>, line 400); <em><a href="#id89">backlink</a></em></p> Unknown target name: "nonexistent".</div> -<div class="system-message" id="id86"> -<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/standard.txt</tt>, line 426); <em><a href="#id87">backlink</a></em></p> +<div class="system-message" id="id90"> +<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/standard.txt</tt>, line 427); <em><a href="#id91">backlink</a></em></p> Unknown target name: "hyperlink reference without a target".</div> -<div class="system-message" id="id88"> -<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/standard.txt</tt>, line 439); <em><a href="#id89">backlink</a></em></p> +<div class="system-message" id="id92"> +<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/standard.txt</tt>, line 440); <em><a href="#id93">backlink</a></em></p> Duplicate target name, cannot be used as a unique reference: "duplicate target names".</div> </div> </div> diff --git a/test/functional/expected/standalone_rst_latex.tex b/test/functional/expected/standalone_rst_latex.tex index 2db3ff0cb..28e8f7e50 100644 --- a/test/functional/expected/standalone_rst_latex.tex +++ b/test/functional/expected/standalone_rst_latex.tex @@ -368,7 +368,7 @@ Paragraphs contain text and may contain inline markup: \emph{emphasis}, (\url{http://www.python.org}), external hyperlinks (\href{http://www.python.org/}{Python}\DUfootnotemark{id30}{id29}{5}), internal cross-references (\hyperref[example]{example}), external hyperlinks with embedded URIs (\href{http://www.python.org}{Python web site}), \href{http://www.python.org/}{anonymous hyperlink -references}\DUfootnotemark{id36}{id29}{5} (\href{http://docutils.sourceforge.net/}{a second reference}\DUfootnotemark{id38}{id37}{7}), footnote references (manually +references}\DUfootnotemark{id38}{id29}{5} (\href{http://docutils.sourceforge.net/}{a second reference}\DUfootnotemark{id40}{id39}{8}), footnote references (manually numbered\DUfootnotemark{id1}{id8}{1}, anonymous auto-numbered\DUfootnotemark{id2}{id12}{3}, labeled auto-numbered\DUfootnotemark{id3}{label}{2}, or symbolic\DUfootnotemark{id4}{id13}{*}), citation references (\hyperlink{cit2002}{[CIT2002]}), substitution references (\includegraphics{../../../docs/user/rst/images/biohazard.png}), and % \phantomsection\label{inline-hyperlink-targets}inline hyperlink targets @@ -380,9 +380,10 @@ reference to the \hyperref[doctitle]{doctitle} and the \hyperref[subtitle]{subti The default role for interpreted text is \DUroletitlereference{Title Reference}. Here are some explicit interpreted text roles: a PEP reference (\href{http://www.python.org/dev/peps/pep-0287}{PEP 287}); an -RFC reference (\href{http://www.faqs.org/rfcs/rfc2822.html}{RFC 2822}); a \textsubscript{subscript}; a \textsuperscript{superscript}; -and explicit roles for \emph{standard} \textbf{inline} -\texttt{markup}. +RFC reference (\href{http://www.faqs.org/rfcs/rfc2822.html}{RFC 2822}); an abbreviation (\DUrole{abbreviation}{abb.}), an acronym +(\DUrole{acronym}{reST}), code (\texttt{\DUrole{code}{print "hello world"}}); a \textsubscript{subscript}; +a \textsuperscript{superscript} and explicit roles for \DUroletitlereference{Docutils}' +\emph{standard} \textbf{inline} \texttt{markup}. % DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! @@ -862,8 +863,8 @@ This footnote shows the next symbol in the sequence. \DUfootnotetext{id16}{id16}{4}{% Here's an unreferenced footnote, with a reference to a nonexistent footnote:% -\raisebox{1em}{\hypertarget{id44}{}}% -\raisebox{1em}{\hypertarget{id17}{}}\hyperlink{id43}{\textbf{\color{red}{[}5{]}\_}}. +\raisebox{1em}{\hypertarget{id46}{}}% +\raisebox{1em}{\hypertarget{id17}{}}\hyperlink{id45}{\textbf{\color{red}{[}5{]}\_}}. } @@ -880,8 +881,8 @@ rendered separately and differently from footnotes. \end{figure} Here's a reference to the above, \hyperlink{cit2002}{[CIT2002]}, and a % -\raisebox{1em}{\hypertarget{id46}{}}% -\raisebox{1em}{\hypertarget{id19}{}}\hyperlink{id45}{\textbf{\color{red}{[}nonexistent{]}\_}} +\raisebox{1em}{\hypertarget{id48}{}}% +\raisebox{1em}{\hypertarget{id19}{}}\hyperlink{id47}{\textbf{\color{red}{[}nonexistent{]}\_}} citation. @@ -909,7 +910,7 @@ Targets may be indirect and anonymous. Thus \hyperref[targets]{this phrase} may refer to the \hyperref[targets]{Targets} section. Here's a % -\raisebox{1em}{\hypertarget{id48}{}}\hyperlink{id47}{\textbf{\color{red}`hyperlink reference without a target`\_}}, which generates an +\raisebox{1em}{\hypertarget{id50}{}}\hyperlink{id49}{\textbf{\color{red}`hyperlink reference without a target`\_}}, which generates an error. @@ -937,7 +938,7 @@ explicit targets will generate ``warning'' (level-2) system messages. Since there are two ``Duplicate Target Names'' section headers, we cannot uniquely refer to either of them by name. If we try to (like this: % -\raisebox{1em}{\hypertarget{id50}{}}\hyperlink{id49}{\textbf{\color{red}`Duplicate Target Names`\_}}), an error is generated. +\raisebox{1em}{\hypertarget{id52}{}}\hyperlink{id51}{\textbf{\color{red}`Duplicate Target Names`\_}}), an error is generated. %___________________________________________________________________________ @@ -1240,14 +1241,18 @@ allowed (e.g. inside a directive). } % \DUfootnotetext{id33}{id34}{6}{% +\url{http://pygments.org/} +} +% +\DUfootnotetext{id35}{id36}{7}{% \url{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf} } % -\DUfootnotetext{id37}{id38}{7}{% +\DUfootnotetext{id39}{id40}{8}{% \url{http://docutils.sourceforge.net/} } % -\DUfootnotetext{id39}{id40}{8}{% +\DUfootnotetext{id41}{id42}{9}{% \url{A:DOS\\path\\} } @@ -1365,6 +1370,47 @@ text},~footnotes\DUfootnotemark{id22}{id8}{1},~% %___________________________________________________________________________ +\subsubsection*{\phantomsection% + 2.14.9~~~Code% + \addcontentsline{toc}{subsubsection}{2.14.9~~~Code}% + \label{code}% +} + +Blocks of source code can be set with the \DUroletitlereference{code} directive. If the +code language is specified, the content is parsed and tagged by the +\href{http://pygments.org/}{Pygments}\DUfootnotemark{id34}{id33}{6} syntax highlighter and can be formatted with a style sheet: +% +\begin{quote}{\ttfamily \raggedright \noindent +\DUrole{k}{print}~\DUrole{s}{'This~is~Python~code.'} +} +\end{quote} + +There is an option for line numbers with optional start value: +% +\begin{quote}{\ttfamily \raggedright \noindent +\DUrole{l}{\DUrole{n}{~8~}}\DUrole{c}{\#~print~integers~from~0~to~9:}~\\ +\DUrole{ln}{~9~}\DUrole{k}{for}~\DUrole{n}{i}~\DUrole{ow}{in}~\DUrole{nb}{range}\DUrole{p}{(}\DUrole{mi}{10}\DUrole{p}{):}~\\ +\DUrole{ln}{10~}~~~~\DUrole{k}{print}~\DUrole{n}{i} +} +\end{quote} + +For inline code snippets, there is the \DUroletitlereference{code} role, which can be used +directly (the code will not be parsed/tagged, as the language is not +known) or as base for special code roles, e.g., + +% +% +\begin{quote} + +Docutils uses LaTeX syntax for math directives and roles: +\texttt{\DUrole{code}{\DUrole{latex}{\DUrole{tex}{\DUrole{k}{\textbackslash{}alpha} = f(x) +}}}} prints $\alpha = f(x)$. + +\end{quote} + + +%___________________________________________________________________________ + \subsection*{\phantomsection% 2.15~~~Substitution Definitions% \addcontentsline{toc}{subsection}{2.15~~~Substitution Definitions}% @@ -1735,7 +1781,7 @@ Modulation Transfer Function: \right). \end{equation*} Math split over two lines: If a double backslash is detected outside a -\texttt{\textbackslash{}begin\{...\} \textbackslash{}end\{...\}} pair, the math code is wrapped in an \href{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf}{AMSmath}\DUfootnotemark{id34}{id33}{6} +\texttt{\textbackslash{}begin\{...\} \textbackslash{}end\{...\}} pair, the math code is wrapped in an \href{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf}{AMSmath}\DUfootnotemark{id36}{id35}{7} \texttt{align} environment: % \begin{align*} @@ -1750,7 +1796,7 @@ Cases (``manually'', with \texttt{matrix} environment): 1 & x>0 \end{matrix}\right. \end{equation*} -Cases with the \href{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf}{AMSmath}\DUfootnotemark{id35}{id33}{6} \texttt{cases} environment (not (yet) supported by +Cases with the \href{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf}{AMSmath}\DUfootnotemark{id37}{id35}{7} \texttt{cases} environment (not (yet) supported by HTML writers with \texttt{-{}-math-output=MathML}): % \begin{equation*} @@ -2533,7 +2579,7 @@ Handling by the LaTeX writer: \url{http://www.w3.org/XML/Schema\#dev} \item[] \href{http://www.w3.org/XML/Schema\%dev}{URL with \%} \url{http://example.org/Schema\%dev} -\item[] \href{A:DOS\\path\\}{file with DOS path}\DUfootnotemark{id40}{id39}{8} \url{A:DOS\\path\\}\DUfootnotemark{id41}{id39}{8} +\item[] \href{A:DOS\\path\\}{file with DOS path}\DUfootnotemark{id42}{id41}{9} \url{A:DOS\\path\\}\DUfootnotemark{id43}{id41}{9} \end{DUlineblock} \DUadmonition[note]{ @@ -2544,7 +2590,7 @@ These URLs are typeset inside a LaTeX command without error. \begin{DUlineblock}{0em} \item[] \url{http://www.w3.org/XML/Schema\#dev} \item[] \url{http://example.org/Schema\%dev} -\item[] \url{A:DOS\\path\\}\DUfootnotemark{id42}{id39}{8} +\item[] \url{A:DOS\\path\\}\DUfootnotemark{id44}{id41}{9} \end{DUlineblock} } @@ -2617,41 +2663,41 @@ Undefined substitution referenced: ``problematic''. \DUadmonition[system-message]{ \DUtitle[system-message]{system-message} -\raisebox{1em}{\hypertarget{id43}{}} +\raisebox{1em}{\hypertarget{id45}{}} -{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~390 +{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~391 -\hyperlink{id44}{ +\hyperlink{id46}{ Unknown target name: ``5''. }} \DUadmonition[system-message]{ \DUtitle[system-message]{system-message} -\raisebox{1em}{\hypertarget{id45}{}} +\raisebox{1em}{\hypertarget{id47}{}} -{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~399 +{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~400 -\hyperlink{id46}{ +\hyperlink{id48}{ Unknown target name: ``nonexistent''. }} \DUadmonition[system-message]{ \DUtitle[system-message]{system-message} -\raisebox{1em}{\hypertarget{id47}{}} +\raisebox{1em}{\hypertarget{id49}{}} -{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~426 +{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~427 -\hyperlink{id48}{ +\hyperlink{id50}{ Unknown target name: ``hyperlink reference without a target''. }} \DUadmonition[system-message]{ \DUtitle[system-message]{system-message} -\raisebox{1em}{\hypertarget{id49}{}} +\raisebox{1em}{\hypertarget{id51}{}} -{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~439 +{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~440 -\hyperlink{id50}{ +\hyperlink{id52}{ Duplicate target name, cannot be used as a unique reference: ``duplicate target names''. }} diff --git a/test/functional/expected/standalone_rst_pseudoxml.txt b/test/functional/expected/standalone_rst_pseudoxml.txt index 5d8dc2b9c..6a89816c1 100644 --- a/test/functional/expected/standalone_rst_pseudoxml.txt +++ b/test/functional/expected/standalone_rst_pseudoxml.txt @@ -93,250 +93,256 @@ <bullet_list classes="auto-toc"> <list_item> <paragraph> - <reference ids="id32" refid="structural-elements"> + <reference ids="id34" refid="structural-elements"> <generated classes="sectnum"> 1 Structural Elements <bullet_list classes="auto-toc"> <list_item> <paragraph> - <reference ids="id33" refid="section-title"> + <reference ids="id35" refid="section-title"> <generated classes="sectnum"> 1.1 Section Title <list_item> <paragraph> - <reference ids="id34" refid="empty-section"> + <reference ids="id36" refid="empty-section"> <generated classes="sectnum"> 1.2 Empty Section <list_item> <paragraph> - <reference ids="id35" refid="transitions"> + <reference ids="id37" refid="transitions"> <generated classes="sectnum"> 1.3 Transitions <list_item> <paragraph> - <reference ids="id36" refid="body-elements"> + <reference ids="id38" refid="body-elements"> <generated classes="sectnum"> 2 Body Elements <bullet_list classes="auto-toc"> <list_item> <paragraph> - <reference ids="id37" refid="paragraphs"> + <reference ids="id39" refid="paragraphs"> <generated classes="sectnum"> 2.1 Paragraphs <bullet_list classes="auto-toc"> <list_item> <paragraph> - <reference ids="id38" refid="inline-markup"> + <reference ids="id40" refid="inline-markup"> <generated classes="sectnum"> 2.1.1 Inline Markup <list_item> <paragraph> - <reference ids="id39" refid="bullet-lists"> + <reference ids="id41" refid="bullet-lists"> <generated classes="sectnum"> 2.2 Bullet Lists <list_item> <paragraph> - <reference ids="id40" refid="enumerated-lists"> + <reference ids="id42" refid="enumerated-lists"> <generated classes="sectnum"> 2.3 Enumerated Lists <list_item> <paragraph> - <reference ids="id41" refid="definition-lists"> + <reference ids="id43" refid="definition-lists"> <generated classes="sectnum"> 2.4 Definition Lists <list_item> <paragraph> - <reference ids="id42" refid="field-lists"> + <reference ids="id44" refid="field-lists"> <generated classes="sectnum"> 2.5 Field Lists <list_item> <paragraph> - <reference ids="id43" refid="option-lists"> + <reference ids="id45" refid="option-lists"> <generated classes="sectnum"> 2.6 Option Lists <list_item> <paragraph> - <reference ids="id44" refid="literal-blocks"> + <reference ids="id46" refid="literal-blocks"> <generated classes="sectnum"> 2.7 Literal Blocks <list_item> <paragraph> - <reference ids="id45" refid="line-blocks"> + <reference ids="id47" refid="line-blocks"> <generated classes="sectnum"> 2.8 Line Blocks <list_item> <paragraph> - <reference ids="id46" refid="block-quotes"> + <reference ids="id48" refid="block-quotes"> <generated classes="sectnum"> 2.9 Block Quotes <list_item> <paragraph> - <reference ids="id47" refid="doctest-blocks"> + <reference ids="id49" refid="doctest-blocks"> <generated classes="sectnum"> 2.10 Doctest Blocks <list_item> <paragraph> - <reference ids="id48" refid="footnotes"> + <reference ids="id50" refid="footnotes"> <generated classes="sectnum"> 2.11 Footnotes <list_item> <paragraph> - <reference ids="id49" refid="citations"> + <reference ids="id51" refid="citations"> <generated classes="sectnum"> 2.12 Citations <list_item> <paragraph> - <reference ids="id50" refid="targets"> + <reference ids="id52" refid="targets"> <generated classes="sectnum"> 2.13 Targets <bullet_list classes="auto-toc"> <list_item> <paragraph> - <reference ids="id51" refid="duplicate-target-names"> + <reference ids="id53" refid="duplicate-target-names"> <generated classes="sectnum"> 2.13.1 Duplicate Target Names <list_item> <paragraph> - <reference ids="id52" refid="id21"> + <reference ids="id54" refid="id21"> <generated classes="sectnum"> 2.13.2 Duplicate Target Names <list_item> <paragraph> - <reference ids="id53" refid="directives"> + <reference ids="id55" refid="directives"> <generated classes="sectnum"> 2.14 Directives <bullet_list classes="auto-toc"> <list_item> <paragraph> - <reference ids="id54" refid="document-parts"> + <reference ids="id56" refid="document-parts"> <generated classes="sectnum"> 2.14.1 Document Parts <list_item> <paragraph> - <reference ids="id55" refid="images-and-figures"> + <reference ids="id57" refid="images-and-figures"> <generated classes="sectnum"> 2.14.2 Images and Figures <list_item> <paragraph> - <reference ids="id56" refid="admonitions"> + <reference ids="id58" refid="admonitions"> <generated classes="sectnum"> 2.14.3 Admonitions <list_item> <paragraph> - <reference ids="id57" refid="topics-sidebars-and-rubrics"> + <reference ids="id59" refid="topics-sidebars-and-rubrics"> <generated classes="sectnum"> 2.14.4 Topics, Sidebars, and Rubrics <list_item> <paragraph> - <reference ids="id58" refid="target-footnotes"> + <reference ids="id60" refid="target-footnotes"> <generated classes="sectnum"> 2.14.5 Target Footnotes <list_item> <paragraph> - <reference ids="id59" refid="replacement-text"> + <reference ids="id61" refid="replacement-text"> <generated classes="sectnum"> 2.14.6 Replacement Text <list_item> <paragraph> - <reference ids="id60" refid="compound-paragraph"> + <reference ids="id62" refid="compound-paragraph"> <generated classes="sectnum"> 2.14.7 Compound Paragraph <list_item> <paragraph> - <reference ids="id61" refid="parsed-literal-blocks"> + <reference ids="id63" refid="parsed-literal-blocks"> <generated classes="sectnum"> 2.14.8 Parsed Literal Blocks + <list_item> + <paragraph> + <reference ids="id64" refid="code"> + <generated classes="sectnum"> + 2.14.9 + Code <list_item> <paragraph> - <reference ids="id62" refid="substitution-definitions"> + <reference ids="id65" refid="substitution-definitions"> <generated classes="sectnum"> 2.15 Substitution Definitions <list_item> <paragraph> - <reference ids="id63" refid="comments"> + <reference ids="id66" refid="comments"> <generated classes="sectnum"> 2.16 Comments <list_item> <paragraph> - <reference ids="id64" refid="raw-text"> + <reference ids="id67" refid="raw-text"> <generated classes="sectnum"> 2.17 Raw text <list_item> <paragraph> - <reference ids="id65" refid="container"> + <reference ids="id68" refid="container"> <generated classes="sectnum"> 2.18 Container <list_item> <paragraph> - <reference ids="id66" refid="colspanning-tables"> + <reference ids="id69" refid="colspanning-tables"> <generated classes="sectnum"> 2.19 Colspanning tables <list_item> <paragraph> - <reference ids="id67" refid="rowspanning-tables"> + <reference ids="id70" refid="rowspanning-tables"> <generated classes="sectnum"> 2.20 Rowspanning tables <list_item> <paragraph> - <reference ids="id68" refid="complex-tables"> + <reference ids="id71" refid="complex-tables"> <generated classes="sectnum"> 2.21 Complex tables <list_item> <paragraph> - <reference ids="id69" refid="list-tables"> + <reference ids="id72" refid="list-tables"> <generated classes="sectnum"> 2.22 List Tables <list_item> <paragraph> - <reference ids="id70" refid="error-handling"> + <reference ids="id73" refid="error-handling"> <generated classes="sectnum"> 3 Error Handling <section ids="structural-elements" names="structural\ elements"> - <title auto="1" refid="id32"> + <title auto="1" refid="id34"> <generated classes="sectnum"> 1 Structural Elements <section ids="section-title" names="section\ title"> - <title auto="1" refid="id33"> + <title auto="1" refid="id35"> <generated classes="sectnum"> 1.1 Section Title @@ -352,12 +358,12 @@ sectsubtitle-xform configuration value. <section ids="empty-section" names="empty\ section"> - <title auto="1" refid="id34"> + <title auto="1" refid="id36"> <generated classes="sectnum"> 1.2 Empty Section <section ids="transitions" names="transitions"> - <title auto="1" refid="id35"> + <title auto="1" refid="id37"> <generated classes="sectnum"> 1.3 Transitions @@ -368,19 +374,19 @@ It divides the section. Transitions may also occur between sections: <transition> <section ids="body-elements" names="body\ elements"> - <title auto="1" refid="id36"> + <title auto="1" refid="id38"> <generated classes="sectnum"> 2 Body Elements <section ids="paragraphs" names="paragraphs"> - <title auto="1" refid="id37"> + <title auto="1" refid="id39"> <generated classes="sectnum"> 2.1 Paragraphs <paragraph> A paragraph. <section ids="inline-markup" names="inline\ markup"> - <title auto="1" refid="id38"> + <title auto="1" refid="id40"> <generated classes="sectnum"> 2.1.1 Inline Markup @@ -417,14 +423,14 @@ anonymous hyperlink references - <footnote_reference auto="1" ids="id29" refid="id25"> + <footnote_reference auto="1" ids="id31" refid="id25"> 5 ( <reference anonymous="1" name="a second reference" refuri="http://docutils.sourceforge.net/"> a second reference - <footnote_reference auto="1" ids="id31" refid="id30"> - 6 + <footnote_reference auto="1" ids="id33" refid="id32"> + 7 ), footnote references (manually numbered <footnote_reference ids="id1" refid="id8"> @@ -485,20 +491,33 @@ RFC reference ( <reference refuri="http://www.faqs.org/rfcs/rfc2822.html"> RFC 2822 + ); an abbreviation ( + <abbreviation> + abb. + ), an acronym + ( + <acronym> + reST + ), code ( + <literal classes="code"> + print "hello world" ); a <subscript> subscript - ; a + ; + a <superscript> superscript - ; - and explicit roles for + and explicit roles for + <title_reference> + Docutils + ' <emphasis> standard <strong> inline - + <literal> markup . @@ -519,7 +538,7 @@ option was supplied, there should be a live link to PEP 258 here. <section ids="bullet-lists" names="bullet\ lists"> - <title auto="1" refid="id39"> + <title auto="1" refid="id41"> <generated classes="sectnum"> 2.2 Bullet Lists @@ -563,7 +582,7 @@ <comment xml:space="preserve"> Even if this item contains a target and a comment. <section ids="enumerated-lists" names="enumerated\ lists"> - <title auto="1" refid="id40"> + <title auto="1" refid="id42"> <generated classes="sectnum"> 2.3 Enumerated Lists @@ -612,7 +631,7 @@ <paragraph> iv <section ids="definition-lists" names="definition\ lists"> - <title auto="1" refid="id41"> + <title auto="1" refid="id43"> <generated classes="sectnum"> 2.4 Definition Lists @@ -650,7 +669,7 @@ <paragraph> Definition <section ids="field-lists" names="field\ lists"> - <title auto="1" refid="id42"> + <title auto="1" refid="id44"> <generated classes="sectnum"> 2.5 Field Lists @@ -684,7 +703,7 @@ about credits but just for ensuring that the class attribute doesn't get stripped away.) <section ids="option-lists" names="option\ lists"> - <title auto="1" refid="id43"> + <title auto="1" refid="id45"> <generated classes="sectnum"> 2.6 Option Lists @@ -797,7 +816,7 @@ There must be at least two spaces between the option and the description. <section ids="literal-blocks" names="literal\ blocks"> - <title auto="1" refid="id44"> + <title auto="1" refid="id46"> <generated classes="sectnum"> 2.7 Literal Blocks @@ -819,7 +838,7 @@ > > Why didn't I think of that? <section ids="line-blocks" names="line\ blocks"> - <title auto="1" refid="id45"> + <title auto="1" refid="id47"> <generated classes="sectnum"> 2.8 Line Blocks @@ -922,7 +941,7 @@ w. <line> <section ids="block-quotes" names="block\ quotes"> - <title auto="1" refid="id46"> + <title auto="1" refid="id48"> <generated classes="sectnum"> 2.9 Block Quotes @@ -946,7 +965,7 @@ ReStructuredText est un langage de balisage léger utilisé notamment dans la documentation du langage Python. <section ids="doctest-blocks" names="doctest\ blocks"> - <title auto="1" refid="id47"> + <title auto="1" refid="id49"> <generated classes="sectnum"> 2.10 Doctest Blocks @@ -956,7 +975,7 @@ >>> print '(cut and pasted from interactive Python sessions)' (cut and pasted from interactive Python sessions) <section ids="footnotes" names="footnotes"> - <title auto="1" refid="id48"> + <title auto="1" refid="id50"> <generated classes="sectnum"> 2.11 Footnotes @@ -1016,11 +1035,11 @@ <paragraph> Here's an unreferenced footnote, with a reference to a nonexistent footnote: - <problematic ids="id80 id17" refid="id79"> + <problematic ids="id84 id17" refid="id83"> [5]_ . <section ids="citations" names="citations"> - <title auto="1" refid="id49"> + <title auto="1" refid="id51"> <generated classes="sectnum"> 2.12 Citations @@ -1035,13 +1054,13 @@ <citation_reference ids="id18" refid="cit2002"> CIT2002 , and a - <problematic ids="id82 id19" refid="id81"> + <problematic ids="id86 id19" refid="id85"> [nonexistent]_ citation. <target refid="another-target"> <section ids="targets another-target" names="targets another\ target"> - <title auto="1" refid="id50"> + <title auto="1" refid="id52"> <generated classes="sectnum"> 2.13 Targets @@ -1086,12 +1105,12 @@ <target anonymous="1" ids="id20" refid="targets"> <paragraph> Here's a - <problematic ids="id84" refid="id83"> + <problematic ids="id88" refid="id87"> `hyperlink reference without a target`_ , which generates an error. <section dupnames="duplicate\ target\ names" ids="duplicate-target-names"> - <title auto="1" refid="id51"> + <title auto="1" refid="id53"> <generated classes="sectnum"> 2.13.1 Duplicate Target Names @@ -1100,7 +1119,7 @@ generate "info" (level-1) system messages. Duplicate names in explicit targets will generate "warning" (level-2) system messages. <section dupnames="duplicate\ target\ names" ids="id21"> - <title auto="1" refid="id52"> + <title auto="1" refid="id54"> <generated classes="sectnum"> 2.13.2 Duplicate Target Names @@ -1108,11 +1127,11 @@ Since there are two "Duplicate Target Names" section headers, we cannot uniquely refer to either of them by name. If we try to (like this: - <problematic ids="id86" refid="id85"> + <problematic ids="id90" refid="id89"> `Duplicate Target Names`_ ), an error is generated. <section ids="directives" names="directives"> - <title auto="1" refid="id53"> + <title auto="1" refid="id55"> <generated classes="sectnum"> 2.14 Directives @@ -1120,52 +1139,58 @@ <bullet_list classes="auto-toc"> <list_item> <paragraph> - <reference ids="id71" refid="document-parts"> + <reference ids="id74" refid="document-parts"> <generated classes="sectnum"> 2.14.1 Document Parts <list_item> <paragraph> - <reference ids="id72" refid="images-and-figures"> + <reference ids="id75" refid="images-and-figures"> <generated classes="sectnum"> 2.14.2 Images and Figures <list_item> <paragraph> - <reference ids="id73" refid="admonitions"> + <reference ids="id76" refid="admonitions"> <generated classes="sectnum"> 2.14.3 Admonitions <list_item> <paragraph> - <reference ids="id74" refid="topics-sidebars-and-rubrics"> + <reference ids="id77" refid="topics-sidebars-and-rubrics"> <generated classes="sectnum"> 2.14.4 Topics, Sidebars, and Rubrics <list_item> <paragraph> - <reference ids="id75" refid="target-footnotes"> + <reference ids="id78" refid="target-footnotes"> <generated classes="sectnum"> 2.14.5 Target Footnotes <list_item> <paragraph> - <reference ids="id76" refid="replacement-text"> + <reference ids="id79" refid="replacement-text"> <generated classes="sectnum"> 2.14.6 Replacement Text <list_item> <paragraph> - <reference ids="id77" refid="compound-paragraph"> + <reference ids="id80" refid="compound-paragraph"> <generated classes="sectnum"> 2.14.7 Compound Paragraph <list_item> <paragraph> - <reference ids="id78" refid="parsed-literal-blocks"> + <reference ids="id81" refid="parsed-literal-blocks"> <generated classes="sectnum"> 2.14.8 Parsed Literal Blocks + <list_item> + <paragraph> + <reference ids="id82" refid="code"> + <generated classes="sectnum"> + 2.14.9 + Code <paragraph> These are just a sample of the many reStructuredText Directives. For others, please see @@ -1173,7 +1198,7 @@ http://docutils.sourceforge.net/docs/ref/rst/directives.html . <section ids="document-parts" names="document\ parts"> - <title auto="1" refid="id71"> + <title auto="1" refid="id74"> <generated classes="sectnum"> 2.14.1 Document Parts @@ -1188,7 +1213,7 @@ table of contents ). <section ids="images-and-figures" names="images\ and\ figures"> - <title auto="1" refid="id72"> + <title auto="1" refid="id75"> <generated classes="sectnum"> 2.14.2 Images and Figures @@ -1325,7 +1350,7 @@ This paragraph might flow around the figure. The specific behavior depends upon the style sheet and the browser or rendering software used. <section ids="admonitions" names="admonitions"> - <title auto="1" refid="id73"> + <title auto="1" refid="id76"> <generated classes="sectnum"> 2.14.3 Admonitions @@ -1375,7 +1400,7 @@ You can make up your own admonition too. <target ids="docutils" names="docutils" refuri="http://docutils.sourceforge.net/"> <section ids="topics-sidebars-and-rubrics" names="topics,\ sidebars,\ and\ rubrics"> - <title auto="1" refid="id74"> + <title auto="1" refid="id77"> <generated classes="sectnum"> 2.14.4 Topics, Sidebars, and Rubrics @@ -1422,24 +1447,30 @@ is not allowed (e.g. inside a directive). <section ids="target-footnotes" names="target\ footnotes"> - <title auto="1" refid="id75"> + <title auto="1" refid="id78"> <generated classes="sectnum"> 2.14.5 Target Footnotes - <footnote auto="1" backrefs="id26 id27 id28 id29" ids="id25" names="TARGET_NOTE:\ id25"> + <footnote auto="1" backrefs="id26 id27 id28 id31" ids="id25" names="TARGET_NOTE:\ id25"> <label> 5 <paragraph> <reference refuri="http://www.python.org/"> http://www.python.org/ - <footnote auto="1" backrefs="id31" ids="id30" names="TARGET_NOTE:\ id30"> + <footnote auto="1" backrefs="id30" ids="id29" names="TARGET_NOTE:\ id29"> <label> 6 <paragraph> + <reference refuri="http://pygments.org/"> + http://pygments.org/ + <footnote auto="1" backrefs="id33" ids="id32" names="TARGET_NOTE:\ id32"> + <label> + 7 + <paragraph> <reference refuri="http://docutils.sourceforge.net/"> http://docutils.sourceforge.net/ <section ids="replacement-text" names="replacement\ text"> - <title auto="1" refid="id76"> + <title auto="1" refid="id79"> <generated classes="sectnum"> 2.14.6 Replacement Text @@ -1460,7 +1491,7 @@ the best language around <section ids="compound-paragraph" names="compound\ paragraph"> - <title auto="1" refid="id77"> + <title auto="1" refid="id80"> <generated classes="sectnum"> 2.14.7 Compound Paragraph @@ -1546,7 +1577,7 @@ <paragraph> Compound 7, another paragraph. <section ids="parsed-literal-blocks" names="parsed\ literal\ blocks"> - <title auto="1" refid="id78"> + <title auto="1" refid="id81"> <generated classes="sectnum"> 2.14.8 Parsed Literal Blocks @@ -1575,8 +1606,87 @@ references <target ids="references" names="references" refuri="http://www.python.org/"> . + <section ids="code" names="code"> + <title auto="1" refid="id82"> + <generated classes="sectnum"> + 2.14.9 + Code + <paragraph> + Blocks of source code can be set with the + <title_reference> + code + directive. If the + code language is specified, the content is parsed and tagged by the + <reference name="Pygments" refuri="http://pygments.org/"> + Pygments + + <footnote_reference auto="1" ids="id30" refid="id29"> + 6 + syntax highlighter and can be formatted with a style sheet: + <literal_block classes="code python" xml:space="preserve"> + <inline classes="k"> + print + + <inline classes="s"> + 'This is Python code.' + <paragraph> + There is an option for line numbers with optional start value: + <literal_block classes="code python" xml:space="preserve"> + <inline classes="ln"> + 8 + <inline classes="c"> + # print integers from 0 to 9: + + <inline classes="ln"> + 9 + <inline classes="k"> + for + + <inline classes="n"> + i + + <inline classes="ow"> + in + + <inline classes="nb"> + range + <inline classes="p"> + ( + <inline classes="mi"> + 10 + <inline classes="p"> + ): + + <inline classes="ln"> + 10 + + <inline classes="k"> + print + + <inline classes="n"> + i + <paragraph> + For inline code snippets, there is the + <title_reference> + code + role, which can be used + directly (the code will not be parsed/tagged, as the language is not + known) or as base for special code roles, e.g., + <comment xml:space="preserve"> + <block_quote> + <paragraph> + Docutils uses LaTeX syntax for math directives and roles: + <literal classes="code latex tex"> + <inline classes="k"> + \alpha + = f(x) + prints + <math> + \alpha = f(x) + . + <target ids="pygments" names="pygments" refuri="http://pygments.org/"> <section ids="substitution-definitions" names="substitution\ definitions"> - <title auto="1" refid="id62"> + <title auto="1" refid="id65"> <generated classes="sectnum"> 2.15 Substitution Definitions @@ -1589,7 +1699,7 @@ <paragraph> (Substitution definitions are not visible in the HTML source.) <section ids="comments" names="comments"> - <title auto="1" refid="id63"> + <title auto="1" refid="id66"> <generated classes="sectnum"> 2.16 Comments @@ -1606,7 +1716,7 @@ <paragraph> (View the HTML source to see the comment.) <section ids="raw-text" names="raw\ text"> - <title auto="1" refid="id64"> + <title auto="1" refid="id67"> <generated classes="sectnum"> 2.17 Raw text @@ -1630,7 +1740,7 @@ <raw format="latex" xml:space="preserve"> Fifth test in LaTeX.\\Line two. <section ids="container" names="container"> - <title auto="1" refid="id65"> + <title auto="1" refid="id68"> <generated classes="sectnum"> 2.18 Container @@ -1640,7 +1750,7 @@ <paragraph> paragraph 2 <section ids="colspanning-tables" names="colspanning\ tables"> - <title auto="1" refid="id66"> + <title auto="1" refid="id69"> <generated classes="sectnum"> 2.19 Colspanning tables @@ -1711,7 +1821,7 @@ <paragraph> True <section ids="rowspanning-tables" names="rowspanning\ tables"> - <title auto="1" refid="id67"> + <title auto="1" refid="id70"> <generated classes="sectnum"> 2.20 Rowspanning tables @@ -1763,7 +1873,7 @@ <paragraph> body row 3 <section ids="complex-tables" names="complex\ tables"> - <title auto="1" refid="id68"> + <title auto="1" refid="id71"> <generated classes="sectnum"> 2.21 Complex tables @@ -1848,7 +1958,7 @@ --> <entry> <section ids="list-tables" names="list\ tables"> - <title auto="1" refid="id69"> + <title auto="1" refid="id72"> <generated classes="sectnum"> 2.22 List Tables @@ -1905,7 +2015,7 @@ <paragraph> On a stick! <section ids="error-handling" names="error\ handling"> - <title auto="1" refid="id70"> + <title auto="1" refid="id73"> <generated classes="sectnum"> 3 Error Handling @@ -1922,15 +2032,15 @@ <system_message backrefs="id24" ids="id23" level="3" line="104" source="functional/input/data/standard.txt" type="ERROR"> <paragraph> Undefined substitution referenced: "problematic". - <system_message backrefs="id80" ids="id79" level="3" line="390" source="functional/input/data/standard.txt" type="ERROR"> + <system_message backrefs="id84" ids="id83" level="3" line="391" source="functional/input/data/standard.txt" type="ERROR"> <paragraph> Unknown target name: "5". - <system_message backrefs="id82" ids="id81" level="3" line="399" source="functional/input/data/standard.txt" type="ERROR"> + <system_message backrefs="id86" ids="id85" level="3" line="400" source="functional/input/data/standard.txt" type="ERROR"> <paragraph> Unknown target name: "nonexistent". - <system_message backrefs="id84" ids="id83" level="3" line="426" source="functional/input/data/standard.txt" type="ERROR"> + <system_message backrefs="id88" ids="id87" level="3" line="427" source="functional/input/data/standard.txt" type="ERROR"> <paragraph> Unknown target name: "hyperlink reference without a target". - <system_message backrefs="id86" ids="id85" level="3" line="439" source="functional/input/data/standard.txt" type="ERROR"> + <system_message backrefs="id90" ids="id89" level="3" line="440" source="functional/input/data/standard.txt" type="ERROR"> <paragraph> Duplicate target name, cannot be used as a unique reference: "duplicate target names". diff --git a/test/functional/expected/standalone_rst_xetex.tex b/test/functional/expected/standalone_rst_xetex.tex index d2d28ad13..8034c0a12 100644 --- a/test/functional/expected/standalone_rst_xetex.tex +++ b/test/functional/expected/standalone_rst_xetex.tex @@ -4,6 +4,7 @@ \usepackage[no-sscript]{xltxtra} % loads fixltx2e, metalogo, xunicode, fontspec \defaultfontfeatures{Scale=MatchLowercase} \usepackage{ifthen} +\usepackage{amsmath} \usepackage{polyglossia} \setdefaultlanguage{english} \setotherlanguages{german,british,french} @@ -366,7 +367,7 @@ Paragraphs contain text and may contain inline markup: \emph{emphasis}, (\url{http://www.python.org}), external hyperlinks (\href{http://www.python.org/}{Python}\DUfootnotemark{id30}{id29}{5}), internal cross-references (\hyperref[example]{example}), external hyperlinks with embedded URIs (\href{http://www.python.org}{Python web site}), \href{http://www.python.org/}{anonymous hyperlink -references}\DUfootnotemark{id35}{id29}{5} (\href{http://docutils.sourceforge.net/}{a second reference}\DUfootnotemark{id37}{id36}{7}), footnote references (manually +references}\DUfootnotemark{id37}{id29}{5} (\href{http://docutils.sourceforge.net/}{a second reference}\DUfootnotemark{id39}{id38}{8}), footnote references (manually numbered\DUfootnotemark{id1}{id8}{1}, anonymous auto-numbered\DUfootnotemark{id2}{id12}{3}, labeled auto-numbered\DUfootnotemark{id3}{label}{2}, or symbolic\DUfootnotemark{id4}{id13}{*}), citation references (\hyperlink{cit2002}{[CIT2002]}), substitution references (\includegraphics{../../../docs/user/rst/images/biohazard.png}), and % \phantomsection\label{inline-hyperlink-targets}inline hyperlink targets @@ -378,9 +379,10 @@ reference to the \hyperref[doctitle]{doctitle} and the \hyperref[subtitle]{subti The default role for interpreted text is \DUroletitlereference{Title Reference}. Here are some explicit interpreted text roles: a PEP reference (\href{http://www.python.org/dev/peps/pep-0287}{PEP 287}); an -RFC reference (\href{http://www.faqs.org/rfcs/rfc2822.html}{RFC 2822}); a \textsubscript{subscript}; a \textsuperscript{superscript}; -and explicit roles for \emph{standard} \textbf{inline} -\texttt{markup}. +RFC reference (\href{http://www.faqs.org/rfcs/rfc2822.html}{RFC 2822}); an abbreviation (\DUrole{abbreviation}{abb.}), an acronym +(\DUrole{acronym}{reST}), code (\texttt{\DUrole{code}{print "hello world"}}); a \textsubscript{subscript}; +a \textsuperscript{superscript} and explicit roles for \DUroletitlereference{Docutils}' +\emph{standard} \textbf{inline} \texttt{markup}. % DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! @@ -860,8 +862,8 @@ This footnote shows the next symbol in the sequence. \DUfootnotetext{id16}{id16}{4}{% Here's an unreferenced footnote, with a reference to a nonexistent footnote:% -\raisebox{1em}{\hypertarget{id43}{}}% -\raisebox{1em}{\hypertarget{id17}{}}\hyperlink{id42}{\textbf{\color{red}{[}5{]}\_}}. +\raisebox{1em}{\hypertarget{id45}{}}% +\raisebox{1em}{\hypertarget{id17}{}}\hyperlink{id44}{\textbf{\color{red}{[}5{]}\_}}. } @@ -878,8 +880,8 @@ rendered separately and differently from footnotes. \end{figure} Here's a reference to the above, \hyperlink{cit2002}{[CIT2002]}, and a % -\raisebox{1em}{\hypertarget{id45}{}}% -\raisebox{1em}{\hypertarget{id19}{}}\hyperlink{id44}{\textbf{\color{red}{[}nonexistent{]}\_}} +\raisebox{1em}{\hypertarget{id47}{}}% +\raisebox{1em}{\hypertarget{id19}{}}\hyperlink{id46}{\textbf{\color{red}{[}nonexistent{]}\_}} citation. @@ -907,7 +909,7 @@ Targets may be indirect and anonymous. Thus \hyperref[targets]{this phrase} may refer to the \hyperref[targets]{Targets} section. Here's a % -\raisebox{1em}{\hypertarget{id47}{}}\hyperlink{id46}{\textbf{\color{red}`hyperlink reference without a target`\_}}, which generates an +\raisebox{1em}{\hypertarget{id49}{}}\hyperlink{id48}{\textbf{\color{red}`hyperlink reference without a target`\_}}, which generates an error. @@ -935,7 +937,7 @@ explicit targets will generate "warning" (level-2) system messages. Since there are two "Duplicate Target Names" section headers, we cannot uniquely refer to either of them by name. If we try to (like this: % -\raisebox{1em}{\hypertarget{id49}{}}\hyperlink{id48}{\textbf{\color{red}`Duplicate Target Names`\_}}), an error is generated. +\raisebox{1em}{\hypertarget{id51}{}}\hyperlink{id50}{\textbf{\color{red}`Duplicate Target Names`\_}}), an error is generated. %___________________________________________________________________________ @@ -1238,14 +1240,18 @@ allowed (e.g. inside a directive). } % \DUfootnotetext{id33}{id34}{6}{% +\url{http://pygments.org/} +} +% +\DUfootnotetext{id35}{id36}{7}{% \url{http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=polyglossia} } % -\DUfootnotetext{id36}{id37}{7}{% +\DUfootnotetext{id38}{id39}{8}{% \url{http://docutils.sourceforge.net/} } % -\DUfootnotetext{id38}{id39}{8}{% +\DUfootnotetext{id40}{id41}{9}{% \url{A:DOS\\path\\} } @@ -1363,6 +1369,47 @@ text},~footnotes\DUfootnotemark{id22}{id8}{1},~% %___________________________________________________________________________ +\subsubsection*{\phantomsection% + 2.14.9 Code% + \addcontentsline{toc}{subsubsection}{2.14.9 Code}% + \label{code}% +} + +Blocks of source code can be set with the \DUroletitlereference{code} directive. If the +code language is specified, the content is parsed and tagged by the +\href{http://pygments.org/}{Pygments}\DUfootnotemark{id34}{id33}{6} syntax highlighter and can be formatted with a style sheet: +% +\begin{quote}{\ttfamily \raggedright \noindent +\DUrole{k}{print}~\DUrole{s}{'This~is~Python~code.'} +} +\end{quote} + +There is an option for line numbers with optional start value: +% +\begin{quote}{\ttfamily \raggedright \noindent +\DUrole{l}{\DUrole{n}{~8~}}\DUrole{c}{\#~print~integers~from~0~to~9:}~\\ +~\DUrole{ln}{~9~}~\DUrole{k}{for}~\DUrole{n}{i}~\DUrole{ow}{in}~\DUrole{nb}{range}\DUrole{p}{(}\DUrole{mi}{10}\DUrole{p}{):}~\\ +~\DUrole{ln}{10~}~~~~\DUrole{k}{print}~\DUrole{n}{i} +} +\end{quote} + +For inline code snippets, there is the \DUroletitlereference{code} role, which can be used +directly (the code will not be parsed/tagged, as the language is not +known) or as base for special code roles, e.g., + +% +% +\begin{quote} + +Docutils uses LaTeX syntax for math directives and roles: +\texttt{\DUrole{code}{\DUrole{latex}{\DUrole{tex}{\DUrole{k}{\textbackslash{}alpha} = f(x) +}}}} prints $\alpha = f(x)$. + +\end{quote} + + +%___________________________________________________________________________ + \subsection*{\phantomsection% 2.15 Substitution Definitions% \addcontentsline{toc}{subsection}{2.15 Substitution Definitions}% @@ -2335,7 +2382,7 @@ Handling by the LaTeX writer: \url{http://www.w3.org/XML/Schema\#dev} \item[] \href{http://www.w3.org/XML/Schema\%dev}{URL with \%} \url{http://example.org/Schema\%dev} -\item[] \href{A:DOS\\path\\}{file with DOS path}\DUfootnotemark{id39}{id38}{8} \url{A:DOS\\path\\}\DUfootnotemark{id40}{id38}{8} +\item[] \href{A:DOS\\path\\}{file with DOS path}\DUfootnotemark{id41}{id40}{9} \url{A:DOS\\path\\}\DUfootnotemark{id42}{id40}{9} \end{DUlineblock} \DUadmonition[note]{ @@ -2346,7 +2393,7 @@ These URLs are typeset inside a LaTeX command without error. \begin{DUlineblock}{0em} \item[] \url{http://www.w3.org/XML/Schema\#dev} \item[] \url{http://example.org/Schema\%dev} -\item[] \url{A:DOS\\path\\}\DUfootnotemark{id41}{id38}{8} +\item[] \url{A:DOS\\path\\}\DUfootnotemark{id43}{id40}{9} \end{DUlineblock} } @@ -2395,7 +2442,7 @@ Latviešu, Lietuvių, Македонски, Монгол, Nāhuatl, Português, Русский, Slovenščina, Српски, Türkçe, Українська, Tiếng Việt, Volapük, Võro, ייִדיש , Žemaitėška. Currently, there is extended support for 28 languages in the -\href{http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=polyglossia}{polyglossia}\DUfootnotemark{id34}{id33}{6} package. +\href{http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=polyglossia}{polyglossia}\DUfootnotemark{id36}{id35}{7} package. % System Messages: @@ -2435,41 +2482,41 @@ Undefined substitution referenced: "problematic". \DUadmonition[system-message]{ \DUtitle[system-message]{system-message} -\raisebox{1em}{\hypertarget{id42}{}} +\raisebox{1em}{\hypertarget{id44}{}} -{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~390 +{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~391 -\hyperlink{id43}{ +\hyperlink{id45}{ Unknown target name: "5". }} \DUadmonition[system-message]{ \DUtitle[system-message]{system-message} -\raisebox{1em}{\hypertarget{id44}{}} +\raisebox{1em}{\hypertarget{id46}{}} -{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~399 +{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~400 -\hyperlink{id45}{ +\hyperlink{id47}{ Unknown target name: "nonexistent". }} \DUadmonition[system-message]{ \DUtitle[system-message]{system-message} -\raisebox{1em}{\hypertarget{id46}{}} +\raisebox{1em}{\hypertarget{id48}{}} -{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~426 +{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~427 -\hyperlink{id47}{ +\hyperlink{id49}{ Unknown target name: "hyperlink reference without a target". }} \DUadmonition[system-message]{ \DUtitle[system-message]{system-message} -\raisebox{1em}{\hypertarget{id48}{}} +\raisebox{1em}{\hypertarget{id50}{}} -{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~439 +{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~440 -\hyperlink{id49}{ +\hyperlink{id51}{ Duplicate target name, cannot be used as a unique reference: "duplicate target names". }} diff --git a/test/functional/input/data/standard.txt b/test/functional/input/data/standard.txt index 194c39fac..d2979844f 100644 --- a/test/functional/input/data/standard.txt +++ b/test/functional/input/data/standard.txt @@ -121,9 +121,10 @@ __ http://docutils.sourceforge.net/ The default role for interpreted text is `Title Reference`. Here are some explicit interpreted text roles: a PEP reference (:PEP:`287`); an -RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`; -and explicit roles for :emphasis:`standard` :strong:`inline` -:literal:`markup`. +RFC reference (:RFC:`2822`); an abbreviation (:ab:`abb.`), an acronym +(:ac:`reST`), code (:code:`print "hello world"`); a :sub:`subscript`; +a :sup:`superscript` and explicit roles for :title:`Docutils`' +:emphasis:`standard` :strong:`inline` :literal:`markup`. .. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! @@ -754,6 +755,41 @@ Parsed Literal Blocks text``, footnotes [1]_, _`hyperlink targets`, and `references <http://www.python.org/>`_. +Code +```` + +Blocks of source code can be set with the `code` directive. If the +code language is specified, the content is parsed and tagged by the +Pygments_ syntax highlighter and can be formatted with a style sheet: + +.. code:: python + + print 'This is Python code.' + +There is an option for line numbers with optional start value: + +.. code:: python + :number-lines: 8 + + # print integers from 0 to 9: + for i in range(10): + print i + +For inline code snippets, there is the `code` role, which can be used +directly (the code will not be parsed/tagged, as the language is not +known) or as base for special code roles, e.g., + +.. role:: tex(code) + :language: latex + +.. + + Docutils uses LaTeX syntax for math directives and roles: + :tex:`\alpha = f(x)` prints :math:`\alpha = f(x)`. + +.. _Pygments: http://pygments.org/ + + Substitution Definitions ------------------------ diff --git a/test/test_parsers/test_rst/test_directives/test_code.py b/test/test_parsers/test_rst/test_directives/test_code.py new file mode 100644 index 000000000..3d5e95409 --- /dev/null +++ b/test/test_parsers/test_rst/test_directives/test_code.py @@ -0,0 +1,233 @@ +#! /usr/bin/env python + +# $Id$ +# Author: Guenter Milde +# Copyright: This module has been placed in the public domain. + +""" +Test the 'code' directive in parsers/rst/directives/body.py. +""" + +from __init__ import DocutilsTestSupport +from docutils.parsers.code_analyzer import with_pygments + +def suite(): + s = DocutilsTestSupport.ParserTestSuite() + if not with_pygments: + del(totest['code-parsing']) + s.generateTests(totest) + return s + +totest = {} + +totest['code'] = [ +["""\ +.. code:: + + This is a code block. +""", +"""\ +<document source="test data"> + <literal_block classes="code" xml:space="preserve"> + This is a code block. +"""], +["""\ +.. code:: + :class: testclass + :name: without argument + + This is a code block with generic options. +""", +"""\ +<document source="test data"> + <literal_block classes="code testclass" ids="without-argument" names="without\ argument" xml:space="preserve"> + This is a code block with generic options. +"""], +["""\ +.. code:: text + :class: testclass + + This is a code block with text. +""", +"""\ +<document source="test data"> + <literal_block classes="code text testclass" xml:space="preserve"> + This is a code block with text. +"""], +["""\ +.. code:: + :number-lines: + + This is a code block with text. +""", +"""\ +<document source="test data"> + <literal_block classes="code" xml:space="preserve"> + <inline classes="ln"> + 1 \n\ + This is a code block with text. +"""], +["""\ +.. code:: + :number-lines: 30 + + This is a code block with text. +""", +"""\ +<document source="test data"> + <literal_block classes="code" xml:space="preserve"> + <inline classes="ln"> + 30 \n\ + This is a code block with text. +"""], +["""\ +.. code:: +""", +"""\ +<document source="test data"> + <system_message level="3" line="1" source="test data" type="ERROR"> + <paragraph> + Content block expected for the "code" directive; none found. + <literal_block xml:space="preserve"> + .. code:: +"""], +] + +totest['code-parsing'] = [ +["""\ +.. code:: python + :class: testclass + + print 'hello world' # to stdout +""", +"""\ +<document source="test data"> + <literal_block classes="code python testclass" xml:space="preserve"> + \n\ + <inline classes="k"> + print + \n\ + <inline classes="s"> + 'hello world' + \n\ + <inline classes="c"> + # to stdout +"""], +["""\ +.. code:: python + :class: testclass + :name: my_function + :number-lines: 7 + + def my_function(): + '''Test the lexer. + ''' + + # and now for something completely different + print 8/2 +""", +"""\ +<document source="test data"> + <literal_block classes="code python testclass" ids="my-function" names="my_function" xml:space="preserve"> + <inline classes="ln"> + 7 \n\ + <inline classes="k"> + def + \n\ + <inline classes="nf"> + my_function + <inline classes="p"> + (): + \n\ + <inline classes="ln"> + 8 \n\ + \n\ + <inline classes="sd"> + \'\'\'Test the lexer. + <inline classes="ln"> + 9 \n\ + <inline classes="sd"> + \'\'\' + \n\ + <inline classes="ln"> + 10 \n\ + \n\ + <inline classes="ln"> + 11 \n\ + \n\ + <inline classes="c"> + # and now for something completely different + \n\ + <inline classes="ln"> + 12 \n\ + \n\ + <inline classes="k"> + print + \n\ + <inline classes="mi"> + 8 + <inline classes="o"> + / + <inline classes="mi"> + 2 +"""], +["""\ +.. code:: latex + :class: testclass + + hello \emph{world} % emphasize +""", +"""\ +<document source="test data"> + <literal_block classes="code latex testclass" xml:space="preserve"> + hello \n\ + <inline classes="k"> + \\emph + <inline classes="nb"> + { + world + <inline classes="nb"> + } + \n\ + <inline classes="c"> + % emphasize"""], +["""\ +.. code:: s-lang + + % abc.sl + autoload("abc_mode", "abc"); +""", +"""\ +<document source="test data"> + <system_message level="2" line="1" source="test data" type="WARNING"> + <paragraph> + Cannot analyze code. No Pygments lexer found for "s-lang". + <literal_block xml:space="preserve"> + .. code:: s-lang + \n\ + % abc.sl + autoload("abc_mode", "abc"); +"""], +["""\ +Place the language name in a class argument to avoid the no-lexer warning: + +.. code:: + :class: s-lang + + % abc.sl + autoload("abc_mode", "abc"); +""", +"""\ +<document source="test data"> + <paragraph> + Place the language name in a class argument to avoid the no-lexer warning: + <literal_block classes="code s-lang" xml:space="preserve"> + % abc.sl + autoload("abc_mode", "abc"); +"""], +] + + +if __name__ == '__main__': + import unittest + unittest.main(defaultTest='suite') diff --git a/test/test_parsers/test_rst/test_directives/test_code_long.py b/test/test_parsers/test_rst/test_directives/test_code_long.py new file mode 100644 index 000000000..5240cfaa5 --- /dev/null +++ b/test/test_parsers/test_rst/test_directives/test_code_long.py @@ -0,0 +1,104 @@ +#! /usr/bin/env python + +# $Id$ +# Author: Guenter Milde +# Copyright: This module has been placed in the public domain. + +""" +Test the 'code' directive in body.py with syntax_highlight = 'long'. +""" + +from __init__ import DocutilsTestSupport +from docutils.parsers.code_analyzer import with_pygments + +def suite(): + s = DocutilsTestSupport.ParserTestSuite() + s = DocutilsTestSupport.ParserTestSuite(suite_settings={'syntax_highlight':'long'}) + if with_pygments: + s.generateTests(totest) + return s + +totest = {} + +totest['code-parsing-long'] = [ +["""\ +.. code:: python + :number-lines: 7 + + def my_function(): + '''Test the lexer. + ''' + + # and now for something completely different + print 8/2 +""", +"""\ +<document source="test data"> + <literal_block classes="code python" xml:space="preserve"> + <inline classes="ln"> + 7 \n\ + <inline classes="keyword"> + def + \n\ + <inline classes="name function"> + my_function + <inline classes="punctuation"> + (): + \n\ + <inline classes="ln"> + 8 \n\ + \n\ + <inline classes="literal string doc"> + \'\'\'Test the lexer. + <inline classes="ln"> + 9 \n\ + <inline classes="literal string doc"> + \'\'\' + \n\ + <inline classes="ln"> + 10 \n\ + \n\ + <inline classes="ln"> + 11 \n\ + \n\ + <inline classes="comment"> + # and now for something completely different + \n\ + <inline classes="ln"> + 12 \n\ + \n\ + <inline classes="keyword"> + print + \n\ + <inline classes="literal number integer"> + 8 + <inline classes="operator"> + / + <inline classes="literal number integer"> + 2 +"""], +["""\ +.. code:: latex + + hello \emph{world} % emphasize +""", +"""\ +<document source="test data"> + <literal_block classes="code latex" xml:space="preserve"> + hello \n\ + <inline classes="keyword"> + \\emph + <inline classes="name builtin"> + { + world + <inline classes="name builtin"> + } + \n\ + <inline classes="comment"> + % emphasize"""], +] + + +if __name__ == '__main__': + import unittest + unittest.main(defaultTest='suite') diff --git a/test/test_parsers/test_rst/test_directives/test_code_none.py b/test/test_parsers/test_rst/test_directives/test_code_none.py new file mode 100644 index 000000000..e30f3e59a --- /dev/null +++ b/test/test_parsers/test_rst/test_directives/test_code_none.py @@ -0,0 +1,80 @@ +#! /usr/bin/env python + +# $Id$ +# Author: Guenter Milde +# Copyright: This module has been placed in the public domain. + +""" +Test the 'code' directive in body.py with syntax_highlight = 'none'. +""" + +from __init__ import DocutilsTestSupport + +def suite(): + s = DocutilsTestSupport.ParserTestSuite() + s = DocutilsTestSupport.ParserTestSuite(suite_settings={'syntax_highlight':'none'}) + s.generateTests(totest) + return s + +totest = {} + +totest['code-parsing-none'] = [ +["""\ +.. code:: + + This is a code block. +""", +"""\ +<document source="test data"> + <literal_block classes="code" xml:space="preserve"> + This is a code block. +"""], +["""\ +.. code:: python + :number-lines: 7 + + def my_function(): + '''Test the lexer. + ''' + + # and now for something completely different + print 8/2 +""", +"""\ +<document source="test data"> + <literal_block classes="code python" xml:space="preserve"> + <inline classes="ln"> + 7 \n\ + def my_function(): + <inline classes="ln"> + 8 \n\ + \'\'\'Test the lexer. + <inline classes="ln"> + 9 \n\ + \'\'\' + <inline classes="ln"> + 10 \n\ + \n\ + <inline classes="ln"> + 11 \n\ + # and now for something completely different + <inline classes="ln"> + 12 \n\ + print 8/2 +"""], +["""\ +.. code:: latex + + hello \emph{world} % emphasize +""", +"""\ +<document source="test data"> + <literal_block classes="code latex" xml:space="preserve"> + hello \\emph{world} % emphasize +"""], +] + + +if __name__ == '__main__': + import unittest + unittest.main(defaultTest='suite') diff --git a/test/test_parsers/test_rst/test_interpreted.py b/test/test_parsers/test_rst/test_interpreted.py index a75c0ac9f..fcf3359d0 100755 --- a/test/test_parsers/test_rst/test_interpreted.py +++ b/test/test_parsers/test_rst/test_interpreted.py @@ -9,9 +9,12 @@ Tests for interpreted text in docutils/parsers/rst/states.py. """ from __init__ import DocutilsTestSupport +from docutils.parsers.code_analyzer import with_pygments def suite(): s = DocutilsTestSupport.ParserTestSuite() + if not with_pygments: + del(totest['code-parsing']) s.generateTests(totest) return s @@ -214,6 +217,80 @@ Simple explicit roles: """], ] +totest['code'] = [ +["""\ +Code role for inline code snippets: +:code:`$\alpha = \int_0^\infty f(x) dx$`. +""", +"""\ +<document source="test data"> + <paragraph> + Code role for inline code snippets: + <literal classes="code"> + $\x07lpha = \\int_0^\\infty f(x) dx$ + . +"""], +] + +totest['code-parsing'] = [ +["""\ +.. role:: tex(code) + :language: latex + +Custom role based on code role: +:tex:`$\alpha = f(x)$`. +""", +"""\ +<document source="test data"> + <paragraph> + Custom role based on code role: + <literal classes="code latex tex"> + <inline classes="s"> + $ + <inline classes="nb"> + \x07lpha \n\ + <inline classes="o"> + = + <inline classes="nb"> + f + <inline classes="o"> + ( + <inline classes="nb"> + x + <inline classes="o"> + ) + <inline classes="s"> + $ + . +"""], +["""\ +Custom role based on code role: + +.. role:: python(code) + :language: python + :class: testclass + +Python code :python:`print("The end")`. +""", +"""\ +<document source="test data"> + <paragraph> + Custom role based on code role: + <paragraph> + Python code \n\ + <literal classes="code python testclass"> + <inline classes="k"> + print + <inline classes="p"> + ( + <inline classes="s"> + "The end" + <inline classes="p"> + ) + . +"""], +] + totest['references'] = [ ["""\ :PEP:`0` |