| 1 |
%% BEGIN fancybox-doc |
| 2 |
%% |
| 3 |
%% COPYRIGHT 1992, by Timothy Van Zandt, [email protected]. |
| 4 |
%% COPYRIGHT 2010, by Herbert Voss [email protected]. |
| 5 |
%% |
| 6 |
%% Documentation for fancybox.sty. |
| 7 |
%% |
| 8 |
%% This file may be distributed and/or modified under the conditions of |
| 9 |
%% the LaTeX Project Public License, either version 1.2 of this license |
| 10 |
%% or (at your option) any later version. The latest version of this |
| 11 |
%% license is in: |
| 12 |
%% |
| 13 |
%% http://www.latex-project.org/lppl.txt |
| 14 |
%% |
| 15 |
%% and version 1.2 or later is part of all distributions of LaTeX version |
| 16 |
%% 1999/12/01 or later. |
| 17 |
%% |
| 18 |
%% |
| 19 |
%% |
| 20 |
%% This creates two temporary files: \jobname.ex1 and \jobname.tmp |
| 21 |
|
| 22 |
\documentclass[12pt]{article} |
| 23 |
\usepackage [T1]{fontenc} |
| 24 |
\usepackage{mathpazo,url} |
| 25 |
|
| 26 |
\usepackage{fancybox} |
| 27 |
\let\FBfv\fileversion |
| 28 |
\usepackage{url} |
| 29 |
|
| 30 |
\VerbatimFootnotes |
| 31 |
\makeatletter |
| 32 |
% Short meta (works in verbatim. Can't use < for other purposes. |
| 33 |
\catcode`\<=13 \def<#1>{{\rm\it #1\/}} % <meta> (works in verbatim) |
| 34 |
|
| 35 |
% Short verbatim. " can appear in verbatim environments. |
| 36 |
\def\temp{\Verb"} |
| 37 |
\expandafter\def\expandafter\dospecials\expandafter{\dospecials\do\"} |
| 38 |
\catcode`\"=13 |
| 39 |
\let"\temp |
| 40 |
|
| 41 |
% Verbatim item: |
| 42 |
\newcommand{\vitem}{\SaveVerb[{\def\bf{}\item[\UseVerb{\MyTemp}]}]{\MyTemp}} |
| 43 |
|
| 44 |
%% EXAMPLES: |
| 45 |
|
| 46 |
\setlength{\fboxsep}{6pt} |
| 47 |
|
| 48 |
\begin{VerbatimOut}{\jobname.ex1} |
| 49 |
% 1. Save example verbatim to \jobname.tmp, |
| 50 |
% 2. Input verbatim with \catcode`\"=14 (" is a comment). |
| 51 |
% 3. Input again with \catcode\`"=9 (" is ignored). |
| 52 |
|
| 53 |
\renewcommand{\EveryVerbatimLine}[2]{} |
| 54 |
\renewcommand{\EveryVerbOutLine}[2]{} |
| 55 |
\newcommand\BeginExample{% |
| 56 |
\VerbatimEnvironment\begin{VerbatimOut}{\jobname.tmp}} |
| 57 |
\newcommand\EndExample{% |
| 58 |
\end{VerbatimOut}%. |
| 59 |
\renewcommand{\EveryVerbatimLine}{}% |
| 60 |
\renewcommand{\EveryVerbatimCodes}{\catcode`\"=14}% |
| 61 |
\LVerbatimInput{\jobname.tmp}% |
| 62 |
\catcode`\"=9} |
| 63 |
\newenvironment{example}{\BeginExample}{\EndExample |
| 64 |
\begin{center}\input{\jobname.tmp}\end{center}} |
| 65 |
\newenvironment{example*}{\BeginExample}% |
| 66 |
{\EndExample \input{\jobname.tmp}} |
| 67 |
\newenvironment{example**}{\BeginExample}% |
| 68 |
{\EndExample \globaldefs=1 \input{\jobname.tmp}} |
| 69 |
\end{VerbatimOut} |
| 70 |
|
| 71 |
\input{\jobname.ex1} |
| 72 |
\makeatother |
| 73 |
|
| 74 |
\title{Documentation for fancybox.sty:\\ |
| 75 |
Box tips and tricks for \LaTeX\thanks{Documentation revised by Herbert Vo\ss}} |
| 76 |
\author{Timothy Van Zandt\\ \url{[email protected]}} |
| 77 |
\date{Version \FBfv\\ \today} |
| 78 |
|
| 79 |
|
| 80 |
\begin{document} |
| 81 |
\maketitle |
| 82 |
\begin{abstract} |
| 83 |
"fancybox.sty", together with its documentation, gives extensive answers to |
| 84 |
and solutions for many questions about how to frame or rotate this or that in |
| 85 |
\LaTeX. It also contains commands for shadow, double and oval frames. |
| 86 |
\end{abstract} |
| 87 |
\vfill |
| 88 |
Thanks to Heiko Oberdiek, Marcin Wolinski. |
| 89 |
\clearpage |
| 90 |
\tableofcontents |
| 91 |
\clearpage |
| 92 |
\section{Fancy frames} |
| 93 |
|
| 94 |
"fancybox.sty" has five variants of \LaTeX's "\fbox" command: |
| 95 |
\begin{quote}\raggedright |
| 96 |
"\shadowbox", "\doublebox", "\ovalbox" (with "\thinlines") and "\Ovalbox" |
| 97 |
(with "\thicklines"). |
| 98 |
\end{quote} |
| 99 |
Here are examples:\footnote{In this documentation, the default value of |
| 100 |
"\fboxsep" has been changed from 3pt to 6pt.} |
| 101 |
\begin{example} |
| 102 |
\shadowbox{\large\bf New Glarus Birdwatch} |
| 103 |
\end{example} |
| 104 |
\begin{example} |
| 105 |
\doublebox{\large\bf New Glarus Birdwatch} |
| 106 |
\end{example} |
| 107 |
\begin{example} |
| 108 |
\ovalbox{\large\bf New Glarus Birdwatch} |
| 109 |
\end{example} |
| 110 |
\begin{example} |
| 111 |
\Ovalbox{\large\bf New Glarus Birdwatch} |
| 112 |
\end{example} |
| 113 |
|
| 114 |
The distance between the box and the frame is "\fboxsep", as with \LaTeX's |
| 115 |
"\fbox" command. The commands use other parameters as well: |
| 116 |
\begin{description} |
| 117 |
\vitem"\shadowbox" The width of the frame is "\fboxrule" (the same as with |
| 118 |
"\fbox"). The width of the shadow is "\shadowsize" (default: "4pt"). |
| 119 |
|
| 120 |
\vitem"\doublebox" The width of the inner frame is .75"\fboxrule", and the |
| 121 |
width of the outer frame is 1.5"\fboxrule". The distance between the two |
| 122 |
frames is 1.5"\fboxrule" plus .5pt. |
| 123 |
|
| 124 |
\vitem"\ovalbox" The width of the frame is set by the "\thinlines" |
| 125 |
declaration. The diameter of the corner arcs is set with the "\cornersize" |
| 126 |
command. |
| 127 |
\begin{LVerbatim} |
| 128 |
\cornersize{<num>} |
| 129 |
\end{LVerbatim} |
| 130 |
sets the diameter of the corners arcs to <num> times the lessor of the width |
| 131 |
and height of the box. |
| 132 |
\begin{LVerbatim} |
| 133 |
\cornersize*{<dim>} |
| 134 |
\end{LVerbatim} |
| 135 |
sets the diameter of the corner arcs to <dim>. This is all approximate, |
| 136 |
because \LaTeX\ has a limited range of arc sizes to choose from. The default |
| 137 |
is |
| 138 |
\begin{LVerbatim} |
| 139 |
\cornersize{.5} |
| 140 |
\end{LVerbatim} |
| 141 |
|
| 142 |
\vitem"\Ovalbox" This is like "\ovalbox", except that the width of the lines |
| 143 |
is set by the "\thicklines" declaration. |
| 144 |
\end{description} |
| 145 |
|
| 146 |
There are no analogs to \LaTeX's "\framebox" command, which has various |
| 147 |
optional arguments not supported by "\fbox". You can get the exact same |
| 148 |
functionality by putting the argument of the above framing commands in a |
| 149 |
"\makebox". |
| 150 |
|
| 151 |
There is also a variant "\fancyoval" of \LaTeX's "\oval" picture object. The |
| 152 |
difference is that "\oval" always makes the diameter of the corner arcs as |
| 153 |
large as possible, and "\fancyoval" uses the "\cornersize" command to set the |
| 154 |
diameter. |
| 155 |
|
| 156 |
\section{A short course on boxes} |
| 157 |
|
| 158 |
\begingroup\sloppy |
| 159 |
The "\shadowbox", "\doublebox", "\ovalbox" and "\Ovalbox" commands described |
| 160 |
in the previous section are examples of LR-box commands, meaning that their |
| 161 |
argument is processed in LR mode. \LaTeX\ LR-box commands include "\mbox", |
| 162 |
"\makebox", "\fbox", "\framebox", "\sbox" and "\savebox". All the PSTricks |
| 163 |
commands whose argument is text are LR-box commands, including, e.g, the |
| 164 |
framing, rotating, scaling and positioning commands, and some of the node |
| 165 |
commands. Any rotation command is an LR-box command. |
| 166 |
|
| 167 |
\endgroup |
| 168 |
|
| 169 |
The purpose of the rest of this documentation is to provide answers to, and |
| 170 |
solutions for, frequently asked questions about using LR-box commands with |
| 171 |
\LaTeX. I will use "\fbox" for the leading example of a box framing |
| 172 |
command,\footnote{In the examples using "\fbox", be aware that the default |
| 173 |
value of "\fboxsep" has been changed in this documentation from 3pt to 6pt.} |
| 174 |
and "\rotateleft" for the leading example of a box rotation command. |
| 175 |
("fancybox.sty" does not contain a "\rotateleft" command, as this must be |
| 176 |
implemented via "\special"'s, but there are numerous box-rotation style files |
| 177 |
around.) However, most of what is said here applies to any LR-box command. |
| 178 |
|
| 179 |
In each LR-box command, the text is processed in restricted horizontal mode, |
| 180 |
which is referred to as ``LR-mode'' in Lamport's {\em \LaTeX: User's Guide and |
| 181 |
Reference Manual}. In restricted horizontal mode, the input, consisting of |
| 182 |
regular characters and boxes, is made into one (long or short) line. There is |
| 183 |
no line-breaking, nor can there be vertical mode material such as an entire |
| 184 |
displayed equation. However, the fact that you can include another box means |
| 185 |
that this isn't really a restriction. |
| 186 |
|
| 187 |
For one thing, alignment environments such as \LaTeX's "tabular" are just |
| 188 |
boxes, and thus present no problem. Picture environments and the LR-box |
| 189 |
commands themselves are also just boxes. Entire paragraphs or other vertical |
| 190 |
mode material such as displayed equations can be nested in a "\parbox" or |
| 191 |
"minipage". |
| 192 |
|
| 193 |
\section{Defining LR-box environments} |
| 194 |
|
| 195 |
To frame a "minipage", you have to write |
| 196 |
\begin{LVerbatim} |
| 197 |
\fbox{% |
| 198 |
\begin{minipage}{3in} |
| 199 |
blah |
| 200 |
\end{minipage}} |
| 201 |
\end{LVerbatim} |
| 202 |
You might want to define an environment "fminipage" that frames its contents, |
| 203 |
but you can't use |
| 204 |
\begin{LVerbatim} |
| 205 |
\newenvironment{fminipage}% |
| 206 |
{\fbox{\begin{minipage}}% |
| 207 |
{\end{minipage}}} |
| 208 |
\end{LVerbatim} |
| 209 |
because the braces are not balanced in the definition. |
| 210 |
|
| 211 |
"fancybox.sty" contains an "Sbox" environment that makes it easy to define |
| 212 |
your own LR-box environments. It is a variant of \LaTeX's "\sbox" command that |
| 213 |
saves the contents of the environment in a storage bin that can be retrieved |
| 214 |
with the command "\TheSbox".\footnote{The difference between |
| 215 |
\begin{LVerbatim} |
| 216 |
\begin{Sbox} |
| 217 |
blah |
| 218 |
\end{Sbox} |
| 219 |
\TheSbox |
| 220 |
\end{LVerbatim} |
| 221 |
and |
| 222 |
\begin{LVerbatim} |
| 223 |
\newsavebox{\mybox} |
| 224 |
\sbox{\mybox}{blah} |
| 225 |
\usebox{\mybox} |
| 226 |
\end{LVerbatim} |
| 227 |
is that "Sbox" saves the contents globally, and "\TheSbox" erases the contents |
| 228 |
globally.} |
| 229 |
For example, here is a framed minipage: |
| 230 |
\begin{LVerbatim} |
| 231 |
\begin{Sbox} |
| 232 |
\begin{minipage}{3in} |
| 233 |
blah |
| 234 |
\end{minipage} |
| 235 |
\end{Sbox} |
| 236 |
\fbox{\TheSbox} |
| 237 |
\end{LVerbatim} |
| 238 |
and here is an "fminipage" environment that works: |
| 239 |
\begin{example**} |
| 240 |
\newenvironment{fminipage}% |
| 241 |
{\begin{Sbox}\begin{minipage}}% |
| 242 |
{\end{minipage}\end{Sbox}\fbox{\TheSbox}} |
| 243 |
\end{example**} |
| 244 |
Let's see that it really works: |
| 245 |
\begin{example} |
| 246 |
\begin{fminipage}{2in} |
| 247 |
Since the former doesn't use braces to delimit |
| 248 |
the contents of the box, $\ldots$ |
| 249 |
\end{fminipage} |
| 250 |
\end{example} |
| 251 |
|
| 252 |
|
| 253 |
\section{Math} |
| 254 |
|
| 255 |
In-line math, or pieces of a displayed equation (as opposed to a whole |
| 256 |
equation), are horizontal mode material, but most LR-box commands switch out |
| 257 |
of math mode when they occur in math mode. Thus, you have to explicitly switch |
| 258 |
back in to math mode when desired.\footnote{This is {\em not} true for the |
| 259 |
PSTricks LR-box commands.} |
| 260 |
For example: |
| 261 |
\begin{example} |
| 262 |
$x + y = \fbox{$\Omega$}$ |
| 263 |
\end{example} |
| 264 |
|
| 265 |
You also have to explicitly write |
| 266 |
\begin{quote} |
| 267 |
"\scriptstyle", "\scriptscriptstyle" or "\displaystyle" |
| 268 |
\end{quote} |
| 269 |
if you want one of these special math styles. For example, here I will frame |
| 270 |
an equation, but not the equation number: |
| 271 |
\begin{example*} |
| 272 |
\begin{equation} |
| 273 |
\fbox{$\displaystyle |
| 274 |
\int_{\Omega_0} \zeta(\omega) d\omega |
| 275 |
\geq \bar{r}$} |
| 276 |
\end{equation} |
| 277 |
\end{example*} |
| 278 |
|
| 279 |
Entire displayed equations or "eqnarray" environments work differently because |
| 280 |
they are vertical mode material. Thus, they have to go inside a "\parbox" or |
| 281 |
"minipage". E.g., |
| 282 |
\begin{example*} |
| 283 |
\newlength{\mylength} |
| 284 |
\[ |
| 285 |
\setlength{\fboxsep}{15pt} |
| 286 |
\setlength{\mylength}{\linewidth} |
| 287 |
\addtolength{\mylength}{-2\fboxsep} |
| 288 |
\addtolength{\mylength}{-2\fboxrule} |
| 289 |
\fbox{% |
| 290 |
\parbox{\mylength}{ |
| 291 |
\setlength{\abovedisplayskip}{0pt} |
| 292 |
\setlength{\belowdisplayskip}{0pt} |
| 293 |
\begin{equation} |
| 294 |
x + y = z |
| 295 |
\end{equation}}} |
| 296 |
\] |
| 297 |
\end{example*} |
| 298 |
The outer "\[" "\]" are just used to display the boxed equation, rather than |
| 299 |
actually switch into math mode. Note how I set the width of the "\parbox" so |
| 300 |
that the displayed box would exactly have width "\linewidth".\footnote{That is |
| 301 |
what "\mylength" is for. It is better to define a single scratch length that |
| 302 |
you reuse rather than creating a new one each time.} |
| 303 |
|
| 304 |
I also set the display skips to "0pt" and increased the size of "\fboxsep" so |
| 305 |
that I would have the same distance all around between the equation and the |
| 306 |
frame. |
| 307 |
|
| 308 |
This is again a mouthful, and so I might instead define:\footnote{The reason |
| 309 |
for using "\minipage" instead of "\begin{minipage}", and so on, is that with |
| 310 |
AmS-\LaTeX, "\begin" and "\end" cannot appear in the definition of a new |
| 311 |
equation environment.} |
| 312 |
\begin{example**} |
| 313 |
\newenvironment{FramedEqn}% |
| 314 |
{\setlength{\fboxsep}{15pt} |
| 315 |
\setlength{\mylength}{\linewidth}% |
| 316 |
\addtolength{\mylength}{-2\fboxsep}% |
| 317 |
\addtolength{\mylength}{-2\fboxrule}% |
| 318 |
\Sbox |
| 319 |
\minipage{\mylength}% |
| 320 |
\setlength{\abovedisplayskip}{0pt}% |
| 321 |
\setlength{\belowdisplayskip}{0pt}% |
| 322 |
\equation}% |
| 323 |
{\endequation\endminipage\endSbox |
| 324 |
\[\fbox{\TheSbox}\]} |
| 325 |
\end{example**} |
| 326 |
"fancybox.sty" doesn't bother defining any such environments, because there |
| 327 |
are too many possible designs. But let's see if the one above works: |
| 328 |
\begin{example*} |
| 329 |
\begin{FramedEqn} |
| 330 |
\Rightarrow P\sim\xi(P_\gamma)- \frac{1}{3} |
| 331 |
\end{FramedEqn} |
| 332 |
\end{example*} |
| 333 |
|
| 334 |
"fancybox.sty" contains a "Beqnarray" environment, which is like the |
| 335 |
"eqnarray" environment but it is not vertical mode material. Instead, it |
| 336 |
produces a box just large enough to hold all the equations. For example: |
| 337 |
\begin{example} |
| 338 |
\fbox{% |
| 339 |
\begin{Beqnarray*} |
| 340 |
x & = & y\\ |
| 341 |
y & > & x \\ |
| 342 |
\int_4^5 f(x)dx & = & \sum_{i\in F} x_i |
| 343 |
\end{Beqnarray*}} |
| 344 |
\end{example} |
| 345 |
The unstarred version produces standard equation numbers on the right (even |
| 346 |
with the "leqno" style option and AmS-\LaTeX). It might not work with special |
| 347 |
equation numbering macros. |
| 348 |
|
| 349 |
|
| 350 |
\section{Floats}\label{floats} |
| 351 |
|
| 352 |
A common mistake is to put a whole "table", "figure" or other float |
| 353 |
environment inside an LR-box command. Instead, you should put everything that |
| 354 |
is {\em inside} the environment (including the "\caption", if you want that |
| 355 |
boxed too) inside a "minipage" of the desired width, and then put the |
| 356 |
"minipage" inside the LR-box command. |
| 357 |
|
| 358 |
For example: |
| 359 |
\begin{example*} |
| 360 |
\begin{table}[h] |
| 361 |
\begin{center} |
| 362 |
\fbox{% |
| 363 |
\begin{minipage}{.8\textwidth} |
| 364 |
\begin{center} |
| 365 |
\begin{tabular}{rl} |
| 366 |
foo & bar |
| 367 |
\end{tabular} |
| 368 |
\end{center} |
| 369 |
\caption{A table of foo and bar.} |
| 370 |
\end{minipage}} |
| 371 |
\end{center} |
| 372 |
\end{table} |
| 373 |
\end{example*} |
| 374 |
Note how I had to use "center" twice: once to center the framed box, and again |
| 375 |
to center the stuff inside the box. |
| 376 |
|
| 377 |
That is a mouthful, and so I might define a "FramedTable" environment like the |
| 378 |
following, which sets the size of the "minipage" so that the framed box is |
| 379 |
exactly the width of the page (no need for the first "center" environment this |
| 380 |
time): |
| 381 |
\begin{example**} |
| 382 |
\newenvironment{FramedTable}% |
| 383 |
{\begin{table}[h] |
| 384 |
\begin{Sbox}% |
| 385 |
\setlength{\mylength}{\textwidth}% |
| 386 |
\addtolength{\mylength}{-2\fboxsep}% |
| 387 |
\addtolength{\mylength}{-2\fboxrule}% |
| 388 |
\begin{minipage}{\mylength}}% |
| 389 |
{\end{minipage}\end{Sbox}\fbox{\TheSbox}\end{table}}% |
| 390 |
\end{example**} |
| 391 |
Now let's see if it works: |
| 392 |
\begin{example*} |
| 393 |
\begin{FramedTable} |
| 394 |
\begin{center} |
| 395 |
\begin{tabular}{rl} |
| 396 |
foo & bar |
| 397 |
\end{tabular} |
| 398 |
\end{center} |
| 399 |
\caption{A table of foo and bar.} |
| 400 |
\end{FramedTable} |
| 401 |
\end{example*} |
| 402 |
|
| 403 |
The most common reason to want to rotate an entire float, caption and all, is |
| 404 |
to put it on a page by itself in landscape mode, centered both horizontally |
| 405 |
and vertically. Compared to the table framing we did above, we just have to |
| 406 |
replace "\fbox" by our box rotation command (e.g., "\rotateleft" or whatever), |
| 407 |
set the width of the minipage to "\textheight" (if you want to use the full |
| 408 |
size of the page), and use the float position specifier "[p]". "fancybox.sty" |
| 409 |
contains an environment, |
| 410 |
\begin{LVerbatim} |
| 411 |
\begin{landfloat}{<float>}{<rotation command>} |
| 412 |
... |
| 413 |
\end{landfloat} |
| 414 |
\end{LVerbatim} |
| 415 |
that automates this. It has two arguments: the name of the floating |
| 416 |
environment, and your rotation command. For example, if "\rotateleft{foo}" |
| 417 |
rotates "foo" by 90 degrees, and you want a landscape mode "table", then try |
| 418 |
\begin{LVerbatim} |
| 419 |
\begin{landfloat}{table}{\rotateleft} |
| 420 |
... |
| 421 |
\end{landfloat} |
| 422 |
\end{LVerbatim} |
| 423 |
If the whole document is in landscape mode, then "landfloat" gives you a |
| 424 |
portrait-mode float---good for a table that is too tall to fit in landscape |
| 425 |
mode. |
| 426 |
|
| 427 |
If you don't add a caption to a float, it doesn't matter much what floating |
| 428 |
environment you use (e.g., "table", "figure" or whatever). Thus, you can put |
| 429 |
anything in a landscape float. For example, suppose I have a very wide |
| 430 |
equation. Then I can write: |
| 431 |
\begin{LVerbatim} |
| 432 |
\begin{landfloat}{table}{\rotateleft} |
| 433 |
\begin{equation} |
| 434 |
... |
| 435 |
\end{equation} |
| 436 |
\end{landfloat} |
| 437 |
\end{LVerbatim} |
| 438 |
"fancybox.sty" defines a generic caption, "\GenericCaption", that doesn't |
| 439 |
affect the numbering of floats, doesn't make an entry in a list of floats, and |
| 440 |
doesn't add anything to the argument you give. I could have used this if I |
| 441 |
wanted to add a caption to the previous example. |
| 442 |
|
| 443 |
\section{Center, flushleft and flushright} |
| 444 |
|
| 445 |
There are two ways to box a "center", "flushleft" or "flushright" environment. |
| 446 |
If you have long lines and you want \TeX\ to do the line breaking, then put |
| 447 |
the environment inside a "minipage".\footnote{List and other such environments |
| 448 |
work best inside a "minipage" environment rather than a "\parbox".} If you |
| 449 |
have short lines and you want the frame to adjust itself to the size of the |
| 450 |
longest line, then use "fancybox.sty"'s |
| 451 |
\begin{quote} |
| 452 |
"Bcenter", "Bflushleft" or "Bflushright" |
| 453 |
\end{quote} |
| 454 |
environment instead. |
| 455 |
|
| 456 |
These are basically just "tabular" environments with a single column, and so |
| 457 |
each line should end with "\\", or "\\["<dim>"]" to insert extra space, and |
| 458 |
the text on each line must be balanced. Also, each line is sitting in its own |
| 459 |
group, and so, e.g., if you want to change the font for the whole environment, |
| 460 |
you should do this before the environment rather than after. |
| 461 |
Like the "tabular" environment, the box that is produced has the baseline at |
| 462 |
the center, unless you include an optional argument "[t]" to align the box |
| 463 |
with the top line or "[b]" to align the box with the bottom line. |
| 464 |
|
| 465 |
For example: |
| 466 |
\begin{example} |
| 467 |
\setlength{\fboxsep}{10pt}% |
| 468 |
\fbox{% |
| 469 |
\begin{Bcenter} |
| 470 |
Love of life\\ |
| 471 |
and other short stories\\ |
| 472 |
by Policarpa Salabarrieta |
| 473 |
\end{Bcenter}} |
| 474 |
\end{example} |
| 475 |
Compare this with: |
| 476 |
\begin{example} |
| 477 |
\setlength{\fboxsep}{10pt}% |
| 478 |
\fbox{% |
| 479 |
\begin{minipage}{6cm} |
| 480 |
\begin{center} |
| 481 |
Love of life and other short stories |
| 482 |
by Policarpa Salabarrieta |
| 483 |
\end{center} |
| 484 |
\end{minipage}} |
| 485 |
\end{example} |
| 486 |
|
| 487 |
In either case, if we want the resulting framed box centered, we have to |
| 488 |
include it inside another "center" environment. |
| 489 |
|
| 490 |
Here is another example: |
| 491 |
\begin{example} |
| 492 |
My list: \fbox{% |
| 493 |
\begin{Bflushleft}[b] |
| 494 |
Galanga root\\ |
| 495 |
Coconut\\ |
| 496 |
Tempeh |
| 497 |
\end{Bflushleft}} |
| 498 |
\end{example} |
| 499 |
|
| 500 |
|
| 501 |
\section{Lists} |
| 502 |
|
| 503 |
There are again two ways to box a list environment such as |
| 504 |
\begin{quote} |
| 505 |
"itemize", "enumerate" or "description". |
| 506 |
\end{quote} |
| 507 |
You can put it in a "minipage" of pre-determined size and let \TeX\ do the |
| 508 |
line breaking, or you can use |
| 509 |
\begin{quote} |
| 510 |
"Bitemize", "Benumerate" or "Bdescription" |
| 511 |
\end{quote} |
| 512 |
instead, and let the box adjust to the size of the longest line. |
| 513 |
|
| 514 |
For example. |
| 515 |
\begin{example} |
| 516 |
\fbox{% |
| 517 |
\begin{Bitemize} |
| 518 |
\item Groceries |
| 519 |
\item Clean hamster cages |
| 520 |
\item Pick up Peter |
| 521 |
\end{Bitemize}} |
| 522 |
\end{example} |
| 523 |
|
| 524 |
Most of the usual list parameters are irrelevant except for "\itemsep" and |
| 525 |
"\labelsep". These environments are also based on the "tabular" environment, |
| 526 |
and so each item should be balanced text. You can't write "\vspace{4pt}" |
| 527 |
either, but you can insert an extra amount of space before an item by writing |
| 528 |
"\item(4pt)" (or "\item(4pt)[label]" if you have a label). Also, you can break |
| 529 |
lines within an item using "\\" or "\\[<dim>]". For example: |
| 530 |
\begin{example} |
| 531 |
\fbox{% |
| 532 |
\begin{Bdescription} |
| 533 |
\item[David] Groceries |
| 534 |
\item[Eli] Hamster cages\\ |
| 535 |
Surreal numbers |
| 536 |
\item(3pt)[Doris] Pick up Peter |
| 537 |
\end{Bdescription}} |
| 538 |
\end{example} |
| 539 |
|
| 540 |
These environments also have an optional argument, "[t]" to align the box with |
| 541 |
the top line, and "[b]" to align the box with the bottom line. |
| 542 |
\begin{example} |
| 543 |
To do: |
| 544 |
\fbox{\setlength{\itemsep}{0pt}% |
| 545 |
\begin{Benumerate}[t] |
| 546 |
\item Groceries |
| 547 |
\item Hamster cages |
| 548 |
\item Pick up Peter |
| 549 |
\end{Benumerate}} |
| 550 |
\end{example} |
| 551 |
|
| 552 |
There is also a generic "\Blist" command that is analogous to \LaTeX's |
| 553 |
"\list". It has the same two obligatory arguments, plus a third optional |
| 554 |
"[t]" or "[b]" argument for changing the alignment. |
| 555 |
|
| 556 |
\section{Superimposing boxes} |
| 557 |
|
| 558 |
The command |
| 559 |
\begin{LVerbatim} |
| 560 |
\boxput*(<x>,<y>){<LR stuff1>}{<LR stuff2>} |
| 561 |
\end{LVerbatim} |
| 562 |
puts <LR stuff1> either behind (the default) or in front of (with the "*") <LR |
| 563 |
stuff2>.\footnote{You will only notice the difference between "\boxput" and |
| 564 |
"\boxput*" if you are using color implemented by "\special"'s} The resulting |
| 565 |
box has the dimensions of <LR stuff2>. |
| 566 |
|
| 567 |
The coordinates "(<x>,<y>)" determine where the center of <LR stuff1> is |
| 568 |
positioned. For example, "(0,0)" puts it at the center of <LR stuff2>, "(0,1)" |
| 569 |
puts it at the center-top, and "(-1,-1)" puts it in the bottom-left corner. |
| 570 |
|
| 571 |
More generally, the origin of the coordinate system is at the center of <LR |
| 572 |
stuff2>, one unit in the vertical direction is half the vertical size of <LR |
| 573 |
stuff2>, and one unit in the horizontal direction is half the width of <LR |
| 574 |
stuff2>. Thus, <x> and <y> should always be numbers (without units such as |
| 575 |
"pt" or "cm"), with one exception: If <y> is "b" or "B", <LR stuff1> is |
| 576 |
positioned vertically at the baseline of <LR stuff2>. "(<x>,<y>)" is |
| 577 |
optional---the default is "(0,0)". |
| 578 |
|
| 579 |
Except for the funny coordinate system, "\boxput" is like the "\put" command |
| 580 |
in a "picture". In particular, you can use "\makebox" in <LR stuff1> to |
| 581 |
fine-tune the positioning, and <LR-stuff1> can contain a "picture" |
| 582 |
environment. |
| 583 |
|
| 584 |
You might use "\boxput" to put a ``water mark'' in the background of a box, or |
| 585 |
to put a label next to a box, when you don't want this label to take up any |
| 586 |
space. Here is a lazy example: |
| 587 |
\begin{example} |
| 588 |
\boxput{\makebox(0,0){\Huge Censored!}}{\parbox{3in}{% |
| 589 |
The origin of the coordinate system is at the center of |
| 590 |
{\em LR stuff2}, and one unit in the x-direction |
| 591 |
is half the width of {\em LR stuff2}.}} |
| 592 |
\end{example} |
| 593 |
|
| 594 |
This would be a lot more interesting using PSTricks, with ``Censored!'' in the |
| 595 |
foreground, rotated 30 degrees, and red: |
| 596 |
\begin{LVerbatim} |
| 597 |
\boxput*{\rput{30}{\Huge\red Censored}}{\parbox{3in}{% |
| 598 |
blah blah}} |
| 599 |
\end{LVerbatim} |
| 600 |
|
| 601 |
Here is another example using PSTricks: |
| 602 |
\begin{LVerbatim} |
| 603 |
\newcommand{\titledframe}[2]{% |
| 604 |
\boxput*(0,1){\psframebox*{#1}}% |
| 605 |
{\psframebox[framesep=12pt]{#2}}} |
| 606 |
\end{LVerbatim} |
| 607 |
\newcommand{\titledframe}[2]{% |
| 608 |
\boxput*(0,1){#1}% |
| 609 |
{\fboxsep=12pt \fbox{#2}}} |
| 610 |
The following example illustrated roughly how it works, but ``My title'' does |
| 611 |
not blot out the frame behind it because this documentation does not use |
| 612 |
PSTricks. \begin{example} |
| 613 |
\titledframe{My title}{% |
| 614 |
\parbox{2in}{The title is superimposed |
| 615 |
on the top part of the frame.}} |
| 616 |
\end{example} |
| 617 |
|
| 618 |
\section{Framing a whole page} |
| 619 |
|
| 620 |
The commands |
| 621 |
\begin{LVerbatim} |
| 622 |
\fancyput*(<x>,<y>){<LR stuff>} |
| 623 |
\thisfancyput*(<x>,<y>){<LR stuff>} |
| 624 |
\end{LVerbatim} |
| 625 |
are pretty much like "\put" commands in a \LaTeX\ picture environment whose |
| 626 |
origin is 1 inch down and to the right from the top left corner of the |
| 627 |
page.\footnote{Don't blame me for \TeX's peculiar 1 inch margins.} The only |
| 628 |
differences are that (i) that any LR-mode material is permitted (including |
| 629 |
\LaTeX\ "picture" environment, of course), (ii) the coordinate is optional |
| 630 |
"(0pt,0pt)" is substituted by default), and (iii) if the coordinate is |
| 631 |
included, you {\em must} specify the units. |
| 632 |
|
| 633 |
"\thisfancyput" affects only the current page, and is a global declaration |
| 634 |
(analogous to "\thispagestyle"). |
| 635 |
|
| 636 |
If you include the optional "*", then the command adds to, rather than |
| 637 |
replaces, other things that have been inserted with "\fancyput" or |
| 638 |
"\thisfancyput". |
| 639 |
|
| 640 |
These commands are particularly useful for framing a page, because you can get |
| 641 |
a frame that is, e.g., 1 inch from each side of the physical page without |
| 642 |
having to worry about what margins you are using for the document. Here is an |
| 643 |
example: |
| 644 |
\begin{example*} |
| 645 |
\thisfancyput(3.25in,-4.5in){% |
| 646 |
\setlength{\unitlength}{1in}\fancyoval(7,9.5)} |
| 647 |
\end{example*} |
| 648 |
You could also use "\fancyput" to add some kind of ``watermark'' or background |
| 649 |
image (e.g., a light gray ``DRAFT''). |
| 650 |
|
| 651 |
There are other commands that directly frame or in some other way box the page |
| 652 |
of text: |
| 653 |
\begin{LVerbatim} |
| 654 |
\fancypage{<cmds1>}{<cmds2>} |
| 655 |
\thisfancypage{<cmds1>}{<cmds2>} |
| 656 |
\end{LVerbatim} |
| 657 |
|
| 658 |
Each finished page, before adding the headers and footers, (and thus having |
| 659 |
width and height "\textwidth" and "\textheight", is boxed with |
| 660 |
\begin{LVerbatim} |
| 661 |
<cmds1>{<pagebox>} |
| 662 |
\end{LVerbatim} |
| 663 |
Thus, <cmds1> should be, or should end with, a command whose argument can be a |
| 664 |
box, such as "\fbox" or "\rotateleft". |
| 665 |
|
| 666 |
Then the headers and footers are added, using the new width of the page, and |
| 667 |
this is boxed with |
| 668 |
\begin{LVerbatim} |
| 669 |
<cmds2>{<pagebox>} |
| 670 |
\end{LVerbatim} |
| 671 |
The same rules apply to <cmds2> as to <cmds1>. |
| 672 |
|
| 673 |
Here is an example: |
| 674 |
\begin{example*} |
| 675 |
\thisfancypage{% |
| 676 |
\setlength{\fboxsep}{8pt}% |
| 677 |
\setlength{\shadowsize}{8pt}% |
| 678 |
\shadowbox}{} |
| 679 |
\end{example*} |
| 680 |
|
| 681 |
{\bf Warning:} The commands described in this section change \LaTeX's output |
| 682 |
routine, and may not work with document styles that do the same. Also, bad |
| 683 |
arguments can cause serious errors with uninformative error messages. |
| 684 |
|
| 685 |
\section{Switching to landscape mode midstream} |
| 686 |
|
| 687 |
The most common reason to switch to landscape mode midstream is to rotate a |
| 688 |
float, such as a table or figure. This was discussed in Section \ref{floats}. |
| 689 |
|
| 690 |
If you want to rotate one or more pages, without rotating the headers and |
| 691 |
footers, use the |
| 692 |
\begin{LVerbatim} |
| 693 |
\begin{LandScape}{<cmd>} |
| 694 |
... |
| 695 |
\end{LandScape} |
| 696 |
\end{LVerbatim} |
| 697 |
environment. <cmd> should be the command for rotating the page 90 degrees to |
| 698 |
the left or right. (E.g., "\rotateleft", or "\rotate[l]".) |
| 699 |
|
| 700 |
If you want to rotate the headers, footers and margins as well, use the |
| 701 |
\begin{LVerbatim} |
| 702 |
\begin{Landscape}{<paperwidth>}{<paperheight>}{<cmd>} |
| 703 |
... |
| 704 |
\end{Landscape} |
| 705 |
\end{LVerbatim} |
| 706 |
environment (the small "s" makes the difference) to rotate the pages left |
| 707 |
(counterclockwise), and use the "Landscape*" environment (same arguments) to |
| 708 |
rotate the pages right (clockwise). The three arguments are the width of the |
| 709 |
paper, the height of the paper, and the rotation command you are using. For |
| 710 |
example, if I have a portrait mode document using the US 8.5in by 11in paper, |
| 711 |
and if "\rotateleft{foo}" rotates "foo" 90 degrees counterclockwise, then I |
| 712 |
can write |
| 713 |
\begin{LVerbatim} |
| 714 |
\begin{Landscape}{8.5in}{11in}{\rotateleft} |
| 715 |
\end{LVerbatim} |
| 716 |
|
| 717 |
You can use "\LandScape", "\Landscape" and "\Landscape*", rather then the |
| 718 |
"LandScape", "Landscape" and "Landscape*" environments, if you want the rest |
| 719 |
of the document to be in landscape mode. |
| 720 |
|
| 721 |
If your document is being printed in landscape mode, then these environments |
| 722 |
switch to portrait mode. |
| 723 |
|
| 724 |
For example, suppose I have a landscape mode document, and I want to switch to |
| 725 |
portrait mode for the rest of the document, rotating the pages to the |
| 726 |
``right'' with "\rotateright". Then I would write |
| 727 |
\begin{LVerbatim} |
| 728 |
\Landscape*{11in}{8.5in}{\rotateright} |
| 729 |
\end{LVerbatim} |
| 730 |
|
| 731 |
These environments switch the text width and height, leaving the margins |
| 732 |
exactly as they were before. It is quite possible that you want to make other |
| 733 |
changes to the page parameters after switching to landscape mode, but as |
| 734 |
Lamport points out the \LaTeX\ {\em User's Guide and Reference Manual}, this |
| 735 |
generally doesn't work right in the middle of the document. "fancybox.sty" has |
| 736 |
a command "\UsePageParameters" which gets around this. It should be used right |
| 737 |
after you change the page parameters (and the page parameter changes should |
| 738 |
come right after the beginning of the landscape environment, or "\clearpage"). |
| 739 |
|
| 740 |
{\bf Warning:} The commands and environments described in this section change |
| 741 |
\LaTeX's output routine, and may not work with document styles that do the |
| 742 |
same. Also, bad arguments can cause serious errors with uninformative error |
| 743 |
messages. |
| 744 |
|
| 745 |
\section{Verbatim} |
| 746 |
|
| 747 |
If you try to frame some verbatim text by typing |
| 748 |
\begin{LVerbatim} |
| 749 |
\fbox{% |
| 750 |
\begin{minipage}{5cm} |
| 751 |
\begin{verbatim} |
| 752 |
\My \Program \Listing |
| 753 |
if { foo } { bar } fi |
| 754 |
\end{verbatim} |
| 755 |
\end{minipage}} |
| 756 |
\end{LVerbatim} |
| 757 |
you will get nonsense at best. This is because the argument to "\fbox" is read |
| 758 |
before the "\begin{verbatim}" is processed. But then it is too late for \TeX\ |
| 759 |
to go back and interpret the contents of the verbatim environment literally |
| 760 |
rather than as special \TeX\ commands and characters. |
| 761 |
|
| 762 |
One solution is to use the "Sbox" environment: |
| 763 |
\begin{example} |
| 764 |
\begin{Sbox} |
| 765 |
\begin{minipage}{5cm} |
| 766 |
\begin{verbatim} |
| 767 |
\My \Program \Listing |
| 768 |
if { foo } { bar } fi |
| 769 |
\end{verbatim} |
| 770 |
\end{minipage} |
| 771 |
\end{Sbox} |
| 772 |
\setlength{\fboxsep}{8pt} |
| 773 |
\fbox{\TheSbox} |
| 774 |
\end{example} |
| 775 |
|
| 776 |
"fancybox.sty" also contains a command that ``fixes'' \LaTeX's LR-box commands |
| 777 |
for use with verbatim text: |
| 778 |
\begin{LVerbatim} |
| 779 |
\VerbBox{<cmd>}{<LR stuff>} |
| 780 |
\end{LVerbatim} |
| 781 |
This is like |
| 782 |
\begin{LVerbatim} |
| 783 |
<cmd>{<LR stuff>} |
| 784 |
\end{LVerbatim} |
| 785 |
but <LR stuff> can contain verbatim text.\footnote{Or other tricks that |
| 786 |
involve "\catcode" changes, as occurs with some foreign language macros.} For |
| 787 |
example: |
| 788 |
\begin{example} |
| 789 |
\VerbBox{\fbox}{\verb+\foo{bar}+} |
| 790 |
\end{example} |
| 791 |
|
| 792 |
For footnotes, put the command "\VerbatimFootnotes" in the preamble, and then |
| 793 |
you can use verbatim commands or environments in the argument of "\footnote". |
| 794 |
This is an optional feature because it might conflict with somebody else's |
| 795 |
modification of the footnote system. |
| 796 |
|
| 797 |
If you try to define your own framed verbatim environment with |
| 798 |
\begin{LVerbatim} |
| 799 |
\newenvironment{FramedVerb}% |
| 800 |
{\begin{Sbox}\begin{minipage}{5in}\begin{verbatim}} |
| 801 |
{\end{verbatim}\end{minipage}\end{Sbox} |
| 802 |
\setlength{\fboxsep}{8pt}\fbox{\TheSbox}} |
| 803 |
\end{LVerbatim} |
| 804 |
and then type |
| 805 |
\begin{LVerbatim} |
| 806 |
\begin{FramedVerb} |
| 807 |
if { foo } { bar } fi |
| 808 |
\end{FramedVerb} |
| 809 |
\end{LVerbatim} |
| 810 |
you will again run into trouble because after the "\begin{verbatim}", \LaTeX\ |
| 811 |
is searching for the literal string "\end{verbatim}" as the end of the |
| 812 |
verbatim text. It just skips right over the "\end{FramedVerb}" and may well |
| 813 |
continue to the end of the file or until it throws up. |
| 814 |
|
| 815 |
"fancybox.sty" contains some verbatim environments that get around this |
| 816 |
problem and that have other advantages for LR-boxing verbatim listings, when |
| 817 |
compared to the standard \LaTeX\ "verbatim" environment. Admittedly, many of |
| 818 |
their special features have nothing to do with boxes. |
| 819 |
|
| 820 |
Here are the basic verbatim environments: |
| 821 |
\begin{description} |
| 822 |
\vitem"Verbatim" Works pretty much like \LaTeX's "verbatim". |
| 823 |
\vitem"LVerbatim" Like "Verbatim", but "list" rather than "trivlist" is used |
| 824 |
to display the listing, and so it is indented from the left margin. (This is |
| 825 |
what I am using for verbatim listings in this document.) |
| 826 |
\vitem"BVerbatim[<pos>]" Produces a box with the same width as the longest |
| 827 |
verbatim line. The baseline is in the center, unless you include the optional |
| 828 |
argument "[t]" for alignment with the top line or "[b]" for alignment with the |
| 829 |
bottom line. |
| 830 |
\vitem"VerbatimOut{<file>}" Writes the verbatim text to <file>. |
| 831 |
\vitem"SaveVerbatim{<cmd>}" Saves the verbatim text as <cmd>. <cmd> is |
| 832 |
defined globally, without checking whether <cmd> is already defined. Use |
| 833 |
obviously innocuous names like "\MyTemp". |
| 834 |
\end{description} |
| 835 |
|
| 836 |
{\bf Important:} For any of these verbatim environments, or new verbatim |
| 837 |
environments you define yourself (see below), nothing should come after |
| 838 |
"\begin{Verbatim}" or before "\end{Verbatim}" on the same line --- not even |
| 839 |
spaces!% |
| 840 |
\footnote{If you need to allow something to come before "\end{Verbatim}", |
| 841 |
then you have two options: |
| 842 |
\begin{itemize} |
| 843 |
\item Put the command "\AltGetVerbatim" in the preamble. This switches to a |
| 844 |
scheme where anything preceding "\end{Verbatim}" is simply ignored. This can |
| 845 |
cause problems if you do really weird things with active characters or other |
| 846 |
commands within the verbatim environment (e.g., active conditionals that are |
| 847 |
not balanced within a line of verbatim text), but in this case you are |
| 848 |
probably a good enough hacker to use the next option. |
| 849 |
\item "\EndVerbatimTokens" is a token register that you can set to the |
| 850 |
tokens that should precede "\end{Verbatim}" on the same line, with their |
| 851 |
verbatim "\catcode"'s. |
| 852 |
\end{itemize}} |
| 853 |
If you put something after "\begin{Verbatim}" on the same line, it is simply |
| 854 |
ignored. However, if you put something after "\end{Verbatim}" on the same |
| 855 |
line, or if you misspell "\end{Verbatim}", you will get an error such as |
| 856 |
\begin{LVerbatim} |
| 857 |
! File ended while scanning use of \Verbatim. |
| 858 |
\end{LVerbatim} |
| 859 |
and the document will end at that point. |
| 860 |
|
| 861 |
You can define new verbatim environments using "\newenvironment". You just |
| 862 |
have to start the definition with |
| 863 |
\begin{LVerbatim} |
| 864 |
\VerbatimEnvironment |
| 865 |
\end{LVerbatim} |
| 866 |
For example, here is the framed verbatim environment we tried earlier: |
| 867 |
\begin{example**} |
| 868 |
\newenvironment{FramedVerb}% |
| 869 |
{\VerbatimEnvironment |
| 870 |
\begin{Sbox}\begin{minipage}{5cm}\begin{Verbatim}}% |
| 871 |
{\end{Verbatim}\end{minipage}\end{Sbox} |
| 872 |
\setlength{\fboxsep}{8pt}\fbox{\TheSbox}} |
| 873 |
\end{example**} |
| 874 |
Let's give it a try: |
| 875 |
\begin{example} |
| 876 |
\begin{FramedVerb} |
| 877 |
if { foo } { bar } fi |
| 878 |
\end{FramedVerb} |
| 879 |
\end{example} |
| 880 |
|
| 881 |
Here are three commands for inputting a whole file verbatim. The file must end |
| 882 |
with a new line. |
| 883 |
\begin{description} |
| 884 |
\vitem"\VerbatimInput{<file>}" Like "\Verbatim". |
| 885 |
\vitem"\LVerbatimInput{<file>}" Like "\LVerbatim". |
| 886 |
\vitem"\BVerbatimInput[<pos>]{<file>}" Like "\BVerbatim". |
| 887 |
\end{description} |
| 888 |
|
| 889 |
Here are three commands for making use of verbatim text that has been saved to |
| 890 |
a command: |
| 891 |
\begin{description} |
| 892 |
\vitem"\UseVerbatim{<cmd>}" Like "\Verbatim". |
| 893 |
\vitem"\LUseVerbatim{<cmd>}" Like "\LVerbatim". |
| 894 |
\vitem"\BUseVerbatim[<pos>]{<cmd>}" Like "\BVerbatim". |
| 895 |
\end{description} |
| 896 |
The "SaveVerbatim" environment and the "\UseVerbatim" commands are useful for |
| 897 |
including verbatim text in the argument of "\marginpar", "\fbox" and other |
| 898 |
commands. For example, here is another way to define the "FramedVerb" |
| 899 |
environment: |
| 900 |
\begin{LVerbatim} |
| 901 |
\newenvironment{FramedVerb}% |
| 902 |
{\VerbatimEnvironment |
| 903 |
\begin{SaveVerbatim}{\MyTemp}}% |
| 904 |
{\end{SaveVerbatim}% |
| 905 |
\setlength{\fboxsep}{8pt}% |
| 906 |
\fbox{\begin{minipage}{5cm}\UseVerbatim{\MyTemp} |
| 907 |
\end{minipage}}} |
| 908 |
\end{LVerbatim} |
| 909 |
|
| 910 |
Here are some verbatim commands for short-pieces of (in-line) verbatim text: |
| 911 |
\begin{description} |
| 912 |
\vitem"\Verb<char> <literal> <char>" \ \\ |
| 913 |
Like \LaTeX's "\verb" command, but it will complain if it encounters a new |
| 914 |
line in <literal>.\footnote{Be careful that your word processing does not |
| 915 |
insert one for you.} For example: |
| 916 |
\begin{example*} |
| 917 |
"\begin{quote} |
| 918 |
The main use for the \Verb+SaveVerbatim+ |
| 919 |
environment and the \Verb+\UseVerbatim+ |
| 920 |
commands is to include $\ldots$ |
| 921 |
"\end{quote} |
| 922 |
\end{example*} |
| 923 |
\vitem"\UseVerb{<cmd>}" Like "\UseVerbatim", but without any particular |
| 924 |
formatting. It is intended for including short pieces of literal text saved |
| 925 |
with "\SaveVerb" (below).\footnote{But it can also be used for multiple lines |
| 926 |
saved with the "SaveVerbatim" environment if you want to do the formatting |
| 927 |
yourself. E.g., try this in a tabbing environment with "\VerbatimTab" |
| 928 |
appropriately defined.} |
| 929 |
\vitem"\SaveVerb[<whatever>]{<cmd>}<char> <literal> <char>"\ \\ |
| 930 |
This is like "\Verb", but it saves <literal> as <cmd>, and then returns to |
| 931 |
the optional argument <whatever>. Like the "SaveVerbatim" environment, it |
| 932 |
defines <cmd> globally without checking whether <cmd> is already defined. |
| 933 |
Without the optional argument, the most common use is for including verbatim |
| 934 |
text in a "\marginpar", "\section" or other command argument. |
| 935 |
|
| 936 |
The optional argument can be used for special tricks. For example, all the |
| 937 |
listings of commands in this documentation use "\vitem" in a "description" |
| 938 |
environment, where "\vitem" is defined by:\footnote{The braces enclosing the |
| 939 |
optional argument of "\SaveVerb" prevent the "]" inside the argument from |
| 940 |
being mistaken for the end of the argument.} |
| 941 |
\begin{LVerbatim} |
| 942 |
\newcommand{\vitem}% |
| 943 |
{\SaveVerb[{\item[\UseVerb{\MyTemp}]}]{\MyTemp}} |
| 944 |
\end{LVerbatim} |
| 945 |
Whereas |
| 946 |
\begin{LVerbatim} |
| 947 |
\item[\Verb"\foo"] |
| 948 |
\end{LVerbatim} |
| 949 |
would not work because after "\item" reads its argument it is too late to |
| 950 |
interpret "\foo" literally, |
| 951 |
\begin{LVerbatim} |
| 952 |
\vitem"foo" |
| 953 |
\end{LVerbatim} |
| 954 |
does work because it is equivalent to |
| 955 |
\begin{LVerbatim} |
| 956 |
\SaveVerb{\MyTemp}"foo"\item[\UseVerb{\MyTemp}] |
| 957 |
\end{LVerbatim} |
| 958 |
\end{description} |
| 959 |
|
| 960 |
|
| 961 |
These environments and commands use various parameters that make it easy to |
| 962 |
customize their behavior. However, until you want to find the need for such |
| 963 |
customization, you might as well ignore the rest of this section. |
| 964 |
|
| 965 |
Internally, "fancybox.sty" separates the reading and formatting of verbatim |
| 966 |
text. Most of the environments and commands perform both functions, but |
| 967 |
"SaveVerbatim" and "\SaveVerb" only read the text, while "UseVerbatim" (and |
| 968 |
company) and "\UseVerb" only format the text. "VerbatimOut" gets special |
| 969 |
treatment. The parameters that apply to each class of verbatim environment or |
| 970 |
command is listed in Table \ref{verbtable}. |
| 971 |
|
| 972 |
\begin{table} |
| 973 |
\begin{center} |
| 974 |
\renewcommand{\arraystretch}{0} |
| 975 |
\setlength{\tabcolsep}{7pt} |
| 976 |
\newcommand{\vs}{& \\[\tabcolsep]} |
| 977 |
\newcommand{\VS}{\\ \vs \hline \vs} |
| 978 |
\begin{tabular}{|l|l|} |
| 979 |
\hline \vs |
| 980 |
{\em Where} & {\em What} |
| 981 |
\\ \vs \hline |
| 982 |
\hline \vs |
| 983 |
\begin{Bflushleft} |
| 984 |
Environments\\ |
| 985 |
that format |
| 986 |
\end{Bflushleft} |
| 987 |
& |
| 988 |
\begin{Bflushleft} |
| 989 |
"\VerbatimSpace"\\ |
| 990 |
"\VerbatimTab"\\ |
| 991 |
"\VerbatimFont"\\ |
| 992 |
"\VerbatimFuzz"\\ |
| 993 |
"\EveryVerbatimLine"\\ |
| 994 |
"\EveryVerbatim"\\ |
| 995 |
"\ThisVerb" |
| 996 |
\end{Bflushleft} |
| 997 |
\VS |
| 998 |
\begin{Bflushleft} |
| 999 |
Environments\\ |
| 1000 |
that read |
| 1001 |
\end{Bflushleft} |
| 1002 |
& |
| 1003 |
\begin{Bflushleft} |
| 1004 |
"\EveryVerbatimCodes"\\ |
| 1005 |
"\ThisVerbCodes" |
| 1006 |
\end{Bflushleft} |
| 1007 |
\VS |
| 1008 |
\begin{Bflushleft} |
| 1009 |
"\Verb" and\\ |
| 1010 |
"\UseVerb" |
| 1011 |
\end{Bflushleft} |
| 1012 |
& |
| 1013 |
\begin{Bflushleft} |
| 1014 |
"\VerbSpace"\\ |
| 1015 |
"\VerbTab"\\ |
| 1016 |
"\VerbFont"\\ |
| 1017 |
"\EveryVerb"\\ |
| 1018 |
"\ThisVerb" |
| 1019 |
\end{Bflushleft} |
| 1020 |
\VS |
| 1021 |
\begin{Bflushleft} |
| 1022 |
"\Verb" and\\ |
| 1023 |
"\SaveVerb" |
| 1024 |
\end{Bflushleft} |
| 1025 |
& |
| 1026 |
\begin{Bflushleft} |
| 1027 |
"\EveryVerbCodes"\\ |
| 1028 |
"\ThisVerbCodes" |
| 1029 |
\end{Bflushleft} |
| 1030 |
\VS |
| 1031 |
\begin{Bflushleft} |
| 1032 |
"VerbatimOut" |
| 1033 |
\end{Bflushleft} |
| 1034 |
& |
| 1035 |
\begin{Bflushleft} |
| 1036 |
"\EveryVerbOutCodes"\\ |
| 1037 |
"\ThisVerbCodes"\\ |
| 1038 |
"\EveryVerbOutLine"\\ |
| 1039 |
"\ThisVerb" |
| 1040 |
\end{Bflushleft} |
| 1041 |
\\ \vs \hline |
| 1042 |
\end{tabular} |
| 1043 |
\caption{Parameters for the verbatim environments and |
| 1044 |
commands.\label{verbtable}} |
| 1045 |
\end{center} |
| 1046 |
\end{table} |
| 1047 |
|
| 1048 |
All the parameters, including "\VerbatimFuzz", are ordinary commands, and |
| 1049 |
should be changed with "\renewcommand". |
| 1050 |
|
| 1051 |
Here is a description of each of the parameters for environments that format |
| 1052 |
the verbatim text: |
| 1053 |
\begin{description} |
| 1054 |
\vitem"\VerbatimSpace" The insertion text for spaces. The default is "\ ", |
| 1055 |
which produces a blank space. Change it to "\ttspace" to get \ttspace. |
| 1056 |
\vitem"\VerbatimTab" The insertion text for tabs. The default is |
| 1057 |
\begin{LVerbatim} |
| 1058 |
\ \ \ \ \ \ \ \ |
| 1059 |
\end{LVerbatim} |
| 1060 |
\vitem"\VerbatimFont" The font to use for verbatim text. The default is |
| 1061 |
"\tt" |
| 1062 |
\vitem"\VerbatimFuzz" This is the amount by which lines can be too long in a |
| 1063 |
"Verbatim" or "LVerbatim" environment before you get overfull "\hbox" |
| 1064 |
warnings. This threshold is usually .1pt, but the default definition of |
| 1065 |
"\VerbatimFuzz" is "2pt" because verbatim lines won't break and are therefore |
| 1066 |
often too long. |
| 1067 |
\vitem"\EveryVerbatimLine" This is inserted at the beginning of each line of |
| 1068 |
verbatim environments or verbatim files. By default it does nothing. I like to |
| 1069 |
indent each line in the verbatim environment in the input file by 2 spaces, so |
| 1070 |
I define |
| 1071 |
\begin{LVerbatim} |
| 1072 |
\renewcommand{\EveryVerbatimLine}[2]{} |
| 1073 |
\end{LVerbatim} |
| 1074 |
to eat those spaces. (But I have to remember to put in two spaces or space |
| 1075 |
markers for blank lines too.) You might also use it to number the lines. For |
| 1076 |
example: |
| 1077 |
\begin{example} |
| 1078 |
\newcounter{VerbLineNo} |
| 1079 |
\renewcommand{\EveryVerbatimLine}% |
| 1080 |
{\makebox[10pt][r]{% |
| 1081 |
\stepcounter{VerbLineNo}% |
| 1082 |
\tiny\rm\arabic{VerbLineNo}}% |
| 1083 |
\hspace{10pt}} |
| 1084 |
\renewcommand{\EveryVerbatim}% |
| 1085 |
{\setcounter{VerbLineNo}{0}} |
| 1086 |
\begin{SaveVerbatim}{\MyTemp} |
| 1087 |
\setlength{\fboxsep}{15pt} |
| 1088 |
\setlength{\mylength}{\linewidth} |
| 1089 |
\end{SaveVerbatim} |
| 1090 |
\fbox{\BUseVerbatim{\MyTemp}} |
| 1091 |
\end{example} |
| 1092 |
\vitem"\EveryVerbatim" Whatever else you want to say before formatting the |
| 1093 |
verbatim text. By default, it does nothing. |
| 1094 |
\vitem"\ThisVerb" This is executed before any of the commands above, and |
| 1095 |
then its value is cleared. Use this to customize a single verbatim formatting |
| 1096 |
environment. |
| 1097 |
\end{description} |
| 1098 |
|
| 1099 |
Here is a description of the parameters for environments that read the |
| 1100 |
verbatim text: |
| 1101 |
\begin{description} |
| 1102 |
\vitem"\EveryVerbatimCodes" This command is inserted just before reading the |
| 1103 |
verbatim text. Use it to play with "\catcode"'s (see the {\em \TeX book}). For |
| 1104 |
example, I might type |
| 1105 |
\begin{LVerbatim} |
| 1106 |
\renewcommand{\EveryVerbatimCodes}{\catcode`\"=14} |
| 1107 |
\end{LVerbatim} |
| 1108 |
if I want to use \Verb+"+ as a comment character in verbatim text.% |
| 1109 |
%% The use of SaveVerbatim and \SaveVerb is not necessary here because |
| 1110 |
%% \VerbatimFootnotes is in effect. This is just a test. |
| 1111 |
\begin{SaveVerbatim}{\MyTemp} |
| 1112 |
\def\MyQuote{"} % \MyQuote is now the character ", |
| 1113 |
\def\temp{\Verb"} % in case I need it. |
| 1114 |
\catcode`\"=13 % Now " is like a command. |
| 1115 |
\let"\temp % Now "foo" is like \Verb"foo" |
| 1116 |
\def\do{\noexpand\do\noexpand} % Now " can be used in verbatim |
| 1117 |
\edef\dospecials{\dospecials\do\"} % environments anyway. |
| 1118 |
\end{SaveVerbatim}\SaveVerb{\Foo}+"+\SaveVerb{\FFoo}+\Verb"foo"+% |
| 1119 |
\footnote{Here is another "\catcode" trick. We make \UseVerb{\Foo} a short |
| 1120 |
verbatim command, so that we can say \UseVerb{\Foo foo\Foo} instead of |
| 1121 |
\UseVerb{\FFoo}: |
| 1122 |
\LUseVerbatim{\MyTemp}} |
| 1123 |
\vitem"\ThisVerbCodes" This command is executed before "\EveryVerbCodes", |
| 1124 |
and then it is cleared. Use this to fool with the "\catcode"`s of a single |
| 1125 |
verbatim environment. |
| 1126 |
\end{description} |
| 1127 |
|
| 1128 |
The parameters for "\Verb", "\UseVerb" and "\SaveVerb" and the "VerbatimOut" |
| 1129 |
environment are analogous to the similar commands for other environments. |
| 1130 |
|
| 1131 |
Here is an example of the use of "\ThisVerb" to define a variant of "\Verb" |
| 1132 |
that uses \ttspace\ to mark spaces: |
| 1133 |
\begin{LVerbatim} |
| 1134 |
\newcommand{\SVerb}{% |
| 1135 |
\renewcommand{\ThisVerb}% |
| 1136 |
{\renewcommand{\VerbatimSpace}{\ttspace}}% |
| 1137 |
\Verb} |
| 1138 |
\end{LVerbatim} |
| 1139 |
|
| 1140 |
Finally, without further comment, here are the definitions of the "example" |
| 1141 |
and "example*" environments that were used for the examples in this document: |
| 1142 |
{\renewcommand{\EveryVerbatimLine}{}\LVerbatimInput{\jobname.ex1}} |
| 1143 |
|
| 1144 |
|
| 1145 |
\end{document} |
| 1146 |
%% END fancybox.doc |