diff options
Diffstat (limited to 'Master/texmf-dist')
| -rw-r--r-- | Master/texmf-dist/doc/latex/versions/versions-doc.pdf | bin | 0 -> 348924 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/versions/versions-doc.tex | 271 |
2 files changed, 271 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/versions/versions-doc.pdf b/Master/texmf-dist/doc/latex/versions/versions-doc.pdf Binary files differnew file mode 100644 index 00000000000..4c04085ff51 --- /dev/null +++ b/Master/texmf-dist/doc/latex/versions/versions-doc.pdf diff --git a/Master/texmf-dist/doc/latex/versions/versions-doc.tex b/Master/texmf-dist/doc/latex/versions/versions-doc.tex new file mode 100644 index 00000000000..68d3e289416 --- /dev/null +++ b/Master/texmf-dist/doc/latex/versions/versions-doc.tex @@ -0,0 +1,271 @@ +\documentclass[pagesize=auto]{scrartcl} + +\usepackage{fixltx2e} +\usepackage{etex} +\usepackage{lmodern} +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage{textcomp} +\usepackage{hologo} +\usepackage{framed} +\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*{\env}[1]{\texttt{#1}} +\newcommand*{\opt}[1]{\texttt{#1}} +\newcommand*{\meta}[1]{\textlangle\textsl{#1}\textrangle} +\newcommand*{\marg}[1]{\texttt{\{}\meta{#1}\texttt{\}}} +\newcommand*{\oarg}[1]{\texttt{[}\meta{#1}\texttt{]}} + +\addtokomafont{title}{\rmfamily} + +\title{The \pkg{versions} package\thanks{This manual corresponds to \pkg{versions.sty}~v0.55, dated~2005/04/28.}} +\subtitle{Omit passages optionally under \LaTeX} +\author{Uwe Lück\thanks{\url{http://contact-ednotes.sty.de.vu}}} +\date{2005/04/28} + + +\begin{document} + +\maketitle + +\section{Legal matters:} + +Released under the terms of the \LaTeX\ Project Public License +(\url{ftp://ctan.tug.org/tex-archive/macros/latex/base/lppl.txt} +version~1.3a; +essentially: Free to use, copy, distribute [sell] and change, +but, if changed, the name must be changed; \emph{no warranty}). +For copyright see above. + +This file has the LPPL maintenance status ``author-maintained''. +The Current Maintainer of this file is Uwe Lück. + + +\section{Short description:} +\label{sec:short} + +Varies Stephen Bellantoni's `\pkg{version.sty}' in optionally omitting +environments, defining (among others) \cmd{\includeversion} and +\cmd{\excludeversion} as well as a `\env{comment}' environment. (For comparison +to `\pkg{version.sty}', see Section `\hyperref[sec:version]{Improvements}' below.) So +multiple versions of a document may be printed from one source file. +Cf.~packages `\pkg{comment}' (very similar functions and more, see +\hyperref[sec:comment]{comparison} below), `\pkg{verbatim}', `\pkg{optional}' (on CTAN). +---Needs \LaTeX, even should work with \LaTeX 2.09 +(please tell me if not). + + +\section{Usage:} + +\subsection{User commands:} +\label{sec:user} + +In the document part of your source file, put into environments +\cmd{\begin}\marg{version} \meta{code} \cmd{\end}\marg{version} +passages \meta{code} (or other code) to be omitted optionally. \meta{version} may +be any string consisting of character tokens (see \TeX book, p.~40: +`\cmd{\csname}'), and the document may contain environments with several +names of this kind (\env{VERSIONa}, \env{VERSIONb}, etc.). Preceding +\cmd{\excludeversion}\marg{version}, \cmd{\includeversion}\marg{version}, +\cmd{\markversion}\marg{version} +(in the preamble or even later on) control how these environments +behave. +% +\begin{labeling}{\cmd{\excludeversion}\marg{version}} +\item[\cmd{\excludeversion}\marg{version}] `\meta{version}' environments just not + processed (ignored, i.\,e.); +\item[\cmd{\includeversion}\marg{version}] `\meta{version}' environments processed as + if \cmd{\begin}\marg{version} and \cmd{\end}\marg{version} + just were not present, however they + form groups like + \verb+\begin{relax}+\meta{code}\verb+\end{relax}+ + or \cmd{\begingroup} \meta{code} \cmd{\endgroup}. +\item[\cmd{\markversion}\marg{version}] `\meta{version}' environments processed, + resulting text may be marked in + printout---for comparison of + variants of your document, e.\,g. +\end{labeling} +% +By default, these three commands send a message to screen, and +\cmd{\markversion}\marg{version} results in printed marks indicating start, +\cmd{\end}, and `\meta{version}'. Cf.~subsection `\hyperref[sec:customize]{Customize}' below. +A warning is sent to screen if `\meta{version}' has been defined earlier +(by \LaTeX, e.\,g.). (A `\meta{version}' environment must not overlap with +other environments, of course, must be balanced with respect to +\cs{if\dots}\cs{fi}, and must not contain \cmd{\outer} macros. In \LaTeX\ the only +\cmd{\outer} macro is \verb+^^L+---\textsc{ascii} form feed.) +TODO: +(`\pkg{comment.sty}' and \env{comment} environment from `\pkg{verbatim.sty}' +are superior concerning \cmd{\outer} macros. On request, I could +equip my \cmd{\processifversion} with that \cmd{\outer} feature.) + +However, \cmd{\begin}\marg{version}\dots\cmd{\end}\marg{version} breaks inside macro +arguments, e.g. of \cmd{\footnote} (it is even fragile). So there is +\cmd{\processifversion}\marg{version}\marg{code} +working analogously (grouping as well), depending on \cmd{\excludeversion} +etc.\ (it is even robust). (`\pkg{optional.sty}' works similarly.) + +A pre-installed instance of `\meta{version}' is `\env{comment}', which is +ignored by default. So you may put rather long comments as \meta{code} +in \verb+\begin{comment}+\meta{code}\verb+\end{comment}+. (This feature serves +compatibility with Stephen Bellantoni's `\pkg{version.sty}'.) +Note that alternative packages `\pkg{comment}' and `\pkg{verbatim}' define +\cmd{\comment} as well. + + +\subsection{Options:} + +\verb+\usepackage[tracing]{versions}+ +causes (i)~checking package commands for undefinedness, +(ii)~messages on screen indicating line numbers of single excluded +environments (`Ignore \meta{version}, lines \meta{xx} to \meta{yy}]'). If final line +number and closing bracket don't appear on screen, the environment +presumably contains (implicit) \cs{fi} or \cs{if\dots} not matching each other +within that environment. This package option needs \LaTeXe\ and +\TeX\ version greater equal~3.0\@. (No change of \cmd{\processifversion}.) + +\verb+\usepackage[nogroup]{versions}+ +provides a user command \cmd{\includeversionno\-group}\marg{version} working like +\cmd{\includeversion}\marg{version}, but included `\meta{version}' will form no +grouping. + + +\subsection{Customize:} +\label{sec:customize} + +\sloppy +To change messages from \cmd{\excludeversion}, \cmd{\includeversion}, +\cmd{\markversion}, or to change printed marks resulting from +\cmd{\markversion}, take some of the following lines into your file, +remove left hand comment marks (`\verb+%+'), and change the definition. +(Must perhaps be enclosed in \cmd{\makeatletter}\dots\cmd{\makeatother} +or \verb+\catcode`\@=12+ \dots \verb+\catcode`\@=11+.) +% +\begin{verbatim} +\renewcommand\versionmessage[2]{\typeout{*** `#1' #2. ***}} +\renewcommand\beginmarkversion{\@Vs@sffbox{\@currenvir$>$}} +\renewcommand\endmarkversion{\@Vs@sffbox{$<$\@currenvir}} +\end{verbatim} +% +(For \LaTeXe, replace \cmd{\renewcommand} by \cmd{\renewcommand*}.) + +\fussy +\renewcommand*{\labelenumi}{(\theenumi)} +\begin{enumerate} +\item \cmd{\versionmessage} is the style of screen reports from + \cmd{\excludeversion} etc. Any redefinition must use two arguments. + The first is the version name (\meta{version}), the second is one out of + `\texttt{excluded}', `\texttt{included}', `\texttt{included with marks}'. + +\item \cmd{\beginmarkversion} and \cmd{\endmarkversion} is the style of marks + surrounding environments `\meta{version}' after \cmd{\markversion}\marg{version}. + Any redefinition must use no argument. \cmd{\@currenvir} is `\meta{version}'. + \cmd{\@Vs@sffbox}\marg{code} as in package definition typesets argument CODE + as \cmd{\textsf}\marg{code} and puts into an \cmd{\fbox}. +\end{enumerate} + + +\subsection{General warnings:} + +(For legal warnings see top of file, for errors and requirements see `\hyperref[sec:short]{Short description}', +option `\opt{tracing}' and `\hyperref[sec:user]{user commands}' above.) +This package uses \cmd{\includeversion} and \cmd{\excludeversion} and thus +cannot be used at the same time as Stephen Bellantoni's +`\pkg{version.sty}'. + +\begin{framed} + Please send bug reports and other comments to above e-mail address! +\end{framed} + + +\section{Comparison with Viktor Eijkhout's `\pkg{comment.sty}':} +\label{sec:comment} + +`\pkg{Comment}' even works under \hologo{plainTeX} as well as \LaTeX, present package +under \LaTeX\ only. \cmd{\specialcomment} in `\pkg{comment}' supports special +surroundings---this is missing here (but could easily be supplied on +request). +Included environments never form groups in `\pkg{comment}', here user may +choose whether they form groups or not, at least for simple including +(not with marks). `\pkg{comment}' includes by writing on and reading from +disk, present package needs no writing on disk. +Unlike the present package, `\pkg{comment}' skips even \cmd{\outer} macros, +\cs{if\dots}'s and \cs{fi}'s. (So `\pkg{comment}' is better for ``real'' comments. +---Concerning \cmd{\outer}, this feature is important for \hologo{plainTeX}, while +under \LaTeX\ the only \cmd{\outer} macro usually is \verb+^^L+.) +`\pkg{Comment}' sometimes produces wrong spaces +and discovers `\verb+\end{comment}+' only if nothing else is in the input +line. + + +\section{Improvements vis-a-vis Stephen Bellantoni's `\pkg{version.sty}':} +\label{sec:version} + +\begin{itemize} +\item \cmd{\processifversion} added for excluding text inside arguments of, + e.\,g., \cmd{\footnote} (where excluding \emph{environment} would break). + \cmd{\processifversion} is even robust. +\item \cmd{\@Esphack} instead of \cmd{\@esphack} at \cs{end} of excluded environment; + needed for properly processing input space symbols there. +\item \cmd{\begin} and \cmd{\end} of included environment may appear in separate + lines without doubling spaces (\cmd{\@bsphack} and \cmd{\@esphack} used). +\item Screen messages sent by \cmd{\includeversion} and \cmd{\excludeversion}. +\item Large passages don't fill main memory when excluded. + (`s' in `\pkg{versions}' means `safe'!) +\item Optional tracing of excluded environments added. +\item Option of including without grouping. +\item Original \cmd{\gdef} and \verb+\csname #1END@NOTE\endcsname+ in + \cmd{\excludeversion} were superfluous. +\end{itemize} + + +\section{Version history:} + +\newcommand*{\ver}{} +\def\ver#1.#2 #3.{\rlap{#1.#2}\hphantom{v0.00} #3} +\begin{labeling}{\ver v0.55 2005/04/28.} +\item[\ver v0.1 2003/09/29.] Very first; + sent to Donald, Victor, Christian, Volker. +\item[\ver v0.2 2003/09/30.] \cmd{\@sV@iffalse} replacing \verb+\csname iffalse\fi+; + \cmd{\@sV@ex}: \cmd{\@Esphack} in group, extra \cmd{\ignorespaces}. +\item[\ver v0.3 2003/10/01.] Documentation: added warnings about \cs{if\dots} \cs{fi} and + \cmd{\outer}---thanks to Victor Eijkhout; sent it to him. +\item[\ver v0.31 2003/10/03.] Documentation: added that `\pkg{comment.sty}' and + `\pkg{verbatim.sty}' are superior in the respect + discussed above; also added comparison with + `\pkg{comment.sty}'. +\item[\ver v0.4 2003/10/06.] Documentation: Replaced stupid proposal of + \cmd{\aftergroup} for including (needs stack!); + retreated offer of partially enable skipping \\ + \cmd{\outer}/\cs{if\dots}/\cs{fi}. (\cmd{\process\dots} typically comes too + late to change category codes.) \\ + \cmd{\xdef} $\to$ \cmd{\gdef} for \cmd{\@sV@ex}. + Then changed all `\texttt{@sV}' into `\texttt{@Vs}'. + Documentation: Referred to \TeX book for character + tokens in version names. + Removed \cmd{\@Vs@sphgobble} from \cmd{\@Vs@iprocess} (leave + spacing to user); now robust without \cmd{\Declare\dots} \\ + Then `\texttt{phgobble}' $\to$ `\texttt{phnoop}'. + Added option `\opt{nogroup}'. + Added \cmd{\nor\-malfont} in \cmd{\@Vs@sffbox}. + Sent to Victor E. 2005/10/05; minor changes in + documentation afterwards. +\item[\ver v0.5 2003/10/10.] \cmd{\@vS@iprocess} $\to$ \cmd{\@vS@iprocess}; + \verb+\long\def\@Vs@iprocess+. Sent to CTAN. +\item[\ver v0.51 2003/10/15.] Documentation: added `\pkg{comment}' drawback: + \verb+\end{document}+ works in own line only. +\item[\ver v0.52 2004/05/24.] One `makro' $\to$ `macro'. +\item[\ver v0.53 2004/08/19.] Named LPPL~v1.3, added maintenance status. +\item[\ver v0.54 2005/01/10.] \url{http://www.contact.uwe.lueck.de.vu}, LPPL v1.3a. +\item[\ver v0.55 2005/04/28.] \url{http://contact-ednotes.sty.de.vu}; + \verb+\global\@ignorefalse+. +\end{labeling} + +\end{document} |