1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
\documentclass[DIV=8, pagesize=auto]{scrartcl}
\usepackage{fixltx2e}
\usepackage{etex}
\usepackage{lmodern}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{array}
\usepackage{booktabs}
\usepackage{microtype}
\usepackage[unicode=true]{hyperref}
\newcommand*{\mail}[1]{\href{mailto:#1}{\texttt{#1}}}
\newcommand*{\pkg}[1]{\textsf{#1}}
\newcommand*{\cs}[1]{\texttt{\textbackslash#1}}
\makeatletter
\newcommand*{\cmd}[1]{\cs{\expandafter\@gobble\string#1}}
\makeatother
\newcommand*{\env}[1]{\texttt{#1}}
\newcommand*{\opt}[1]{\texttt{#1}}
\newcommand*{\meta}[1]{\textlangle\textsl{#1}\textrangle}
\newcommand*{\marg}[1]{\texttt{\{}\meta{#1}\texttt{\}}}
\addtokomafont{title}{\rmfamily}
\title{The \pkg{framed} package\thanks{This manual corresponds to \pkg{framed}~v0.96, dated~2011/10/22.}}
\author{Donald Arseneau (\mail{asnd@triumf.ca})}
\date{2012/05/31}
\begin{document}
\maketitle
\noindent
Create framed, shaded, or differently highlighted regions that can
break across pages. The environments defined are
\medskip
\noindent
\begin{tabular}{@{}>{\ttfamily}l@{~~--~~}l@{}}
framed & ordinary frame box (\cmd{\fbox}) with edge at margin \\
oframed & framed with open top/bottom at page breaks \\
shaded & shaded background (\cmd{\colorbox}) bleeding into margin \\
shaded* & shaded background (\cmd{\colorbox}) with edge at margin \\
snugshade & shaded with tight fit around text (esp. in lists) \\
snugshade*& like snugshade with shading edge at margin \\
leftbar & thick vertical line in left margin \\
titled-frame & frame with title-bar; template for others
\end{tabular}
\medskip
\noindent
to be used like
%
\begin{verbatim}
\begin{framed}
copious text
\end{framed}
\end{verbatim}
But the more general purpose of this package is to facilitate the
definition of new environments that take multi-line material,
wrap it with some non-breakable formatting (some kind of box or
decoration) and allow page breaks in the material. Such environments
are defined to declare (or use) \cmd{\FrameCommand} for applying the boxy
decoration, and \cmd{\MakeFramed}\marg{settings} \ldots\ \cmd{\endMakeFramed}
wrapped around the main text (environment body).
The ``\env{framed}'' environment uses \cmd{\fbox}, by default, as its \cmd{\FrameCommand}
with the additional settings \verb+\fboxrule=\FrameRule+ and \verb+\fboxsep=\FrameSep+.
You can change these lengths (using \cmd{\setlength}) and you can change
the definition of \cmd{\FrameCommand} to use much fancier boxes.
In fact, the ``\env{shaded}'' environment just redefines \cmd{\FrameCommand} to be
\verb+\colorbox{shadecolor}+ (and you have to define the color ``\texttt{shadecolor}'':
\verb+\definecolor{shadecolor}...+).
Although the intention is for other packages to define the varieties
of decoration, a command \cmd{\OpenFbox} is defined for frames with open
tops or bottoms, and used for the ``\env{oframed}'' environment. This
facility is based on a more complex and capable command \cmd{\CustomFBox} which can
be used for a wider range of frame styles. One such style of a title-bar
frame with continuation marks is provided as an example. It is used by
the ``\env{titled-frame}'' environment. To make use of \env{titled-frame} in your
document, or the \cmd{\TitleBarFrame} command in your own environment
definitions, you must define the colors \texttt{TFFrameColor} (for the frame)
and a contrasting \texttt{TFTitleColor} (for the title text).
A page break is allowed, and even encouraged, before the \env{framed}
and other environments. If you want to attach some text (a box title) to the
frame, then the text should be inserted by \cmd{\FrameCommand} so it cannot
be separated from the body.
The contents of the framed regions are restricted:
Floats, footnotes, marginpars and head-line entries will be lost.
(Some of these may be handled in a later version.)
This package will not work with the page breaking of \pkg{multicol.sty},
or other systems that perform column-balancing.
The \env{MakeFramed} environment does the work. Its ``\meta{settings}'' argument
should contain any adjustments to the text width (via a setting of \cmd{\hsize}).
Here, the parameter \cmd{\width} gives the measured extra width
added by the frame, so a common setting is ``\verb+\advance\hsize-\width+''
which reduces the width of the text just enough that the outer edge
of the frame aligns with the margins. The ``\meta{settings}'' should also
include a `restore' command -- \cmd{\@parboxrestore} or \cmd{\FrameRestore}
or something similar; for instance, the snugshade environment uses
settings to eliminate list indents and vertical space, but uses
\cmd{\hspace} in its \cmd{\FrameCommand} to reproduce the list margin ouside the
shading.
There are actually four variants of \cmd{\FrameCommand} to allow different
formatting for each part of an environment broken over pages. Unbroken
text is adorned by \cmd{\FrameCommand}, whereas split text first uses
\cmd{\FirstFrameCommand}, possibly followed by \cmd{\MidFrameCommand}, and
finishing with \cmd{\LastFrameCommand}. The default definitions for
these three just invokes \cmd{\FrameCommand}, so that all portions are
framed the same way. See the \env{oframe} environment for use of distinct
First/Mid/Last frames.
\section*{Expert commands:}
\begin{itemize}
\item \cmd{\MakeFramed}, \cmd{\endMakeFramed}: the ``\env{MakeFramed}'' environment
\item \cmd{\FrameCommand}: command to draw the frame around its argument
\item \cmd{\FirstFrameCommand}: the frame for the first part of a split environment
\item \cmd{\LastFrameCommand}: frame for the last portion
\item \cmd{\MidFrameCommand}: for any intermediate segments
\item \cmd{\FrameRestore}: restore some text settings, but fewer than \cmd{\@parbox\-restore}
\item \cmd{\FrameRule}: length register; \cmd{\fboxrule} for default ``\env{framed}''.
\item \cmd{\FrameSep}: length register; \cmd{\fboxsep} for default ``\env{framed}''.
\item \cmd{\FrameHeightAdjust}: macro; height of frame above baseline at top of page
\item \cmd{\OuterFrameSep}: vertical space before and after the framed env.; defaults to \cmd{\topsep}
\end{itemize}
\medskip
This is still a `pre-production' version because I can think of many
features/improvements that should be made. Also, a detailed manual needs
to be written. Nevertheless, starting with version~0.5 it should be bug-free.
\section*{ToDo:}
\begin{itemize}
\item Test more varieties of list
\item Improve and correct documentation
\item Propagation of \cmd{\marks}
\item Handle footnotes (how??) floats (?) and marginpars.
\item Stretchability modification.
\end{itemize}
\end{document}
|
