Section 4.4 Verbatim and Literal Text
This section expands on parts of Section 3.16. For descriptions of more involved uses, such as program listings and console sessions, see Section 4.15.
The tags described here contain only raw characters. By that we typically mean the first 128 characters of the ASCII code. Unicode characters are likely to migrate to HTML output just fine, but results for LaTeX output will be variable. The restriction to character data has two consequences. First, any markup mistakenly included will have its content silently ignored and dropped. Second, you need to observe the rules on exceptional characters and escaped characters for XML for literal text, which are mercifully simple.
In your source, use&for an &, use<for <, and optionally use>for >. Otherwise, every other ASCII character will render faithfully across all possible formats.
See Subsubsection 4.1.4.2 for more detail and explanation.
Subsection 4.4.1 Short, Inline, Verbatim Text
The
<c> tag is a mnemonic for “code”, but is really meant to be any chunk of literal characters that you want to emphasise that way. So a “typewriter” font of fixed-width characters would be a typical presentation. It is meant for use within a sentence or caption (“inline”) so its use is limited to those situations, and others that are similar, such as a title or a cell of a table. Typically these pieces of text do not hyphenate words, and so can lead to spillover into a right margin. In these situations, consider options below for longer pieces of text.Subsection 4.4.2 Longer, Inline, Verbatim Text
For longer pieces of verbatim text, use the
<cd> tag, which is short for “code display”, analogous to the <md> for mathematics. It is used within sentences of a paragraph and will be presented with a vertical break above and below, but without interrupting the paragraph. Because of the display presentation, it cannot be used other places, such as a <title>, where a vertical gap is not appropriate. All of the previous discussion about exceptional characters applies for this tag.You have two options in use. You may author inline with the rest of a sentence, with no extra newlines or whitespace before, after, or within the content. The result will be a single displayed line.
Or you may structure the content using one, or more, of the
<cline> tag, which is meant to be similar to the <line> tag used elsewhere. You should still take care to not place any extra whitespace before or after the <cd> element, but in between the <cline> you may use as much visual formatting of your source as you wish, especially if you like your source to mirror your output.Subsection 4.4.3 Blocks of Verbatim Text
If you want to isolate large chunks of verbatim text outside of paragraphs, the
<pre> tag is the one to use. It can be used as a peer of paragraphs (and other structures) as a child of a division, or it can be placed into a <listing> to receive a caption, title and number.You can structure the contents with
<cline> in exactly the same manner as for <cd>. But you may find this tedious. Instead, you can make the content of <pre> a sequence of lines separated by newlines. So that you can preserve the indentation of your source, the line closest to the left margin is taken to actually be the left margin, and a corresponding amount of leading whitespace will be removed from every line. This will work well if you recognize two caveats. First, results will be unpredictable if you mix spaces and tabs for indentation. Sticking with spaces is best. Second, if your first characters of content immediately follow the <pre> tag then there is no leading whitespace and it is as if that line is already at the left margin. Then subsequent indentation may seem too severe to you.As previously mentioned, Section 4.15 discusses the
<console> and <program> tags which are more specific, and hence more capable. Review the possibilities before you decide between <pre>, <console>, and <program>.
