1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
|
\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}
|
