framed 0.96 (1jun12)

git-svn-id: svn://tug.org/texlive/trunk@26789 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 247 insertions, 51 deletions

diff --git a/Master/texmf-dist/tex/latex/framed/framed.sty b/Master/texmf-dist/tex/latex/framed/framed.sty
index 82081cee07b..b044e96593a 100644
--- a/Master/texmf-dist/tex/latex/framed/framed.sty
+++ b/Master/texmf-dist/tex/latex/framed/framed.sty
@@ -1,7 +1,7 @@
-% framed.sty   v 0.95    2007/10/04
-% Copyright (C) 1992-2007 by Donald Arseneau  (asnd@triumf.ca)
+% framed.sty   v 0.96    2011/10/22
+% Copyright (C) 1992-2011 by Donald Arseneau  (asnd@triumf.ca)
 % These macros may be freely transmitted, reproduced, or modified
-% provided that this notice is left intact.
+% for any purpose provided that this notice is left intact.
 % 
 %====================== Begin Instructions =======================
 %
@@ -9,33 +9,51 @@
 %                       ~~~~~~~~~~
 % Create framed, shaded, or differently highlighted regions that can 
 % break across pages.  The environments defined are 
-%   framed    -- ordinary frame box (\fbox) with edge at margin
-%   shaded    -- shaded background (\colorbox) bleeding into margin
-%   snugshade -- similar
-%   leftbar   -- thick vertical line in left margin
+%   framed     - ordinary frame box (\fbox) with edge at margin
+%   oframed    - framed with open top/bottom at page breaks
+%   shaded     - shaded background (\colorbox) bleeding into margin
+%   shaded*    - shaded background (\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
+% 
 % to be used like
 % \begin{framed}
 %  copious text
 % \end{framed}
 %
 % 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 \FrameCommand and
-% \begin{MakeFramed}{settings} ... \end{MakeFramed}
+% 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) \FrameCommand for applying the boxy 
+% decoration, and \MakeFramed{settings} ... \endMakeFramed wrapped
+% around the main text argument (environment body).
 %
-% The "framed" environment uses "\fbox" as its "\FrameCommand" with 
-% the additional settings \fboxrule=\FrameRule and \fboxsep=\FrameSep.
-% You can change these lengths (using \setlength) and you can change 
-% the definition of \FrameCommand to use much fancier boxes.
+% The "framed" environment uses "\fbox", by default, as its "\FrameCommand"
+% with the additional settings "\fboxrule=\FrameRule" and "\fboxsep=\FrameSep".
+% You can change these lengths (using "\setlength") and you can change 
+% the definition of "\FrameCommand" to use much fancier boxes.  
 %
 % In fact, the "shaded" environment just redefines \FrameCommand to be
-% \colorbox{shadecolor} (and you have to define the color "shadecolor":
-% \definecolor{shadecolor}...).
+% "\colorbox{shadecolor}" (and you have to define the color `"shadecolor"':
+% "\definecolor{shadecolor}...").
+%
+% Although the intention is for other packages to define the varieties
+% of decoration, a command "\OpenFbox" is defined for frames with open 
+% tops or bottoms, and used for the "oframed" environment.  This facility
+% is based on a more complex and capable command "\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 "titled-frame" environment.  To make use of "titled-frame" in your
+% document, or the "\TitleBarFrame" command in your own environment
+% definitions, you must define the colors TFFrameColor (for the frame)
+% and a contrasting TFTitleColor (for the title text).
 %
 % A page break is allowed, and even encouraged, before the framed
 % environment.  If you want to attach some text (a box title) to the
-% frame, then the text should be inserted by \FrameCommand.
+% frame, then the text should be inserted by \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.
@@ -43,24 +61,42 @@
 % This package will not work with the page breaking of multicol.sty,
 % or other systems that perform column-balancing.
 %
-% The MakeFramed environment does the work.  Its "settings" argument
-% should contain any adjustments to the text width (applied to \hsize,
-% and using the "\width" of the frame itself) as well as a "restore" 
-% command -- \@parboxrestore or \FrameRestore or something similar;
-% as an example, the snugshade environment shows how to suppress excess
-% spacing within the box, copying the code from minipage.
+% The MakeFramed environment does the work.  Its `settings' argument
+% should contain any adjustments to the text width (via a setting of
+% "\hsize"). Here, the parameter "\width" gives the measured extra width
+% added by the frame, so a common setting is "\advance\hsize-\width"
+% which reduces the width of the text just enough that the outer edge
+% of the frame aligns with the margins.  The `settings' should also
+% include a `restore' command -- "\@parboxrestore" or "\FrameRestore"
+% or something similar; for instance, the snugshade environment uses
+% settings to eliminate list indents and vertical space, but uses
+% "\hspace" in "\FrameCommand" to reproduce the list margin ouside the
+% shading.
+%
+% There are actually four variants of "\FrameCommand" to allow different
+% formatting for each part of an environment broken over pages.  Unbroken
+% text is adorned by "\FrameCommand", whereas split text first uses 
+% "\FirstFrameCommand", possibly followed by "\MidFrameCommand", and
+% finishing with "\LastFrameCommand".  The default definitions for 
+% these three just invokes "\FrameCommand", so that all portions are
+% framed the same way.  See the oframe environment for use of distinct
+% First/Mid/Last frames.
 %
 % Expert commands:
 % \MakeFramed, \endMakeFramed: the "MakeFramed" environment
 % \FrameCommand: command to draw the frame around its argument
+% \FirstFrameCommand: the frame for the first part of a split environment
+% \LastFrameCommand: for the last portion
+% \MidFrameCommand: for any intermediate segments
 % \FrameRestore: restore some text settings, but fewer than \@parboxrestore
 % \FrameRule: length register; \fboxrule for default "framed".
 % \FrameSep: length register; \fboxsep for default "framed".
 % \FrameHeightAdjust: macro; height of frame above baseline at top of page
-% 
+% \OuterFrameSep: vertical space before and after the framed env. Defaults to "\topsep"
+%
 % 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.
 %
 % ToDo: 
 % Test more varieties of list 
@@ -68,9 +104,10 @@
 % Propagation of \marks
 % Handle footnotes (how??) floats (?) and marginpars.
 % Stretchability modification.
+% Make inner contents height/depth influence placement.
 %======================== End Instructions ========================
 
-\ProvidesPackage{framed}[2007/10/04 v 0.95: 
+\ProvidesPackage{framed}[2011/10/22 v 0.96: 
    framed or shaded text with page breaks]
 
 \newenvironment{framed}% using default \FrameCommand
@@ -82,20 +119,176 @@
   \MakeFramed {\FrameRestore}}%
  {\endMakeFramed}
 
+\newenvironment{shaded*}{%
+  \def\FrameCommand{\fboxsep=\FrameSep \colorbox{shadecolor}}%
+  \MakeFramed {\advance\hsize-\width \FrameRestore}}%
+ {\endMakeFramed}
+
 \newenvironment{leftbar}{%
   \def\FrameCommand{\vrule width 3pt \hspace{10pt}}%
   \MakeFramed {\advance\hsize-\width \FrameRestore}}%
  {\endMakeFramed}
 
+% snugshde:  Shaded environment that 
+%  -- uses the default \fboxsep instead of \FrameSep
+%  -- leaves the text indent unchanged (shading bleeds out)
+%  -- eliminates possible internal \topsep glue (\@setminipage)
+%  -- shrinks inside the margins for lists
+%  An \item label will tend to hang outside the shading, thanks to
+%  the small \fboxsep.
+
 \newenvironment{snugshade}{%
-  \def\FrameCommand{\colorbox{shadecolor}}%
-  \MakeFramed {\FrameRestore\@setminipage}}%
- {\par\unskip\endMakeFramed}
+  \def\FrameCommand##1{\hskip\@totalleftmargin \hskip-\fboxsep
+  \colorbox{shadecolor}{##1}\hskip-\fboxsep
+      % There is no \@totalrightmargin, so:
+      \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}%
+  \MakeFramed {\advance\hsize-\width 
+    \@totalleftmargin\z@ \linewidth\hsize
+    \@setminipage}%
+ }{\par\unskip\@minipagefalse\endMakeFramed}
+
+\newenvironment{snugshade*}{%
+  \def\FrameCommand##1{\hskip\@totalleftmargin 
+  \colorbox{shadecolor}{##1}%
+      % There is no \@totalrightmargin, so:
+      \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}%
+  \MakeFramed {\advance\hsize-\width 
+    \@totalleftmargin\z@ \linewidth\hsize
+    \advance\labelsep\fboxsep
+    \@setminipage}%
+ }{\par\unskip\@minipagefalse\endMakeFramed}
+
+\newenvironment{oframed}{% open (top or bottom) framed
+  \def\FrameCommand{\OpenFBox\FrameRule\FrameRule}%
+  \def\FirstFrameCommand{\OpenFBox\FrameRule\z@}%
+  \def\MidFrameCommand{\OpenFBox\z@\z@}%
+  \def\LastFrameCommand{\OpenFBox\z@\FrameRule}%
+  \MakeFramed {\advance\hsize-\width \FrameRestore}%
+  }{\endMakeFramed}
+
+% A simplified entry to \CustomFBox with two customized parameters:
+% the thicknesses of the top and bottom rules.  Perhaps we want to
+% use less \fboxsep on the open edges?
+
+\def\OpenFBox#1#2{\fboxsep\FrameSep
+   \CustomFBox{}{}{#1}{#2}\FrameRule\FrameRule}
+
+% \CustomFBox is like an amalgamation of \fbox and \@frameb@x,
+% so it can be used by an alternate to \fbox or \fcolorbox, but
+% it has more parameters for various customizations.
+% Parameter #1 is inserted (in vmode) right after the top rule 
+% (useful for a title or assignments), and #2 is similar, but
+% inserted right above the bottom rule.
+% The thicknesses of the top, bottom, left, and right rules are
+% given as parameters #3,#4,#5,#6 respectively.  They should be
+% \fboxrule or \z@ (or some other thickness).
+% The text argument is #7.
+% An instance of this can be used for the frame of \fcolorbox by
+% locally defining \fbox before \fcolorbox; e.g.,
+% \def\fbox{\CustomFBox{}{}\z@\z@\fboxrule\fboxrule}\fcolorbox
+%
+% Do we need to use different \fboxsep on different sides too?
+%
+\long\def\CustomFBox#1#2#3#4#5#6#7{%
+  \leavevmode\begingroup
+  \setbox\@tempboxa\hbox{%
+    \color@begingroup
+      \kern\fboxsep{#7}\kern\fboxsep
+    \color@endgroup}%
+  \hbox{%
+    % Here we calculate and shift for the depth.  Done in
+    % a group because one of the arguments might be \@tempdima
+    % (we could use \dimexpr instead without grouping).
+    \begingroup
+      \@tempdima#4\relax
+      \advance\@tempdima\fboxsep
+      \advance\@tempdima\dp\@tempboxa
+    \expandafter\endgroup\expandafter
+    \lower\the\@tempdima\hbox{%
+      \vbox{%
+        \hrule\@height#3\relax
+        #1%
+        \hbox{%
+          \vrule\@width#5\relax
+          \vbox{%
+            \vskip\fboxsep % maybe these should be parameters too
+            \copy\@tempboxa
+            \vskip\fboxsep}%
+          \vrule\@width#6\relax}%
+        #2%
+        \hrule\@height#4\relax}%
+    }%
+  }%
+  \endgroup
+}
+
+
+% A particular type of titled frame with continuation marks.  
+% Parameter #1 is the title, repeated on each page.
+\newenvironment{titled-frame}[1]{%
+  \def\FrameCommand{\fboxsep8pt\fboxrule2pt
+     \TitleBarFrame{\textbf{#1}}}%
+  \def\FirstFrameCommand{\fboxsep8pt\fboxrule2pt
+     \TitleBarFrame[$\blacktriangleright$]{\textbf{#1}}}%
+  \def\MidFrameCommand{\fboxsep8pt\fboxrule2pt
+     \TitleBarFrame[$\blacktriangleright$]{\textbf{#1\ (cont)}}}%
+  \def\LastFrameCommand{\fboxsep8pt\fboxrule2pt
+     \TitleBarFrame{\textbf{#1\ (cont)}}}%
+  \MakeFramed{\advance\hsize-20pt \FrameRestore}}%
+%  note: 8 + 2 + 8 + 2 = 20.  Don't use \width because the frame title
+%  could interfere with the width measurement.
+ {\endMakeFramed}
+
+% \TitleBarFrame[marker]{title}{contents}
+% Frame with a label at top, optional continuation marker at bottom right.
+% Frame color is TFFrameColor and title color is a contrasting TFTitleColor; 
+% both need to be defined before use.  The frame itself use \fboxrule and
+% \fboxsep.  If the title is omitted entirely, the title bar is omitted
+% (use a blank space to force a blank title bar).
+% 
+\newcommand\TitleBarFrame[3][]{\begingroup
+  \ifx\delimiter#1\delimiter
+    \let\TF@conlab\@empty
+  \else
+    \def\TF@conlab{% continuation label
+     \nointerlineskip
+     \smash{\rlap{\kern\wd\@tempboxa\kern\fboxrule\kern\fboxsep #1}}}%
+  \fi
+  \let\TF@savecolor\current@color
+  \textcolor{TFFrameColor}{%
+  \CustomFBox
+    {\TF@Title{#2}}{\TF@conlab}%
+    \fboxrule\fboxrule\fboxrule\fboxrule
+    {\let\current@color\TF@savecolor\set@color #3}%
+  }\endgroup
+}
+
+% The title bar for \TitleBarFrame
+\newcommand\TF@Title[1]{%
+  \ifx\delimiter#1\delimiter\else
+  \kern-0.04pt\relax
+  \begingroup
+  \setbox\@tempboxa\vbox{%
+   \kern0.8ex
+   \hbox{\kern\fboxsep\textcolor{TFTitleColor}{#1}\vphantom{Tj)}}%
+   \kern0.8ex}%
+  \hrule\@height\ht\@tempboxa
+  \kern-\ht\@tempboxa
+  \box\@tempboxa
+  \endgroup
+  \nointerlineskip 
+  \kern-0.04pt\relax
+  \fi
+}
 
 \chardef\FrameRestore=\catcode`\| % for debug
 \catcode`\|=\catcode`\% % (debug: insert space after backslash)
 
+\newlength\OuterFrameSep \OuterFrameSep=\maxdimen \relax
+
 \def\MakeFramed#1{\par
+ % apply default \OuterFrameSep = \topsep
+ \ifdim\OuterFrameSep=\maxdimen \OuterFrameSep\topsep \fi
  % measure added width and height; call result \width and \height
  \fb@sizeofframe\FrameCommand
  \let\width\fb@frw \let\height\fb@frh
@@ -119,10 +312,10 @@
     \advance\skip@ \z@ plus-.5\baselineskip
     \advance\skip@ \z@ plus-.231\height
     \advance\skip@ \z@ plus-.231\skip@
-    \advance\skip@ \z@ plus-.231\topsep
+    \advance\skip@ \z@ plus-.231\OuterFrameSep
     \vskip-\skip@ \penalty 1800 \vskip\skip@
  \fi
- \addvspace{\topsep}%
+ \addvspace{\OuterFrameSep}%
  \endgroup
  % clear out pending page break
  \penalty\@M \vskip 2\baselineskip \vskip\height
@@ -137,13 +330,14 @@
 
 \def\endMakeFramed{\par
      \kern\z@
-     \hrule\@width\hsize\@height\z@
-     \penalty-100 % put depth into height
+     \hrule\@width\hsize\@height\z@ % possibly bad
+     \penalty-100 % (\hrule moves depth into height)
  \egroup
-  % {\showoutput\showbox\@tempboxa}%
+%%%   {\showoutput\showbox\@tempboxa}%
  \begingroup 
    \fb@put@frame\FrameCommand\FirstFrameCommand
  \endgroup
+ \@minipagefalse % In case it was set and not cleared
 }
 
 % \fb@put@frame takes the contents of \@tempboxa and puts all, or a piece,
@@ -174,17 +368,18 @@
 |        \string\pagegoal=\the\pagegoal,
 |        \string\pagestretch=\the\pagestretch,
 |        \string\pageshrink=\the\pageshrink,
-|        \string\fb@frh=\fb@frh. \space}
-|    \message{Box of size \the\ht\@tempboxa\space + \fb@frh}%
+|        \string\fb@frh=\the\fb@frh. \space}
+|    \message{^^JBox of size \the\ht\@tempboxa\space}%
      \begingroup % temporarily set \dimen@ to be...
      \advance\dimen@.8\pageshrink  % maximum space available on page
-     \advance\dimen@-\fb@frh\relax % space available for frame's contents
+     \advance\dimen@-\fb@frh\relax % max space available for frame's contents
+%%% LOOKS SUBTRACTED AND ADDED, SO DOUBLE ACCOUNTING!
      \expandafter\endgroup
      % expand \ifdim, then restore \dimen@ to real room left on page
      \ifdim\dimen@>\ht\@tempboxa % whole box does fit
 |       \message{fits in \the\dimen@. }%
-        % Use vsplit anyway to capture the marks
-        % !!!???!!! MERGE THIS WITH THE else CLAUSE!!!
+        % ToDo: Change this to use vsplit anyway to capture the marks
+        % MERGE THIS WITH THE else CLAUSE!!!
         \fb@putboxa#1%
         \fb@afterframe
      \else % box must be split
@@ -198,7 +393,7 @@
         \edef\fb@resto@set{\boxmaxdepth\the\boxmaxdepth 
                            \splittopskip\the\splittopskip}%
         \boxmaxdepth\z@ \splittopskip\z@
-|       \message{Padded box of size \the\ht\@tempboxa\space split to \the\dimen@}%
+|       \message{^^JPadded box of size \the\ht\@tempboxa\space split to \the\dimen@}%
         % Split box here
         \setbox\tw@\vsplit\@tempboxa to\dimen@
 |       \toks99\expandafter{\splitfirstmark}%
@@ -207,7 +402,7 @@
         \setbox\tw@\vbox{\unvbox\tw@}% natural-sized
 |       \message{Natural height of split box is \the\ht\tw@, leaving 
 |          \the\ht\@tempboxa\space remainder. }%
-        % If the split-to size > (\vsize-\topskip), then set box to full size
+        % If the split-to size > (\vsize-\topskip), then set box to full size.
         \begingroup
         \advance\dimen@\topskip
         \expandafter\endgroup
@@ -216,7 +411,7 @@
           \dimen@ii\pagegoal
           \advance\dimen@ii -\topskip
           \advance\dimen@ii \FrameHeightAdjust\relax
-        \else  % suspect this is wrong:
+        \else  % suspect this is implemented incorrectly:
           % If the split-to size > feasible room_on_page, rebox it smaller.
           \advance\dimen@.8\pageshrink
           \ifdim\ht\tw@>\dimen@
@@ -263,7 +458,7 @@
 
 \def\fb@putboxa#1{%
   \ifvoid\@tempboxa
-    PackageWarning{framed}{Boxa is void -- discard it. }%
+    \PackageWarning{framed}{Boxa is void -- discard it. }%
   \else
 |   \message{Frame and place boxa. }%
 |   %{\showoutput\showbox\@tempboxa}%
@@ -273,11 +468,12 @@
 
 \def\fb@afterframe{%
     \nointerlineskip \null %{\showoutput \showlists}
-    \penalty-30 \vskip\topsep \relax
+    \penalty-30 \vskip\OuterFrameSep \relax
 }
 
 % measure width and height added by frame (#1 = frame command)
 % call results \fb@frw and \fb@frh
+% todo: a mechanism to handle wide frame titles 
 \newdimen\fb@frw
 \newdimen\fb@frh
 \def\fb@sizeofframe#1{\begingroup
@@ -286,7 +482,7 @@
    \vskip\z@skip}%
 |  \message{Measuring frame addition for \string#1 in \@currenvir\space 
 |    gives ht \the\ht\z@\space and wd \the\wd\z@. }%
-%{\showoutput\showbox\z@}%
+|  %{\showoutput\showbox\z@}%
  \global\fb@frw\wd\z@ \global\fb@frh\ht\z@
  \endgroup
 }
@@ -315,8 +511,8 @@
 \providecommand\FrameHeightAdjust{6pt}
 
 % \FrameRestore has parts of \@parboxrestore, performing a similar but 
-% less complete restoration of a default layouy.  See how it is used in the 
-% "settings" argument of \MakeFrame.  Though not a parameter, \hsize 
+% less complete restoration of the default layout.  See how it is used in
+% the "settings" argument of \MakeFrame.  Though not a parameter, \hsize 
 % should be set to the desired total line width available inside the
 % frame before invoking \FrameRestore.  
 \def\FrameRestore{%
@@ -331,11 +527,11 @@
    % Test if we are in a list (or list-like paragraph)
    \ifnum \ifdim\@totalleftmargin>\z@ 1\fi  
           \ifdim\rightmargin>\z@ 1\fi
-          \ifnum\@listdepth>0 1\fi 0>\z@
+          \ifnum\@listdepth>\z@ 1\fi 0>\z@
      %     \message{In a list: \linewidth=\the\linewidth, \@totalleftmargin=\the\@totalleftmargin,
      %       \parshape=\the\parshape, \columnwidth=\the\columnwidth, \hsize=\the\hsize, 
      %       \labelwidth=\the\labelwidth. }%
-     \@setminipage % snug fit around the item
+     \@setminipage % snug fit around the item.  I would like this to be non-global.
      % Now try to propageate changes of width from \hsize to list parameters.
      % This is deficient, but a more advanced way to indicate modification to text 
      % dimensions is not (yet) provided; in particular, no separate left/right