path: root/macros/latex/contrib/moreverb/moreverb.dtx

% 
% \iffalse
%
% Copyright (C) 1997 2002 2008 2011 by
%    Robin Fairbairns <rf10@cam.ac.uk>
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3c 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 Robin Fairbairns.
%
% This work consists of the source files moreverb.dtx,
%                                        moreverb.ins
%                  and the derived files moreverb.sty,
%                                        moreverb.pdf
%
% RCS information:
%
% $Id: moreverb.dtx,v 1.12 2011/04/18 19:03:28 rf10 Exp rf10 $
%
% \section{Initially: identify the package}
%
% We use the same body for the \cs{ProvidesFile} as for the
% \cs{ProvidesPackage} command.
%
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
%<*dtx>
\ProvidesFile{moreverb.dtx}
%</dtx>
%<moreverb>\ProvidesPackage{moreverb}
        [2008/06/03 v2.3a
%<moreverb>    `more' verbatim facilities%
%<*dtx>
               moreverb source file%
%</dtx>
                   ]
%    \end{macrocode}
% Code to compile the thing using LaTeX2e
%
%<*driver>
\documentclass{ltxdoc}
%
\setcounter{errorcontextlines}{999}
%
\GetFileInfo{moreverb.dtx}
%
% The definition of \star in ltxdoc.cls is useless (bug report
% LaTeX/2117).  \env is something I would like to have -- I'm
% not sure this definition is entirely kosher (in any case, why aren't
% all these things in doc.sty?)
%
\renewcommand\star{\texttt{*}}
\DeclareRobustCommand\env[1]{\cs{begin\char`\{#1\char`\}}}
%
\begin{document}
 \title{The \textsf{moreverb} package\thanks{This file
        has version number \fileversion, last
        revised \filedate}}
    \author{Robin Fairbairns (\small\texttt{rf10@cam.ac.uk})\\
            after\\
            Angus Duggan, Rainer Sch\"opf and Victor Eijkhout}
 \date{\the\year-\ifnum\month<10 0\fi\the\month
                -\ifnum\day  <10 0\fi\the\day}
 \maketitle
 \tableofcontents
 \DocInput{moreverb.dtx}
\end{document}
%</driver>
%
% \fi
%
% \CheckSum{402}
%
% \section{This package}
%
% This package uses the facilities provide by the \textsf{verbatim}
% package in the \LaTeXe{} \emph{tools} distribution to provide a
% number of things that were rejected as unnecessary in the
% development of that package.  (Nevertheless, the tab-expansion code
% in this package responds to one of the FAQs of |comp.text.tex|)
%
% The package provides things in three broad areas:
% \begin{itemize}
% \item Tab expansion and related stuff,
% \item Line numbering,
% \item Miscellaneous: writing verbatim to a file (for example, for
%   later re-input), and `boxed' verbatim.
% \end{itemize}
%
% \subsection{Tab expansion}
%
% The package enables you to specify the expected width of the
% tabulation, and also allows input of files containing tabs.
%
% \DescribeEnv{verbatimtab}
%
% \env{verbatimtab}\oarg{tab width}
% reproduces its body verbatim, with the tabs expanded to the given
% width (the default value is 8).
%
% \DescribeMacro{\verbatimtabinput}
%
% \cs{verbatimtabinput}\oarg{tab width}\marg{file name}
% is a file input version of the \texttt{verbatimtab} environment.
%
% \DescribeMacro{\verbatimtabsize}
%
% The size of the tabs is stored in \cs{verbatimtabsize}, and persists
% between uses of the environments.  (I.e., an optional argument to
% one of them applies to all subsequent ones.)
%
% \noindent To replace the value other than by use of an optional
% argument, you need to say:
%
% \cs{renewcommand}\cs{verbatimtabsize}|{|\meta{value}\cs{relax}|}|
%
% There are no promises offered as to the performance if you omit the
% \cs{relax}!
%
% \subsection{Line numbering}
%
% Line numbering is often useful when reproducing code examples
% (useful, that is, for those of us who don't want to pretty-print
% such snippets).
%
% \DescribeEnv{listing}
%
% \env{listing}\oarg{interval}\marg{start line} numbers the lines of
% its body.  The argument \meta{start line} specifies the starting
% line number.  The optional argument \meta{interval} specifies the
% number of lines between numbered lines: that is, every line whose
% number \(=0\pmod{\mbox{\meta{interval}}}\) will be numbered in the
% output.  (In addition, line number 1 will always be numbered.)  The
% default value of the \meta{interval} is 1 (i.e., every line will be
% numbered).
%
% \DescribeEnv{listingcont}
%
% \env{listingcont} continues from the place where the last
% listing left off.
%
% The style in which the label is set can be altered, for either
% environment, by re-defining \cs{listinglabel}.  Both environments
% also expand tabs.
%
% `\star' versions of both the listing environments are provided;
% these do the usual |verbatim*| thing of outputting spaces as
% `\verb*| |', but don't expand tabs.
%
% \DescribeMacro{listinginput}
%
% \cs{listinginput}\oarg{interval}\marg{start line}\marg{filename}
% is a file input version of listing.  There is no `\star' form.
%
% \subsection{Miscellanea}
%
% \DescribeEnv{verbatimwrite}
%
% \env{verbatimwrite}\marg{filename} writes all text in its body to a
% file, the name of which it is given as an argument.
%
% \DescribeEnv{boxedverbatim}
%
% \env{boxedverbatim} puts the contents of a verbatim environment in a
% framing box.  If you try to do this in a na\"\i ve way, you find
% that the verbatim lines have all become the width of the page, so
% that the box is, more often than not, a very poor fit to the text it
% surrounds.
%
% \DescribeEnv{verbatimcmd}
%
% The |verbatimcmd| environment was provided by the \LaTeX2.09 and
% early \LaTeXe{} versions of this package.  However, its capabilities
% are now provided by |alltt|, which is defined by the \textsf{alltt}
% package, now part of the \LaTeX{} base distribution, and so
% |verbatimcmd| has been withdrawn.
%
% \StopEventually{}
%
% \section{The code of the package}
%
%    \begin{macrocode}
%<*moreverb>
%    \end{macrocode}
%
% \subsection{Initial code}
%
% Load the \textsf{verbatim} package if it's not already loaded.
%
%    \begin{macrocode}
\@ifundefined{verbatim@processline}{\RequirePackage{verbatim}}{}
%    \end{macrocode}
%
% \subsection{Writing to a file}
%
% \begin{environment}{verbatimwrite}
% \env{verbatimwrite}\marg{filename} writes all text in its body to a
% file, the name of which it is given as an argument. (This code was
% written by Rainer Sch\"opf.)
%
% Note that the code creates its own output stream at first use.
% (This is a conservation measure; if the user never uses
% \env{verbatimwrite}, no \cs{write} stream is created.  An actual
% problematic use case appeared on tex.sx\dots)
%
%    \begin{macrocode}
\def\verbatimwrite#1{%
  \@ifundefined{verbatim@out}{\newwrite\verbatim@out}{}%
  \@bsphack
  \immediate\openout \verbatim@out #1
  \let\do\@makeother\dospecials
  \catcode`\^^M\active \catcode`\^^I=12
  \def\verbatim@processline{%
    \immediate\write\verbatim@out
      {\the\verbatim@line}}%
  \verbatim@start}
%    \end{macrocode}
%    \begin{macrocode}
\def\endverbatimwrite{%
  \immediate\closeout\verbatim@out
  \@esphack}
%    \end{macrocode}
% \end{environment}
%
% \subsection{Tab expansion}
%
% We define a few auxiliary macros and counters for expanding tabs.
% They are used by the |listing| and |verbatimtab| environments.
%
%    \begin{macrocode}
\newcount\tab@position \newcount\tab@size
%    \end{macrocode}
%
% \cs{verbatimtabsize} used to be a counter, but that seems to me
% overkill (\LaTeX{} uses too many counters as it is\dots).
%
%    \begin{macrocode}
\def\verbatimtabsize{8\relax}
%    \end{macrocode}
%
% \begin{macro}{\@xobeytab}
%
% \cs{@xobeytab} puts enough spaces in to get us to the next nominal
% tab stop
%    \begin{macrocode}
\def\@xobeytab{%
  \loop
    \toks@\expandafter{\the\toks@\@xobeysp}%
    \advance\tab@position-1
  \ifnum\tab@position>0 \repeat
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@vobeytabs}
% \cs{@vobeytabs} initialises use of \cs{@xobeytab}.  Needs to be
% executed within a group, as mustn't be allowed to leak out into the
% wide world.
%
%    \begin{macrocode}
\begingroup
  \catcode`\^^I=\active
  \gdef\@vobeytabs{\catcode`\^^I\active\let^^I\@xobeytab}%
\endgroup
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\verbatim@tabexpand}
% \cs{verbatim@tabexpand}\meta{body of line}\cs{@nil} processes every
% character of a line by tail recursion, counting the characters and
% juggling things when a tab is encountered.  (What used to be called
% `line imaging'\dots)
%
%    \begin{macrocode}
\def\verbatim@tabexpand#1{%
  \ifx#1\@nil
%   \showthe\toks@
    \the\toks@
    \expandafter\par
  \else
    \ifx#1\@xobeytab
      \@xobeytab
    \else
%    \end{macrocode}
%
% We can safely put \cs{@xobeysp} into the token register, since it
% does precisely what we need
%    \begin{macrocode}
      \toks@\expandafter{\the\toks@#1}%
      \advance\tab@position\m@ne
    \fi
    \ifnum\tab@position=0 \tab@position\tab@size \fi
    \expandafter\verbatim@tabexpand
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{environment}{listing}
% \env{listing}\oarg{interval}\marg{start line}
% 
% Defines a verbatim environment with numbered lines; the optional
% argument \meta{interval} specifies the number of lines between
% numbered lines, and the argument \meta{start line} specifies the
% starting line.
%
% \begin{environment}{listingcont}
% \env{listingcont}
%
% Continues from the place where listing left off.  The style in which
% the label is set can be altered by re-defining \cs{listinglabel}.
%
% `\star' versions of both environments are provided.
%
% \begin{macro}{\listing@line}
% \cs{listing@line} holds the current line number; its default value
% is 1, so one can merrily use |listingcont| throughout a document if
% there's but one stream of verbatim text being written.
%
%    \begin{macrocode}
\newcount\listing@line \listing@line=1
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\listing@step}
% \cs{listing@step} is another case where a counter used to be used,
% to no very obvious utility, but using up a valuable count register.
% Again, the value is modal; the trailing \cs{relax} is necessary.
%
%    \begin{macrocode}
\def\listing@step{1\relax}
%    \end{macrocode}
% \end{macro}
%    
% Adding an \cs{hbox} in front of the line causes a line break, so
% I\footnote{The personal pronoun was present in the comments in the
%   original version of this package; I'm not sure who it relates
%   to~--- RF} go through this rigmarole to get the lines aligned
% nicely.  I probably missed some obvious reason why \cs{hbox}es don't
% work\footnote{It's because an \cs{hbox} in vertical mode makes a
%   complete paragraph in its own right; this problem could be dealt
%   with in the fullness of time, but just now\dots}.
%
%    \begin{macrocode}
\def\listinglabel#1{\llap{\small\rmfamily\the#1}\hskip\listingoffset\relax}
\def\thelisting@line{%
  \setbox0\hbox{\listinglabel\listing@line}%
  \@tempcnta=\listing@line
  \divide\@tempcnta\listing@step \multiply\@tempcnta\listing@step
  \ifnum\listing@line=\@ne
    \unhbox0
  \else
    \ifnum\@tempcnta=\listing@line
      \unhbox0
    \else
      \hskip\wd0
    \fi
  \fi}
%    \end{macrocode}
%
% \begin{macro}{\listingoffset}
% \cs{listingoffset} is the separation between the line number and the
% actual line being listed; default value is \verb|1.5em|
%    \begin{macrocode}
\providecommand\listingoffset{1.5em}
%    \end{macrocode}
% \end{macro}
%
% Define \cs{listing} simply to suck in parameters and then to use
% \cs{listingcont}
%
%    \begin{macrocode}
\newcommand\listing[2][1]{%
  \global\listing@line=#2\relax
  \gdef\listing@step{#1\relax}
  \listingcont}
%    \end{macrocode}
%
% \cs{listingcont} is the business end of the two environments.
%
%    \begin{macrocode}
\def\listingcont{%
  \tab@size=\verbatimtabsize
  \def\verbatim@processline{\tab@position\tab@size
    \thelisting@line \global\advance\listing@line1
    \toks@{}%
    \expandafter\verbatim@tabexpand\the\verbatim@line\@nil}%
  \@verbatim\frenchspacing\@vobeyspaces\@vobeytabs\verbatim@start}
%    \end{macrocode}
%
% Nothing special at the end of the two environments.
%
%    \begin{macrocode}
\let\endlisting=\endtrivlist
\let\endlistingcont=\endtrivlist
%    \end{macrocode}
%
% Now the same rigmarole for the `\verb+*+' versions.
%
%    \begin{macrocode}
\expandafter\newcommand\csname listing*\endcsname[2][1]{%
  \global\listing@line=#2\relax
  \gdef\listing@step{#1\relax}
  \csname listingcont*\endcsname}
\@namedef{listingcont*}{%
  \def\verbatim@processline{%
    \thelisting@line \global\advance\listing@line1
    \the\verbatim@line\par}%
  \@verbatim\verbatim@start}
%    \end{macrocode}
%
% Nobbut a bit of hassle in the name definitions for the end of the
% environments
%
%    \begin{macrocode}
\expandafter\let\csname endlisting*\endcsname\endtrivlist
\expandafter\let\csname endlistingcont*\endcsname\endtrivlist
%    \end{macrocode}
% \end{environment}
% \end{environment}
%
% \begin{macro}{listinginput}
% \cs{listinginput}\oarg{interval}\marg{start line}\marg{filename}
% is a file input version of listing.
%
%    \begin{macrocode}
\def\listinginput{%
   \@ifnextchar[%]
     {\@listinginput}%
     {\@listinginput[1]}}
\begingroup
  \catcode`\~=\active \lccode`\~=`\^^M \lccode`\N=`\N
  \lowercase{\endgroup
    \def\@listinginput[#1]#2#3{\begingroup
      \global\listing@line=#2
      \gdef\listing@step{#1\relax}
      \tab@size=\verbatimtabsize
      \def\verbatim@processline{\tab@position\tab@size
        \thelisting@line \global\advance\listing@line1
        \toks@{}%
        \expandafter\verbatim@tabexpand\the\verbatim@line\@nil}%
      \@verbatim\frenchspacing\@vobeyspaces\@vobeytabs
      \def\verbatim@addtoline##1~{%
        \verbatim@line\expandafter{\the\verbatim@line##1}}%
      \openin\verbatim@in@stream=#3
      \ifeof\verbatim@in@stream
        \PackageWarning{moreverb}{No file #3.}%
      \else
        \do@verbatimtabinput
        \closein\verbatim@in@stream
      \fi
      \endtrivlist\endgroup
    \@doendpe
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{verbatimcmd}
% \texttt{verbatimcmd} was a verbatim environment with the exception
% of the escape and grouping characters \verb+\+, \verb+{+, \verb+}+.
% This is (err) exactly the specification of the \texttt{alltt}
% environment, and that is in the \textsf{alltt} package that is now
% part of the base distribution.
%    \begin{macrocode}
\def\verbatimcmd{%
  \PackageError{moreverb}{The verbatimcmd environment is obsolete}%
                         {Use alltt (from the LaTeX required package
                           alltt) in place of verbatimcmd}%
}
\let\endverbatimcmd\relax
%    \end{macrocode}
% \end{macro}
%
% \begin{environment}{boxedverbatim}
% \texttt{boxedverbatim} puts the contents of a verbatim environment
% in a framing box.
%
% (Written by Victor Eijkhout.)
%
% \noindent Bug fixes:
% \begin{itemize}
% \item David Carlisle 1995-12-28, dealing with spacing issues (iirc)
% \item Moretn H\o gholm 2008-06-01, positioning of frame in lists
% \end{itemize}
%
% First, redefine `processline' to produce only a line as wide
% as the natural width of the line
%
%    \begin{macrocode}
\def\boxedverbatim{%
  \def\verbatim@processline{%
    {\setbox0=\hbox{\the\verbatim@line}%
    \hsize=\wd0 \the\verbatim@line\par}}%
%    \end{macrocode}
%
% Now save the verbatim code in a box
%
%    \begin{macrocode}
  \@minipagetrue           % DPC
  \@tempswatrue            % DPC
  \@totalleftmargin\z@     % MH
  \setbox0=\vbox\bgroup \verbatim
}
%    \end{macrocode}
%
% At the end of the environment, we (umm) simply have to stick the
% results into a frame.
%
%    \begin{macrocode}
\def\endboxedverbatim{%
  \endverbatim
  \unskip\setbox0=\lastbox % DPC
%    \end{macrocode}
%
% Now everything's in the box, so we can close it\dots
%    \begin{macrocode}
  \egroup
%    \end{macrocode}
%
% To change the code for centring, the next line needs a spot of
% hacking.
%    \begin{macrocode}
  \fbox{\box0}%
}
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{verbatimtab}
% \env{verbatimtab}\oarg{tab width}
% is a verbatim environment which expands tab characters; the optional
% argument specifies the distance between tab stops.
%
% Executing \cs{obeylines} before looking for the optional argument
% prevents an empty first line of the environment becoming a \cs{par}
% token (this bug was reported by Werner Lemberg).
%    \begin{macrocode}
\newenvironment{verbatimtab}{\obeylines\@verbatimtab}{\endtrivlist}
%    \end{macrocode}
%
% Process the optional argument of the |verbatimtab|, now that we have
% protected ourselves from the dreaded \cs{par} tokens
%    \begin{macrocode}
\newcommand\@verbatimtab[1][\verbatimtabsize]{%
  \do@verbatimtab{#1}{%
     \@verbatim\frenchspacing\@vobeyspaces\@vobeytabs\verbatim@start}%
}
%    \end{macrocode}
% \end{environment}
%
% \begin{macro}{\do@verbatimtab}
%
% Prepare a tabbing environment; \verb+#1+ is the value of the tab
% size (generally, originally, an optional argument), \verb+#2+ is the
% `startup commands' to execute once an appropriate definition of
% \cs{verbatim@processline} has been established:
%    \begin{macrocode}
\def\do@verbatimtab#1#2{%
  \tab@size=#1
  \def\verbatim@processline{\tab@position\tab@size
    \toks@{}%
    \expandafter\verbatim@tabexpand\the\verbatim@line\@nil}%
  #2%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\verbatimtabinput}
% \cs{verbatimtabinput}\oarg{tab width}\marg{file name}
% is a file input version of the \texttt{verbatimtab} environment.
%
% We use the input stream acquired by the \textsf{verbatim} package;
% we did after all require it to be loaded.  (One has to admit that
% the name of that stream isn't actually part of the package's defined
% interface, but on the other hand there's no particular likelihood
% that it will ever change.)
%
% We didn't (originally) use fancy features of \cs{newcommand} since
% the definition was inside a group, and hence global.  So \dots\
% `traditional' code to provide a command with an optional argument
% (which may no longer be necessary):
%
%    \begin{macrocode}
\def\verbatimtabinput{%
   \@ifnextchar[%]
     {\@verbatimtabinput}%
     {\@verbatimtabinput[\verbatimtabsize]}}
\begingroup
\catcode`\~=\active \lccode`\~=`\^^M \lccode`\N=`\N
\lowercase{\endgroup
  \def\@verbatimtabinput[#1]#2{\begingroup
    \do@verbatimtab{#1}{%
      \@verbatim\frenchspacing\@vobeyspaces\@vobeytabs}%
    \def\verbatim@addtoline##1~{%
      \verbatim@line\expandafter{\the\verbatim@line##1}}%
    \openin\verbatim@in@stream=#2
    \ifeof\verbatim@in@stream
      \PackageWarning{moreverb}{No file #2.}
    \else
      \@addtofilelist{#2}%
      \do@verbatimtabinput
      \closein\verbatim@in@stream
    \fi
  \endtrivlist\endgroup\@doendpe}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\do@verbatimtabinput}
% Written-out (tail recursion) loop for reading the file
%    \begin{macrocode}
\def\do@verbatimtabinput{%
  \read\verbatim@in@stream to \verbtab@line
  \ifeof\verbatim@in@stream
  \else
    \expandafter\verbatim@addtoline\verbtab@line
    \verbatim@processline
    \verbatim@startline
    \expandafter\do@verbatimtabinput
  \fi
}
%</moreverb>
%    \end{macrocode}
% \end{macro}
%
% \Finale
%
\endinput
%
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}