manual/optional.sty

   1 %
   2 % O P T I O N A L . S T Y
   3 % ~~~~~~~~~~~~~~~~~~~~~~~
   4 % ver 2.2b  Jan 2005
   5 %
   6 % Enable multiple versions of a document to be printed from one source file,
   7 % especially if most of the text is shared between versions.
   8 %
   9 % Copyright 1993,1999,2001,2005 by Donald Arseneau (asnd@triumf.ca).
  10 % This software is released under the terms of the LaTeX Project Public
  11 % License  (ftp://ctan.tug.org/tex-archive/macros/latex/base/lppl.txt).
  12 % (Essentially: Free to use, copy, distribute (sell) and change, but, if
  13 % changed, that fact must be made apparent to the user.)  It has a
  14 % status of "maintained".
  15 %
  16 %
  17 % HOW TO USE
  18 % ~~~~~~~~~~
  19 % One way to use this package is to declare (for example)
  20 %
  21 %     \usepackage[opta]{optional}
  22 %
  23 % at the beginning of your document, and flag optional text throughout
  24 % your document like:
  25 %
  26 %     \opt{opta}{Do this if option opta was declared}
  27 %     \opt{optb}{Do this if option optb was declared}
  28 %     \opt{optx,opty}{Do this if either option optx or opty}
  29 %     \opt{}{Never print this text!}
  30 %     \opt{opta}{\input{appendices}}
  31 %     \optv{xam}{Type: \verb|[root /]$ rm -r *|.}
  32 %
  33 % Note that both the package option and the "\opt" argument can contain
  34 % lists of options although, in practice, one or the other should be a
  35 % single option name.  Lists are allowed in both places to allow more
  36 % flexibility in the style of use. (But making the definitions much more
  37 % difficult, Grrr.)
  38 %
  39 % Just as for "\includeonly", you will have to edit the main document
  40 % file to switch option codes (i.e., change the "\usepackage" line).
  41 % There are, however, several ways to use this package without altering
  42 % the main document file: separate files, file-name sensing, interactive
  43 % prompting, and command-line option selection.
  44 %
  45 % Typically, different versions of a document will require different
  46 % document class and package setup, besides the different tags for
  47 % optional.sty.  In that case it is best to have a separate main file
  48 % for each version of the document.  Each stub file will declare the
  49 % document class and load some packages (including this one) and then
  50 % input the rest of the document from a file common to all versions.
  51 %
  52 %     \documentclass[A0]{poster}
  53 %     \usepackage[poster]{optional}
  54 %     \input{my_paper}
  55 %
  56 % If the different opt-tags match the different stub file names (file
  57 % poster.tex will typeset the "poster" version) then you can specify
  58 %
  59 %     \usepackage[\jobname]{optional}
  60 %
  61 % Alternatively, this "\jobname" technique can make use of symbolic links,
  62 % if your computer system supports them, by having a single main input
  63 % file accessed under different names (and different "\jobname"s).
  64 %
  65 % Another scheme is to invoke LaTeX with the command line such as:
  66 %
  67 %     latex "\def\UseOption{opta,optb}\input{file}"
  68 %
  69 % (with quoting appropriate to your operating system) then options "opta"
  70 % and "optb" will be used in addition to any options specified with the
  71 % "\usepackage" command.
  72 %
  73 % You can prompt yourself to specify the option(s) with every run
  74 % through LaTeX:
  75 %
  76 %     \usepackage{optional}
  77 %     \newcommand{\ExplainOptions}{man = users manual, check = checklist,
  78 %           ref = reference card, post = poster.}
  79 %     \AskOption
  80 %
  81 % The definition of "\ExplainOptions" is optional; it only serves to help
  82 % the person who answers the question.  The "\AskOption" is also optional;
  83 % it will be executed automatically whenever optional.sty sees no list of
  84 % options.  This method is too tedious to use much.
  85 %
  86 % The normal restrictions forbidding special characters in package options
  87 % and reference tags apply also the the tags used by the "\opt" command.
  88 %
  89 % These are not `comment' macros: The optional text must be well-formed
  90 % with balanced braces, even if not printed.  The "\opt" command *IS*
  91 % completely `expandable' which means  it is robust and can even be used
  92 % in messages ("\typeout").
  93 %
  94 % As usual, "\verb" commands and verbatim environments cannot be used
  95 % in the argument to "\opt".  For this purpose there is a variant form
  96 % of "\opt" called "\optv" (optional verbatim) which may have a limited
  97 % class of verbatim material in the argument.  It can do so by leaving
  98 % the braces around the argument, which may have undesired side effects.
  99 % For an "\optv" argument to be successfully ignored, the verbatim material
 100 % must have balanced braces etc.
 101 %
 102 % The "\opt" command is only intended for small sections of text.  If you
 103 % need to optionally include whole sections or chapters, put that material
 104 % in a separate file, and "\opt"-ionally use an "\input" command:
 105 %
 106 %     \opt{internal}{\input{prog_listings}}
 107 %
 108 %====================== END INSTRUCTIONS ========================
 109
 110 \ProvidesPackage{optional}[2005/01/26 ver 2.2b; \space
 111   Optional inclusion/omission]
 112 % Initialize used-option-list to \@gobble to eat the comma when the first
 113 % entry is `appended'.
 114 \@ifundefined{UseOption}{\let\UseOption\@gobble}{}
 115 \DeclareOption*{\edef\UseOption{\UseOption,\CurrentOption}}
 116 \ProcessOptions
 117 \AtBeginDocument{\Opl@Setup}
 118
 119 \newcommand*\opt[1]{\if\Opl@notlisted{#1}\expandafter\@gobble
 120    \else \expandafter\@firstofone \fi}
 121
 122 \newcommand*\optv[1]{\if\Opl@notlisted{#1}\expandafter\@gobble\fi}
 123
 124 % This initial definition forces immediate setup if \opt used in the preamble
 125 \def\Opl@notlisted{\fi \Opl@Setup \if\Opl@notlisted}
 126
 127 \newcommand\AskOption{%
 128  \@ifundefined{ExplainOptions}{}{\typeout{\ExplainOptions}}%
 129  \typein[\UseOption]{Specify which optional text to process:}%
 130  }
 131
 132 \def\Opl@Setup{%
 133  \ifx\UseOption\@gobble\AskOption\fi
 134  \let\Opl@notlisted\@empty % initialize list of checks
 135  \@for\@tempa:=\UseOption\do{%
 136    \ifx\@tempa\@empty\else\expandafter\Opl@oneop\expandafter{\@tempa}\fi}%
 137  \ifx\Opl@notlisted\@empty \PackageWarning{optional}%
 138    {No options were selected, so all optional text will be printed}%
 139    \let\opt\@secondoftwo
 140  \else
 141    \typeout{Using optional text marked with \UseOption. }%
 142    \toks@\expandafter{\Opl@notlisted}%
 143    \edef\@tempa{\def\noexpand\Opl@notlisted####1{,\the\toks@,}}\@tempa
 144  \fi
 145  \let\Opl@Setup\@empty \let\Opl@oneop\undefined
 146  \let\AskOption\undefined \let\ExplainOptions\undefined
 147 }
 148 \begingroup
 149 \catcode`\Z= 3 % special delimiter
 150 \gdef\Opl@oneop#1{%
 151  \@ifundefined{Opl@Match@#1}{%
 152    \toks@\expandafter{\Opl@notlisted}%
 153    \edef\Opl@notlisted{\the\toks@ \csname Opl@Match@#1\endcsname ,####1,#1,Z}%
 154   \@namedef{Opl@Match@#1}##1,#1,##2Z{##2}%
 155  }\relax
 156 }
 157 \endgroup
 158 \endinput