Your support for our advertisers helps cover the cost of hosting, research, and maintenance of this document

Formatting Information — An introduction to typesetting with LATEX

Chapter 4: Lists, tables, figures

Section 4.7: Verbatim text

If you are documenting computer procedures, you probably need fixed-width type for examples of programming or data input or output. Even if you are writing about completely non-computer topics, you may often want to quote a URI, filename, or email address which needs to be typeset specially.

LATEX includes two features for handling fixed-format text: inline verbatim and display verbatim. There are many more variations available in other packages.

4.7.1 Inline verbatim

To specify a word or phrase as verbatim text in typewriter type within a sentence, use the special command \verb, followed by the word or phrase surrounded by any suitable character which does not occur in the word or phrase itself. This is a very rare exception to the rule that arguments go in curly braces.

For example, you could use the plus sign to show a LATEX command in a manual like this one:

You can typeset a phrase verbatim, even if it includes
\LaTeX\ command characters, for example the command to 
insert an image: \verb+\includegraphics[width=3in]{myhouse}+
	  

You can typeset a phrase verbatim, even if it includes LATEX command characters, for example the command to insert an image: \verb+\includegraphics[width=3in]{myhouse}+

The plus sign is ‘safe’ to use here because it doesn’t appear in the code you want to typeset but you could use the grave accent or backtick key ` or the vertical bar  | if the phrase already had a plus sign in it:

for example \verb|\(a=b+c)| when illustrating the
\LaTeX\ equation \(a=b+c\).
	  

for example \verb|\(a=b+c\)| when illustrating the LATEX equation a=b+c.

The \verb command has the advantage that it turns off all special characters (see § 1.6) except the one you use as the delimiter, so you can easily quote sequences of characters in any computer syntax — including TEX. However, LATEX will never break the argument of \verb at a line-end when formatting a paragraph, even if it contains spaces, so if it happens to be long, and falls towards the end of a line, it will stick out into the margin. See § 1.9.2 for more information on line-ends and hyphenation. The argument to \verb MUST NOT contain a linebreak in your editor: this will cause it to fail.

4.7.1.1 Typesetting URIs

The url package avoids this by performing a hyphenless break at punctuation characters. It is particularly important in URIs to avoid adding a spurious hyphen if they have to break over a line-end, because a hyphen might be mistaken by the user as a part of the address.

URIs present another problem: it’s important for them to be visibly accurate, so they can be copied and retyped from print. It is therefore essential to use a typeface which distinguishes well between 1 (digit one), l (lowercase ell) and I (uppercase eye), and between 0 (zero) and O (uppercase oh). Monospaced ‘typewriter’ type usually makes this clear, but many sans-serif fonts do not. It is a common error by designers not to distinguish URIs in this way.

The url package provides the command \url which works in the same way as \verb, but uses the standard curly braces to enclose the address, eg \url{http://latex.silmaril.ie} — the command understands the syntax of a URI (Berners-Lee, Fielding and Masinter, 2005) and will never break mid-way through an unpunctuated word, only at slashes and full points (and never at embedded hyphens unless the hyphen package option is used). Bear in mind, however, that spaces and non-ASCII characters are (currently) forbidden in URIs, so using spaces in a \url argument will cause it to fail, as will using other non-URI-valid characters like accented letters.

4.7.1.2 Enhanced inline verbatim

The listings package, which we look at more below for display verbatim, also has an inline form. This can use colour to highlight your examples based on the language you are documenting — I am using it extensively in the PDF of this book.

The command \lstinline uses the same syntax as \verb (two matching but otherwise unused characters) to enclose the argument, but it provides for very extensive options to specify the language, font, size, style, and formatting. The most useful is the language, of which about 100 are predefined, from ADA to Verilog, and you can add new keywords and even whole new languages.

This is probably the most effective way to show computer-language examples inline, because it handles the syntax-based enhancement for you. It is, however, still subject to the same limitations as \verb, in that the code must fit on the space available in the line, or it will stick out into the margin.

For example, you could use the plus sign to show a \LaTeX\ command:
\lstlisting[language={[LaTeX]TeX}]`\verb+\includegraphics[width=3in]{myhouse}+`
in order to display 
\lstlisting{[LaTeX]TeX}]`\includegraphics[width=3in]{myhouse}`, because the 
plus sign does not occur in the command, and is therefore free to be used.
	    

For example, you could use the plus sign to show a LATEX command: \verb+\includegraphics[width=3in]{myhouse}+ in order to display \includegraphics[width=3in]{myhouse}, because the plus sign does not occur in the command, and is therefore free to be used.

4.7.2 Display verbatim

For longer (multiline) chunks of fixed-format text like examples of programming, use the verbatim environment. Like \verb, this turns off all special characters, so you can include anything at all in the verbatim text except the exact line \end{verbatim}, which MUST occur on a line by itself.

\begin{verbatim}
\documentclass[11pt,a4paper,oneside]{report}
\begin{document}

\title{Practical Typesetting}
\author{Peter Flynn\\Silmaril Consultants}
\date{December 2004}
\maketitle

\end{document}
\end{verbatim}
	

For more control over formatting there are two useful packages: the verbatim package, which overcomes a few of the limitations of the built-in verbatim environment; and the fancyvrb package, which provides much greater flexibility with a Verbatim environment (note the capital letter).

However, as I mentioned above, for a much more powerful verbatim environment, I use the listings package for its ability to colour the keywords of a program according to the language used. It can also add rules, interpret internal formatting, and include external files, and let you add your own language definitions for new languages. The penalty is a slightly more complex configuration, but if you are documenting any kind of computer code in significant quantities, the quality and usability of the result is well worth it.

Exercise 15: Try some fixed-format text

  1. Add your email address and home page URI using the \verb and \url commands. You’ll need to \usepackage{url} for the latter.

  2. Load the listings package and try the \lstinline command to do the same.

  1. The original term Uniform Resource Locator (URL) is now deprecated in favour of the more accurate Uniform Resource Indicator (URI). For details see http://www.w3.org/Addressing/. Unfortunately the older term still persists, especially in this LATEX package and its command, and in some XML markup vocabularies.