%
% (c) 2003 Mark Wooding
%
-%----- Revision history -----------------------------------------------------
-%
-% $Log: slowbox.dtx,v $
-% Revision 1.2 2003/09/06 13:08:16 mdw
-% Missing \leavevmode in \frameonly makes life very confusing if you're
-% too clever.
-%
-% Revision 1.1 2003/09/05 16:09:56 mdw
-% New feature\!
-%
-%
% \end{meta-comment}
%
% \begin{meta-comment} <general public licence>
%% it under the terms of the GNU General Public License as published by
%% the Free Software Foundation; either version 2 of the License, or
%% (at your option) any later version.
-%%
+%%
%% This program is distributed in the hope that it will be useful,
%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
%% GNU General Public License for more details.
-%%
+%%
%% You should have received a copy of the GNU General Public License
%% along with this program; if not, write to the Free Software Foundation,
%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
%<+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>
% mode, everything happens normally; in \opt{hide} mode, slow boxes are
% replaced by frames. In order for the package to know the sizes of all of
% your boxes, you must first run through once in \opt{show} mode.
-% Thereafter, all should be well.
+% Thereafter, all should be well.
%
% \DescribeEnv{slowbox}
% In \opt{show} mode, the \env{slowbox} environment typesets its contents in
% \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}}%
- \immediate\write\@auxout{\string\sb@def{#4}{#1}{#2}{#3}}%
+ \immediate\write\@auxout{\string\sb@def{#4}{#1}{#2}{#3}}%
}
% \end{macrocode}
% \end{macro}
}%
\dimen@#3\advance\dimen@-\dp\z@%
\setbox\z@\hbox{\lower\dimen@\box\z@}%
- \leavevmode\box\z@%
+ \leavevmode\box\z@%
}
% \end{macrocode}
% \end{macro}
% \end{macrocode}
%
% \Finale
-\endinput
\ No newline at end of file
+\endinput