Defines for reStructuredText parser

Defines for reStructuredText transforms

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 an option which determines how the returned value is interpreted:

: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 defines the following global variables:

$SOURCE

The name of the source file containing the perl directive.

$LINENO

The line number of the perl directive within $SOURCE.

$opt_<x>

The <x> option from the command line.

$TOP_FILE

The name of the top-level file.

$VERSION

The version of trip.

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 an option which determines how the returned value is interpreted:

: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. An index is either an inline internal target or an indirect target that points to an inline internal target. 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 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 '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>: <sourceFileName><ext>.<suffix>#<targetID>
   

2. All citations, exported as:

   .. <citationName>: <sourceFileName><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.

This writer uses the following output definitions: