everyhook (4feb11)

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

1 files changed, 170 insertions, 71 deletions

diff --git a/Master/texmf-dist/source/latex/everyhook/everyhook.dtx b/Master/texmf-dist/source/latex/everyhook/everyhook.dtx
index bc02d75ff2a..9567ec290bb 100644
--- a/Master/texmf-dist/source/latex/everyhook/everyhook.dtx
+++ b/Master/texmf-dist/source/latex/everyhook/everyhook.dtx
@@ -1,7 +1,7 @@
 % \iffalse The license starting three lines down applies to this file
 %<*batchfile>
-{\catcode`\^^M13 \catcode`@11 \gdef\eh@preamble{
-Copyright (C) 2010 by Stephen Checkoway
+\begingroup\input docstrip \preamble
+Copyright (C) 2010, 2011 by Stephen Checkoway
 
 This file may be distributed and/or modified under the
 conditions of the LaTeX Project Public License, either
@@ -19,28 +19,13 @@ The Current Maintainer of this work is Stephen Checkoway.
 
 This work consists of everyhook.dtx and the derived file
 everyhook.sty.
-}}
-%</batchfile>
-%
-%<*package>
-\NeedsTeXFormat{LaTeX2e}[1999/12/01]
-\RequirePackage{svn-prov}
-\ProvidesPackageSVN
-	{$Id: everyhook.dtx 9 2010-09-27 07:39:15Z steve $}
-	[v1.0 \revinfo\ Hooks for low level TeX everyX primitives.]
-%</package>
-%<*batchfile>
-\begingroup
-\input docstrip
+\endpreamble
 \keepsilent
 \usedir{tex/latex/everyhook}
-\expandafter\preamble\eh@preamble
-\endpreamble
 \askforoverwritefalse
-\generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}}
+\generate{\file{\jobname.sty}{\from{\jobname.dtx}{}}}
 \endgroup
-%</batchfile>
-%<*driver>
+
 \documentclass{ltxdoc}
 \usepackage{fixltx2e}
 \usepackage{etoolbox}
@@ -50,7 +35,7 @@ everyhook.sty.
 \usepackage[T1]{fontenc}
 \usepackage{microtype}
 \usepackage[margin=1.5in]{geometry}
-\usepackage{everyhook}
+\usepackage[excludeor]{everyhook}
 \usepackage{enumitem}
 \usepackage[pdfborder={0 0 0}]{hyperref}
 \usepackage{ifpdf}
@@ -84,11 +69,6 @@ everyhook.sty.
   Grave accent  \`     Left brace    \{     Vertical bar  \|
   Right brace   \}     Tilde     \~}
 
-\DoNotIndex{\csdef,\cslet,\csname,\csuse,\def,\endcsname,\endinput,
-\every,\expandafter,\gdef,\global,\ifcsdef,\ifcsempty,\ifdefequal,
-\letcs,\newrobustcmd,\newtoks,\PackageError,\protect,\RequirePackage,
-\space,\the,\undef}
-
 \EnableCrossrefs
 \CodelineIndex
 \RecordChanges
@@ -104,6 +84,24 @@ moretexcs={paragraph,RequirePackage},xleftmargin=\parindent}
 \renewcommand*\arg[1]{\textsf{\{#1\}}}
 \makeatletter
 \renewcommand*\meta@font@select{\normalfont\itshape}
+% \DescribeOption taken from trivfloat.dtx
+\newcommand*{\DescribeOption}{%
+  \leavevmode
+  \@bsphack
+  \begingroup
+    \MakePrivateLetters
+    \Describe@Option
+}
+\newcommand*{\Describe@Option}[1]{%
+    \endgroup
+  \marginpar{%
+    \raggedleft
+    \PrintDescribeEnv{#1}%
+  }%
+  \@esphack
+  \ignorespaces
+}
+\makeatother
 \begin{document}
 \maketitle
 
@@ -189,16 +187,23 @@ of the list of tokens to appear before those in \cs{everyhbox} whereas
 tokens to appear after those in \cs{everyhbox}.
 
 \section{Usage}
-The \textsf{\jobname} package has no options and so should be loaded
-using
+The \textsf{\jobname} package has one (rather experimental) option,
+|excludeor| and is loaded using
 \begin{lstlisting}
-\usepackage{everyhook}
+\usepackage[excludeor]{everyhook}
 \end{lstlisting}
 or
 \begin{lstlisting}
-\RequirePackage{everyhook}
+\RequirePackage[excludeor]{everyhook}
 \end{lstlisting}
-as required.
+as required where the option is, of course, optional.
+
+\subsection{Options}
+\DescribeOption{excludeor}
+Some of the hooks described below can cause unwanted behavior when
+active during the execution of \LaTeX's output routine. The
+experimental |excludeor| option saves and clears the hooks at
+the beginning of the output routine and restores them at the end.
 
 \subsection{Manipulating hooks}
 There are 12 hooks, a pre and post hook for each of the six token
@@ -301,8 +306,11 @@ list of pitfalls to watch out for when using \textsf{\jobname}.
 \item When using the |par| hooks, be aware that TeX will insert a box
 with the width of \cs{parindent} before the tokens in the pre hook.
 One way to handle this is to propogate the box to the right.
-\item It is probably not a good idea to use the |hbox| and |vbox|
-hooks at any place where TeX's output routine is likely to run.
+\item It is probably not a good idea to use the |hbox|, |vbox|, and
+|par| hooks at any place where TeX's output routine is likely to run.
+The |excludeor| option \emph{should} help with this, but it might
+cause problems with other packages that also modify the output
+routine.
 \item \LaTeX's kernel takes control of the \cs{everymath} and
 \cs{everydisplay} token parameters to make its own adjustments in much
 the same way this package does. The \textsf{trace} package uses the
@@ -314,46 +322,67 @@ in math mode.
 appears in a \cs{setbox} will have the \cs{afterassignment} token
 inserted \emph{before} the hooks. This is no different from TeX's
 normal behavior with \cs{afterassignment} and
-\cs{everyhbox}/\cs{everyvbox}.
+\cs{everyhbox}/\cs{everyvbox}, but can be surprising.
 \item I'm sure there are others.
 \end{enumerate}
 
+\StopEventually{
+	\typeout{**************************************************}
+	\typeout{*}
+	\typeout{* To finish the installation, you have to move the}
+	\typeout{* following file into a directory searched by TeX:}
+	\typeout{*}
+	\typeout{* \space\space \jobname.sty}
+	\typeout{*}
+	\typeout{* Documentation is in \jobname.\ifpdf pdf\else dvi\fi.}
+	\typeout{*}
+	\typeout{* Happy TeXing!}
+	\typeout{**************************************************}
+	\end{document}
+}
+
+\clearpage
 \DocInput{\jobname.dtx}
+\clearpage
+\phantomsection
+\addcontentsline{toc}{section}{Change History}%
+\PrintChanges
+\phantomsection
+\addcontentsline{toc}{section}{Index}%
+\PrintIndex
 \Finale
-
-\typeout{**************************************************}
-\typeout{*}
-\typeout{* To finish the installation, you have to move the}
-\typeout{* following file into a directory searched by TeX:}
-\typeout{*}
-\typeout{* \space\space \jobname.sty}
-\typeout{*}
-\typeout{* Documentation is in \jobname.\ifpdf pdf\else dvi\fi.}
-\typeout{*}
-\typeout{* Happy TeXing!}
-\typeout{**************************************************}
-\end{document}
-%</driver>
+%</batchfile>
 % \fi
+% \DoNotIndex{\csdef,\cslet,\csname,\csuse,\def,\endcsname,\endinput,
+% \every,\expandafter,\gdef,\global,\ifcsdef,\ifcsempty,\ifdefequal,
+% \letcs,\newrobustcmd,\newtoks,\PackageError,\protect,\RequirePackage,
+% \space,\the,\undef}
 %
-% \StopEventually{%
-% 	\clearpage
-% 	\phantomsection
-% 	\addcontentsline{toc}{section}{Change History}
-% 	\PrintChanges
-% 	\phantomsection
-% 	\addcontentsline{toc}{section}{Index}
-% 	\PrintIndex
-% }
-% \clearpage
 % \section{Implementation}
-% The package begins with the usual package identification (not shown)
-% and then it loads the \textsf{etoolbox} package. This is not
-% strictly necessary, but it does simplify some stuff and provides
-% handy macros for dealing with control sequence names.
+% The package begins with the usual package identification and then it
+% declares the one option |excludeor| and finally it loads the
+% \textsf{etoolbox} package. This package is not strictly necessary,
+% but it does simplify some stuff and provides handy macros for
+% dealing with control sequence names.
 %
 % \changes{v1.0}{2010/09/26}{Initial version}
+% \changes{v1.1}{2011/02/03}{Add excludeor}
 %    \begin{macrocode}
+\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+\RequirePackage{svn-prov}
+\ProvidesPackageSVN
+	{$Id: everyhook.dtx 10 2011-02-04 06:43:36Z steve $}
+	[v1.1 \revinfo\ Hooks for low level TeX everyX primitives.]
+\DeclareOption{excludeor}{%
+	\AtBeginDocument{%
+		\output\expandafter{%
+			\expandafter\eh@saveclearallhooks
+			\the\output
+			\eh@restoreallhooks
+		}%
+	}%
+}
+\ProcessOptions\relax
 \RequirePackage{etoolbox}
 %    \end{macrocode}
 %
@@ -517,17 +546,40 @@ normal behavior with \cs{afterassignment} and
 % \end{macro}
 % \end{macro}
 % \end{macro}
+% \begin{macro}{\eh@clearhook}
+% Internal hook reset.
+%    \begin{macrocode}
+\def\eh@clearhook#1{%
+	\global\csdef{eh@#1}{}%
+}
+%    \end{macrocode}
+% \end{macro}
 % \begin{macro}{\ClearPreHook}
 % \begin{macro}{\ClearPostHook}
 % Reset the pre/post hook to empty.
 %    \begin{macrocode}
 \newrobustcmd\ClearPreHook[1]{%
 	\eh@checkhook{#1}\ClearPreHook
-	\global\csdef{eh@pre#1}{}%
+	\eh@clearhook{pre#1}%
 }
 \newrobustcmd\ClearPostHook[1]{%
 	\eh@checkhook{#1}\ClearPostHook
-	\global\csdef{eh@post#1}{}%
+	\eh@clearhook{post#1}%
+}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\eh@savehook}
+% \begin{macro}{\eh@restorehook}
+% Internal macros to \cs{let} the hook to the supplied control
+% sequence to save. Perform the \cs{let} in the other direction to
+% restore.
+%    \begin{macrocode}
+\def\eh@savehook#1#2{%
+	\letcs#2{eh@#1}%
+}
+\def\eh@restorehook#1#2{%
+	\global\cslet{eh@#1}#2%
 }
 %    \end{macrocode}
 % \end{macro}
@@ -536,29 +588,76 @@ normal behavior with \cs{afterassignment} and
 % \begin{macro}{\SavePostHook}
 % \begin{macro}{\RestorePreHook}
 % \begin{macro}{\RestorePostHook}
-% \cs{let} the hook to the supplied control sequence to save. Perform
-% the \cs{let} in the other direction to restore.
+% User macros to save and restore hooks.
 %    \begin{macrocode}
 \newrobustcmd\SavePreHook[2]{%
 	\eh@checkhook{#1}\SavePreHook
-	\letcs#2{eh@pre#1}%
+	\eh@savehook{pre#1}#2%
 }
 \newrobustcmd\SavePostHook[2]{%
 	\eh@checkhook{#1}\SavePostHook
-	\letcs#2{eh@post#1}%
+	\eh@savehook{post#1}#2%
 }
 \newrobustcmd\RestorePreHook[2]{%
 	\eh@checkhook{#1}\RestorePreHook
-	\global\cslet{eh@pre#1}#2%
+	\eh@restorehook{pre#1}#2%
 }
 \newrobustcmd\RestorePostHook[2]{%
 	\eh@checkhook{#1}\RestorePostHook
-	\global\cslet{eh@post#1}#2%
+	\eh@restorehook{post#1}#2%
 }
-\endinput
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
 % \end{macro}
 % \end{macro}
+% \begin{macro}{\eh@saveclearallhooks}
+% \begin{macro}{\eh@restoreallhooks}
+% Internal macros to save and clear (resp.\ restore) all hooks at the
+% start (resp.\ end) of the output routine.
+%    \begin{macrocode}
+\def\eh@saveclearallhooks{%
+	\global\eh@savehook{prepar}\eh@or@prepar
+	\global\eh@savehook{postpar}\eh@or@postpar
+	\global\eh@savehook{premath}\eh@or@premath
+	\global\eh@savehook{postmath}\eh@or@postmath
+	\global\eh@savehook{predisplay}\eh@or@predisplay
+	\global\eh@savehook{postdisplay}\eh@or@postdisplay
+	\global\eh@savehook{prehbox}\eh@or@prehbox
+	\global\eh@savehook{posthbox}\eh@or@posthbox
+	\global\eh@savehook{prevbox}\eh@or@prevbox
+	\global\eh@savehook{postvbox}\eh@or@postvbox
+	\global\eh@savehook{precr}\eh@or@precr
+	\global\eh@savehook{postcr}\eh@or@postcr
+	\eh@clearhook{prepar}%
+	\eh@clearhook{postpar}%
+	\eh@clearhook{premath}%
+	\eh@clearhook{postmath}%
+	\eh@clearhook{predisplay}%
+	\eh@clearhook{postdisplay}%
+	\eh@clearhook{prehbox}%
+	\eh@clearhook{posthbox}%
+	\eh@clearhook{prevbox}%
+	\eh@clearhook{postvbox}%
+	\eh@clearhook{precr}%
+	\eh@clearhook{postcr}%
+}
+\def\eh@restoreallhooks{%
+	\eh@restorehook{prepar}\eh@or@prepar
+	\eh@restorehook{postpar}\eh@or@postpar
+	\eh@restorehook{premath}\eh@or@premath
+	\eh@restorehook{postmath}\eh@or@postmath
+	\eh@restorehook{predisplay}\eh@or@predisplay
+	\eh@restorehook{postdisplay}\eh@or@postdisplay
+	\eh@restorehook{prehbox}\eh@or@prehbox
+	\eh@restorehook{posthbox}\eh@or@posthbox
+	\eh@restorehook{prevbox}\eh@or@prevbox
+	\eh@restorehook{postvbox}\eh@or@postvbox
+	\eh@restorehook{precr}\eh@or@precr
+	\eh@restorehook{postcr}\eh@or@postcr
+}
+\endinput
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
 \endinput