X-Git-Url: https://git.distorted.org.uk/~mdw/mdwtools/blobdiff_plain/c8ea265ae80303acb1d20a8473294fc96c28e1ff..0fb4766da19521ffc4b25ab564ce36e8c8df5f4b:/slowbox.dtx

diff --git a/slowbox.dtx b/slowbox.dtx
index ae32bbf..baa04ba 100644
--- a/slowbox.dtx
+++ b/slowbox.dtx
@@ -1,6 +1,6 @@
 % \begin{meta-comment}
 %
-% $Id: slowbox.dtx,v 1.2 2003/09/06 13:08:16 mdw Exp $
+% slowbox.dtx
 %
 % Cop-out for slow things
 %
@@ -17,12 +17,12 @@
 %% 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.
@@ -34,7 +34,7 @@
 %<+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
@@ -56,9 +56,9 @@
 %
 %<*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>
@@ -83,7 +83,7 @@
 % 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
@@ -112,34 +112,57 @@
 % \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>"}"\*
@@ -265,24 +288,25 @@
   \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}
@@ -315,7 +339,7 @@
   }%
   \dimen@#3\advance\dimen@-\dp\z@%
   \setbox\z@\hbox{\lower\dimen@\box\z@}%
-  \leavevmode\box\z@%  
+  \leavevmode\box\z@%
 }
 %    \end{macrocode}
 % \end{macro}
@@ -372,4 +396,4 @@
 %    \end{macrocode}
 %
 % \Finale
-\endinput
\ No newline at end of file
+\endinput
