(eplain.info)Verbatim listing

---

Next: Contents Prev: Lists Up: User definitions

---

Enter node , (file) or (file)node

4.7 Verbatim listing
====================

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 '\kern's 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' (Note: 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
(Note: Category codes).