summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/version/version-doc.tex
blob: 72b53341e2c79329edf07f8df34cd77c4f2385ab (plain)
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
\documentclass[pagesize=auto, fontsize=12pt, DIV=10]{scrartcl}

\usepackage{fixltx2e}
\usepackage{etex}
\usepackage{xspace}
\usepackage{lmodern}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage[svgnames]{xcolor}
\usepackage{listings}
\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*{\meta}[1]{\textlangle\textsl{#1}\textrangle}
\newcommand*{\marg}[1]{\texttt{\{}\meta{#1}\texttt{\}}}
\newcommand*{\oarg}[1]{\texttt{[}\meta{#1}\texttt{]}}

\addtokomafont{title}{\rmfamily}

\lstset{%
  language=[LaTeX]TeX,%
  columns=flexible,%
  upquote=true,%
  numbers=left,%
  basicstyle=\ttfamily,%
  keywordstyle=\color{Navy},%
  commentstyle=\color{DimGray},%
  stringstyle=\color{SeaGreen},%
  numberstyle=\scriptsize\color{SlateGray}%
}

\title{The \pkg{version} package\thanks{This manual corresponds to \pkg{version.sty}~v2.0, dated~2009/09/15.}}
\author{Donald Arseneau\thanks{\mail{asnd@triumf.ca}}\and Stephen Bellantoni}
\date{2009/09/15}


\begin{document}

\maketitle

\noindent
Version control macros. This package lets you define environments whose
contents will be optionally included in or excluded from the text when
you run \LaTeX.

Maybe you should be using one of \pkg{versions.sty}, \pkg{comment.sty}, or \pkg{optional.sty}.


\section{Usage:}

\begin{description}
\item[\cmd{\includeversion}\marg{name}] \leavevmode \\
  After this declaration, contents of the environment \meta{name}, that is,
  text between \cmd{\begin}\marg{name} and \cmd{\end}\marg{name}, will be processed in the 
  normal way.  If an environment called \meta{name} is already defined, that
  definition is retained; if no such environment exists a simple 
  definition is provided.

\item[\cmd{\excludeversion}\marg{name}] \leavevmode \\
  This indicates that text between \cmd{\begin}\marg{name} and \cmd{\end}\marg{name} will
  be totally deleted. Very long sections of excluded text might cause 
  a `\TeX\ capacity exceeded' error.  Exclusion ends with the first
  detected \cmd{\end}\marg{name}, even if there are additional \cmd{\begin}\marg{name} 
  declarations in the skipped text; that is, nesting of environments
  is not permitted.  Skipped text may have unbalanced braces, if
  they would also work in the \cmd{\includeversion} case.

\item[\cmd{\excludeversion}\oarg{text}\marg{name}] \leavevmode \\
  This indicates that text between \cmd{\begin}\marg{name} and \cmd{\end}\marg{name} will
  be replaced by the specified \meta{text}.
\end{description}

You can define environments for as many versions as you want.
A `\env{comment}' environment has already been pre-defined with
\verb+\excludeversion{comment}+; you can override this by declaring 
\verb+\includeversion{comment}+.


\section{Example:}

\begin{lstlisting}
\includeversion{abridged}\excludeversion{unabridged}
\excludeversion[(redacted)]{redact}
Text for the
\begin{abridged}
   short
\end{abridged}
\begin{unabridged}
   long and really longwinded, opaque and boring
\end{unabridged}
version of the paper. Punctuation works correctly\begin{unabridged}
because sphack is used\end{unabridged}.
\begin{comment} This is deleted by default. \end{comment}
\begin{redact}This information was withdrawn\end{redact}
\end{lstlisting}

\end{document}