Section 3.12 Programs and Consoles¶
If you are writing about scientific or engineering topics, you may wish to include sample computer programs, or command-line sessions.
<program> will be treated as verbatim text (see Section 3.14), subject to all the exceptions for exceptional characters. Indentation will be preserved, though an equal amount of leading whitespace will be stripped from every line, so as to keep the code shifted left as far as possible. So you can indent your code consistently along with your XML indentation. For this reason it is best to indent with spaces, and not tabs. A mix will almost surely end badly, and in some programming languages tabs are discouraged (e.g. Python).
@language attribute may be used to get some degree of language-specific syntax highlighting. See Section 6.13 for details.
<console> is a transcript of an interactive session in a terminal at a command-line. It is a sequence of the following elements, in this order, possibly repeated many times as a group:
<output> is optional, and a
<prompt> is only displayed when there is an immediately subsequent
<input> (which could be empty). The content is treated as verbatim text (see Section 3.14), subject to all the exceptions for exceptional characters.
<console> may be wrapped in a
<listing>, which is analogous to a
<listing> may contain a
<title> for use in cross-references or lists. A
<caption> will be displayed and will generate a number.