\documentclass[pagesize=auto]{scrartcl}

\usepackage{fixltx2e}
\usepackage{etex}
\usepackage{lmodern}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{textcomp}
\usepackage{hologo}
\usepackage{framed}
\usepackage{microtype}
\usepackage{hyperref}

\newcommand*{\mail}[1]{\href{mailto:#1}{\texttt{#1}}}
\newcommand*{\pkg}[1]{\textsf{#1}}
\newcommand*{\cs}[1]{\texttt{\textbackslash#1}}
\makeatletter
\newcommand*{\cmd}[1]{\cs{\expandafter\@gobble\string#1}}
\makeatother
\newcommand*{\env}[1]{\texttt{#1}}
\newcommand*{\opt}[1]{\texttt{#1}}
\newcommand*{\meta}[1]{\textlangle\textsl{#1}\textrangle}
\newcommand*{\marg}[1]{\texttt{\{}\meta{#1}\texttt{\}}}
\newcommand*{\oarg}[1]{\texttt{[}\meta{#1}\texttt{]}}

\addtokomafont{title}{\rmfamily}

\title{The \pkg{versions} package\thanks{This manual corresponds to \pkg{versions.sty}~v0.55, dated~2005/04/28.}}
\subtitle{Omit passages optionally under \LaTeX}
\author{Uwe Lück\thanks{\url{http://contact-ednotes.sty.de.vu}}}
\date{2005/04/28}


\begin{document}

\maketitle

\section{Legal matters:}

Released under the terms of the \LaTeX\ Project Public License
(\url{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; \emph{no warranty}).
For copyright see above.

This file has the LPPL maintenance status ``author-maintained''.
The Current Maintainer of this file is Uwe Lück.


\section{Short description:}
\label{sec:short}

Varies Stephen Bellantoni's `\pkg{version.sty}' in optionally omitting
environments, defining (among others) \cmd{\includeversion} and
\cmd{\excludeversion} as well as a `\env{comment}' environment. (For comparison
to `\pkg{version.sty}', see Section `\hyperref[sec:version]{Improvements}' below.) So
multiple versions of a document may be printed from one source file.
Cf.~packages `\pkg{comment}' (very similar functions and more, see
\hyperref[sec:comment]{comparison} below), `\pkg{verbatim}', `\pkg{optional}' (on CTAN).
---Needs \LaTeX, even should work with \LaTeX 2.09
(please tell me if not).


\section{Usage:}

\subsection{User commands:}
\label{sec:user}

In the document part of your source file, put into environments
\cmd{\begin}\marg{version} \meta{code} \cmd{\end}\marg{version}
passages \meta{code} (or other code) to be omitted optionally. \meta{version} may
be any string consisting of character tokens (see \TeX book, p.~40:
`\cmd{\csname}'), and the document may  contain environments with several
names of this kind (\env{VERSIONa}, \env{VERSIONb}, etc.). Preceding
\cmd{\excludeversion}\marg{version}, \cmd{\includeversion}\marg{version},
\cmd{\markversion}\marg{version}
(in the preamble or even later on) control how these environments
behave.
%
\begin{labeling}{\cmd{\excludeversion}\marg{version}}
\item[\cmd{\excludeversion}\marg{version}] `\meta{version}' environments just not
  processed (ignored, i.\,e.);
\item[\cmd{\includeversion}\marg{version}] `\meta{version}' environments processed as
  if \cmd{\begin}\marg{version} and \cmd{\end}\marg{version}
  just were not present, however they
  form groups like
  \verb+\begin{relax}+\meta{code}\verb+\end{relax}+
  or \cmd{\begingroup} \meta{code} \cmd{\endgroup}.
\item[\cmd{\markversion}\marg{version}] `\meta{version}' environments processed,
  resulting text may be marked in
  printout---for comparison of
  variants of your document, e.\,g.
\end{labeling}
%
By default, these three commands send a message to screen, and
\cmd{\markversion}\marg{version} results in printed marks indicating start,
\cmd{\end}, and `\meta{version}'. Cf.~subsection `\hyperref[sec:customize]{Customize}' below.
A warning is sent to screen if `\meta{version}' has been defined earlier
(by \LaTeX, e.\,g.). (A `\meta{version}' environment must not overlap with
other environments, of course, must be balanced with respect to
\cs{if\dots}\cs{fi}, and must not contain \cmd{\outer} macros. In \LaTeX\ the only
\cmd{\outer} macro is \verb+^^L+---\textsc{ascii} form feed.)
TODO:
(`\pkg{comment.sty}' and \env{comment} environment from `\pkg{verbatim.sty}'
are superior concerning \cmd{\outer} macros. On request, I could
equip my \cmd{\processifversion} with that \cmd{\outer} feature.)

However, \cmd{\begin}\marg{version}\dots\cmd{\end}\marg{version} breaks inside macro
arguments, e.g. of \cmd{\footnote} (it is even fragile). So there is
\cmd{\processifversion}\marg{version}\marg{code}
working analogously (grouping as well), depending on \cmd{\excludeversion}
etc.\ (it is even robust). (`\pkg{optional.sty}' works similarly.)

A pre-installed instance of `\meta{version}' is `\env{comment}', which is
ignored by default. So you may put rather long comments as \meta{code}
in \verb+\begin{comment}+\meta{code}\verb+\end{comment}+. (This feature serves
compatibility with Stephen Bellantoni's `\pkg{version.sty}'.)
Note that alternative packages `\pkg{comment}' and `\pkg{verbatim}' define
\cmd{\comment} as well.


\subsection{Options:}

\verb+\usepackage[tracing]{versions}+
causes (i)~checking package commands for undefinedness,
(ii)~messages on screen indicating line numbers of single excluded
environments (`Ignore \meta{version}, lines \meta{xx} to \meta{yy}]'). If final line
number and closing bracket don't appear on screen, the environment
presumably contains (implicit) \cs{fi} or \cs{if\dots} not matching each other
within that environment. This package option needs \LaTeXe\ and
\TeX\ version greater equal~3.0\@. (No change of \cmd{\processifversion}.)

\verb+\usepackage[nogroup]{versions}+
provides a user command \cmd{\includeversionno\-group}\marg{version} working like
\cmd{\includeversion}\marg{version}, but included `\meta{version}' will form no
grouping.


\subsection{Customize:}
\label{sec:customize}

\sloppy
To change messages from \cmd{\excludeversion}, \cmd{\includeversion},
\cmd{\markversion}, or to change printed marks resulting from
\cmd{\markversion}, take some of the following lines into your file,
remove left hand comment marks (`\verb+%+'), and change the definition.
(Must perhaps be enclosed in \cmd{\makeatletter}\dots\cmd{\makeatother}
or \verb+\catcode`\@=12+ \dots \verb+\catcode`\@=11+.)
%
\begin{verbatim}
\renewcommand\versionmessage[2]{\typeout{*** `#1' #2. ***}}
\renewcommand\beginmarkversion{\@Vs@sffbox{\@currenvir$>$}}
\renewcommand\endmarkversion{\@Vs@sffbox{$<$\@currenvir}}
\end{verbatim}
%
(For \LaTeXe, replace \cmd{\renewcommand} by \cmd{\renewcommand*}.)

\fussy
\renewcommand*{\labelenumi}{(\theenumi)}
\begin{enumerate}
\item \cmd{\versionmessage} is the style of screen reports from
  \cmd{\excludeversion} etc. Any redefinition must use two arguments.
  The first is the version name (\meta{version}), the second is one out of
  `\texttt{excluded}', `\texttt{included}', `\texttt{included with marks}'.

\item \cmd{\beginmarkversion} and \cmd{\endmarkversion} is the style of marks
  surrounding environments `\meta{version}' after \cmd{\markversion}\marg{version}.
  Any redefinition must use no argument. \cmd{\@currenvir} is `\meta{version}'.
  \cmd{\@Vs@sffbox}\marg{code} as in package definition typesets argument CODE
  as \cmd{\textsf}\marg{code} and puts into an \cmd{\fbox}.
\end{enumerate}


\subsection{General warnings:}

(For legal warnings see top of file, for errors and requirements see `\hyperref[sec:short]{Short description}',
option `\opt{tracing}' and `\hyperref[sec:user]{user commands}' above.)
This package uses \cmd{\includeversion} and \cmd{\excludeversion} and thus
cannot be used at the same time as Stephen Bellantoni's
`\pkg{version.sty}'.

\begin{framed}
  Please send bug reports and other comments to above e-mail address!
\end{framed}


\section{Comparison with Viktor Eijkhout's `\pkg{comment.sty}':}
\label{sec:comment}

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


\section{Improvements vis-a-vis Stephen Bellantoni's `\pkg{version.sty}':}
\label{sec:version}

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


\section{Version history:}

\newcommand*{\ver}{}
\def\ver#1.#2 #3.{\rlap{#1.#2}\hphantom{v0.00} #3}
\begin{labeling}{\ver v0.55 2005/04/28.}
\item[\ver v0.1  2003/09/29.]  Very first;
  sent to Donald, Victor, Christian, Volker.
\item[\ver v0.2  2003/09/30.]  \cmd{\@sV@iffalse} replacing \verb+\csname iffalse\fi+;
  \cmd{\@sV@ex}: \cmd{\@Esphack} in group, extra \cmd{\ignorespaces}.
\item[\ver v0.3  2003/10/01.]  Documentation: added warnings about \cs{if\dots} \cs{fi} and
  \cmd{\outer}---thanks to Victor Eijkhout; sent it to him.
\item[\ver v0.31 2003/10/03.]  Documentation: added that `\pkg{comment.sty}' and
  `\pkg{verbatim.sty}' are superior in the respect
  discussed above; also added comparison with
  `\pkg{comment.sty}'.
\item[\ver v0.4  2003/10/06.]  Documentation: Replaced stupid proposal of
  \cmd{\aftergroup} for including (needs stack!);
  retreated offer of partially enable skipping \\
  \cmd{\outer}/\cs{if\dots}/\cs{fi}. (\cmd{\process\dots} typically comes too
  late to change category codes.) \\
  \cmd{\xdef} $\to$ \cmd{\gdef} for \cmd{\@sV@ex}.
  Then changed all `\texttt{@sV}' into `\texttt{@Vs}'.
  Documentation: Referred to \TeX book for character
  tokens in version names.
  Removed \cmd{\@Vs@sphgobble} from \cmd{\@Vs@iprocess} (leave
  spacing to user); now robust without \cmd{\Declare\dots} \\
  Then `\texttt{phgobble}' $\to$ `\texttt{phnoop}'.
  Added option `\opt{nogroup}'.
  Added \cmd{\nor\-malfont} in \cmd{\@Vs@sffbox}.
  Sent to Victor E. 2005/10/05; minor changes in
  documentation afterwards.
\item[\ver v0.5  2003/10/10.]  \cmd{\@vS@iprocess} $\to$ \cmd{\@vS@iprocess};
  \verb+\long\def\@Vs@iprocess+. Sent to CTAN.
\item[\ver v0.51 2003/10/15.]  Documentation: added `\pkg{comment}' drawback:
  \verb+\end{document}+ works in own line only.
\item[\ver v0.52 2004/05/24.]  One `makro' $\to$ `macro'.
\item[\ver v0.53 2004/08/19.]  Named LPPL~v1.3, added maintenance status.
\item[\ver v0.54 2005/01/10.]  \url{http://www.contact.uwe.lueck.de.vu}, LPPL v1.3a.
\item[\ver v0.55 2005/04/28.]  \url{http://contact-ednotes.sty.de.vu};
  \verb+\global\@ignorefalse+.
\end{labeling}

\end{document}