%% VERSIONS.STY -- omit passages optionally under LaTeX --
%% Copyright (c) 2003--2005 by Uwe L"uck, Munich, Germany;
%% http://contact-ednotes.sty.de.vu,
\def\fileversion{0.55} \def\filedate{2005/04/28}
%% 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
\global %% v0.55, support for LaTeX < 1996/07/26 !?
%% (Cf. lineno.sty.)
\@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.
v0.55 2005/04/28 http://contact-ednotes.sty.de.vu;
\global\@ignorefalse.
%% TODO: delete at higher stages!?