path: root/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox.tex

\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}