summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/verbatimbox/verbatimbox.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/verbatimbox/verbatimbox.tex')
-rw-r--r--macros/latex/contrib/verbatimbox/verbatimbox.tex544
1 files changed, 544 insertions, 0 deletions
diff --git a/macros/latex/contrib/verbatimbox/verbatimbox.tex b/macros/latex/contrib/verbatimbox/verbatimbox.tex
new file mode 100644
index 0000000000..6ae4998898
--- /dev/null
+++ b/macros/latex/contrib/verbatimbox/verbatimbox.tex
@@ -0,0 +1,544 @@
+\documentclass{article}
+% 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.
+%
+\parskip 1em
+\parindent 0em
+\usepackage{verbatimbox}
+\usepackage{etoolbox}
+\usepackage{color}
+\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}{\bgn}\begin\end{myverbbox}
+\begin{myverbbox}{\edng}\end\end{myverbbox}
+\begin{myverbbox}{\vrbox}verbbox\end{myverbbox}
+\begin{myverbbox}{\vrnobox}verbnobox\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}{\vbfnobox}\verbfilenobox\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
+{\centering
+\begin{minipage}{.7\textwidth}%
+Routines for placing stylized verbatim text into boxes, useful in
+places where the verbatim environment is inaccessible. Secondarily,
+for adding vertical buffer around an object.
+\end{minipage}
+}\\
+\rule{0em}{2.7em}\large Steven B. Segletes\\
+steven.b.segletes.civ@mail.mil\\
+\rule{0em}{1.7em}\today\\
+\verbatimboxVersionNumber
+\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.
+
+One very nice feature of this package is the optional argument to both
+environments and macros that allows custom stylization of the verbatim
+text (fontshapes, sizes, numbering lines, \textit{etc.}) through the use
+of pre-commands. For those who prefer this form of optional-argument
+customization, the environments and macros are \textit{also} provided in
+a ``no-box'' form that is output directly, rather than being saved in a
+box. The no-box forms can be used when the verbatim has to span across
+page breaks.
+
+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 environments and macros 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\\
+ \bgn\lbr\vrnobox\rbr\lb pre-commands\rb\ldots\edng\lbr\vrnobox\rbr\\
+ \vbfnobox\lb pre-commands\rb\lbr filename\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
+
+The customization can make use of the \verb|VerbboxLineNo| counter in
+ways that make it line specific. Note that the optional argument
+must be contained on a single line.
+
+\begin{verbatim}
+\newcommand*\ifline[3]{%
+ \ifthenelse{\value{VerbboxLineNo} = #1}{#2}{#3}}
+\newcommand*\highlight{%
+ \color{red}\rmfamily\itshape\bfseries\large\(\bullet~\)}
+\newcommand\nohighlight{\arabic{VerbboxLineNo}:\hspace{1ex}}
+\begin{verbbox}[\ifline{2}{\highlight}{\nohighlight}]
+Line 1
+Line 2
+Line 3
+\end{verbbox}
+\theverbbox
+\end{verbatim}
+
+\newcommand*\ifline[3]{%
+ \ifthenelse{\value{VerbboxLineNo} = #1}{#2}{#3}}
+\newcommand*\highlight{%
+ \color{red}\rmfamily\itshape\bfseries\large\(\bullet~\)}
+\newcommand\nohighlight{\arabic{VerbboxLineNo}:\hspace{1ex}}
+\begin{verbbox}[\ifline{2}{\highlight}{\nohighlight}]
+Line 1
+Line 2
+Line 3
+\end{verbbox}
+\rl\theverbbox
+
+\begin{verbbox}[\arabic{VerbboxLineNo}:\hspace{1ex}]
+first line
+second line
+third line
+\end{verbbox}
+
+\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
+
+\rl\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
+
+\rl\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|
+
+\rl\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}}|:
+
+\rl\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}}|:
+
+\rl\fbox{\addvbuffer[-5pt -5pt]{A test}}
+
+This ability to work on a variety of objects makes {\avb} a powerful
+command in many applications.
+
+\textbf{ATTENTION. This paragraph represents a change as of V3.11, and
+can break backward compatibilty}.
+Likewise, if two length variables are to be used in the optional
+argument, the two lengths must be separately braced, with a space in between:
+
+\begin{verbatim}
+ \fbox{\addvbuffer[{\baselineskip} {.5\baselineskip}]{A test}}
+\end{verbatim}
+
+\rl\fbox{\addvbuffer[{\baselineskip} {.5\baselineskip}]{A test}}
+
+{\bfseries One may no longer use a ``\verb|\ |'' hard space to separate the
+two arguments.}
+
+\subsection{The ``nobox'' Alternatives}
+
+Alternatives are provided for the {\vrbox} environment and the {\vbfbox}
+macro, which output the content directly, rather than place it into a
+box. These alternatives are named {\vrnobox}\margenv{\vrnobox} and
+{\vbfnobox}\margenv{\vbfnobox}. Like their boxed counterparts, these
+alternatives make use of the convenient optional pre-commands that allow
+for custom stylization of the verbatim content.
+
+Because they are not placed into a box, but instead output directly,
+their content cannot be recalled at a later time in the document. While
+the boxed versions have a particular use in environments where verbatim is
+inaccessible, the no-boxed alternatives may be used when the content
+must span a page break.
+
+\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}
+\rl\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}
+\rl\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}
+\rl\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}
+\rl\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}
+\rl\theverbbox
+
+There is also a quirk with the macro \verb|\addvbuffer|.
+If the \verb|\addvbuffer| macro adds negative space below an argument,
+the argument is
+vertically shifted downward by the same amount. For example,
+compare the following constructions,
+\verb|\fbox{gb}| and \verb|\fbox{\addvbuffer[-3pt]{gb}}|:
+\fbox{gb}\fbox{\addvbuffer[-3pt]{gb}}.
+In the latter case, the box is bottom-trimmed, but the result is shifted downward.
+This adverse outcome can generally be overcome with a countering
+\verb|\raisebox|,
+\fbox{gb}\fbox{\raisebox{3pt}{\addvbuffer[-3pt]{gb}}}.
+However, if the \verb|\raisebox| would otherwise place
+the new box above the baseline, the effect of the
+\verb|\addvbuffer| on the bottom of the box is spoiled, as in the
+comparison given by the constructions
+\verb|\fbox{\addvbuffer[-3pt]{X}}| versus
+\verb|\fbox{\raisebox{3pt}{\addvbuffer[-3pt]{X}}}|
+which produces this result:
+\fbox{\addvbuffer[-3pt]{X}}\fbox{\raisebox{3pt}{\addvbuffer[-3pt]{X}}}.
+Note how 3pt are not trimmed from the bottom of the second box.
+For this reason, the \verb|\raisebox| remedy has not been incorporated into the definition
+of \verb|\addvbuffer|; instead, the quirk has been allowed to stand.
+
+
+\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
+ }}
+
+\section{Code Listing}
+
+\verbatiminput{verbatimbox.sty}
+
+\end{document}
+
+
+