From 5d08379edd5bdc198bfaad79907a6d346aa9de44 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 1 Jun 2012 22:08:28 +0000 Subject: framed 0.96 (1jun12) git-svn-id: svn://tug.org/texlive/trunk@26789 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/framed/framed.pdf | Bin 240493 -> 235475 bytes Master/texmf-dist/doc/latex/framed/framed.tex | 83 ++++++++++++++++++-------- 2 files changed, 59 insertions(+), 24 deletions(-) (limited to 'Master/texmf-dist/doc/latex') diff --git a/Master/texmf-dist/doc/latex/framed/framed.pdf b/Master/texmf-dist/doc/latex/framed/framed.pdf index 85414ad00c5..fd00302d6a8 100644 Binary files a/Master/texmf-dist/doc/latex/framed/framed.pdf and b/Master/texmf-dist/doc/latex/framed/framed.pdf differ diff --git a/Master/texmf-dist/doc/latex/framed/framed.tex b/Master/texmf-dist/doc/latex/framed/framed.tex index dd411b02e49..4fffa8839ef 100644 --- a/Master/texmf-dist/doc/latex/framed/framed.tex +++ b/Master/texmf-dist/doc/latex/framed/framed.tex @@ -23,9 +23,9 @@ \addtokomafont{title}{\rmfamily} -\title{The \pkg{framed} package\thanks{This manual corresponds to \pkg{framed}~v0.95, dated~2007/10/04.}} +\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{2007/10/04} +\date{2012/05/31} \begin{document} @@ -40,9 +40,13 @@ break across pages. The environments defined are \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 \\ - snugshade & similar \\ - leftbar & thick vertical line in left 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 @@ -50,20 +54,22 @@ break across pages. The environments defined are to be used like % \begin{verbatim} -\begin{framed} - copious text -\end{framed} + \begin{framed} + copious text + \end{framed} \end{verbatim} But the more general purpose of this package is to facilitate the -creation of environments that enable page breaking -within arbitrary decorations using a simple new-environment definition -incorporating \cmd{\FrameCommand} and\\ -\verb+\begin{MakeFramed}+\marg{settings} \ldots\ \verb+\end{MakeFramed}+ - -The ``\env{framed}'' environment uses ``\cmd{\fbox}'' as its ``\cmd{\FrameCommand}'' with -the additional settings \verb+\fboxrule=\FrameRule+ and \verb+\fboxsep=\FrameSep+. +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. @@ -71,9 +77,21 @@ In fact, the ``\env{shaded}'' environment just redefines \cmd{\FrameCommand} to \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} -environment. If you want to attach some text (a box title) to the -frame, then the text should be inserted by \cmd{\FrameCommand}. +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. @@ -82,28 +100,45 @@ 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 (applied to \cmd{\hsize}, -and using the ``\cmd{\width}'' of the frame itself) as well as a ``restore'' -command -- \cmd{\@parboxrestore} or \cmd{\FrameRestore} or something similar; -as an example, the \env{snugshade} environment shows how to suppress excess -spacing within the box, copying the code from minipage. - +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. Nevertheless, starting -with version~0.5 it should be bug-free. +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:} -- cgit v1.2.3