lines 6-73 of file: xrst/code_command.py

{xrst_begin code_cmd user}

Code Command
############

Syntax
******
- ``\{xrst_code`` *language* ``}``
- ``\{xrst_code}``

Purpose
*******
A code block, directly below in the current input file, begins (ends) with
a code command that contains *language* (not containing *language*).

code-block
**********
This command is similar to the following sphinx directive

| |tab| .. code-block:: *language*
|
| |tab| |tab| Source code in the specified language


The xrst code command has the following difference:

#. Other characters on the same line as the code commands
   are not included in the rst output or the displayed source code.
   One can use these characters to end and begin comments so that the
   code also executes.
#. The source code does not need to be indented. This is especially useful
   with languages like python and rst where the indentation is used to
   begin and end sections of code.
#. The source code does not need to be surrounded by empty lines.

Requirements
************
Each code section ends with
a line containing the second version of the command; i.e., ``\{xrst_code}``.
Hence there must be an even number of code commands.

language
********
A *language* is a non-empty sequence of lower case letters.
It determines the language for highlighting the code block.

Rest of Line
************
Other characters on the same line as a code commands
are not included in the xrst output.
This enables one to begin or end a comment block
without having the comment characters in the xrst output.

Spell Checking
**************
Code blocks as usually small and
spell checking is done for these code blocks.
You can turn off this spell checking by putting
:ref:`spell_cmd@spell_off` before and :ref:`spell_cmd@spell_on` after
a code block.
Spell checking is not done for code blocks included using the
:ref:`literal command<literal_cmd-name>` .

Example
*******
:ref:`code_example-name`

{xrst_end code_cmd}