--------------------------------------------
lines 6-145 of file: xrst/literal_command.py
--------------------------------------------

{xrst_begin literal_cmd user}
{xrst_spell
   literalinclude
}

Literal Command
###############

Syntax
******

Entire File
===========
``\{xrst_literal}``

With Separator
==============
| ``\{xrst_literal`` *separator*
|     *display_file*
|     *start_after_1* *separator* *end_before_1*
|     *start_after_2* *separator* *end_before_2*
|     ...
| ``}``

Without Separator
=================
| ``\{xrst_literal``
|     *display_file*
|     *start_after_1*
|     *end_before_1*
|     *start_after_2*
|     ...
| ``}``

Purpose
*******
Literal text, from any where in any file,
can be included using this command.

literalinclude
**************
This command is similar to the following sphinx directive
(see :ref:`dir_cmd-name`) :

| |tab| .. literalinclude:: \{xrst_dir *display_file*}
| |tab| |tab| :start-after: *start_after_1*
| |tab| |tab| :end-before: *end_before_1*

The xrst literal command has the following difference:

#. If the *display_file* is not specified, the current
   :ref:`begin_cmd@Page File` is used.
#. If the *display_file* is the current :ref:`template_cmd@Input File` ,
   the *start_after* and *end_before* in the command are not considered
   a match for the corresponding text. This makes it possible to put a literal
   command in the same file as the text it will display.
#. It is an error for there to be more than one copy of each *start_after*
   or *end_before* in the *display_file* (not counting the copy in the
   command when the display file is the current input file).
   This makes sure that the intended section of *display_file* is displayed.
#. It is possible to specify multiple sections of a file using
   the start after and end before patterns.

Tokens
******
#. Leading and trailing spaces are not included in
   *separator*, *display_file*, each *start_after*, and each *end_before*.
#. Each *start_after* must have a corresponding *end_before*.
#. If there are an even number of tokens (not counting *separator*),
   the *display_file* is not present and the current page file is used.
#. The new line character separates the tokens.
#. If there are multiple lines in the command, the last line contains
   the ``}`` and must have nothing else but white space.


separator
*********
If *separator* is present, it must be a single character.
At most one *separator* can be in each line and it also separates tokens.

display_file
************
If *display_file* is not present,
the literal input block is in the current page file.
Otherwise, the literal input block is in *display_file*.
The file name *display_file* is relative to the
:ref:`config_file@directory@project_directory` .

1. This may seem verbose, but it makes it easier to write scripts
   that move files and automatically change references to them.
2. Note that if you use the sphinx ``literalinclude`` directive,
   the corresponding file name will be relative to the
   :ref:`config_file@directory@rst_directory` , which is a path relative
   to the project_directory; see :ref:`dir_cmd-name` .

extension
=========
The *display_file* extension is used to determine what language
to use when highlighting the input block.
In the special case where *display_file* ends with ``.in`` ,
the final ``.in`` is not included when file name
when determining the extension.
This is done because configure files use the ``.in`` extension,
and usually create a file with the ``.in`` dropped.

No start or end
***************
In the case where there is no *start_after* or *end_before*,
the entire display file is displayed.
In the case of the ``\{xrst_literal}`` syntax,
the entire current page file is displayed.

start_after
***********
Each literal input block starts with the line following the occurrence
of the text *start_after* in *display_file*.
If this is the same as the file containing the command,
the text *start_after* will not match any text in the command.
There must be one and only one occurrence of *start_after* in *display_file*,
not counting the command itself when the files are the same.

end_before
**********
Each literal input block ends with the line before the occurrence
of the text *end_before* in *display_file*.
If this is the same as the file containing the command,
the text *end_before* will not match any text in the command.
There must be one and only one occurrence of *end_before* in *display_file*,
not counting the command itself when the files are the same.

Spell Checking
**************
Spell checking is **not** done for these literal input blocks.


Example
*******
see :ref:`literal_example-name` .

{xrst_end literal_cmd}