verbatimbox (25apr13)

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

5 files changed, 456 insertions, 90 deletions

diff --git a/Master/texmf-dist/doc/latex/verbatimbox/README b/Master/texmf-dist/doc/latex/verbatimbox/README
index 55ee4311328..9d5dfe0c6ab 100644
--- a/Master/texmf-dist/doc/latex/verbatimbox/README
+++ b/Master/texmf-dist/doc/latex/verbatimbox/README
@@ -1,24 +1,25 @@
 The style file verbatimbox has been created for the report writer's
 convenience.
 
-Do you need to include blocks of verbatim text inside figures or
-tables?  The verbatim environment is not compatible with some of these
-other environments.  But now, the verbbox environment allows you to
-input verbatim text and store it in a LaTeX box.  That box then becomes
-generally usable in all other LaTeX environments, and can be simply
-recalled.  
+Do you need to include blocks of verbatim text inside figures, tables or
+footnotes?  The verbatim environment is not compatible with some of
+these other environments.  But now, the verbbox environment allows you
+to input verbatim text and store it in a LaTeX box.  That box then
+becomes generally usable in all other LaTeX environments, and can be
+simply recalled.
 
 This style therefore allows for a greater use of the verbatim
 environment within other LaTeX constructs where verbatim was previously
 inaccessible.
 
 Input to the verbatim box can either be as text typed into the verbbox
-environment, or else as the contents of a file, provided as an argument
-to the \verbfilebox command.  In either case, an optional argument may
-be provided to modify the text appearance, for example, by changing the
-font size of the verbatim text placed into the box.
+or myverbbox environments, or else as the contents of a file, provided
+as an argument to the \verbfilebox command.  In either case, an optional
+argument may be provided to modify the text appearance, for example, by
+changing the font size of the verbatim text placed into the box.
 
-Sorry I don't have a separate documentation file, but it's very simply
-documented in the style file itself and in the verbatimbox_example.
+The \addvbuffer command, while supporting this package, also provides a
+flexible way to add vertical buffer space above and below most LaTeX
+objects, which can be handy in a variety of applications.
 
 						-Steven Segletes
diff --git a/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox.pdf b/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox.pdf
new file mode 100644
index 00000000000..5798d11a436
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox.pdf
diff --git a/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox.tex b/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox.tex
new file mode 100644
index 00000000000..03e5783ebee
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox.tex
@@ -0,0 +1,443 @@
+\documentclass{article}
+\def\version{3.0}
+% Copyright 2013 Steven B. Segletes
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+%   http://www.latex-project.org/lppl.txt
+% and version 1.3c or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The Current Maintainer of this work is Steven B. Segletes.
+% Revisions:
+% 2.01 -Added LPPL License info to package
+% 3.0  -Added myverbbox environment
+%      -Corrected problem when no optional arguments are passed to
+%         verbbox environment
+%      -Added optional arguments to \addvbuffer
+%
+\parskip 1em
+\parindent 0em
+\usepackage{verbatimbox}
+\usepackage{etoolbox}
+\makeatletter
+\preto{\@verbatim}{\topsep=0pt \partopsep=0pt }
+\makeatother
+
+\newcommand\rl{\rule{1em}{0in}}
+\def\vbx{\textsf{verbatimbox}}
+\let\vb\verb
+\def\bs{{\ttfamily\char'134}}
+\reversemarginpar
+\marginparwidth 1.5in
+\newcommand\margcmd[1]{\marginpar{\hfill\ttfamily\char'134#1}}
+\newcommand\margenv[1]{\marginpar{\hfill\ttfamily#1}}
+
+\begin{document}
+\begin{myverbbox}{\vrbox}verbbox\end{myverbbox}
+\begin{myverbbox}{\myvrbox}myverbbox\end{myverbbox}
+\begin{myverbbox}{\ovrbox}origverbbox\end{myverbbox}
+\begin{myverbbox}{\vbenv}\begin{verbbox}\end{myverbbox}
+\begin{myverbbox}{\evbenv}\end{verbbox}\end{myverbbox}
+\begin{myverbbox}{\myvb}\begin{myverbbox}\end{myverbbox}
+\begin{myverbbox}{\emyvb}end{myverbbox}\end{myverbbox}
+\begin{myverbbox}{\vbfbox}\verbfilebox\end{myverbbox}
+\begin{myverbbox}{\tvb}\theverbbox\end{myverbbox}
+\begin{myverbbox}{\avb}\addvbuffer\end{myverbbox}
+\begin{myverbbox}{\bts}\boxtopsep\end{myverbbox}
+\begin{myverbbox}{\bbs}\boxbottomsep\end{myverbbox}
+\begin{myverbbox}{\eq} = \end{myverbbox}
+\begin{myverbbox}{\vln}VerbboxLineNo\end{myverbbox}
+\begin{myverbbox}{\lb}[\end{myverbbox}
+\begin{myverbbox}{\rb}]\end{myverbbox}
+\begin{myverbbox}{\lbr}{\end{myverbbox}
+\begin{myverbbox}{\rbr}}\end{myverbbox}
+\begin{myverbbox}[\footnotesize]{\fsvrbox}verbbox\end{myverbbox}
+\begin{myverbbox}[\footnotesize]{\fbx}\fbox\end{myverbbox}
+\begin{myverbbox}[\footnotesize]{\fbs}\fboxsep\end{myverbbox}
+
+\begin{center}
+\LARGE The {\vbx} Package\\
+\rule{0em}{.7em}\small
+Routines for placing verbatim text into boxes, useful in places where
+the verbatim environment is inaccessible.  Secondarily, for adding
+vertical buffer around an object.\\
+\rule{0em}{2.7em}\large Steven B. Segletes\\
+steven.b.segletes.civ@mail.mil\\
+\rule{0em}{1.7em}\today\\
+v\version
+\end{center}
+
+\section{Description and Commands}
+
+The {\vbx} package allows verbatim material to be placed into \LaTeX{}
+boxes, for later recall.  This function is useful in several situations,
+primarily in places where the verbatim environment is otherwise
+inaccessible (for example, in the midst of a tabular environment).  It
+is also useful if a given verbatim text needs to be recalled multiple
+times within a document.
+
+While there is application for its use within the {\vbx} application,
+this package also offers an independent command for conveniently
+providing vertical buffer space above and below an object.
+
+The commands provided by this package are given as follows:\\\itshape
+\rl%
+\addvbuffer[1ex 1ex]%
+{\parbox{4in}{%
+  \vbenv\lb pre-commands\rb\ldots\evbenv\\
+  \myvb\lb pre-commands\rb\lbr token\rbr\ldots\bs\emyvb\\
+  \vbfbox\lb pre-commands\rb\lbr filename\rbr\\
+  \tvb\lb\texttt{\upshape t}\rb\\
+  \bts\eq length\\
+  \bbs\eq length\\
+  \avb\lb length \lb below length\rb\rb\lbr object\rbr
+}}\\\upshape 
+In addition, there is a counter, \vln\margenv{\vln}, which contains the
+current verbatim line number being processed.  It's use as part of
+the optional pre-commands to \vrbox, \myvrbox, or {\vbfbox} (in the form
+  of\\ \rl\verb|[\arabic{VerbboxLineNo}:]|\\
+will cause the lines of the environment to be numbered.
+
+\subsection{The \texttt{verbbox} Environment}
+
+The {\vrbox} environment places the content of the environment into a
+verbatim box.  The box is not printed when the environment is closed.
+However, the box can be later recalled (even in a verbatim-restricted
+environment) by way of the command \tvb\margenv{\tvb}.  Being placed
+into a box, it is important to remember that a \LaTeX{} box cannot span
+across page boundaries.
+
+The width of the box into which the contents of the environment are
+placed is the width of the longest line in your environment, rather than
+the width of the page.  This feature can be useful if the box is being
+recalled inline with other text,
+\begin{verbbox}[\scriptsize\scshape]
+as in This Example
+\end{verbbox}
+\theverbbox, shown immediately to the left.
+
+The environment has one optional argument, which can contain commands
+that will be executed before each line of verbatim text is output.
+Thus, they can include font size, series, shape, or family changes
+affecting the appearance of the verbatim text in the box.  They can also
+include printed matter, like a bullet
+
+\begin{verbatim}
+ \begin{verbbox}[\(\bullet\)\hspace{1ex}]
+ first line
+ second line
+ third line
+ \end{verbbox}
+ \theverbbox
+\end{verbatim}
+
+\begin{verbbox}[\(\bullet\)\hspace{1ex}]
+first line
+second line
+third line
+\end{verbbox}
+\rl\theverbbox
+
+or, as mentioned earlier, the lines can be numbered:
+
+\begin{verbatim}
+ \begin{verbbox}[\arabic{VerbboxLineNo}:\hspace{1ex}]
+ first line
+ second line
+ third line
+ \end{verbbox}
+ \theverbbox
+\end{verbatim}
+
+\begin{verbbox}[\arabic{VerbboxLineNo}:\hspace{1ex}]
+first line
+second line
+third line
+\end{verbbox}
+\rl\theverbbox
+
+\subsection{The \texttt{myverbbox} Environment}
+
+With the {\vrbox} environment, one is limited to one verbatimbox at a
+time, since each new environment invocation overwrites the prior box.  A
+new environment, {\myvrbox}, has therefore been introduced with version
+3.0 of the package.  It is very similar to \vrbox, except that it is not
+recalled with the use of \tvb.  In addition to the optional argument
+which functions like that in \vrbox, {\myvrbox} must be supplied a
+mandatory argument which is the command name that will recall the box
+contents.
+
+This environment was created for the situation when there is a need to
+recall more than one verbatimbox in a given restricted environment.
+Here is an example where two verbatimboxes must be inserted into the
+tabular environment (where verbatim is prohibited):
+
+\begin{verbatim}
+ \begin{myverbbox}{\vtheta}\theta\end{myverbbox}
+ \begin{myverbbox}{\valpha}\alpha\end{myverbbox}
+ \begin{tabular}{|c|c|} \hline
+ \valpha & $\alpha$ \\  \hline
+ \vtheta & $\theta$ \\  \hline
+ \end{tabular}
+\end{verbatim}
+
+\begin{myverbbox}{\vtheta}\theta\end{myverbbox}
+\begin{myverbbox}{\valpha}\alpha\end{myverbbox}
+\rl\begin{tabular}{|c|c|} \hline
+\valpha & $\alpha$ \\  \hline
+\vtheta & $\theta$ \\  \hline
+\end{tabular}
+
+In this example the the command \verb|\valpha| will recall a verbatimbox
+with the verbatim content \valpha.  Likewise for \verb|\vtheta|.
+
+\subsection{The \bs\texttt{verbfilebox} Command}
+
+The {\vbfbox} command is comparable to the aforementioned environments,
+except that it is a command which takes the contents of a file specified
+in the mandatory argument and places it in a verbatimbox.  Like
+\vrbox, the boxed content can be recalled with an invocation of \tvb.
+The optional argument contains pre-commands and functions in the same
+manner as described for the {\vrbox} environment.
+
+\subsection{The \bs\texttt{theverbbox} Command}
+
+As already mentioned in the prior sections, the {\tvb} command is issued
+to recall the contents of a box created by either the {\vrbox}
+environment or the {\vbfbox} command.  This command can be issued in
+places where the verbatim environment is otherwise inaccessible, such as
+in the tabular environment or inside footnotes.
+
+There is a \verb|[t]| option to this command, which preconditions {\tvb}
+for environments where it will be framed, by adding 3pt (by default) of
+space above the boxed content, since the top of the box is otherwise
+clipped to the verbatim contents.  So in the following example, the left
+invocation of {\tvb} is done without the \verb|[t]| option, whereas for
+the right invocation, it is done with the \verb|[t]| option.  As you can
+see, the framing on the right-hand box is more symmetric.
+
+\rl\begin{tabular}{|c|}
+\hline
+\theverbbox\\
+\hline
+\end{tabular}
+%
+\rl\begin{tabular}{|c|}
+\hline
+\theverbbox[t]\\
+\hline
+\end{tabular}
+
+If one wishes\margenv{\bts} a different vertical-buffer preconditioning
+of {\tvb}, one can either reset the lengths {\bts} and
+{\bbs}\margenv{\bbs} or else one can use the {\avb}\margenv{\avb}
+command described below.
+
+\subsection{The \bs\texttt{addvbuffer} Command}
+
+The prior section already showed how when a verbatimbox is framed, it
+may need some buffer space added above the box which is otherwise (by
+design) clipped to the verbatim content.  While the \verb|[t]| option
+will work for \tvb, that option does not exist for any of the boxes
+created through the {\myvrbox} environment.  Furthermore, the user may
+sometimes wish to add an arbitrary vertical buffer above and below an
+object, without changing the underlying {\bts} and {\bbs} lengths
+associated with the \verb|[t]| option of \tvb.
+
+The {\avb} command is made to do this, and is useful in many situations
+inside and outside of verbatimbox manipulations.  The mandatory argument
+to the command is the object over and under which to place vertical
+buffer.  As of version 3.0 of this package, the command comes with an
+optional argument to specify how much buffer to use.  If the optional
+argument is omitted, the buffer will be the amounts specified by the
+{\bts} and {\bbs} lengths.
+
+The optional argument can take two forms.  If the optional argument
+comprises a single length, that length is symmetrically added above and
+below the object.  So, for example,
+  \verb|\fbox{\addvbuffer[5pt]{\theverbbox}}|
+will produce
+
+\fbox{\addvbuffer[5pt]{\theverbbox}}
+
+On the other hand, the optional argument may comprise two lengths, in
+which case the first length is added above the object and the second is
+added below the object.  Thus, 
+\verb|\fbox{\addvbuffer[15pt 5pt]{\theverbbox}}|
+will produce
+
+\fbox{\addvbuffer[15pt 5pt]{\theverbbox}}
+
+But {\avb} need not only be used for \tvb.  It can be used on other
+objects, for example a \verb|\parbox|
+
+\fbox{\addvbuffer[15pt 5pt]{\parbox{1in}{This is a test of the
+emergency broadcast system}}}
+
+or even on just plain text \verb|\fbox{\addvbuffer[15pt 5pt]{A test}}|:
+
+\fbox{\addvbuffer[15pt 5pt]{A test}}
+
+It can even be used to remove vertical space from an objects size, by
+adding negative buffer \verb|\fbox{\addvbuffer[-5pt -5pt]{A test}}|:
+
+\fbox{\addvbuffer[-5pt -5pt]{A test}}
+
+This ability to work on a variety of objects makes {\avb} a powerful
+command in many applications.
+
+
+\section{Quirks}\fboxsep=0pt
+
+The use of a single optional argument for the {\vrbox} environment has
+caused problems in the past, if the first item in the environment was a
+command, rather than text.  This problem has been resolved as of version
+3.0 of the package (for backward compatibility, we have kept the earlier
+incarnation of {\vrbox}, now renamed as \ovrbox).  However, a few minor
+quirks remain even with the new version (which, incidentally, can be
+avoided by using the {\myvrbox} environment).  Note that the commands of
+this package do not enclose the created boxes in frames.\footnote{In all
+these examples, the {\fsvrbox} material is explicitly placed in an \fbx,
+to expressedly show the limits of the boxed material.  Throughout this
+section, {\fbs} has been set to 0pt.} Thus, frames shown in these
+examples are for illustrative purposes only.
+
+The primary quirk of {\vrbox} is that its optional argument does not
+take effect until the second line (on the line following the environment
+invocation), so that
+
+\begin{verbatim}
+ \begin{verbbox}[\LARGE]first line
+ second line
+ \end{verbbox}
+ \fbox{\theverbbox}
+\end{verbatim}
+
+would look like:\\
+\begin{verbbox}[\LARGE]first line
+second line
+\end{verbbox}
+\addvbuffer[3pt 0pt]{\fbox{\theverbbox}}
+
+The solution, in the presence of an optional argument, is to begin the
+first line of the environment contents on the following line.  Thus
+
+\begin{verbatim}
+ \begin{verbbox}[\LARGE]
+ first line
+ second line
+ \end{verbbox}
+ \fbox{\theverbbox}
+\end{verbatim}
+
+will yield the expected result:\\
+\begin{verbbox}[\LARGE]
+first line
+second line
+\end{verbbox}
+\addvbuffer[3pt 0pt]{\fbox{\theverbbox}}
+
+No such requirement is necessary if there are no optional arguments.
+So, for example,
+\verb|\begin{verbbox}Hello World\end{verbbox}|
+\begin{verbbox}Hello World\end{verbbox} 
+will produce, upon issue of \tvb, the box ``\theverbbox.''  As with all
+verbatim environments, the {\evbenv} must be followed by a linebreak, or
+the subsequent text on that line will be lost.
+
+The {\myvrbox} environment does not suffer the above quirk, so that\\
+\verb|\begin{myverbbox}[\scriptsize]{\mybox}Hello World\end{myverbbox}|\\
+gives, \begin{myverbbox}[\scriptsize]{\mybox}Hello World\end{myverbbox}
+upon issue of \verb|\mybox|, the expected result: \mybox.
+
+The optional argument of {\vrbox} may contain both printing or
+nonprinting material.  The printing material will appear (as \LaTeX{},
+not as \verb|verbatim|) at the beginning of every line of the \vrbox.
+However, it is recommended to place nonprinting material at the lead of
+the optional argument, or the box width may be improperly set, as in
+this following example:
+
+\begin{verbatim}
+ \begin{verbbox}[\rmfamily\textsc{Debug}:\footnotesize]
+ first line
+ second line
+ \end{verbbox}
+ \fbox{\theverbbox}
+\end{verbatim}
+\begin{verbbox}[\rmfamily\textsc{Debug}:\footnotesize]
+first line
+second line
+\end{verbbox}
+\fbox{\theverbbox}
+
+Note how the box does not extend to the end of the text line.  When
+placing printing commands before non-printing commands that change the
+fontsize, the reverse is also possible, where the box is set too large
+for the actual text.
+
+The {\myvrbox} environment behaves identically in this regard.  Below we
+show the prior example, this time created in the {\myvrbox} environment,
+except that the non-printing optional material has been placed before
+the printing optional material, so that the box size is correctly
+interpreted:
+
+\begin{myverbbox}[\rmfamily\footnotesize\textsc{Debug}:]{\mybox}
+first line
+second line
+\end{myverbbox}
+\fbox{\mybox}
+
+There are differences, however, in how {\vrbox} and {\myvrbox} process
+the optional argument, which relate to overcoming the problems
+associated with a single optional argument for the {\vrbox} environment.
+In particular, while the {\myvrbox} optional argument should behave as
+one would otherwise expect, the optional argument of {\vrbox} will
+ignore spaces (which can be overcome with \verb|\hspace{}|) and will
+choke on the dollar symbol (\verb|$|) as a way to enter and exit math 
+mode (which can be overcome by using the \verb|\(|\ \verb|\)| syntax 
+instead).  Thus, an optional argument like\\
+  \rl\verb|[\arabic{VerbboxLineNo}$\cdot$ ]|\\
+which works fine for \myvrbox,  would need to appear as\\
+  \rl\verb|[\arabic{VerbboxLineNo}\(\cdot\)\hspace{1ex}]|\\
+in the {\vrbox} environment.  In that case, it would number the lines of
+the environment in the following manner:
+
+\begin{verbbox}[\arabic{VerbboxLineNo}\(\cdot\)\hspace{1ex}]
+first line
+second line
+third line
+\end{verbbox}
+\theverbbox
+
+\section{Acknowledgements}
+
+I would like to thank Dr. David Carlisle for his great assistance
+in helping me to understand the nuances of optional arguments used in
+verbatim environments, allowing me to correct a longstanding bug in the
+{\vrbox} environment:\\
+  \rl\addvbuffer[1.1ex 1.4ex]{\parbox{\textwidth}{%
+    http://tex.stackexchange.com/questions/109030/ \\
+     optional-arguments-in-verbatim-environments
+  }}\\
+I would also like to acknowledge the use of three lines of code created
+by Prof. Enrico Gregorio, to strip the leading backslash from a
+\LaTeX{} command name\\
+  \rl\addvbuffer[1.1ex 0ex]{\parbox{\textwidth}{%
+    http://tex.stackexchange.com/questions/42318/ \\
+      removing-a-backslash-from-a-character-sequence
+  }}
+
+\clearpage
+\section{Code Listing}
+
+\verbatiminput{verbatimbox.sty}
+
+\end{document}
+
+
+
diff --git a/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox_example.pdf b/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox_example.pdf
deleted file mode 100644
index 8dbcc0fea26..00000000000
--- a/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox_example.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox_example.tex b/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox_example.tex
deleted file mode 100644
index 5f06af0a3cf..00000000000
--- a/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox_example.tex
+++ /dev/null
@@ -1,78 +0,0 @@
-\documentclass{article}
-%
-% This work may be distributed and/or modified under the
-% conditions of the LaTeX Project Public License, either version 1.3
-% of this license or (at your option) any later version.
-% The latest version of this license is in
-%   http://www.latex-project.org/lppl.txt
-% and version 1.3c or later is part of all distributions of LaTeX
-% version 2005/12/01 or later.
-%
-% This work has the LPPL maintenance status `maintained'.
-%
-% The Current Maintainer of this work is Steven B. Segletes.
-%
-\pagestyle{empty}
-\usepackage{verbatimbox}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\begin{document}
-
-\parskip 1em
-
-This is a test of the \textsf{verbatimbox} style package, to 
-test the \verb,verbbox, environment.  I am about to call on the
-\verb,verbbox, environment to see how if I can stuff \verb,verbatim,
-text into a \LaTeX{} box.  Here goes...
-
-\begin{verbbox}[\footnotesize]
-      Program test
-      implicit none
-      integer a, x
-      a = 0
-      x = 1
-   10 a = a + x
-      if (a .eq. 100) stop
-      goto 10
-      end
-!@#$%^&*()_+=-{}|\][<>?/\\\
-\end{verbbox}
-
-OK, I have created a \verb,verbbox, (which creates no output in and of
-itself).  When doing so, I used an optional argument of
-\verb,\footnotesize,. I now wish to see if I can stick it into a
-\verb,tabular, environment.  Note, when sticking a verbbox into the
-\verb,tabular, environment, use the \verb,[t], option of \verb,\theverbbox,.
-
-\begin{center}
-\begin{tabular}{| c | c | c |}
-\hline
-\raisebox{0.7in}{First box of table}&%
-\theverbbox[t] &
-\raisebox{0.7in}{last box of table}\\
-\hline
-\end{tabular}
-\end{center}
-
-Otherwise, if I choose, I can just stick the \verb,verbatim, box into an
-\verb,fbox,,
-so as to frame the result.  This latter case produces the same output as
-would the \verb,boxedverbatim, environment in the \textsf{moreverb}
-package.
-
-\fbox{\theverbbox}
-
-Being a box, I can use \verb,verbbox, output as part of a figure or
-table, for example.  Bottom line: the \textsf{verbatimbox} package
-provides nice flexibility in utilizing the \verb,verbatim, environment
-in a variety of ways, including some places where \verb,verbatim, would
-not otherwise be allowed.
-
-Finally, the \verb,\verbfilebox, command acts just like the
-\verb,verbbox, environment, except that it takes as its input the
-contents of a file (provided as the mandatory argument to the command).
-Like, the \verb,verbbox, environment, the \verb,\verbfilebox, command
-also has an optional argument through which things like font size of
-\verb,\theverbbox, can be altered.
-
-\end{document}