blob: 847589cb61fd389f2fe239d0461633531892662a [file] [log] [blame]
% O P T I O N A L . S T Y
% ~~~~~~~~~~~~~~~~~~~~~~~
% ver 2.2b Jan 2005
% Enable multiple versions of a document to be printed from one source file,
% especially if most of the text is shared between versions.
% Copyright 1993,1999,2001,2005 by Donald Arseneau (
% This software is released under the terms of the LaTeX Project Public
% License (
% (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".
% ~~~~~~~~~~
% One way to use this package is to declare (for example)
% \usepackage[opta]{optional}
% at the beginning of your document, and flag optional text throughout
% your document like:
% \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 *|.}
% Note that both the package option and the "\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 "\includeonly", you will have to edit the main document
% file to switch option codes (i.e., change the "\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
% 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.
% \documentclass[A0]{poster}
% \usepackage[poster]{optional}
% \input{my_paper}
% If the different opt-tags match the different stub file names (file
% poster.tex will typeset the "poster" version) then you can specify
% \usepackage[\jobname]{optional}
% Alternatively, this "\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 "\jobname"s).
% Another scheme is to invoke LaTeX with the command line such as:
% latex "\def\UseOption{opta,optb}\input{file}"
% (with quoting appropriate to your operating system) then options "opta"
% and "optb" will be used in addition to any options specified with the
% "\usepackage" command.
% You can prompt yourself to specify the option(s) with every run
% through LaTeX:
% \usepackage{optional}
% \newcommand{\ExplainOptions}{man = users manual, check = checklist,
% ref = reference card, post = poster.}
% \AskOption
% The definition of "\ExplainOptions" is optional; it only serves to help
% the person who answers the question. The "\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 "\opt" command.
% These are not `comment' macros: The optional text must be well-formed
% with balanced braces, even if not printed. The "\opt" command *IS*
% completely `expandable' which means it is robust and can even be used
% in messages ("\typeout").
% As usual, "\verb" commands and verbatim environments cannot be used
% in the argument to "\opt". For this purpose there is a variant form
% of "\opt" called "\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 "\optv" argument to be successfully ignored, the verbatim material
% must have balanced braces etc.
% The "\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 "\opt"-ionally use an "\input" command:
% \opt{internal}{\input{prog_listings}}
%====================== END INSTRUCTIONS ========================
\ProvidesPackage{optional}[2005/01/26 ver 2.2b; \space
Optional inclusion/omission]
% Initialize used-option-list to \@gobble to eat the comma when the first
% entry is `appended'.
\else \expandafter\@firstofone \fi}
% This initial definition forces immediate setup if \opt used in the preamble
\def\Opl@notlisted{\fi \Opl@Setup \if\Opl@notlisted}
\typein[\UseOption]{Specify which optional text to process:}%
\let\Opl@notlisted\@empty % initialize list of checks
\ifx\Opl@notlisted\@empty \PackageWarning{optional}%
{No options were selected, so all optional text will be printed}%
\typeout{Using optional text marked with \UseOption. }%
\let\Opl@Setup\@empty \let\Opl@oneop\undefined
\let\AskOption\undefined \let\ExplainOptions\undefined
\catcode`\Z= 3 % special delimiter
\edef\Opl@notlisted{\the\toks@ \csname Opl@Match@#1\endcsname ,####1,#1,Z}%