Defines for reStructuredText parser

Defines for reStructuredText transforms

Documentation for plug-in directive 'code_block'

Formats a block of text as a code block. This directive depends upon the availability of the "states" program, part of the Unix "enscript" suite, to mark up the code; otherwise the code block will be returned as a simple literal block. The argument is optional and specifies the source language of the code block. If the code block is read from a file, the language will usually default correctly. The following language specifications are recognized:

ada asm awk c changelog cpp elisp fortran haskell html idl java javascript mail makefile nroff objc pascal perl postscript python scheme sh states synopsys tcl vba verilog vhdl

The directive has the following options:

:file: <filename>

Reads the code sample from a file rather than using the content block.

:color:

Specifies that "color" markup should be done. What this actually means is that the following interpreted-text roles are used for parts of the code markup:

comment	A comment in the language
function-name	A function name
variable-name	A variable name
keyword	A reserved keyword
reference-name	A reference name
string	A quoted string
builtin	Variable names built into language
type-name	Names associated with the language's type system

If any of these roles is undefined before processing the macro, a null definition is entered for them.

:level: <level>

The level of markup. <level> can be one of none, light, or heavy (default heavy). Ignored if :color: is specified.

:numbered:

Number the lines of the code block.

This directive also uses the following command-line definition:

-D code-block-states-file=<file>
	The file to be passed to the states program to specify how to do the formatting. Searches the perl include path to find the file. Default is "Text/Restructured/Directive/rst.st".

Documentation for plug-in directive 'if'

Executes its argument as a perl expression and returns its content if the perl expression is true. The content is interpreted as reStructuredText. It has no options. It processes the following defines:

-D perl='$a=1; $b=2'

Documentation for plug-in directive 'perl'

Executes perl code and interpolates the results. The code can be contained either in the arguments or the contents section (or both). It has the following options:

:lenient:

Causes the exit code for the subprocess to be ignored.

:file: <filename>

Takes the perl code from file <filename>.

:literal:

Interpret the returned value as a literal block.

If this option is not present, the return value is interpreted based on its type. If you return a text string, the text is interpreted as reStructuredText and is parsed again. If you return an internal DOM object (or list of them), the object is included directly into the parsed DOM structure. (This latter option requires knowledge of trip internals, but is the only way to create a pending DOM object for execution at transformation time rather than parse time.)

The perl directive makes the following global variables available for use within the perl code:

$SOURCE

The name of the source file containing the perl directive.

$LINENO

The line number of the perl directive within $SOURCE.

$DIRECTIVE

The literal text of the perl directive.

@INCLUDES

Array of [filename, linenumber] pairs of files which have included this one.

$opt_<x>

The <x> option from the command line. Changing one of these variables has no effect upon the parser. If you need to change one of the -D options to affect subsequent parsing, use $PARSER->{opt}{D}{option}.

$PARSER

The Text::Restructured parser object to allow text parsing within a perl directive.

$TOP_FILE

The name of the top-level file.

$VERSION

The version of prest (0.3.36).

The following defines are processed by the perl directive:

-D perl='$a=1; $b=2'

Documentation for plug-in directive 'system'

Executes a system (shell) command and interpolates the results. It has the following options:

:lenient:

Causes the exit code for the subprocess to be ignored.

:literal:

Interpret the returned value as a literal block.

If this option is not present, the return value is interpreted as reStructuredText and is parsed again.

Any error returned by the shell generates a level 3 error message. To see the output of a command that is expected to generate an error, do:

.. system:: <your command> 2>&1 | cat

The following defines are processed by the system directive:

Documentation for writer 'dom'

This writer dumps out the internal Document Object Model (DOM, also known as a doctree) in an indented format known as pseudo-XML. It is useful for checking the results of the parser or transformations. It recognizes the following defines:

Documentation for writer 'html'

This writer creates HTML output. It uses the following output defines:

Documentation for writer 'index'

This writer dumps index entries from one or more input files out in reST format. The following items are indexed:

1. Inline targets (if -W index-inline-targets)
2. Targets created using a target role (either the target role or some other role based upon target) specified with -W index-role-target). The index entry is either the visible text, or if there is none, the target name.
3. Indirect targets pointing to indexed targets (if -W index-indirect-targets)

The index writer sorts indices from all input files and put them into a table. Each row of the table contains an index entry and the location of the entry in the html version of the source file. An entry is also a reference to the definition in the corresponding html file.

This writer uses the following output defines:

Documentation for writer 'latex'

This writer creates an output in LaTeX format. It is definitely in alpha test state and will be reworked when the final docutils LaTeX writer becomes available.

It uses the following output defines:

There are a number of commands defined which specify default styles for rendering various items. These default styles can be overridden by putting \renewcommand definitions for them into some file.tex and then invoking with -W inputs=file. These commands are

\styleadmonitiontitle

Argument: the title (type) of the admonition. Default is centered boldface followed by a colon.

\styleauthor

Argument: an author. Default is emphasized.

\stylefieldname

Argument: the name of a field. Default is boldface followed by a colon.

\stylelegendtitle

Argument: the word "Legend". Default is boldface followed by a colon.

\styleoption

Arguments: the option string, the option argument(s) (may be null). Default is teletype option string followed by non-breaking space and italic option argument(s).

\stylesidebartitles

Arguments: the title for a sidebar, the subtitle for a sidebar (may be null). Default is centered boldface title followed by centered italic subtitle. Is not invoked if sidebar's title is null.

\styleterm

Arguments: description term, description classifier (may be null). Default is italic term followed by italic ": classifier" if the classifier is not null.

\styletitle

Arguments: the document's title, the document's subtitle (may be null). Default is the title followed by ":", a newline and the subtitle in a smaller font, if the subtitle is not null.

\styletopictitle

Arguments: the title of a topic. Default is bold face.

It is probably easiest to define these by first creating a .tex file with the writer and then copying the definition you want to modify from the top of the generated file into your style file, changing the "\newcommand" to "\renewcommand" and supplanting the definition.

Documentation for writer 'toc'

This writer creates table of content (TOC) for one or more reStructuredText documents. The output includes section headers from the source files organized into lists, one per top level section. The TOC entries are references to the corresponding sections in the source documents.

This writer uses the following output defines:

Documentation for writer 'xml'

This writer dumps out the internal Document Object Model (DOM, also known as a doctree) as an XML file. It is useful for checking the results of the parser or transformations. It recognizes no defines.

Documentation for writer 'xref'

This writer exports cross reference targets defined in the source reStructuredText (reST) file. The output is in reST format and includes:

1. All non-anonymous internal targets, exported as

   .. _<targetName>: <base-file><ext>.<suffix>#<targetID>
   

   Here <base-file> is the base file name (file name without extension).

2. All citations, exported as:

   .. _<citationName>: <base-file><ext>.<suffix>#<citationID>
   

3. Substitution definitions that have the same names as internal targets but do not, directly or indirectly through substitution references, define internal target or refer to external references or footnotes.

4. Definition of substitutions referred to by the substitutions exported according to 3. Substitution definitions are exported as defined in the source file.

5. If -W xref-sections is specified,

   1. Targets for all section titles, exported as

      .. _<base-file>.<base-title>: <base-file><ext>.<suffix>#<titleID>
      

      Here <base-title> is the title name prior to any autonumbering.

   2. Substitution definitions for all section titles, exported as

      .. |<base-file>.<base-title>| replace:: <section-title>
      

   3. Target for the file itself, exported as

      .. _<base-file>.: <sourceFileName><ext>.<suffix>
      

   4. Substitution definition for the file itself, exported as

      .. |<base-file>.| replace:: <document-title>
      

6. If -W xref-role-targets is specified, then inline targets that are defined through an interpreted text target role are included in the index.

This writer uses the following output definitions: