diff options
author | Karl Berry <karl@freefriends.org> | 2010-02-23 00:21:51 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2010-02-23 00:21:51 +0000 |
commit | 92b847bdf8735e7e5bfa6fd55595cfe9c2d3d73c (patch) | |
tree | dc2691f166bc73a2f85887ae9b0c16393a251558 /Master/texmf-dist/doc/latex/comment/comment.tex | |
parent | 0e58934d8bef398085e805fac10f23c715adc69b (diff) |
comment doc update (22feb09)
git-svn-id: svn://tug.org/texlive/trunk@17155 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/comment/comment.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/comment/comment.tex | 242 |
1 files changed, 242 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/comment/comment.tex b/Master/texmf-dist/doc/latex/comment/comment.tex new file mode 100644 index 00000000000..0c1f3597896 --- /dev/null +++ b/Master/texmf-dist/doc/latex/comment/comment.tex @@ -0,0 +1,242 @@ +\documentclass[parskip=false, DIV=8, headings=normal, pagesize=auto]{scrartcl} + +\usepackage{fixltx2e} +\usepackage{etex} +\usepackage{xspace} +\usepackage{lmodern} +\usepackage[T1]{fontenc} +\usepackage{textcomp} +\usepackage{microtype} +\usepackage[unicode=true]{hyperref} + +\newenvironment*{noverb}{% + \flushleft + \vskip\parskip + \parskip=0pt\relax +}{% + \endflushleft +} + +\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*{\meta}[1]{\textlangle\textsl{#1}\textrangle} +\newcommand*{\marg}[1]{\texttt{\{}\meta{#1}\texttt{\}}} + +\addtokomafont{title}{\rmfamily} + +\title{The \pkg{comment} package\thanks{This manual corresponds to \pkg{comment}~v3.6, dated~October 1999.}} +\author{Victor Eijkhout\\\mail{victor@eijkhout.net}} +\date{October 1999} + + +\begin{document} + +\maketitle + +\section{Purpose:} + +selectively in/exclude pieces of text: the user can define new +comment versions, and each is controlled separately. +Special comments can be defined where the user specifies the +action that is to be taken with each comment line. + +This style can be used with plain \TeX\ or \LaTeX, and probably +most other packages too. + + +\section{Usage:} + +all text included between +% +\begin{verbatim} +\comment ... \endcomment +\end{verbatim} +% +or +% +\begin{verbatim} +\begin{comment} ... \end{comment} +\end{verbatim} +% +is discarded. + +The opening and closing commands should appear on a line +of their own. No starting spaces, nothing after it. +This environment should work with arbitrary amounts +of comment, and the comment can be arbitrary text. + +Other `\env{comment}' environments are defined by +and are selected/deselected with +% +\begin{verbatim} +\includecomment{versiona} +\excludecoment{versionb} +\end{verbatim} +% +These environments are used as +% +\begin{verbatim} +\versiona ... \endversiona +\end{verbatim} +% +or +% +\begin{verbatim} +\begin{versiona} ... \end{versiona} +\end{verbatim} +% +with the opening and closing commands again on a line of +their own. + +\pagebreak[1] + +\LaTeX\ users note: for an included comment, the +\cmd{\begin} and \cmd{\end} lines act as if they don't exist. +In particular, they don't imply grouping, so assignments +\&c are not local. + +\pagebreak[2] + +Special comments are defined as +% +\begin{noverb} +\cmd{\specialcomment}\marg{name}\marg{before commands}\marg{after commands} +\end{noverb} +% +where the second and third arguments are executed before +and after each comment block. You can use this for global +formatting commands. +To keep definitions \&c local, you can include \cmd{\begingroup} +in the `\meta{before commands}' and \cmd{\endgroup} in the `\meta{after commands}'. +ex: +% +\begin{verbatim} +\specialcomment{smalltt} + {\begingroup\ttfamily\footnotesize}{\endgroup} +\end{verbatim} +% +You do \emph{not} have to do an additional +% +\begin{verbatim} +\includecomment{smalltt} +\end{verbatim} +% +To remove `\env{smalltt}' blocks, give \verb+\excludecomment{smalltt}+ +after the definition. + +Processing comments can apply processing to each line. +% +\begin{noverb} +\cmd{\processcomment}\marg{name}\marg{each-line commands}\marg{before commands}\marg{after commands} +\end{noverb} +% +By defining a control sequence +% +\begin{verbatim} +\def\Thiscomment##1{...} +\end{verbatim} +% +in the before commands the user can +specify what is to be done with each comment line. +BUG this does not work quite yet BUG + +Trick for short in/exclude macros (such as \verb+\maybe{this snippet}+): +% +\begin{verbatim} +\includecomment{cond} +\newcommand{\maybe}[1]{} +\begin{cond} +\renewcommand{\maybe}[1]{#1} +\end{cond} +\end{verbatim} + + +\section{Basic approach of the implementation:} + +to comment something out, scoop up every line in verbatim mode +as macro argument, then throw it away. +For inclusions, in \LaTeX\ the block is written out to +a file \cmd{\CommentCutFile} (default ``\texttt{comment.cut}''), which is +then included. +In plain \TeX\ (and other formats) both the opening and +closing comands are defined as noop. + + +\section{Changes in version 3.1} + +\begin{itemize} +\item updated author's address +\item cleaned up some code +\item trailing contents on \cmd{\begin}\marg{env} line is always discarded + even if you've done \cmd{\includecomment}\marg{env} +\item comments no longer define grouping!! you can even + % +\begin{verbatim} +\includecomment{env} +\begin{env} +\begin{itemize} +\end{env} +\end{verbatim} + % + Isn't that something\ldots +\item included comments are written to file and input again. +\end{itemize} + + +\section{Changes in 3.2} + +\begin{itemize} +\item \cmd{\specialcomment} brought up to date (thanks to Ivo Welch). +\end{itemize} + + +\section{Changes in 3.3} + +\begin{itemize} +\item updated author's address again +\item parametrised \cmd{\CommentCutFile} +\end{itemize} + + +\section{Changes in 3.4} + +\begin{itemize} +\item added GNU public license +\item added \cmd{\processcomment}, because Ivo's fix (above) brought an + inconsistency to light. +\end{itemize} + + +\section{Changes in 3.5} + +\begin{itemize} +\item corrected typo in header. +\item changed author email +\item corrected \cmd{\specialcomment} yet again. +\item fixed excludecomment of an earlier defined environment. +\end{itemize} + + +\section{Changes in 3.6} + +\begin{itemize} +\item The `cut' file is now written more verbatim, using \cmd{\meaning}; + some people reported having trouble with ISO~latin~1, or \texttt{umlaute.sty}. +\item removed some \cmd{\newif} statements. + Has this suddenly become \cmd{\outer} again? +\end{itemize} + + +\section{Known bugs:} + +\begin{itemize} +\item \texttt{excludecomment} leads to one superfluous space +\item \texttt{processcomment} leads to a superfluous line break +\end{itemize} + +\end{document} |