Debian Codegraph @

texmf-dist/doc/latex/fancybox/fancybox-doc.tex

raw
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