The ‘fancyvrb’ package Fancy Verbatims in L^{A}TEX

Timothy Van Zandt Princeton University Princeton – USA

email: tvz@Princeton.EDU

Packaging, documentation and support

Denis Girou (CNRS/IDRIS – France) – Denis.Girou@idris.fr and Sebastian Rahtz (Elsevier – GB) – s.rahtz@elsevier.co.uk

Version 2.5 January 28, 1998

Documentation revised March 27, 1998

Abstract

This package provides very sophisticated facilities for reading and writing verbatim TEX code. Users can perform common tasks like changing font family and size, numbering lines, framing code examples, colouring text and conditionally processing text.

Contents

1 Introduction 2

2 Verbatim material in footnotes 3

3 Improved verbatim commands 3

4 Verbatim environments 3

4.1 Customization of verbatim environments . . . . . . . . . . . . . . . 4 4.1.1 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 4.1.2 Initial characters to suppress . . . . . . . . . . . . . . . . . 4 4.1.3 Customization of formatting . . . . . . . . . . . . . . . . . 4 4.1.4 Changing individual line formatting . . . . . . . . . . . . . 5 4.1.5 Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4.1.6 Types and characteristics of frames . . . . . . . . . . . . . . 6 4.1.7 Line numbering . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.1.8 Selection of lines to print . . . . . . . . . . . . . . . . . . . 9 4.1.9 Spaces and tab characters . . . . . . . . . . . . . . . . . . . 10 4.1.10 Space between lines . . . . . . . . . . . . . . . . . . . . . . 11 4.1.11 Escape characters for inserting commands . . . . . . . . . . 11 4.1.12 Margins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.1.13 Overfull box messages . . . . . . . . . . . . . . . . . . . . . 12 4.1.14 Page breaks . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.1.15 Catcode characters . . . . . . . . . . . . . . . . . . . . . . . 12 4.1.16 Active characters . . . . . . . . . . . . . . . . . . . . . . . . 13

4.2 Different kinds of verbatim environments . . . . . . . . . . . . . . 13 4.2.1 Verbatim environment . . . . . . . . . . . . . . . . . . . . . 13 4.2.2 BVerbatim environment . . . . . . . . . . . . . . . . . . . . 13 4.2.3 LVerbatim environment . . . . . . . . . . . . . . . . . . . . 14 4.2.4 Personalized environments . . . . . . . . . . . . . . . . . . . 14

5 Saving and restoring verbatim text and environments 14

6 Writing and reading verbatim files 15

7 Conclusion 17

1 Introduction

‘fancyvrb’ is the development of the verbatim macros of the ‘fancybox’ package, Section 11 of [1]. It offers six kinds of extended functionality, compared to the standard L^{A}TEX verbatim environment:

1. verbatim commands can be used in footnotes,

2. several verbatim commands are enhanced,

3. a variety of verbatim environments are provided, with many parameters to change the way the contents are printed; it is also possible to define new customized verbatim environments,

4. a way is provided to save and restore verbatim text and environments,

5. there are macros to write and read files in verbatim mode, with the usual versatility,

6. you can build example environments (showing both result and verbatim text), with the same versatility as normal verbatim.

The package works by scanning a line at a time from an environment or a file. This allows it to pre-process each line, rejecting it, removing spaces, numbering it, etc, before going on to execute the body of the line with the appropriate catcodes set.

2 Verbatim material in footnotes

After a \VerbatimFootnotes macro declaration (to use after the preamble), it is possible to put verbatim commands and environments in footnotes, unlike in standard L^{A}TEX:

1 \VerbatimFootnotes
2 We can put verbatim\footnote{\verb+_Yes!_+} text in footnotes.

We can put verbatim^{1} text in footnotes.

3 Improved verbatim commands

The \DefineShortVerb macro allows us to define a special character as an abbreviation to enclose verbatim text and the \UndefineShortVerb macro suppresses the special meaning of the specified character (the same functionalities are provided in the L^{A}TEX docstrip package):

We can simply write _verbatim_material us-

ing a single _delimiter_

And we can _change_the character.

                         1 \DefineShortVerb{\|}
                         2 We can simply write \Verb+_verbatim_+
                         3 material using a single |_delimiter_|
                         4 \UndefineShortVerb{\|}
                         5 \DefineShortVerb{\+}
                         6 And we can +_change_+ the character.

To make matters more versatile, we can nominate escape characters in verbatim text (using the \Verb macro or with a ‘shortverb’ character defined), to perform formatting or similar tasks, using the commandchars parameter as shown for environments in paragraph 4.1.11.

4 Verbatim environments

Several verbatim environments are available, each with a lot of parameters to customize them. In the following examples we use the Verbatim environment, which is the equivalent of the standard verbatim. The parameters can be set globally using the \fvset macro or in an optional argument after the start of the environment^{2}^{,}^{3}.

1_Yes!_

2For clarification in this paper, note that we generally indent each verbatim line with two spaces.

3This mechanism uses the ‘keyval’ package from the standard L^{A}TEX graphics distribution, written by David Carlisle.

First verbatim line.
Second verbatim line.

1 \begin{Verbatim}
2 First verbatim line.
3 Second verbatim line.
4 \end{Verbatim}

4.1 Customization of verbatim environments

The appearance of verbatim environments can be changed in many and varied ways; here we list some of the keys that can be set.

4.1.1 Comments

commentchar (character) : character to define comments in the verbatim code, so that lines starting with this character will not be printed (Default: empty).

% A comment
Verbatim line.

1 \begin{Verbatim}[commentchar=!]
2 % A comment
3 Verbatim line.
4 ! A comment that you will not see
5 \end{Verbatim}

4.1.2 Initial characters to suppress

gobble (integer) : number of characters to suppress at the beginning of each line (up to a maximum of 9), mainly useful when environments are indented (Default: empty — no character suppressed).

Verbatim line.
Verbatim line.
im line.

1 \begin{Verbatim}
2 Verbatim line.
3 \end{Verbatim}

4

5 \begin{Verbatim}[gobble=2]
6 Verbatim line.
7 \end{Verbatim}

8

9 \begin{Verbatim}[gobble=8]
10 Verbatim line.
11 \end{Verbatim}

4.1.3 Customization of formatting

formatcom (command) : command to execute before printing verbatim text (Default: empty).

First verbatim line.
Second verbatim line.

1 \begin{Verbatim}[formatcom=\color{red}]
2 First verbatim line.
3 Second verbatim line.
4 \end{Verbatim}

4.1.4 Changing individual line formatting

The macro \FancyVerbFormatLine defines the way each line is formatted. Its

default value is \def\FancyVerbFormatLine#1{\FV@ObeyTabs{#1}}, but we can

redefine it at our convenience (FancyVerbLine is the name of the line counter):

⇒First verbatim line.
⇒Second verbatim line.
⇒Third verbatim line.
FIRST VERBATIM LINE.
Second verbatim line.
THIRD VERBATIM LINE.

1 \renewcommand{\FancyVerbFormatLine}[1]{%
2 \makebox[0cm][l]{$\Rightarrow$}#1}
3 \begin{Verbatim}
4 First verbatim line.
5 Second verbatim line.
6 Third verbatim line.
7 \end{Verbatim}

8

9 \renewcommand{\FancyVerbFormatLine}[1]{%
10 \ifodd\value{FancyVerbLine}%
11  \MakeUppercase{#1}\else#1\fi}
12 \begin{Verbatim}
13 First verbatim line.
14 Second verbatim line.
15 Third verbatim line.
16 \end{Verbatim}

4.1.5 Fonts

fontfamily (family name) : font family to use. tt, courier and helvetica are pre-defined (Default: tt).

Verbatim line.

1 \begin{Verbatim}[fontfamily=helvetica]
2 Verbatim line.
3 \end{Verbatim}

fontsize (font size) : size of the font to use (Default: auto — the same as the current font).

Verbatim line.
Verbatim line.

1 \begin{Verbatim}[fontsize=\small]
2 Verbatim line.
3 \end{Verbatim}

4

5 \begin{Verbatim}[fontfamily=courier,
6  fontsize=\large]
7 Verbatim line.
8 \end{Verbatim}

fontshape (font shape) : font shape to use (Default: auto — the same as the current font).

Verbatim line.

1 \begin{Verbatim}[fontfamily=courier,
2  fontshape=it]
3 Verbatim line.
4 \end{Verbatim}

fontseries (series name) : L^{A}TEX font ‘series’ to use (Default: auto — the same as the current font).

Verbatim line.

1 \begin{Verbatim}[fontfamily=courier,
2  fontseries=b]
3 Verbatim line.
4 \end{Verbatim}

4.1.6 Types and characteristics of frames

frame (none|topline|bottomline|lines|single) : type of frame around the verbatim environment (Default: none — no frame).

Verbatim line.
Verbatim line.

Verbatim line.
Verbatim line.

1 \begin{Verbatim}[frame=topline]
2 Verbatim line.
3 \end{Verbatim}

4

5 \begin{Verbatim}[frame=bottomline]
6 Verbatim line.
7 \end{Verbatim}

8

9 \begin{Verbatim}[frame=lines]
10 Verbatim line.
11 \end{Verbatim}

12

13 \begin{Verbatim}[frame=single]
14 Verbatim line.
15 \end{Verbatim}

framerule (dimension) : width of the rule of the frame (Default: 0.4pt if framing specified).

Verbatim line.

1 \begin{Verbatim}[frame=single,
2  framerule=1mm]
3 Verbatim line.
4 \end{Verbatim}

framesep (dimension) : width of the gap between the frame and the text (Default:

\fboxsep ).

Verbatim line.

1 \begin{Verbatim}[frame=single,
2  framesep=5mm]
3 Verbatim line.
4 \end{Verbatim}

rulecolor (color command) : color of the frame rule, expressed in the standard L^{A}TEX way (Default: black).

Verbatim line.

1 \begin{Verbatim}[frame=single,
2  rulecolor=\color{red}]
3 Verbatim line.
4 \end{Verbatim}

fillcolor (color command) : color used to fill the space between the frame and the text (its thickness is given by framesep) (Default: none — no color).

Verbatim line.

1 \begin{Verbatim}[frame=single,
2  framerule=1mm,framesep=3mm,
3  rulecolor=\color{red},
4  fillcolor=\color{yellow}]
5 Verbatim line.
6 \end{Verbatim}

4.1.7 Line numbering

numbers (none|left|right) : numbering of the verbatim lines (Default: none — no numbering). If requested, this numbering is done outside the verbatim environment.

1 First verbatim line.
2 Second verbatim line.
First verbatim line.  1
Second verbatim line.  2

1 \begin{Verbatim}[gobble=2,numbers=left]
2 First verbatim line.
3 Second verbatim line.
4 \end{Verbatim}

5

6 \begin{Verbatim}[gobble=2,
7  numbers=right,numbersep=0pt]
8 First verbatim line.
9 Second verbatim line.
10 \end{Verbatim}

numbersep (dimension) : gap between numbers and verbatim lines (Default: 12pt).

1 First verbatim line.
2 Second verbatim line.

1 \begin{Verbatim}[gobble=2,
2  numbers=left,numbersep=2pt]
3 First verbatim line.
4 Second verbatim line.
5 \end{Verbatim}

firstnumber (auto|last|integer) : number of the first line (Default: auto — numbering starts from 1). last means that the numbering is continued from the previous verbatim environment. If an integer is given, its value will be used to start the numbering.

1 Verbatim line.
2 Verbatim line.
100 Verbatim line.

1 \fvset{gobble=2,
2  numbers=left,numbersep=3pt}
3 \begin{Verbatim}
4 Verbatim line.
5 \end{Verbatim}

6

7 \begin{Verbatim}[firstnumber=last]
8 Verbatim line.
9 \end{Verbatim}

10

11 \begin{Verbatim}[firstnumber=100]
12 Verbatim line.
13 \end{Verbatim}

stepnumber (integer) : interval at which line numbers are printed (Default: 1 — all lines are numbered).

First verbatim line.
2 Second verbatim line.
Third verbatim line.

1 \begin{Verbatim}[gobble=2,numbers=left,
2  numbersep=3pt,stepnumber=2]
3 First verbatim line.
4 Second verbatim line.
5 Third verbatim line.
6 \end{Verbatim}

The macro \theFancyVerbLine defines the typesetting style of the numbering, and the counter used is FancyVerbLine:

8.aFirst verbatim line.
8.bSecond verbatim line.
8.cThird verbatim line.

1 \renewcommand{\theFancyVerbLine}{%
2 \textcolor{red}{\small
3  8.\alph{FancyVerbLine}}}
4 \begin{Verbatim}[gobble=2,
5  numbers=left,numbersep=2pt]
6 First verbatim line.
7 Second verbatim line.
8 Third verbatim line.
9 \end{Verbatim}

4.1.8 Selection of lines to print

firstline (integer) : first line to print (Default: empty — all lines from the first are printed).

2 Second verbatim line.
3 Third verbatim line.

1 \begin{Verbatim}[gobble=2,firstline=2,
2  numbers=left,numbersep=2pt]
3 First verbatim line.
4 Second verbatim line.
5 Third verbatim line.
6 \end{Verbatim}

lastline (integer) : last line to print (Default: empty — all lines until the last one are printed).

1 First verbatim line.

1 \begin{Verbatim}[gobble=2,lastline=1,
2  numbers=left,numbersep=2pt]
3 First verbatim line.
4 Second verbatim line.
5 Third verbatim line.
6 \end{Verbatim}

4.1.9 Spaces and tab characters

showspaces (boolean) : print a special character representing each space (Default: false — spaces not shown).

␣␣Verbatim␣line.

1 \begin{Verbatim}[showspaces=true]
2 Verbatim line.
3 \end{Verbatim}

In practice, all verbatim environments have a * variant, which sets showspaces=true:

␣␣Verbatim␣line.

1 \begin{Verbatim*}
2 Verbatim line.
3 \end{Verbatim*}

There are also some parameters to determine the way tab characters are interpreted (using tabs is in fact a rather old-fashioned style of coding):

showtabs (boolean) : explicitly show tab characters (Default: false — tab characters not shown).

obeytabs (boolean) : position characters according to the tabs (Default: false — tab characters are added to the current position).

tabsize (integer) : number of spaces given by a tab character (Default: 8 ).

4.1.10 Space between lines

baselinestretch (auto|dimension) : value to give to the usual ‘baselinestretch’ L^{A}TEX parameter (Default: auto — its current value just before the verbatim command).

First verbatim line.
Second verbatim line.

1 \begin{Verbatim}[baselinestretch=2]
2 First verbatim line.
3 Second verbatim line.
4 \end{Verbatim}

4.1.11 Escape characters for inserting commands

commandchars (three characters) : characters which define the character which starts a macro and marks the beginning and end of a group; thus lets us introduce escape sequences in verbatim code. Of course, it is better to choose special characters which are not used in the verbatim text! (Default: empty).

% This is a comment
First verbatim line.
Second  verbatim line.
Third verbatim line.
\textbf{Verbatim} line.

1 \begin{Verbatim}[commandchars=\\\{\}]
2 \textit{% This is a comment}
3 First verbatim line.
4 \fbox{Second} verbatim line.
5 \textcolor{red}{Third} verbatim line.
6 \end{Verbatim}

7

8 \begin{Verbatim}[commandchars=+\[\]]
9 +textit[\textbf{Verbatim} line].
10 \end{Verbatim}

4.1.12 Margins

xleftmargin (dimension) : indentation to add at the start of each line (Default: 0pt — no left margin).

Verbatim line.

1 \begin{Verbatim}[frame=single,
2  xleftmargin=5mm]
3 Verbatim line.
4 \end{Verbatim}

xrightmargin (dimension) : right margin to add after each line (Default: 0pt — no right margin).

Verbatim line.

1 \begin{Verbatim}[frame=single,
2  xrightmargin=1cm]
3 Verbatim line.
4 \end{Verbatim}

resetmargins (boolean) : reset the left margin, which is useful if we are inside other indented environments (Default: false — no reset of the margin).

• First item

Verbatim line.

• Second item

Verbatim line.

1 \begin{itemize}
2 \item First item
3 \begin{Verbatim}[frame=single]
4 Verbatim line.
5 \end{Verbatim}
6 \item Second item
7 \begin{Verbatim}[frame=single,
8  resetmargins=true]
9 Verbatim line.
10 \end{Verbatim}
11 \end{itemize}

4.1.13 Overfull box messages

hfuzz (dimension) : value to give to the TEX \hfuzz dimension for text to format. This can be used to avoid seeing some unimportant Overfull box messages (Default: 2pt).

4.1.14 Page breaks

samepage (boolean) : in very special circumstances, we may want to make sure that a verbatim environment is not broken, even if it does not fit on the current page. To avoid a page break, we can set the samepage parameter to true (Default: false).

4.1.15 Catcode characters

codes (macro) : to specify catcode changes (Default: empty).

For instance, this allows us to include formatted mathematics in verbatim text:

x=1/sqrt(z**2) ! \frac{1}{\sqrt{z^{2}}}

1 \begin{Verbatim}[commandchars=\\\{\}, 2  codes={\catcode`$=3\catcode`^=7}] 3 x=1/sqrt(z**2) ! $\frac{1}{\sqrt{z^2}}$ 4 \end{Verbatim}

4.1.16 Active characters

defineactive (macro) : to define the effect of active characters (Default: empty).

This allows us to do some devious tricks: see the example in Section 6 on page 15.

4.2 Different kinds of verbatim environments

4.2.1 Verbatim environment

This is the ‘normal’ verbatim environment which we have been using up to now.

4.2.2 BVerbatim environment

This environment puts the verbatim material in a TEX box. Some parameters do not work inside this environment (notably the framing ones), but two new ones are available:

boxwidth (auto|dimension) : size of the box used (Default: auto — the width of the longest line is used).

baseline (b|c|t) : position of the baseline (on the baseline, the center or the top of the box) (Default: b).

First SecondFirst Second

1 \fvset{gobble=2}
2 \begin{BVerbatim}
3 First
4 Second
5 \end{BVerbatim}
6 \begin{BVerbatim}[baseline=c]
7 First
8 Second
9 \end{BVerbatim}

First Second     First Second

1 \begin{BVerbatim}[boxwidth=2cm]
2 First
3 Second
4 \end{BVerbatim}
5 \begin{BVerbatim}[boxwidth=2cm,
6  baseline=t]
7 First
8 Second
9 \end{BVerbatim}

4.2.3 LVerbatim environment

This environment puts verbatim material into L^{A}TEX ‘LR’ mode (the so-called left-to-right mode, which in fact is the same thing that TEX itself calls restricted horizontal mode).

4.2.4 Personalized environments

It is easy to define personal customized environments, using the \DefineVerbatimEnvironment macro; you specify the name of the new environment, the type of environment on which it is based, and a set of initial option values. The options can be overridden with an optional argument in the normal way:

1 First verbatim line.
2 Second verbatim line.

First verbatim line.
Second verbatim line.

                         1 \DefineVerbatimEnvironment%
                         2 {MyVerbatim}{Verbatim}
                         3 {gobble=2,numbers=left,numbersep=5pt,
                         4  frame=lines,framerule=0.8mm}
                         5 \begin{MyVerbatim}
                         6 First verbatim line.
                         7 Second verbatim line.
                         8 \end{MyVerbatim}

9

                         10 \begin{MyVerbatim}[numbers=none,
                         11  framerule=1pt]
                         12 First verbatim line.
                         13 Second verbatim line.
                         14 \end{MyVerbatim}

5 Saving and restoring verbatim text and environments

The \SaveVerb and \UseVerb macros allow us to save and restore verbatim material.

I have saved _verbatim_

and reuse it later as many times as I want

_verbatim_.

                         1 \DefineShortVerb{\|}
                         2 \SaveVerb{Verb}|_verbatim_|
                         3 I have saved \UseVerb{Verb} and reuse
                         4 it later as many times as I want
                         5 \UseVerb{Verb}.

This also provides a solution to putting verbatim text inside L^{A}TEX commands which do not normally permit it:

1 \DefineShortVerb{\|}
2 \SaveVerb{Verb}|_OK^|

3 \marginpar{\UseVerb{Verb}}
_OK^

There is a useful ability to use verbatim text as the item text in a description list (something not normally permitted in L^{A}TEX), using the aftersave parameter:

aftersave (macro) : macro to dynamically save some verbatim material (Default: empty).

\MyCommand : my command

1 \newcommand{\Vitem}{%
2 \SaveVerb[aftersave={%
3  \item[\UseVerb{Vitem}]}]{Vitem}}
4 \DefineShortVerb{\|}
5 \begin{description}
6 \Vitem|\MyCommand|: my command
7 \end{description}

In the same way, we can use and restore (in normal, boxed and LR mode, using

\UseVerbatim, \BUseVerbatim and \LUseVerbatim respectively) entire verbatim

environments: fancyvrb/

Verbatim line.

and

Verbatim line.

1 \begin{SaveVerbatim}{VerbEnv}
2 Verbatim line.
3 \end{SaveVerbatim}
4 \UseVerbatim{VerbEnv}
5 and \UseVerbatim{VerbEnv}

{st \atop ond} and {st \atop ond}.
st
ond

and

st
ond

1 \begin{SaveVerbatim}[gobble=5]{VerbEnv}
2 First
3 Second
4 \end{SaveVerbatim}

5

6 \fbox{\BUseVerbatim{VerbEnv}}
7 and \BUseVerbatim{VerbEnv}.

8

9 \LUseVerbatim{VerbEnv} and
10 \LUseVerbatim{VerbEnv}

6 Writing and reading verbatim files

The command \VerbatimInput (the variants \BVerbatimInput and \LVerbatimInput

also exist) allows inclusion of the contents of a file with verbatim formatting. Of course, the various parameters which we have described for customizing can still be used:

! A "hello" program
program hello
print *,"Hello world"
end program hello
1 ! A "hello" program

2

3 program hello
4 print *,"Hello world"
5 end program hello
3 program hello
4 print *,"Hello world"
5 end program hello

1 ! A "hello" program

2

3 program hello
4 print *,"Hello world"
5 end program hello

1 \fvset{fontsize=\small}
2 \VerbatimInput{hello.f90}

3

4 \fvset{frame=single,numbers=left,
5  numbersep=3pt}
6 \VerbatimInput{hello.f90}

7

8 \VerbatimInput[firstline=3,
9  rulecolor=\color{green}]
10 {hello.f90}

11

12 \VerbatimInput[frame=lines,
13  fontshape=sl,fontsize=\footnotesize]
14 {hello.f90}

We can make use of the ‘defineactive’ parameter to set the comment lines in the program text in a different style:

! A "hello" program
program hello
print *,"Hello world"
end program hello

1 \def\ExclamationPoint{\char33}
2 \catcode`!=\active
3 \VerbatimInput%
4 [defineactive=%
5  \def!{\color{cyan}\itshape
6  \ExclamationPoint}]
7 {hello.f90}

It is important to note that if the contents of the file does not fit on the page, it will be automatically broken across pages as needed (unless the samepage parameter has been set to true).

There is also a VerbatimOut environment to write verbatim text to an output file, in the same way:

1 I write that.
2 And that too.

1 \begin{VerbatimOut}{file.txt}
2 I write that.
3 And that too.
4 \end{VerbatimOut}

5

6 \VerbatimInput[frame=single,
7 numbers=left,numbersep=6pt]{file.txt}

7 Conclusion

There are a few other possibilities that we have not described here. It is possible to define a customization file (fancyvrb.cfg) loaded at the end of the package, to store definitions of your customized commands and environments and to redefine the attributes of existing ones. This latter task can be performed using

the \RecustomVerbatimCommand and \RecustomVerbatimEnvironment macros;

for instance,

\RecustomVerbatimCommand{\VerbatimInput}{VerbatimInput}{frame=single}

References

[1] Timothy van Zandt, Documentation for ‘fancybox’: Box tips and tricks for

   L^{A}TEX. Available from CTAN: macros/latex/contrib/supported/fancybox,

1993.

[2] Timothy van Zandt, ‘fancyvrb’: Fancy Verbatims in L^{A}TEX. Available from

   CTAN: macros/latex/contrib/supported/fancyvrb, 1998.