fancyvrb update (13may08)

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

1 files changed, 120 insertions, 15 deletions

diff --git a/Master/texmf-dist/source/latex/fancyvrb/fancyvrb.dtx b/Master/texmf-dist/source/latex/fancyvrb/fancyvrb.dtx
index a06cf159520..dfdb8778a59 100644
--- a/Master/texmf-dist/source/latex/fancyvrb/fancyvrb.dtx
+++ b/Master/texmf-dist/source/latex/fancyvrb/fancyvrb.dtx
@@ -12,7 +12,8 @@
 %% July 17, 1998
 %%
 % \fi
-%
+% \changes{v2.7a}{2008/02/07}{NMM fixed lastline=firstline bug}
+% \changes{v2.7}{2000/03/21}{DG/SR changed how fancyvrb.cfg included}
 % \changes{v2.6}{1998/07/17}{. Three bug corrected, options numberblanklines,
 %                            label, labelposition and leftline added and few
 %                            precisions.}
@@ -20,7 +21,7 @@
 % \changes{v2.0 Beta}{1994/03/30}{First version personally shown by Timothy
 %                                 \textsc{van Zandt}.}
 %
-% \CheckSum{3107}
+% \CheckSum{3113}
 %
 % \newif\ifPostScriptFonts
 % \IfFileExists{times.sty}{\PostScriptFontstrue}{}
@@ -195,14 +196,12 @@
 % \title{The `\textsf{fancyvrb}' package\\Fancy Verbatims in \LaTeX}
 % \author{Timothy Van Zandt\\Princeton University\\Princeton -- USA\\
 %         {\footnotesize email: tvz@Princeton.EDU}\\[5mm]
-%         {Packaging, documentation and support}\\
-%         {\footnotesize Denis Girou (CNRS/IDRIS -- France) -- %
-%                        Denis.Girou@idris.fr}\\[-2mm]
+%         {Packaging, documentation and support originally (but no longer) by}\\
+%         {\footnotesize Denis Girou (CNRS/IDRIS -- France)}\\[-2mm]
 %         {\footnotesize and}\\[-2mm]
-%         {\footnotesize Sebastian Rahtz (Elsevier -- GB) -- %
-%                        s.rahtz@elsevier.co.uk}}
-% \date{Version 2.6\\July 17, 1998\\
-%       {\small Documentation revised July 17, 1998}}
+%         {\footnotesize Sebastian Rahtz (Elsevier -- GB)}}
+% \date{Version 2.7a\\ 7-Feb-2008\\
+%       {\small Documentation revised 7-Feb-2008}}
 %
 % \maketitle
 %
@@ -817,6 +816,28 @@
 %   \end{Verbatim}
 % \end{SideBySideExample}
 %
+% % Instead of specifying a firstline at which to start printing a range
+% of lines, you can define a start string; the start of the range is
+% the first line that exactly equals the string.  (The comparison is made
+% before any characters are gobbled off the front of the line.) Similarly for a stop
+% string. You can mix line-numbers and strings, e.g.\ start at
+% firstline, and end at a stop string.  Specifying the strings is a
+% bit klunky.  Initially you must define the strings with
+% \cs{newcommand*} as in:
+% \begin{SideBySideExample}
+%   \newcommand*\FancyVerbStartString{FROM}
+%   \newcommand*\FancyVerbStopString{TO}
+%   \begin{Verbatim}[gobble=2]
+%     First verbatim line.
+%   FROM
+%     Second verbatim line.
+%   TO
+%     Third verbatim line.
+%   \end{Verbatim}
+% \end{SideBySideExample}
+%
+% \noindent To redefine the strings, you must use \cs{renewcommand*}.
+
 % \subsubsection{Spaces and tab characters}
 %
 % \begin{optlist}
@@ -1397,8 +1418,8 @@
 %
 % Who we are.
 %    \begin{macrocode}
-\def\fileversion{2.6, with DG/SPQR fixes}
-\def\filedate{1998/07/17}
+\def\fileversion{2.7a, with DG/SPQR fixes, and firstline=lastline fix}
+\def\filedate{2008/02/07}
 \ProvidesPackage{fancyvrb}[\filedate]
 \message{Style option: `fancyvrb' v\fileversion \space  <\filedate> (tvz)}
 \csname fancyvrb@loaded\endcsname
@@ -1810,6 +1831,12 @@
 % \noindent if value is a number, then after the assignment the next token is
 % \cs{relax}.
 %
+% "Preprocessing the line" involves:
+%   \begin{itemize}
+%     \item Checking whether this line falls in the range specified by start or stop strings.
+%     or \texttt{firstline} or \texttt{lastline} line-numbers, or a mixture.
+%     \item Gobble'ing initial characters.
+%   \end{itemize}
 %    \begin{macrocode}
 \define@key{FV}{firstline}{%
   \afterassignment\FV@ParseStart\@tempcnta=0#1\relax\@nil{#1}}
@@ -1891,6 +1918,80 @@
 % The definition of \cs{FV@FindStartStop} changes, so that we don't
 % have to check irrelevant conditions with each line.
 %
+% Here's how it works; for simplicity we assume \texttt{firstline} and \texttt{lastline}
+% have been specified, rather than start or stop strings.
+%
+% The first time \cs{FV@FindStartStop} is called:
+% \begin{enumerate}
+% \item It calls
+% \cs{FV@DefineFindStart}.  (The name roughly means "define\\
+% \cs{FV@FindStartStop} to detect when we've reached the \underline{start} of the
+% specified range".)  This checks the range parameters that have been
+% specified, and then redefines \cs{FV@FindStartStop} (yes, the
+% function that has called this code) to contain only
+% the necessary checks, for efficiency reasons:
+%
+% 	\begin{itemize}
+% 	
+% 	\item If we haven't printed any lines yet, which is true when\\
+% 	\cs{FV@FindStartStop} is first called, we only need to check
+% 	the current line-number against \texttt{firstline}, so we redefine
+% 	\cs{FV@FindStartStop} to be\\
+% 	\cs{FV@FindStartNum}.
+%
+% 	\item If \texttt{firstline} isn't set, we only have to check the
+% 	current line-number against \texttt{lastline}, so we redefine 
+% 	\cs{FV@FindStartStop} to be \cs{FV@DefineFindStop}.
+% 	(The name roughly means "define\\
+% 	\cs{FV@FindStartStop} to detect when we've reached the
+% 	\underline{stop} (end) of the
+%	 specified range", but unlike the START case, it includes code
+% 	(\cs{FV@@PreProcessLine}) to print the current line.)
+%
+%	\end{itemize}
+% 
+%
+% \item It then calls the newly-defined  \cs{FV@FindStartStop} to see
+% if the current line being processed is within the range to be printed.
+%
+% \end{enumerate}
+%
+% \cs{FV@FindStartStop} is redefined once as described above, but it
+% can be redefined again:
+%
+% 	\begin{enumerate}
+%
+% 	\item When we have reached \texttt{firstline}, i.e.\ have entered the
+% 	range to be printed,  we redefine 
+% 	\cs{FV@FindStartStop} to be \cs{FV@DefineFindStop}.  (We know
+% 	we've reached the start, so there's no point checking that again on
+% 	future calls.)
+%
+% 	\item When we reach \texttt{lastline} and have printed it, we won't
+% 	want to print any more lines, so we redefine
+% 	\cs{FV@FindStartStop} to \cs{relax} so we do nothing (and do
+% 	it efficiently).
+%
+% 	Note that when \texttt{firstline} = \texttt{lastline} (= 6, say), it is
+% 	\cs{FV@FindStartNum} (which \cs{FV@FindStartStop} has
+% 	initially been redefined to) that notices when we reach line
+% 	6, and prints it, and redefines \cs{FV@FindStartStop} to be \cs{FV@DefineFindStop}.
+% 	Then we read line 7, so \cs{FV@DefineFindStop} has to check
+% 	whether we've passed \texttt{lastline}, and therefore shouldn't print
+% 	the current line, before
+% 	redefining \cs{FV@FindStartStop} to \cs{relax} as explained above.
+%
+% 	By contrast, when \texttt{firstline} is less than \texttt{lastline} (= 6, 8, say), when we
+% 	reach line 8, \cs{FV@DefineFindStop} sees that we're at the
+% 	end of the range, and \emph{does} print the line, before
+% 	redefining \cs{FV@FindStartStop} to \cs{relax} as above.
+%
+% 	This slight weirdness is because several of the macros are
+% 	defining themselves and one another, resulting in a slightly weird
+% 	execution flow.
+%
+% 	\end{enumerate}
+% 
 % \begin{macro}{\FV@FindStartStop}
 %    \begin{macrocode}
 \def\FV@FindStartStop{\FV@DefineFindStart\FV@FindStartStop}
@@ -1969,13 +2070,17 @@
 % \begin{macro}{\FV@FindStopNum}
 %    \begin{macrocode}
 \def\FV@FindStopNum{%
-  \ifnum\FancyVerbStopNum=\FV@CodeLineNo
+  \ifnum\FancyVerbStopNum>\FV@CodeLineNo
+  \else
     \let\FV@FindStartStop\relax
     \ifeof\FV@InFile\else
       \immediate\closein\FV@InFile
     \fi
   \fi
-  \FV@@PreProcessLine}
+  \ifnum\FancyVerbStopNum<\FV@CodeLineNo
+  \else
+    \FV@@PreProcessLine
+  \fi}
 %    \end{macrocode}
 % \end{macro}
 %
@@ -4423,9 +4528,9 @@
 %    \end{macrocode}
 %
 %    \begin{macrocode}
-%% DG/SR modification begin - Jan. 22, 1998
+%% DG/SR modification begin -  Mar 21 2000
 %%\@input{fancyvrb.rc}
-\@input{fancyvrb.cfg}
+\InputIfFileExists{fancyvrb.cfg}{}{}
 %% DG/SR modification end
 %    \end{macrocode}
 %