template_cmd

View page source

Template Command

Syntax

{xrst_template separator
      template_file
      match_1 separator replace_1
      match_2 separator replace_2
      …
      comment_1
      comment_2
      …
}

Input File

During the expansion of a template command, the current input file is its template_file . Otherwise, the current input file is the current Page File .

Rst Include

A similar sphinx include directive, in the context of xrst, is:

      .. include {xrst_dir file_name }

see dir_cmd . The template command differs form the include directive in the following ways:

  1. The template command allows for text replacement during the include so that template_file is like function or macro.

  2. It also allows for conditional including of sections of the template file when combined with the boolean or left, right arguments in the suspend command.

  3. Errors and warnings in a template expansion will include both the line in the template file and the line where it is used. Errors and warnings in a sphinx include only report the line number in the include file.

  4. xrst commands in template_file ( file_name ) will get interpreted (will not get interpreted).

  5. Template command comments can be used to check that the included file still satisfies the requirements of the file doing the include.

White Space

The newline character separates the lines of input above and excluded from white space in the discussion below..

separator

The separator argument is a single character that separates matches from their replacements. Leading and trailing white space around separator is ignored.

template_file

is the name of the template file. Leading and trailing white space around template_file is ignored and template_file cannot contain the @ character (the template file may contain the @ character). Template files are different from other xrst input file because none of the following xrst commands can be in a template expansion: begin_cmd , comment_ch_cmd , indent_cmd , spell_cmd , template_cmd .

match

Each match in the template file gets replaced. Leading and trailing white space around each match is ignored.

replace

For each match, the corresponding replace is used in its place. Leading and trailing white space around each replace is ignored.

comment

A comment is any line below the template_file that does not contain the separator character. Leading and trailing white space around each comment is ignored. If comment is empty, it is ignored. Otherwise, it is an error if a comment does not appear in the template file (before template expansion). In other words, a template file can have a list of comments that can be in a template command that uses the template file. This enables the template command to check that certain features of the template file have not changed.

Command End

The first occurrence of a right brace } , directly after a newline , terminates the template command.

Example

template_example