%<+package> [2003/08/27 1.0 skipping of slow boxes]
% \end{meta-comment}
%
-% \CheckSum{222}
+% \CheckSum{223}
%% \CharacterTable
%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%
%<*driver>
\input{mdwtools}
+\PassOptionsToPackage{hide}{slowbox}
\describespackage{slowbox}
\newcommand\opt[1]{\textsf{#1}}
-\expandafter\def\csname sb@box:tag\endcsname{{2cm}{1cm}{0.5cm}}
\def\*{\hspace{0pt plus 0.1pt}\ignorespaces}
\mdwdoc
%</driver>
% \env{slowbox$*$} environment takes a tag name, just like \env{slowbox}
% does.
%
+% However, if \package{slowbox} sees a slow box \<tag> it's not noticed
+% before, it always typesets the box contents, and saves the measurements for
+% later.
+%
+% \begin{demo}{Slow boxes}
+%\newcommand{\pic}
+% {\parbox[t]{20mm}
+% {Just pretend that there's a picture
+% here that would take aaaages to draw.}}
+%--
+%\begin{slowbox*}{show}
+% \pic
+%\end{slowbox*}
+%--
+%\begin{slowbox}{hide}
+% \pic
+%\end{slowbox}
+%--
+% \end{demo}
+%
% \DescribeMacro\slowboxbegin
% \DescribeMacro\slowboxend
% It's useful to define your own commands environments which create slow
% boxes. Often, though, what happens is that you want to put some stuff
% \emph{inside} the slow box, but that doesn't work properly. What you must
% do instead is say something like
-% \begin{verbatim}
+%\begin{verbatim}
% \newenvironment{splunt}[1]
% {...\slowboxbegin{#1}{...\startsplunt...}}
% {\slowboxend{...\finishsplunt...}...}
-% \end{verbatim}
-% That is, \syntax{"\\slowboxbegin{"<tag>"}{{"<stuff>"}"} starts a slow box,
-% beginning with \<stuff> if we're in \opt{show} mode.
+%\end{verbatim}
+% That is, \syntax{"\\slowboxbegin{"<tag>"}{"<stuff>"}"} starts a slow box,
+% beginning with \<stuff> if we're in \opt{show} mode; and
+% \syntax{"\\slowboxend{"<stuff>"}"} finishes it, ending with \<stuff>.
%
% The |\slowboxbegin| command has a |*|-variant, which causes the box to be
% typeset regardless of the current mode setting.
%
% \DescribeMacro\newslowboxenv
-% There's an environment for building slow box environments. Say
-% \syntax{"\\newslowboxenv{"<env-name>"}"\* "["<n-args>"]"\*
+% Plumbing all of this together is rather tedious, so there's also a
+% command for building slow box environments. Say
+% \syntax{"\\newslowboxenv{"<env-name>"}"\* "["<n-args>"]"\*"["<default>"]"\*
% "{"<before-text>"}"\* "{"<start-text>"}"\* "{"<end-text>"}"\*
% "{"<after-text>"}"}. This creates a new environment (just like with
-% |\newenvironment|). The contents are put in a slow box with \<start-text>
-% on the front and \<end-text> on the end. Before the box is begun,
-% \<before-text> is performed, and \<after-text> is done afterwards. The
-% environments so created have \env{$*$}-variants which ignore the current
-% mode, just like \env{slowbox$*$}. They also gather an additional \<tag>
-% argument, which you don't have to bother with.
+% |\newenvironment|, taking \<n-args> arguments, maybe with the first one
+% optional and defaulting to \<default>). The contents are put in a slow box
+% with \<start-text> on the front and \<end-text> on the end. Before the box
+% is begun, \<before-text> is performed, and \<after-text> is done
+% afterwards. The environments so created have \env{$*$}-variants which
+% ignore the current mode, just like \env{slowbox$*$}. They also gather an
+% additional \<tag> argument, which you don't have to bother with.
%
% \DescribeMacro\doslowbox
% Finally, for commands, there's \syntax{"\\doslowbox{"<tag>"}"\*
\begingroup%
\def\sb@end##1{\endgroup}%
\let\sb@ignore\ignore%
- \expandafter\sb@hidden\csname sb@box:#1\endcsname{#1}%
+ \expandafter\sb@hidden\csname sb@box:#1\endcsname{#1}{#2}%
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\sb@hidden}
% We're given the control token and the tag name. If the control sequence is
-% like |\relax| then |\csname| must have invented it and we just have to make
-% something up. Otherwise we put the right stuff in a frame. Don't forget
-% to write out the box dimensions to the new aux file!
+% like |\relax| then |\csname| must have invented it and we should typeset it
+% anyway in order to measure it. Otherwise we put the right stuff in a
+% frame. Don't forget to write out the box dimensions to the new aux file!
% \begin{macrocode}
-\def\sb@hidden#1#2{%
- \ifx#1\relax\fbox{Unknown slow box \texttt{#2}!}%
- \else\edef\next@{\noexpand\sb@hidden@i#1{#2}}\expandafter\next@\fi%
+\def\sb@hidden#1#2#3{%
+ \ifx#1\relax\def\next@{\endgroup\sb@begin@show{#2}{#3}}%
+ \else\edef\next@{\noexpand\sb@hidden@i#1{#2}}\fi%
+ \next@%
}
\def\sb@hidden@i#1#2#3#4{%
\frameonly{#1}{#2}{#3}{Omitted \texttt{#4}}%