From 3aab32591e4dcaddfffd6cca2b84919eb453cfa5 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 6 May 2010 16:19:56 +0000 Subject: doc + separate package optional (3may10) git-svn-id: svn://tug.org/texlive/trunk@18131 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/optional/optional.pdf | Bin 0 -> 303670 bytes Master/texmf-dist/doc/latex/optional/optional.tex | 154 ++++++++++++++++++++++ 2 files changed, 154 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/optional/optional.pdf create mode 100644 Master/texmf-dist/doc/latex/optional/optional.tex (limited to 'Master/texmf-dist/doc') diff --git a/Master/texmf-dist/doc/latex/optional/optional.pdf b/Master/texmf-dist/doc/latex/optional/optional.pdf new file mode 100644 index 00000000000..102c135aa31 Binary files /dev/null and b/Master/texmf-dist/doc/latex/optional/optional.pdf differ diff --git a/Master/texmf-dist/doc/latex/optional/optional.tex b/Master/texmf-dist/doc/latex/optional/optional.tex new file mode 100644 index 00000000000..1e3cabba56f --- /dev/null +++ b/Master/texmf-dist/doc/latex/optional/optional.tex @@ -0,0 +1,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} -- cgit v1.2.3