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
|
\documentclass[pagesize=auto, fontsize=12pt, DIV=10]{scrartcl}
\usepackage{fixltx2e}
\usepackage{etex}
\usepackage{xspace}
\usepackage{lmodern}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\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*{\opt}[1]{\texttt{#1}}
\addtokomafont{title}{\rmfamily}
\title{The \pkg{optional} package\thanks{This manual corresponds to \pkg{optional}~v2.2b, dated~2005/01/26.}}
\author{Donald Arseneau\thanks{\mail{asnd@triumf.ca}}}
\date{2005/01/26}
\begin{document}
\maketitle
\begin{abstract}
\noindent
Enable multiple versions of a document to be printed from one source file,
especially if most of the text is shared between versions.
\end{abstract}
\begin{quote}
\scriptsize
Copyright 1993, 1999, 2001, 2005 by Donald Arseneau (\mail{asnd@triumf.ca}).
This software is released under the terms of the \LaTeX\ Project Public
License (\url{ftp://ctan.tug.org/tex-archive/macros/latex/base/lppl.txt}).
(Essentially: Free to use, copy, distribute (sell) and change, but, if
changed, that fact must be made apparent to the user.) It has a
status of ``maintained''.
\end{quote}
\section{How to use}
One way to use this package is to declare (for example)
%
\begin{verbatim}
\usepackage[opta]{optional}
\end{verbatim}
%
at the beginning of your document, and flag optional text throughout
your document like:
%
\begin{verbatim}
\opt{opta}{Do this if option opta was declared}
\opt{optb}{Do this if option optb was declared}
\opt{optx,opty}{Do this if either option optx or opty}
\opt{}{Never print this text!}
\opt{opta}{\input{appendices}}
\optv{xam}{Type: \verb|[root /]$ rm -r *|.}
\end{verbatim}
%
Note that both the package option and the ``\cmd{\opt}'' argument can contain
lists of options although, in practice, one or the other should be a
single option name. Lists are allowed in both places to allow more
flexibility in the style of use. (But making the definitions much more
difficult, Grrr.)
Just as for ``\cmd{\includeonly}'', you will have to edit the main document
file to switch option codes (i.\,e.,\ change the ``\cmd{\usepackage}'' line).
There are, however, several ways to use this package without altering
the main document file: separate files, file-name sensing, interactive
prompting, and command-line option selection.
Typically, different versions of a document will require different
document class and package setup, besides the different tags for
\pkg{optional.sty}. In that case it is best to have a separate main file
for each version of the document. Each stub file will declare the
document class and load some packages (including this one) and then
input the rest of the document from a file common to all versions.
%
\begin{verbatim}
\documentclass[A0]{poster}
\usepackage[poster]{optional}
\input{my_paper}
\end{verbatim}
%
If the different opt-tags match the different stub file names (file
\texttt{poster.tex} will typeset the ``\opt{poster}'' version) then you can specify
%
\begin{verbatim}
\usepackage[\jobname]{optional}
\end{verbatim}
%
Alternatively, this ``\cmd{\jobname}'' technique can make use of symbolic links,
if your computer system supports them, by having a single main input
file accessed under different names (and different ``\cmd{\jobname}''s).
Another scheme is to invoke \LaTeX\ with the command line such as:
%
\begin{verbatim}
latex "\def\UseOption{opta,optb}\input{file}"
\end{verbatim}
%
(with quoting appropriate to your operating system) then options ``\opt{opta}''
and ``\opt{optb}'' will be used in addition to any options specified with the
``\cmd{\usepackage}'' command.
You can prompt yourself to specify the option(s) with every run
through \LaTeX:
%
\begin{verbatim}
\usepackage{optional}
\newcommand{\ExplainOptions}{man = users manual, check = checklist,
ref = reference card, post = poster.}
\AskOption
\end{verbatim}
%
The definition of ``\cmd{\ExplainOptions}'' is optional; it only serves to help
the person who answers the question. The ``\cmd{\AskOption}'' is also optional;
it will be executed automatically whenever optional.sty sees no list of
options. This method is too tedious to use much.
The normal restrictions forbidding special characters in package options
and reference tags apply also the the tags used by the ``\cmd{\opt}'' command.
These are not `comment' macros: The optional text must be well-formed
with balanced braces, even if not printed. The ``\cmd{\opt}'' command \emph{is}
completely `expandable' which means it is robust and can even be used
in messages (``\cmd{\typeout}'').
As usual, ``\cmd{\verb}'' commands and verbatim environments cannot be used
in the argument to ``\cmd{\opt}''. For this purpose there is a variant form
of ``\cmd{\opt}'' called ``\cmd{\optv}'' (optional verbatim) which may have a limited
class of verbatim material in the argument. It can do so by leaving
the braces around the argument, which may have undesired side effects.
For an ``\cmd{\optv}'' argument to be successfully ignored, the verbatim material
must have balanced braces etc.
The ``\cmd{\opt}'' command is only intended for small sections of text. If you
need to optionally include whole sections or chapters, put that material
in a separate file, and ``\cmd{\opt}''-ionally use an ``\cmd{\input}'' command:
%
\begin{verbatim}
\opt{internal}{\input{prog_listings}}
\end{verbatim}
\end{document}
|
