It is sometimes useful to include a file verbatim in your document;
for example, part of a computer program. The \listing
command is given one argument, a filename, and produces the contents of
that file in your document. \listing expands \listingfont
to set the current font. The default value of \listingfont
is \tt.
You can take arbitrary actions before reading the file by defining the macro
\setuplistinghook.
This is expanded just before the file is input.
If you want to have line numbers on the output, you can say
\let\setuplistinghook = \linenumberedlisting.
The line numbers are stored in the count register \lineno while
the file is being read. You can redefine the macro
\printlistinglineno
to change how they are printed.
Normally, the \listing command will add a final empty line at
the end of the output, even if the file does not end in a newline. To
suppress this final line, you can say
\let\setuplistinghook = \nolastlinelisting.
This also works with line numbers (say
\def\setuplistinghook{\linenumberedlisting \nolastlinelisting}),
but only if \printlistinglineno
consists exclusively of boxes at the top level (i.e., any
\kerns or glue should be wrapped up in a box).
You can use the form feed control character (ASCII code 12, typed as CTRL-L) in the file to force a page break in the output.
You can produce in-line verbatim text in your document with \verbatim.
End the text with |endverbatim. If you need a ‘|’ in the text,
double it. If the first character of the verbatim text is a space, use
| . (| will work elsewhere in the argument, too, but
isn't necessary.)
For example:
\verbatim| ||\#%&!|endverbatim
produces |\#%&!.
Line breaks and spaces in the verbatim text are preserved.
You can change the verbatim escape character from the default ‘|’
with \verbatimescapechar char; for example, this changes
it to ‘@’.
\verbatimescapechar \@
The backslash is not necessary in some cases, but is in
others, depending on the catcode of the character. The argument to
\verbatimescapechar is used as \catcode `char, so
the exact rules follow that for \catcode.
To reset the category code of all special characters to 12
(“other”), \verbatim uses \uncatcodespecials
(see Category codes). If you make additional characters
“special”, you should extend \dospecials to include those
characters, lest they be given special treatment inside verbatim
environments. For example,
\catcode`\A=\active
% Try commenting out the following line.
\expandafter\def\expandafter\dospecials\expandafter{\dospecials\do\A}
\verbatimA#$%_^|endverbatim
Because \verbatim must change the category code of special
characters, calling inside a macro definition of your own does not work
properly. For example:
\def\mymacro{\verbatim &#%|endverbatim}% Doesn't work!
To accomplish this, you must change the category codes yourself before
making the macro definition. Perhaps \uncatcodespecials will
help you (see Category codes).