%      O P T I O N A L . S T Y            ver 2.0  April 1999
%
% 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 by Donald Arseneau (asnd@reg.triumf.ca).
% This software is released under the terms of the LaTeX Project Public 
% License  (ftp://ctan.tug.org/tex-archive/macros/latex/base/lppl.txt).
% (Essentially: Free to use, copy, distribute (sell) and change, but, if
% changed, the name must be changed.)
%
% HOW TO USE
% ~~~~~~~~~~
% 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}}
%
% 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, two ways to use this package without altering 
% the main document file: command-line option selection and interactive 
% prompting.
%
% If you invoke LaTeX with the command line:
%
%     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.
%
% Alternatively, 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 here also.
%
% These are not `comment' macros: The optional text must be well-formed
% with balanced braces, even if not printed.  It cannot contain any "\verb" 
% commands.  The "\opt" command *IS* completely `expandable' which means 
% it is robust and can even be used in messages ("\typeout").  
%
% 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}}
%
% DEFINITIONS

\ProvidesPackage{optional}[20/04/1999 ver 2.0; \space 
  Optional inclusion/omission]
% Initialize used-option-list to \@gobble to eat the comma when the first
% entry is `appended'.
\@ifundefined{UseOption}{\let\UseOption\@gobble}{}
\DeclareOption*{\edef\UseOption{\UseOption,\CurrentOption}}
\ProcessOptions
\AtBeginDocument{\Opl@Setup}

\newcommand*\opt[1]{\if\Opl@notlisted{#1}\expandafter\@gobble
   \else \expandafter\@firstofone \fi}

\newcommand\AskOption{%
 \@ifundefined{ExplainOptions}{}{\typeout{\ExplainOptions}}%
 \typein[\UseOption]{Specify which optional text to process:}%
 }

\def\Opl@Setup{%
 \ifx\UseOption\@gobble\AskOption\fi
 \let\Opl@notlisted\@empty % initialize list of checks
 \@for\@tempa:=\UseOption\do{%
   \ifx\@tempa\@empty\else\expandafter\Opl@oneop\expandafter{\@tempa}\fi}%
 \ifx\Opl@notlisted\@empty \PackageWarning{optional}%
   {No options were selected, so all optional text will be printed}%
   \let\opt\@secondoftwo
 \else
   \typeout{Using optional text marked with \UseOption. }%
   \toks@\expandafter{\Opl@notlisted}%
   \edef\@tempa{\def\noexpand\Opl@notlisted####1{,\the\toks@,}}\@tempa
 \fi
 \let\Opl@Setup\undefined \let\Opl@oneop\undefined
 \let\AskOption\undefined \let\ExplainOptions\undefined
}
\begingroup
\catcode`\Z= 3 % special delimiter
\gdef\Opl@oneop#1{%
 \@ifundefined{Opl@Match@#1}{%
   \toks@\expandafter{\Opl@notlisted}%
   \edef\Opl@notlisted{\the\toks@ \csname Opl@Match@#1\endcsname ,####1,#1,Z}%
  \@namedef{Opl@Match@#1}##1,#1,##2Z{##2}%
 }\relax
}
\endgroup

\endinput
