verbatimbox (7jun13)

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

1 files changed, 104 insertions, 18 deletions

diff --git a/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox.tex b/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox.tex
index 03e5783ebee..60a97445749 100644
--- a/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox.tex
+++ b/Master/texmf-dist/doc/latex/verbatimbox/verbatimbox.tex
@@ -1,5 +1,5 @@
 \documentclass{article}
-\def\version{3.0}
+\def\version{3.1}
 % Copyright 2013 Steven B. Segletes
 %
 % This work may be distributed and/or modified under the
@@ -24,6 +24,7 @@
 \parindent 0em
 \usepackage{verbatimbox}
 \usepackage{etoolbox}
+\usepackage{color}
 \makeatletter
 \preto{\@verbatim}{\topsep=0pt \partopsep=0pt }
 \makeatother
@@ -38,7 +39,10 @@
 \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}
@@ -46,6 +50,7 @@
 \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}
@@ -63,9 +68,13 @@
 \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.\\
+{\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\\
@@ -81,11 +90,21 @@ 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 commands provided by this package are given as follows:\\\itshape
+The environments and macros provided by this package are given as 
+follows:\\\itshape
 \rl%
 \addvbuffer[1ex 1ex]%
 {\parbox{4in}{%
@@ -95,7 +114,9 @@ The commands provided by this package are given as follows:\\\itshape
   \tvb\lb\texttt{\upshape t}\rb\\
   \bts\eq length\\
   \bbs\eq length\\
-  \avb\lb length \lb below length\rb\rb\lbr object\rbr
+  \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
@@ -161,6 +182,42 @@ 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
@@ -263,7 +320,7 @@ below the object.  So, for example,
   \verb|\fbox{\addvbuffer[5pt]{\theverbbox}}|
 will produce
 
-\fbox{\addvbuffer[5pt]{\theverbbox}}
+\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
@@ -271,26 +328,56 @@ added below the object.  Thus,
 \verb|\fbox{\addvbuffer[15pt 5pt]{\theverbbox}}|
 will produce
 
-\fbox{\addvbuffer[15pt 5pt]{\theverbbox}}
+\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|
 
-\fbox{\addvbuffer[15pt 5pt]{\parbox{1in}{This is a test of the
+\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}}|:
 
-\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}}|:
 
-\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.
 
+When length variables are being used in the optional argument to
+\verb|\addvbuffer|, one must use the string form of them (prefixed with
+\verb|\the|), as in
+
+\begin{verbatim}
+  \addvbuffer[\the\mysep]{A test}
+\end{verbatim}
+
+Likewise, if two length variables are to be used in the optional
+argument, an explicit space (backslash space) must be used to separate
+the arguments:
+
+\begin{verbatim}
+  \addvbuffer[\the\mytopsep\ \the\mybottomsep]{A test}
+\end{verbatim}
+
+\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
 
@@ -322,10 +409,10 @@ would look like:\\
 \begin{verbbox}[\LARGE]first line
 second line
 \end{verbbox}
-\addvbuffer[3pt 0pt]{\fbox{\theverbbox}}
+\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
+first line of the environment contents on the following line.  Thus,
 
 \begin{verbatim}
  \begin{verbbox}[\LARGE]
@@ -340,7 +427,7 @@ will yield the expected result:\\
 first line
 second line
 \end{verbbox}
-\addvbuffer[3pt 0pt]{\fbox{\theverbbox}}
+\rl\addvbuffer[3pt 0pt]{\fbox{\theverbbox}}
 
 No such requirement is necessary if there are no optional arguments.
 So, for example,
@@ -373,7 +460,7 @@ this following example:
 first line
 second line
 \end{verbbox}
-\fbox{\theverbbox}
+\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
@@ -390,7 +477,7 @@ interpreted:
 first line
 second line
 \end{myverbbox}
-\fbox{\mybox}
+\rl\fbox{\mybox}
 
 There are differences, however, in how {\vrbox} and {\myvrbox} process
 the optional argument, which relate to overcoming the problems
@@ -412,7 +499,7 @@ first line
 second line
 third line
 \end{verbbox}
-\theverbbox
+\rl\theverbbox
 
 \section{Acknowledgements}
 
@@ -432,7 +519,6 @@ by Prof. Enrico Gregorio, to strip the leading backslash from a
       removing-a-backslash-from-a-character-sequence
   }}
 
-\clearpage
 \section{Code Listing}
 
 \verbatiminput{verbatimbox.sty}