literal_cmd

View page source

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 dir_cmd) :

      .. literalinclude:: {xrst_dir display_file}
            :start-after: start_after_1
            :end-before: end_before_1

The xrst literal command has the following difference:

  1. If the display_file is not specified, the current Page File is used.

  2. If the display_file is the current 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.

  3. 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.

  4. It is possible to specify multiple sections of a file using the start after and end before patterns.

Tokens

  1. Leading and trailing spaces are not included in separator, display_file, each start_after, and each end_before.

  2. Each start_after must have a corresponding end_before.

  3. If there are an even number of tokens (not counting separator), the display_file is not present and the current page file is used.

  4. The new line character separates the tokens.

  5. 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 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 rst_directory , which is a path relative to the project_directory; see dir_cmd .

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 literal_example .