The ‘fvrb-ex’ package Example environments with the ‘fancyvrb’ package

Denis Girou CNRS/IDRIS Orsay – France

email: Denis.Girou@idris.fr

Version 1.7 March 27, 1998

Documentation revised March 27, 1998

Abstract

This package, built above the ‘fancyvrb’ one (from Timothy van Zandt), offer several kinds of the so-called example environments to format some code both in “verbatim” mode and in the “normal” way, below or on the side. The advantage of such environments is that the code itself is included only one time in the source code, which allow to be sure of the consistence of the two versions shown.

Some other kinds of such environments are specially devoted to graphics, allowing to give the size of them. It is possible in this case to draw also a grid.

Contents

1 Introduction 1

2 User interface 2 2.1 Environments . . . . . . . 2 2.2 Loading options . . . . . . 3

2.3 ‘fancyvrb’ options imposed 3

3 Usage examples 4 3.1 Usage of the environments 4 3.2 Usage of the ‘hbaw’ and

‘hcolor’ packages . . . . . 7 3.3 Thanks . . . . . . . . . . 8

1 Introduction

These macros are based on some previous work of Timothy van Zandt, adapted and developed to suit my personal needs.

This package is built above the ‘fancyvrb’ one (from Timothy van Zandt), to offer some example environments showing both the code and it result. It main strength is that it allow to use all the power of ‘fancyvrb’, with it great number of customization parameters.

These macros can also be used in conjunction with the ‘hbaw’ and ‘hcolor’ packages, to allow to generate the verbatim code with some highlighting attributes to emphasize parts of the text. It can also produce different effects according to the choice of a colored or black and white version. This last facility was developed for slides, to allow to generate them both in color for projection and in black and white to distribute them as paper copy.

Some special environments for graphic drawings allow to define directly the size of them, without requiring to use also a picture environment. To be able to use them, the PSTricks package must be available, even if these specialized environments can be used for graphics built with another macro language than PSTricks.

Warning! You must be aware that it has been reported that this package doesn’t work at all on some platforms, due to the way the 8 bits characters are managed by some TEX systems.

2 User interface

Warning! We suppose here that you already know the ‘fancyvrb’ package. If not, look at it own documentation!

2.1 Environments

Five new environments are defined:

Example : show the verbatim text and the formatted result below.

CenterExample : same than Example, but the result is centered.

SideBySideExample : show the formatted result on the left and the verbatim text on the right. The result is centered vertically according to the text.

PCenterExample : same than CenterExample, but the result is put inside a PSTricks pspicture environment. It is undefined if PSTricks is not available. It is specially devoted to graphic drawings, but not specially built with PSTricks itself. It require to specify the dimensions of the graphic. In fact, it is the same thing than to use the CenterExample environment and to put the material inside a L^{A}TEX picture or PSTricks pspicture environment, but it can be more convenient to have not to specify this one explicitely.

PSideBySideExample : same than SideBySideExample, but the result is put inside a PSTricks pspicture environment. The preceding comments for PCenterExample are of course also valid for it.

The syntax of the first three is:

  \begin{EnvironmentName}[optional_fancyvrb_arguments]
    ..................................................
  \end{EnvironmentName}

and for the two last ones:

  \begin{EnvironmentName}[opt_fvrb_args][(x_min,y_min)](x_max,y_max)
    ................................................................
  \end{EnvironmentName}

In these last cases, default values for x_min and y_min are 0.

2.2 Loading options

baw : allow highlighting for a black and white version. In this case the ‘hbaw’ will be loaded and it definitions will be active to emphasize texts.

color : allow highlighting for a color version. In this case the ‘hcolor’ will be loaded and it definitions will be active to emphasize texts.

bawcolor : doesn’t specify in the file if it will be a black and white or a color version to generate. A question will be asked interactively at compile time. This allow to generate at choice one of the two versions without any change in the file.

pstricks : require the loading of PSTricks (which of course must be available on the system) to be able to use the special environments devoted to graphics (but not at all mandatory PSTricks graphics).

Of course, these three keywords are mutually exclusive. If none of the baw, color or bawcolor keyword is specified, none of the supplementary files will be loaded.

2.3 ‘fancyvrb’ options imposed

The following ‘fancyvrb’ parameters are imposed:

gobble=2 : each line inside these environments is supposed to be indented by 2 characters. It only concern the aspect of the source code, which will be more readable like that.

numbersep=3pt : it will be effective only if numbers=left or numbers=right will be chosen.

commentchar=W : it is the comment character for the source text, which will not be printed in the verbatim part, but executed in the formatted part. So, it allow to have the example not generated by the code shown, which can be surprising for readers and must be used only with care in special circumstances! Character chosen is 163 (£). If it cannot be used on your system or if you have it inside your verbatim text, you must change it by yourself in the package file.

commandchars=XYZ : respectively the escape, beginning of group and end of group characters, to allow escape sequences (L^{A}TEX commands as font and color changes) to be applied on the verbatim text, using the ‘hbaw’ or ‘hcolor’ packages. These characters are specially chosen to probably be used by nobody in their codes... Characters chosen are those of codes 167, 181 and 182 (μ). If they cannot be used on your system or if you have some of them inside your verbatim text, you must made yourself the relevant changes in the three files of the package.

3 Usage examples

3.1 Usage of the environments

1 \begin{Example}
2 First verbatim line.
3 Second verbatim line.
4 Third verbatim line.
5 \end{Example}
 First verbatim line.
 Second verbatim line.
 Third verbatim line.

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

It is possible to customize the verbatim environments as in the standard way defined by ‘fancyvrb’, locally as argument of the environment^{1}, or globally using the \fvset command.

1 \begin{Example}[frame=lines,framerule=1mm,numbers=left]
2 First verbatim line.
3 Second verbatim line.
4 Third verbatim line.
5 \end{Example}

1 First verbatim line.
2 Second verbatim line.
3 Third verbatim line.

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

1 \begin{CenterExample}[frame=single,numbers=right]
2 First verbatim line.
3 Second verbatim line.
4 Third verbatim line.
5 \end{CenterExample}

  First verbatim line.  1
  Second verbatim line.  2
  Third verbatim line.  3

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

1Take care that you must define these parameters directly for the Example, CenterExample

and SideBySideExample environments, but that you must put them inside a \fvset macro for

the PCenterExample and PSideBySideExample ones, as in these cases you can also specify some

PSTricks parameters, using the \psset macro.

First Second  1 First 2 Second

                          1 \begin{SideBySideExample}
                          2  [xrightmargin=3cm,numbers=left]
                          3 First
                          4 Second
                          5 \end{SideBySideExample}
    As explained, the PCenterExample and PSideBySideExample environments,

specially devoted to graphics, put their contents inside a PSTricks pspicture environment^{2}. So, we must define the size of it.

1 \fvset{frame=lines,framerule=0.5mm,numbers=left}

2

3 \begin{PCenterExample}(-0.5,-0.5)(0.5,0.5)
4 \setlength{\unitlength}{1cm}
5 \put(0,0){\circle{1}}
6 \end{PCenterExample}

1 \setlength{\unitlength}{1cm}
2 \put(0,0){\circle{1}}

So, it is the same thing than to do:

1 \fvset{frame=lines,framerule=0.5mm,numbers=left}

2

3 \begin{CenterExample}
4 \setlength{\unitlength}{1cm}
5 \begin{picture}(1,1)(-0.5,-0.5)
6  \put(0,0){\circle{1}}
7 \end{picture}
8 \end{CenterExample}

1 \setlength{\unitlength}{1cm}
2 \begin{picture}(1,1)(-0.5,-0.5)
3 \put(0,0){\circle{1}}
4 \end{picture}

2The ∗ convention of the pspicture environment is not accepted here.

Using the\showgrid macro, we can require to superpose the graphic above a grid, which can help to built it as desired. The size of the picture must be at least of 1 unit in this case, and the grid is rounded to the next greater integer.

1 \showgrid
2 \begin{PCenterExample}[frame=single,numbers=left](-1,-1)(1,1)
3 \setlength{\unitlength}{1cm}
4 \put(0,0){\circle{1}}
5 \end{PCenterExample}
1 \setlength{\unitlength}{1cm}
2 \put(0,0){\circle{1}}

1 \fvset{frame=single,xrightmargin=5cm}
2 \begin{PSideBySideExample}(-2,-1)(2,1)
3 \psellipse*[linecolor=yellow](2,1)
4 \end{PSideBySideExample}

5

6 \showgrid
7 \begin{PSideBySideExample}(-2,-1)(2,1)
8 \psellipse[linestyle=dashed](2,1)
9 \end{PSideBySideExample}

                             \psellipse*[linecolor=yellow](2,1)

                             \psellipse[linestyle=dashed](2,1)

The special £ character defined as the comment for ‘fancyvrb’ must be used with care, as it allow to change the code run in the formatted part without showing these changes in the verbatim part. So, the code shown will not correspond any more in this case to the one which produce the result... (we must take care also to do not indent these lines, otherwise we will change the formatting...).

Nevertheless, in very special circumstances, it allow to do special tricks.

1 \begin{CenterExample}[frame=lines,framerule=0.5mm]
2 First verbatim line.
3 £\textit{%
4 Second verbatim line.

5 £}

6 £\LARGE
7 Third verbatim line.
8 \end{CenterExample}

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

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

3.2 Usage of the ‘hbaw’ and ‘hcolor’ packages

If the option baw, color or bawcolor is chosen, we can use special commands to emphasize text in the verbatim formatting. It allow mainly to change the font or the color of special parts of the text. Here we suppose that the package option baw for the ‘fvrb-ex’ has been chosen:

1 \begin{CenterExample}[frame=single,numbers=right]
2 HLaμFirst verbatim line.
3 HLbμSecond verbatim line.
4 HLCBWzμThird verbatim line.
5 \end{CenterExample}

  First verbatim line.  1
  Second verbatim line.  2
  Third verbatim line.  3

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

1 \fvset{frame=single}
2 \begin{PSideBySideExample}[xrightmargin=5.5cm](-2,-1)(2,1)
3 \psellipse[linestyle=HLCBWzμdashed](2,1)
4 \end{PSideBySideExample}

5

6 \begin{PSideBySideExample}[xrightmargin=4.5cm](-2,-1)(2,1)
7 \psellipse[linestyle=HLbμdotted](2,1)
8 \end{PSideBySideExample}

                              \psellipse[linestyle=dashed](2,1)

                         \psellipse[linestyle=dotted](2,1)

3.3 Thanks

I thank you Sebastian Rahtz <s.rahtz@elsevier.co.uk>, Thomas Siegel

<siegel@aix520.informatik.uni-leipzig.de> and Rolf Niepraschk

<niepraschk@ptb.de> for their tests and comments on preliminary versions of this package.