path: root/Master/texmf-dist/tex/latex/versions/versions.sty

%% VERSIONS.STY -- omit passages optionally under LaTeX -- 
%% Copyright 2003, 2004 by Uwe L"uck, Munich, Germany; 
%% http://www.contact.uwe.lueck.de.vu, 
\def\fileversion{0.54}  \def\filedate{2005/01/10} 

%% LEGAL MATTERS: ====================================================
%
% Released under the terms of the LaTeX Project Public License 
% (ftp://ctan.tug.org/tex-archive/macros/latex/base/lppl.txt 
% version 1.3a; 
% essentially: Free to use, copy, distribute [sell] and change, 
% but, if changed, the name must be changed; NO WARRANTY). 
% For copyright see above. 
%
% This file has the LPPL maintenance status "author-maintained".
% The Current Maintainer of this file is Uwe L"uck.
% 
%% SHORT DESCRIPTION: ================================================ 
% 
% Varies Stephen Bellantoni's `version.sty' in optionally omitting 
% environments, defining (among others) \includeversion and 
% \excludeversion as well as a `comment' environment. (For comparison 
% to `version.sty', see Section `IMPROVEMENTS' beneath \endinput.) So 
% multiple versions of a document may be printed from one source file. 
% Cf. packages `comment' (very similar functions and more, see 
% comparison after \endinput below), `verbatim', `optional' (on CTAN). 
% ---Needs LaTeX, even should work with LaTeX 2.09 
% (please tell me if not). 
% 
%% USAGE: ============================================================
% (User commands, Option, Customize, General warnings) 
% 
% *User commands*: ---------------------------------------------------
% 
% In the document part of your source file, put into environments 
%   \begin{VERSION}CODE\end{VERSION} 
% passages CODE (or other code) to be omitted optionally. VERSION may 
% be any string consisting of character tokens (see TeXbook, p. 40: 
% `\csname'), and the document may  contain environments with several 
% names of this kind (VERSIONa, VERSIONb, etc.). Preceding 
%   \excludeversion{VERSION}, \includeversion{VERSION}, 
%   \markversion{VERSION} 
% (in the preamble or even later on) control how these environments 
% behave. 
%   \excludeversion{VERSION}    `VERSION' environments just not 
%                               processed (ignored, i.e.); 
%   \includeversion{VERSION}    `VERSION' environments processed as 
%                               if \begin{VERSION} and \end{VERSION} 
%                               just were not present, however they 
%                               form groups like 
%                               \begin{relax}CODE\end{relax} 
%                               or \begingroup CODE \endgroup. 
%   \markversion{VERSION}       `VERSION' environments processed, 
%                               resulting text may be marked in 
%                               printout---for comparison of 
%                               variants of your document, e.g. 
% By default, these three commands send a message to screen, and 
% \markversion{VERSION} results in printed marks indicating start, 
% \end, and `VERSION'. Cf. subsection `Customize' below. 
% A warning is sent to screen if `VERSION' has been defined earlier 
% (by LaTeX, e.g.). (A `VERSION' environment must not overlap with 
% other environments, of course, must be balanced with respect to 
% \if...\fi, and must not contain \outer macros. In LaTeX the only 
% \outer macro is ^^L---ascii form feed.) 
%% TODO: 
% (`comment.sty' and comment environment from `verbatim.sty' 
%  are superior concerning \outer macros. On request, I could 
%  equip my \processifversion with that \outer feature.) 
% 
% However, \begin{VERSION}...\end{VERSION} breaks inside macro 
% arguments, e.g. of \footnote (it is even fragile). So there is 
%   \processifversion{VERSION}{CODE}
% working analogously (grouping as well), depending on \excludeversion 
% etc. (it is even robust). (`optional.sty' works similarly.)
% 
% A pre-installed instance of `VERSION' is `comment', which is 
% ignored by default. So you may put rather long comments as CODE 
% in \begin{comment}CODE\end{comment}. (This feature serves 
% compatibility with Stephen Bellantoni's `version.sty'.) 
% Note that alternative packages `comment' and `verbatim' define 
% \comment as well. 
% 
% *Options*: ----------------------------------------------------------
% 
%   \usepackage[tracing]{versions}
% causes (i) checking package commands for undefinedness, 
% (ii) messages on screen indicating line numbers of single excluded 
% environments (`Ignore VERSION, lines XX to YY]'). If final line 
% number and closing bracket don't appear on screen, the environment 
% presumably contains (implicit) \fi or \if... not matching each other 
% within that environment. This package option needs LaTeX2e and 
% TeX version greater equal 3.0. (No change of \processifversion.)
% 
%   \usepackage[nogroup]{versions}
% provides a user command \includeversionnogroup{VERSION} working like 
% \includeversion{VERSION}, but included `VERSION' will form no 
% grouping. 
% 
% *Customize*: -------------------------------------------------------
% 
% To change messages from \excludeversion, \includeversion, 
% \markversion, or to change printed marks resulting from 
% \markversion, take some of the following lines into your file, 
% remove left hand comment marks (`%'), and change the definition. 
% (Must perhaps be enclosed in \makeatletter...\makeatother 
%  or \catcode`\@=12 ...\catcode`\@=11.)
%   \renewcommand\versionmessage[2]{\typeout{*** `#1' #2. ***}} 
%   \renewcommand\beginmarkversion{\@Vs@sffbox{\@currenvir$>$}}
%   \renewcommand\endmarkversion{\@Vs@sffbox{$<$\@currenvir}}
% (For LaTeX2e, replace \renewcommand by \renewcommand*.) 
% 
% (1) \versionmessage is the style of screen reports from 
% \excludeversion etc. Any redefinition must use two arguments. 
% The first is the version name (VERSION), the second is one out of 
% `excluded', `included', `included with marks'. 
% 
% (2) \beginmarkversion and \endmarkversion is the style of marks 
% surrounding environments `VERSION' after \markversion{VERSION}. 
% Any redefinition must use no argument. \@currenvir is `VERSION'. 
% \@Vs@sffbox{CODE} as in package definition typesets argument CODE 
% as \textsf{CODE} and puts into an \fbox. 
% 
% *General warnings*: ------------------------------------------------
% (For legal warnings see top of file, 
%  for errors and requirements see `SHORT DESCRIPTION', 
%  option `tracing' and `user commands' above.) 
% This package uses \includeversion and \excludeversion and thus 
% cannot be used at the same time as Stephen Bellantoni's 
% `version.sty'. 
% 
% ====================================================================
% Please send bug reports and other comments to above e-mail address!
% ====================================================================

%% IMPLEMENTATION: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

  \ifx\ProvidesPackage\@undefined \else %% LaTeX 2.09 allowed. 
\ProvidesPackage{versions}[\filedate\space v\fileversion\space 
                           ignore passages optionally (UL)]
%% (Version history at end of file.) 
  \fi 

%% Options: 
  \ifx\DeclareOption\@undefined \else 

\DeclareOption{nogroup}{% 
  \newcommand*\includeversionnogroup[1]{% 
    \versionmessage{#1}{included without grouping}%
    \expandafter \let \csname #1\endcsname\@Vs@sphnoop@ngr 
    \expandafter \let \csname end#1\endcsname\@Vs@Sphnoop@ngr 
    \expandafter \let \csname @Vs@?#1\endcsname\@firstofone 
  }% 
  \global\let\@Vs@stack\@empty 
  \def\@Vs@sphnoop@ngr{%
      \begingroup 
        \let\@elt\relax 
        \xdef\@Vs@stack{% 
          \@currenvir\@elt\the\inputlineno\@elt\@Vs@stack}% 
      \endgroup 
    \endgroup 
    \@Vs@sphnoop 
  }% 
  \def\@Vs@Sphnoop@ngr{% 
    \begingroup 
      \@Vs@Sphnoop 
      \ifx\@Vs@stack\@empty \else 
        \expandafter\@Vs@pop\@Vs@stack\@nil 
      \fi 
  }% 
  \def\@Vs@pop#1\@elt#2\@elt#3\@nil{% 
    \def\@currenvir{#1}\def\@currenvline{ on line #2}% 
    \gdef\@Vs@stack{#3}%
  }% 
} 

\let\@Vs@btrace\relax \let\@Vs@etrace\relax %% Unless tracing. 
\DeclareOption{tracing}{% 
%% First check user commands: 
  \newcommand\versionmessage{}\newcommand\beginmarkversion{}% 
  \@ifundefined{endmarkversion}{}\@notdefinable 
  \newcommand\excludeversion{}\newcommand\includeversion{}% 
  \newcommand\markversion{}\newcommand\processifversion{}% 
%% TODO: package error reports instead of LaTeX's. 
%% Now enable tracing excluded environments: 
  \def\@Vs@btrace{\message{[Ignoring `\@currenvir', 
    lines \the\inputlineno\space to}}% 
  \def\@Vs@etrace{\message{\the\inputlineno.]}}% 
} 

\ProcessOptions 

  \fi 

%% Customizable: 
\def\versionmessage#1#2{\typeout{*** `#1' #2. ***}} 
\def\beginmarkversion{\@Vs@sffbox{\@currenvir$>$}}
\def\endmarkversion{\@Vs@sffbox{$<$\@currenvir}}

%% General auxilaries: 
\def\@Vs@envwarn#1{% 
  \@ifundefined{#1}{}{% 
    \PackageWarning{`Versions'}{Redefining environment `#1'}}% 
}

\def\includeversion#1{%
  \versionmessage{#1}{included}%
%% TODO: Customize `included' etc.!? 
  \@Vs@envwarn{#1}% 
  \expandafter \let \csname #1\endcsname\@Vs@sphnoop 
  \expandafter \let \csname end#1\endcsname\@Vs@Sphnoop 
  \expandafter \let \csname @Vs@?#1\endcsname\@Vs@iprocess 
}%
\def\@Vs@sphnoop{\@bsphack\@esphack} %% Don't double spaces. 
\def\@Vs@Sphnoop{\@bsphack\@Esphack} %% Same at end of environment. 
\long\def\@Vs@iprocess#1{\begingroup #1\endgroup}

\def\markversion#1{%
  \versionmessage{#1}{included with marks}%
  \@Vs@envwarn{#1}% 
%% TODO: \@bsphack etc. OK below? 
  \expandafter \let \csname #1\endcsname\@Vs@bm 
  \expandafter \let \csname end#1\endcsname\@Vs@em 
  \expandafter \def \csname @Vs@?#1\endcsname{\@Vs@mprocess{#1}}% 
}%
\def\@Vs@bm{%% Beware change from vmode to hmode. 
  \edef\@tempa{% 
    \ifhmode \noexpand \@bsphack 
             \noexpand \beginmarkversion 
             \noexpand \@esphack
    \else    \noexpand \beginmarkversion 
             \ignorespaces %% 2003/10/04; 
             %% cf. \incl...: no leading spaces at par start. 
    \fi 
  }\@tempa 
} 
\def\@Vs@em{\@bsphack\endmarkversion\@Esphack}% 
\def\@Vs@sffbox#1{\fbox{\normalfont\sffamily#1}}
\DeclareRobustCommand\@Vs@mprocess[2]{% 
  \begingroup \def\@currenvir{#1}% 
  \beginmarkversion #2\endmarkversion \endgroup}% 
%% TODO: sophisticated version for specially formatted environments 
%% accompanied by corresponding \processifversion!? 

\def\excludeversion#1{%
  \versionmessage{#1}{excluded}%
  \@Vs@envwarn{#1}% 
  \expandafter \let \csname #1\endcsname\@Vs@bx 
  \expandafter \let \csname @Vs@?#1\endcsname\@Vs@xprocess 
} 
  \begingroup 
    \catcode`{=\active \catcode`}=12 
    \catcode`(=1 \catcode`)=2 
\gdef\@Vs@bx(%% 2003/10/04; \xdef before. 
  \@bsphack\@Vs@btrace 
  \catcode`{=\active \catcode`}=12\relax 
%% TODO: \@makeother\^^L which is \outer\active!? 
  \let\end\fi \let{\@Vs@ex %} 
  \iffalse 
) 
%{ 
\gdef\@Vs@ex#1}(%% 2003/09/30; \xdef before. 
  \def\@tempa(#1)% 
  \ifx\@tempa\@currenvir 
    \@Vs@etrace \@Esphack \endgroup %% 2003/09/30. 
%% Note: corresponding \@bshack inside group. 
    \if@ignore\@ignorefalse\ignorespaces\fi %% 2003/09/30. 
  \else 
    \expandafter \@Vs@iffalse %% Explicit \iffalse breaks. 
  \fi 
) 
    \endgroup
\DeclareRobustCommand\@Vs@xprocess[1]{\@bsphack\@esphack}
%% No \@Vs@btrace, \@Vs@etrace as opposed to \@Vs@bx, \@Vs@ex. 
%% TODO: To cope with \outer macros, \@Vs@xprocess could 
%%       \@makeother\\ and \@makeother\^^L before reading. 
\def\@Vs@iffalse{\iffalse}

\def\processifversion#1{\csname @Vs@?#1\endcsname}
%% Inside arguments, e.g. of \footnote, where category codes have 
%% been fixed already so excluded environment would not work. 

\excludeversion{comment} %% Keep `version.sty' functionality. 

\endinput %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

COMPARISON with Viktor Eijkhout's `comment.sty': 
`Comment' even works under PlainTeX as well as LaTeX, present package 
under LaTeX only. \specialcomment in `comment' supports special 
surroundings---this is missing here (but could easily be supplied on 
request). %% TODO 
Included environments never form groups in `comment', here user may 
choose whether they form groups or not, at least for simple including 
(not with marks). `comment' includes by writing on and reading from 
disk, present package needs no writing on disk. 
Unlike the present package, `comment' skips even \outer macros, 
\if...'s and \fi's. (So `comment' is better for "real" comments. 
---Concerning \outer, this feature is important for PlainTeX, while 
under LaTeX the only \outer macro usually is ^^L.) 
`Comment' sometimes produces wrong spaces %% TODO still? 2003/10/03.
and discovers `\end{comment}' only if nothing else is in the input 
line. 

IMPROVEMENTS vis-a-vis Stephen Bellantoni's `version.sty': 
* \processifversion added for excluding text inside arguments of, 
  e.g., \footnote (where excluding *environment* would break). 
  \processifversion is even robust. 
* \@Esphack instead of \@esphack at \end of excluded environment; 
  needed for properly processing input space symbols there. 
* \begin and \end of included environment may appear in separate 
  lines without doubling spaces (\@bsphack and \@esphack used). 
* Screen messages sent by \includeversion and \excludeversion. 
* Large passages don't fill main memory when excluded. 
  (`s' in `versions' means `safe'!) 
* Optional tracing of excluded environments added. 
* Option of including without grouping. 
* Original \gdef and \csname #1END@NOTE\endcsname in 
  \excludeversion were superfluous. 

VERSION HISTORY: 
v0.1  2003/09/29  Very first; 
                  sent to Donald, Victor, Christian, Volker. 
v0.2  2003/09/30  \@sV@iffalse replacing \csname iffalse\fi; 
                  \@sV@ex: \@Esphack in group, extra \ignorespaces. 
v0.3  2003/10/01  Documentation: added warnings about \if...\fi and 
                  \outer---thanks to Victor Eijkhout; sent it to him. 
v0.31 2003/10/03  Documentation: added that `comment.sty' and 
                  `verbatim.sty' are superior in the respect 
                  discussed above; also added comparison with 
                  `comment.sty'. 
v0.4  2003/10/06  Documentation: Replaced stupid proposal of 
                  \aftergroup for including (needs stack!); 
                  retreated offer of partially enable skipping 
                  \outer/\if.../\fi. (\process... typically comes too 
                  late to change category codes.) 
                  \xdef -> \gdef for \@sV@ex. 
                  Then changed all `@sV' into `@Vs'. 
                  Documentation: Referred to TeXbook for character 
                  tokens in version names. 
                  Removed \@Vs@sphgobble from \@Vs@iprocess (leave 
                  spacing to user); now robust without \Declare... 
                  Then `phgobble' -> `phnoop'. 
                  Added option `nogroup'. 
                  Added \normalfont in \@Vs@sffbox. 
                  Sent to Victor E. 2005/10/05; minor changes in 
                  documentation afterwards. 
v0.5  2003/10/10  \@vS@iprocess -> \@vS@iprocess; 
                  \long\def\@Vs@iprocess. Sent to CTAN. 
v0.51 2003/10/15  Documentation: added `comment' drawback: 
                  \end{document} works in own line only. 
v0.52 2004/05/24  One `makro' -> `macro'. 
v0.53 2004/08/19  Named LPPL v1.3, added maintenance status. 
v0.54 2005/01/10  http://www.contact.uwe.lueck.de.vu, LPPL v1.3a. 
%% TODO: delete at higher stages!?