1 % framed.sty v 0.96 2011/10/22
2 % Copyright (C) 1992-2011 by Donald Arseneau (asnd@triumf.ca)
3 % These macros may be freely transmitted, reproduced, or modified
4 % for any purpose provided that this notice is left intact.
6 %====================== Begin Instructions =======================
10 % Create framed, shaded, or differently highlighted regions that can
11 % break across pages. The environments defined are
12 % framed - ordinary frame box (\fbox) with edge at margin
13 % oframed - framed with open top/bottom at page breaks
14 % shaded - shaded background (\colorbox) bleeding into margin
15 % shaded* - shaded background (\colorbox) with edge at margin
16 % snugshade - shaded with tight fit around text (esp. in lists)
17 % snugshade* - like snugshade with shading edge at margin
18 % leftbar - thick vertical line in left margin
25 % But the more general purpose of this package is to facilitate the
26 % definition of new environments that take multi-line material,
27 % wrap it with some non-breakable formatting (some kind of box or
28 % decoration) and allow page breaks in the material. Such environments
29 % are defined to declare (or use) \FrameCommand for applying the boxy
30 % decoration, and \MakeFramed{settings} ... \endMakeFramed wrapped
31 % around the main text argument (environment body).
33 % The "framed" environment uses "\fbox", by default, as its "\FrameCommand"
34 % with the additional settings "\fboxrule=\FrameRule" and "\fboxsep=\FrameSep".
35 % You can change these lengths (using "\setlength") and you can change
36 % the definition of "\FrameCommand" to use much fancier boxes.
38 % In fact, the "shaded" environment just redefines \FrameCommand to be
39 % "\colorbox{shadecolor}" (and you have to define the color `"shadecolor"':
40 % "\definecolor{shadecolor}...").
42 % Although the intention is for other packages to define the varieties
43 % of decoration, a command "\OpenFbox" is defined for frames with open
44 % tops or bottoms, and used for the "oframed" environment. This facility
45 % is based on a more complex and capable command "\CustomFBox" which can
46 % be used for a wider range of frame styles. One such style of a title-bar
47 % frame with continuation marks is provided as an example. It is used by
48 % the "titled-frame" environment. To make use of "titled-frame" in your
49 % document, or the "\TitleBarFrame" command in your own environment
50 % definitions, you must define the colors TFFrameColor (for the frame)
51 % and a contrasting TFTitleColor (for the title text).
53 % A page break is allowed, and even encouraged, before the framed
54 % environment. If you want to attach some text (a box title) to the
55 % frame, then the text should be inserted by \FrameCommand so it cannot
56 % be separated from the body.
58 % The contents of the framed regions are restricted:
59 % Floats, footnotes, marginpars and head-line entries will be lost.
60 % (Some of these may be handled in a later version.)
61 % This package will not work with the page breaking of multicol.sty,
62 % or other systems that perform column-balancing.
64 % The MakeFramed environment does the work. Its `settings' argument
65 % should contain any adjustments to the text width (via a setting of
66 % "\hsize"). Here, the parameter "\width" gives the measured extra width
67 % added by the frame, so a common setting is "\advance\hsize-\width"
68 % which reduces the width of the text just enough that the outer edge
69 % of the frame aligns with the margins. The `settings' should also
70 % include a `restore' command -- "\@parboxrestore" or "\FrameRestore"
71 % or something similar; for instance, the snugshade environment uses
72 % settings to eliminate list indents and vertical space, but uses
73 % "\hspace" in "\FrameCommand" to reproduce the list margin ouside the
76 % There are actually four variants of "\FrameCommand" to allow different
77 % formatting for each part of an environment broken over pages. Unbroken
78 % text is adorned by "\FrameCommand", whereas split text first uses
79 % "\FirstFrameCommand", possibly followed by "\MidFrameCommand", and
80 % finishing with "\LastFrameCommand". The default definitions for
81 % these three just invokes "\FrameCommand", so that all portions are
82 % framed the same way. See the oframe environment for use of distinct
83 % First/Mid/Last frames.
86 % \MakeFramed, \endMakeFramed: the "MakeFramed" environment
87 % \FrameCommand: command to draw the frame around its argument
88 % \FirstFrameCommand: the frame for the first part of a split environment
89 % \LastFrameCommand: for the last portion
90 % \MidFrameCommand: for any intermediate segments
91 % \FrameRestore: restore some text settings, but fewer than \@parboxrestore
92 % \FrameRule: length register; \fboxrule for default "framed".
93 % \FrameSep: length register; \fboxsep for default "framed".
94 % \FrameHeightAdjust: macro; height of frame above baseline at top of page
95 % \OuterFrameSep: vertical space before and after the framed env. Defaults to "\topsep"
97 % This is still a `pre-production' version because I can think of many
98 % features/improvements that should be made. Also, a detailed manual needs
99 % to be written. Nevertheless, starting with version 0.5 it should be bug-free.
102 % Test more varieties of list
103 % Improve and correct documentation
104 % Propagation of \marks
105 % Handle footnotes (how??) floats (?) and marginpars.
106 % Stretchability modification.
107 % Make inner contents height/depth influence placement.
108 %======================== End Instructions ========================
110 \ProvidesPackage{framed}[2011/10/22 v 0.96:
111 framed or shaded text with page breaks]
113 \newenvironment{framed}% using default \FrameCommand
114 {\MakeFramed {\advance\hsize-\width \FrameRestore}}%
117 \newenvironment{shaded}{%
118 \def\FrameCommand{\fboxsep=\FrameSep \colorbox{shadecolor}}%
119 \MakeFramed {\FrameRestore}}%
122 \newenvironment{shaded*}{%
123 \def\FrameCommand{\fboxsep=\FrameSep \colorbox{shadecolor}}%
124 \MakeFramed {\advance\hsize-\width \FrameRestore}}%
127 \newenvironment{leftbar}{%
128 \def\FrameCommand{\vrule width 3pt \hspace{10pt}}%
129 \MakeFramed {\advance\hsize-\width \FrameRestore}}%
132 % snugshde: Shaded environment that
133 % -- uses the default \fboxsep instead of \FrameSep
134 % -- leaves the text indent unchanged (shading bleeds out)
135 % -- eliminates possible internal \topsep glue (\@setminipage)
136 % -- shrinks inside the margins for lists
137 % An \item label will tend to hang outside the shading, thanks to
138 % the small \fboxsep.
140 \newenvironment{snugshade}{%
141 \def\FrameCommand##1{\hskip\@totalleftmargin \hskip-\fboxsep
142 \colorbox{shadecolor}{##1}\hskip-\fboxsep
143 % There is no \@totalrightmargin, so:
144 \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}%
145 \MakeFramed {\advance\hsize-\width
146 \@totalleftmargin\z@ \linewidth\hsize
148 }{\par\unskip\@minipagefalse\endMakeFramed}
150 \newenvironment{snugshade*}{%
151 \def\FrameCommand##1{\hskip\@totalleftmargin
152 \colorbox{shadecolor}{##1}%
153 % There is no \@totalrightmargin, so:
154 \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}%
155 \MakeFramed {\advance\hsize-\width
156 \@totalleftmargin\z@ \linewidth\hsize
157 \advance\labelsep\fboxsep
159 }{\par\unskip\@minipagefalse\endMakeFramed}
161 \newenvironment{oframed}{% open (top or bottom) framed
162 \def\FrameCommand{\OpenFBox\FrameRule\FrameRule}%
163 \def\FirstFrameCommand{\OpenFBox\FrameRule\z@}%
164 \def\MidFrameCommand{\OpenFBox\z@\z@}%
165 \def\LastFrameCommand{\OpenFBox\z@\FrameRule}%
166 \MakeFramed {\advance\hsize-\width \FrameRestore}%
169 % A simplified entry to \CustomFBox with two customized parameters:
170 % the thicknesses of the top and bottom rules. Perhaps we want to
171 % use less \fboxsep on the open edges?
173 \def\OpenFBox#1#2{\fboxsep\FrameSep
174 \CustomFBox{}{}{#1}{#2}\FrameRule\FrameRule}
176 % \CustomFBox is like an amalgamation of \fbox and \@frameb@x,
177 % so it can be used by an alternate to \fbox or \fcolorbox, but
178 % it has more parameters for various customizations.
179 % Parameter #1 is inserted (in vmode) right after the top rule
180 % (useful for a title or assignments), and #2 is similar, but
181 % inserted right above the bottom rule.
182 % The thicknesses of the top, bottom, left, and right rules are
183 % given as parameters #3,#4,#5,#6 respectively. They should be
184 % \fboxrule or \z@ (or some other thickness).
185 % The text argument is #7.
186 % An instance of this can be used for the frame of \fcolorbox by
187 % locally defining \fbox before \fcolorbox; e.g.,
188 % \def\fbox{\CustomFBox{}{}\z@\z@\fboxrule\fboxrule}\fcolorbox
190 % Do we need to use different \fboxsep on different sides too?
192 \long\def\CustomFBox#1#2#3#4#5#6#7{%
193 \leavevmode\begingroup
194 \setbox\@tempboxa\hbox{%
196 \kern\fboxsep{#7}\kern\fboxsep
199 % Here we calculate and shift for the depth. Done in
200 % a group because one of the arguments might be \@tempdima
201 % (we could use \dimexpr instead without grouping).
204 \advance\@tempdima\fboxsep
205 \advance\@tempdima\dp\@tempboxa
206 \expandafter\endgroup\expandafter
207 \lower\the\@tempdima\hbox{%
209 \hrule\@height#3\relax
212 \vrule\@width#5\relax
214 \vskip\fboxsep % maybe these should be parameters too
217 \vrule\@width#6\relax}%
219 \hrule\@height#4\relax}%
226 % A particular type of titled frame with continuation marks.
227 % Parameter #1 is the title, repeated on each page.
228 \newenvironment{titled-frame}[1]{%
229 \def\FrameCommand{\fboxsep8pt\fboxrule2pt
230 \TitleBarFrame{\textbf{#1}}}%
231 \def\FirstFrameCommand{\fboxsep8pt\fboxrule2pt
232 \TitleBarFrame[$\blacktriangleright$]{\textbf{#1}}}%
233 \def\MidFrameCommand{\fboxsep8pt\fboxrule2pt
234 \TitleBarFrame[$\blacktriangleright$]{\textbf{#1\ (cont)}}}%
235 \def\LastFrameCommand{\fboxsep8pt\fboxrule2pt
236 \TitleBarFrame{\textbf{#1\ (cont)}}}%
237 \MakeFramed{\advance\hsize-20pt \FrameRestore}}%
238 % note: 8 + 2 + 8 + 2 = 20. Don't use \width because the frame title
239 % could interfere with the width measurement.
242 % \TitleBarFrame[marker]{title}{contents}
243 % Frame with a label at top, optional continuation marker at bottom right.
244 % Frame color is TFFrameColor and title color is a contrasting TFTitleColor;
245 % both need to be defined before use. The frame itself use \fboxrule and
246 % \fboxsep. If the title is omitted entirely, the title bar is omitted
247 % (use a blank space to force a blank title bar).
249 \newcommand\TitleBarFrame[3][]{\begingroup
250 \ifx\delimiter#1\delimiter
251 \let\TF@conlab\@empty
253 \def\TF@conlab{% continuation label
255 \smash{\rlap{\kern\wd\@tempboxa\kern\fboxrule\kern\fboxsep #1}}}%
257 \let\TF@savecolor\current@color
258 \textcolor{TFFrameColor}{%
260 {\TF@Title{#2}}{\TF@conlab}%
261 \fboxrule\fboxrule\fboxrule\fboxrule
262 {\let\current@color\TF@savecolor\set@color #3}%
266 % The title bar for \TitleBarFrame
267 \newcommand\TF@Title[1]{%
268 \ifx\delimiter#1\delimiter\else
271 \setbox\@tempboxa\vbox{%
273 \hbox{\kern\fboxsep\textcolor{TFTitleColor}{#1}\vphantom{Tj)}}%
275 \hrule\@height\ht\@tempboxa
284 \chardef\FrameRestore=\catcode`\| % for debug
285 \catcode`\|=\catcode`\% % (debug: insert space after backslash)
287 \newlength\OuterFrameSep \OuterFrameSep=\maxdimen \relax
289 \def\MakeFramed#1{\par
290 % apply default \OuterFrameSep = \topsep
291 \ifdim\OuterFrameSep=\maxdimen \OuterFrameSep\topsep \fi
292 % measure added width and height; call result \width and \height
293 \fb@sizeofframe\FrameCommand
294 \let\width\fb@frw \let\height\fb@frh
295 % insert pre-penalties and skips
299 \penalty9999 % updates \page parameters
300 \ifdim\pagefilstretch=\z@ \ifdim\pagefillstretch=\z@
301 % not infinitely stretchable, so encourage a page break here
302 \edef\@tempa{\the\skip@}%
303 \ifx\@tempa\zero@glue \penalty-30
304 \else \vskip-\skip@ \penalty-30 \vskip\skip@
307 % Give a stretchy breakpoint that will always be taken in preference
308 % to the \penalty 9999 used to update page parameters. The cube root
309 % of 10000/100 indicates a multiplier of 0.21545, but the maximum
310 % calculated badness is really 8192, not 10000, so the multiplier
312 \advance\skip@ \z@ plus-.5\baselineskip
313 \advance\skip@ \z@ plus-.231\height
314 \advance\skip@ \z@ plus-.231\skip@
315 \advance\skip@ \z@ plus-.231\OuterFrameSep
316 \vskip-\skip@ \penalty 1800 \vskip\skip@
318 \addvspace{\OuterFrameSep}%
320 % clear out pending page break
321 \penalty\@M \vskip 2\baselineskip \vskip\height
322 \penalty9999 \vskip -2\baselineskip \vskip-\height
323 \penalty9999 % updates \pagetotal
324 |\message{After clearout, \pagetotal=\the\pagetotal, \pagegoal=\the\pagegoal. }%
326 \setbox\@tempboxa\vbox\bgroup
327 #1% Modifications to \hsize (can use \width and \height)
328 \textwidth\hsize \columnwidth\hsize
331 \def\endMakeFramed{\par
333 \hrule\@width\hsize\@height\z@ % possibly bad
334 \penalty-100 % (\hrule moves depth into height)
336 %%% {\showoutput\showbox\@tempboxa}%
338 \fb@put@frame\FrameCommand\FirstFrameCommand
340 \@minipagefalse % In case it was set and not cleared
343 % \fb@put@frame takes the contents of \@tempboxa and puts all, or a piece,
344 % of it on the page with a frame (\FrameCommand, \FirstFrameCommand,
345 % \MidFrameCommand, or \LastFrameCommand). It recurses until all of
346 % \@tempboxa has been used up. (\@tempboxa must have zero depth.)
347 % #1 = attempted framing command, if no split
348 % #2 = framing command if split
349 % First iteration: Try to fit with \FrameCommand. If it does not fit,
350 % split for \FirstFrameCommand.
351 % Later iteration: Try to fit with \LastFrameCommand. If it does not
352 % fit, split for \MidFrameCommand.
353 \def\fb@put@frame#1#2{\relax
354 \ifdim\pagegoal=\maxdimen \pagegoal\vsize \fi
355 | \message{=============== Entering putframe ====================^^J
356 | \pagegoal=\the\pagegoal, \pagetotal=\the\pagetotal. }%
361 \dimen@\pagegoal \advance\dimen@-\pagetotal % natural space left on page
362 \ifdim\dimen@<2\baselineskip % Too little room on page
363 | \message{Page has only \the\dimen@\space room left; eject. }%
364 \eject \fb@adjheight \fb@put@frame#1#2%
365 \else % there's appreciable room left on the page
367 | \message{\string\pagetotal=\the\pagetotal,
368 | \string\pagegoal=\the\pagegoal,
369 | \string\pagestretch=\the\pagestretch,
370 | \string\pageshrink=\the\pageshrink,
371 | \string\fb@frh=\the\fb@frh. \space}
372 | \message{^^JBox of size \the\ht\@tempboxa\space}%
373 \begingroup % temporarily set \dimen@ to be...
374 \advance\dimen@.8\pageshrink % maximum space available on page
375 \advance\dimen@-\fb@frh\relax % max space available for frame's contents
376 %%% LOOKS SUBTRACTED AND ADDED, SO DOUBLE ACCOUNTING!
377 \expandafter\endgroup
378 % expand \ifdim, then restore \dimen@ to real room left on page
379 \ifdim\dimen@>\ht\@tempboxa % whole box does fit
380 | \message{fits in \the\dimen@. }%
381 % ToDo: Change this to use vsplit anyway to capture the marks
382 % MERGE THIS WITH THE else CLAUSE!!!
385 \else % box must be split
386 | \message{must be split to fit in \the\dimen@. }%
387 % update frame measurement to use \FirstFrameCommand or \MidFrameCommand
389 \setbox\@tempboxa\vbox{% simulate frame and flexiblity of the page:
390 \vskip \fb@frh \@plus\pagestretch \@minus.8\pageshrink
391 \kern137sp\kern-137sp\penalty-30
393 \edef\fb@resto@set{\boxmaxdepth\the\boxmaxdepth
394 \splittopskip\the\splittopskip}%
395 \boxmaxdepth\z@ \splittopskip\z@
396 | \message{^^JPadded box of size \the\ht\@tempboxa\space split to \the\dimen@}%
398 \setbox\tw@\vsplit\@tempboxa to\dimen@
399 | \toks99\expandafter{\splitfirstmark}%
400 | \toks98\expandafter{\splitbotmark}%
401 | \message{Marks are: \the\toks99, \the\toks98. }%
402 \setbox\tw@\vbox{\unvbox\tw@}% natural-sized
403 | \message{Natural height of split box is \the\ht\tw@, leaving
404 | \the\ht\@tempboxa\space remainder. }%
405 % If the split-to size > (\vsize-\topskip), then set box to full size.
407 \advance\dimen@\topskip
408 \expandafter\endgroup
409 \ifdim\dimen@>\pagegoal
410 | \message{Frame is big -- Use up the full column. }%
412 \advance\dimen@ii -\topskip
413 \advance\dimen@ii \FrameHeightAdjust\relax
414 \else % suspect this is implemented incorrectly:
415 % If the split-to size > feasible room_on_page, rebox it smaller.
416 \advance\dimen@.8\pageshrink
417 \ifdim\ht\tw@>\dimen@
418 | \message{Box too tall; rebox it to \the\dimen@. }%
420 \else % use natural size
424 % Re-box contents to desired size \dimen@ii
425 \advance\dimen@ii -\fb@frh
426 \setbox\tw@\vbox to\dimen@ii \bgroup
427 % remove simulated frame and page flexibility:
428 \vskip -\fb@frh \@plus-\pagestretch \@minus-.8\pageshrink
429 \unvbox\tw@ \unpenalty\unpenalty
430 \ifdim\lastkern=-137sp % whole box went to next page
431 | \message{box split at beginning! }%
433 \egroup \fb@resto@set \eject % (\vskip for frame size was discarded)
435 \fb@put@frame#1#2% INSERTED ???
436 \else % Got material split off at the head
437 \egroup \fb@resto@set
438 \ifvoid\@tempboxa % it all fit after all
439 | \message{box split at end! }%
440 \setbox\@tempboxa\box\tw@
443 \else % it really did split
444 | \message{box split as expected. Its reboxed height is \the\ht\tw@. }%
447 \centerline{#2{\box\tw@}}% ??? \centerline bad idea
449 | \message{Zero width means likely blank. Don't frame it (guess)}%
452 \hrule \@height\z@ \@width\hsize
455 \fb@put@frame\LastFrameCommand\MidFrameCommand
461 \PackageWarning{framed}{Boxa is void -- discard it. }%
463 | \message{Frame and place boxa. }%
464 | %{\showoutput\showbox\@tempboxa}%
465 \centerline{#1{\box\@tempboxa}}%
470 \nointerlineskip \null %{\showoutput \showlists}
471 \penalty-30 \vskip\OuterFrameSep \relax
474 % measure width and height added by frame (#1 = frame command)
475 % call results \fb@frw and \fb@frh
476 % todo: a mechanism to handle wide frame titles
479 \def\fb@sizeofframe#1{\begingroup
480 \setbox\z@\vbox{\vskip-5in \hbox{\hskip-5in
481 #1{\hbox{\vrule \@height 4.7in \@depth.3in \@width 5in}}}%
483 | \message{Measuring frame addition for \string#1 in \@currenvir\space
484 | gives ht \the\ht\z@\space and wd \the\wd\z@. }%
485 | %{\showoutput\showbox\z@}%
486 \global\fb@frw\wd\z@ \global\fb@frh\ht\z@
491 \vbox to\FrameHeightAdjust{}% get proper baseline skip from above.
492 \penalty\@M \nointerlineskip
493 \vskip-\FrameHeightAdjust
494 \penalty\@M} % useful for tops of pages
496 \edef\zero@glue{\the\z@skip}
498 \catcode`\|=\FrameRestore
500 % Provide configuration commands:
501 \providecommand\FrameCommand{%
502 \setlength\fboxrule{\FrameRule}\setlength\fboxsep{\FrameSep}%
504 \@ifundefined{FrameRule}{\newdimen\FrameRule \FrameRule=\fboxrule}{}
505 \@ifundefined{FrameSep} {\newdimen\FrameSep \FrameSep =3\fboxsep}{}
506 \providecommand\FirstFrameCommand{\FrameCommand}
507 \providecommand\MidFrameCommand{\FrameCommand}
508 \providecommand\LastFrameCommand{\FrameCommand}
510 % Height of frame above first baseline when frame starts a page:
511 \providecommand\FrameHeightAdjust{6pt}
513 % \FrameRestore has parts of \@parboxrestore, performing a similar but
514 % less complete restoration of the default layout. See how it is used in
515 % the "settings" argument of \MakeFrame. Though not a parameter, \hsize
516 % should be set to the desired total line width available inside the
517 % frame before invoking \FrameRestore.
519 \let\if@nobreak\iffalse
520 \let\if@noskipsec\iffalse
522 \let\'\@acci\let\`\@accii\let\=\@acciii
523 % \message{FrameRestore:
524 % \@totalleftmargin=\the \@totalleftmargin,
525 % \rightmargin=\the\rightmargin,
526 % \@listdepth=\the\@listdepth. }%
527 % Test if we are in a list (or list-like paragraph)
528 \ifnum \ifdim\@totalleftmargin>\z@ 1\fi
529 \ifdim\rightmargin>\z@ 1\fi
530 \ifnum\@listdepth>\z@ 1\fi 0>\z@
531 % \message{In a list: \linewidth=\the\linewidth, \@totalleftmargin=\the\@totalleftmargin,
532 % \parshape=\the\parshape, \columnwidth=\the\columnwidth, \hsize=\the\hsize,
533 % \labelwidth=\the\labelwidth. }%
534 \@setminipage % snug fit around the item. I would like this to be non-global.
535 % Now try to propageate changes of width from \hsize to list parameters.
536 % This is deficient, but a more advanced way to indicate modification to text
537 % dimensions is not (yet) provided; in particular, no separate left/right
539 \advance\linewidth-\columnwidth \advance\linewidth\hsize
540 \parshape\@ne \@totalleftmargin \linewidth
543 %\message{No list, set \string\linewidth=\the\hsize. }%
548 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%