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
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, an email address, or raw text containing characters which you don’t want interpreted by LATEX and which needs to be typeset specially, using a fixed-width font.
LATEX includes two features for handling fixed-format text: inline verbatim and display verbatim. There are many more variations available in other packages.
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: \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.7 above) 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.10.2 above 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. See also the warning about using \verb inside \footnote.
Typesetting URIs causes two problems which LATEX overcomes with the url package (and the hyperref package which also handles URIs).
It is 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.
URIs (especially long ones) must never have a hyphen added if they have to be broken over a line-end, because it might be mistaken (and retyped) by the user for a real hyphen needed as a part of the address. Conversely, any existing hyphen must never be used at a line-end.
Handling a URI therefore means being able to perform a hyphenless line-break, but only at some existing punctuation characters — principally the slash and the dot — but not usually the hyphen.
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 & Masinter, 2005) and will never break mid-way through an unpunctuated word, only at slashes and full points (and never at embedded hyphens unless in exceptionally rare circumstances when the hyphen package option can be used).
Bear in mind, however, that spaces and non-ASCII characters are (currently) invalid in URIs, so using spaces in a \url argument will cause it to fail, as will using other non-URI-valid characters.
The hyperref package make links for cross-references, citations, and URIs clickable in LATEX PDFs (it’s used in the PDF version of this document). It can also make footnote links clickable, although as they are usually on the same page, this is probably not needed in most documents.
You can load it with footnote links turned off, and the different classes of link (cross-references, citations, and URIs) in different colours:
\usepackage[hyperfootnotes=false]{hyperref}
\hypersetup{linkcolor=DarkGreen,citecolor=DarkRed,
urlcolor=Blue,pdfborder=0 0 0,
allbordercolors=0 0 0,colorlinks=true}
\AtBeginDocument{\renewcommand{\UrlFont}{\ttfamily}}In some systems, links get borders drawn around them, but in the example above they are turned off by making their colour invisible (0 0 0). The hyperref package likes to use the roman font for URIs (normally A Bad Idea as we saw above in item ‘Visible accuracy’ above) but this can be turned off by changing the vaue of \UrlFont back to ttfamily.
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.
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, starting at the beginning of the line (not indented).
\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).
Add your email address and home page URI using the \verb and \url commands. You’ll need to add \usepackage{url} to your Preamble for the latter.
Load the listings package and try the \lstinline command to do the same.
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.
\documentclass[11pt,a4paper,oneside]{report} \begin{document} \title{Practical Typesetting} \author{Peter Flynn\\Silmaril Consultants} \date{December 2004} \maketitle \end{document}
The original term Uniform Resource Locator (URL) is now deprecated in favour of the more accurate Uniform Resource Identifier (URI). For details see http://www.w3.org/Addressing/. The older term still persists, especially in this LATEX package and its command, and in some XML markup vocabularies.
In fact I am using the hyphens option for the url package in this book because of some very dense URIs.
A number of environments which do complicated things with the category codes of characters have this requirement to end the environment with the \end{...} command on a line by itself, at the start of the line. These include the Verbatim environment from the fancyvrb package, and any of the \end{...} commands taken over by the endfloat package.