comment doc update (22feb09)

git-svn-id: svn://tug.org/texlive/trunk@17155 c570f23f-e606-0410-a88d-b1316a301751

6 files changed, 326 insertions, 78 deletions

diff --git a/Master/texmf-dist/doc/latex/comment/README b/Master/texmf-dist/doc/latex/comment/README
new file mode 100644
index 00000000000..068ba6f0dd0
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/comment/README
@@ -0,0 +1,3 @@
+files:
+comment.sty -- the latest version (August 1998)
+comm_latest.tex -- a LaTeX test file for comment.sty
diff --git a/Master/texmf-dist/doc/latex/comment/comm_latest.tex b/Master/texmf-dist/doc/latex/comment/comm_latest.tex
new file mode 100644
index 00000000000..4974f5f2f14
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/comment/comm_latest.tex
@@ -0,0 +1,81 @@
+% An illustration of comment.sty by Victor Eijkhout,
+% version 3.4 and later.
+%
+% For use with LaTeX2.09, and LaTeX2e in compatibility mode.
+%
+\documentstyle{article}
+\begin{document}
+
+\input comment.sty
+
+\includecomment{thisone}
+\excludecomment{notthisone}
+
+This sentence
+\begin{comment}
+has
+\end{comment}
+no verb.
+
+Check for\begin{notthisone}
+superfluous
+\end{notthisone}
+spaces (there should be none between `for' and `spaces'),
+and around
+\begin{thisone}
+inclusion
+\end{thisone}
+of proper texts (one space between `around' and `inclusion',
+and one between `inclusion' and `of').
+
+Als check for
+\begin{thisone}
+multiple paragraphs.
+
+Such as
+\end{thisone}
+here. (`Such as' should be a new paragraph.)
+
+% a test of the special comments
+\specialcomment{smallfry}{\begingroup\rmfamily\footnotesize}{\endgroup}
+%\tracingmacros=2 \tracingcommands=2
+This text is 
+\begin{smallfry}
+rather small
+\end{smallfry}
+don't you think? (The `rather small' should be footnotesize.)
+
+And now we disable
+\excludecomment{smallfry}
+\begin{smallfry}
+the special comment
+\end{smallfry}
+environment
+(in between `disable' and `environment' is some excluded material).
+
+% test of weird grouping
+We switch to
+\begin{thisone}
+\bf bold face
+\end{thisone}
+inside \rm a comment. (The phrase `bold face inside' should be bold.)
+
+\newcount\comlines
+\processcomment{countedcomment}
+ {\comlines=0\relax
+  \def\ThisComment##1{\global\advance\comlines1\relax}}
+ {}{**Comment: \number\comlines\ line(s) removed**}
+
+This is a line of text
+\begin{countedcomment}
+Oneline
+\end{countedcomment}
+another line of text
+\begin{countedcomment}
+One line
+Two line
+Three line
+\end{countedcomment}
+last line of text.
+
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/comment/comm_test_l.dvi b/Master/texmf-dist/doc/latex/comment/comm_test_l.dvi
deleted file mode 100644
index 2c574648f80..00000000000
--- a/Master/texmf-dist/doc/latex/comment/comm_test_l.dvi
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/comment/comm_test_l.tex b/Master/texmf-dist/doc/latex/comment/comm_test_l.tex
deleted file mode 100644
index ac9778b1763..00000000000
--- a/Master/texmf-dist/doc/latex/comment/comm_test_l.tex
+++ /dev/null
@@ -1,78 +0,0 @@
-% An illustration of comment.sty by Victor Eijkhout.
-% This file belongs to comment.sty version 3.0 or later,
-% it is meant to be used with LaTeX
-
-\documentstyle[comment]{article}
-\begin{document}
-
-\excludecomment{begone}
-
-\includecomment{thisone}
-\excludecomment{notthisone}
-
-% under development \leveledcomment{maybethis}{1}
-
-\parskip=20pt
-This sentence
-\begin{comment}
-has
-\end{comment}
-no verb.
-
-Check for\begin{notthisone}
-superfluous
-\end{notthisone}
-spaces, and
-\begin{thisone}
-inclusion
-\end{thisone}
-of proper texts.
-
-% a test of the special comments
-\newcount\comlines
-\processcomment{countedcomment}
- {\comlines=0\relax
-  \def\ThisComment##1{\global\advance\comlines1\relax}}
- {}{\endgraf **Comment: \number\comlines\ line(s) removed**\endgraf}
-
-This is a line of text
-\begin{countedcomment}
-Oneline
-\end{countedcomment}
-another line of text
-\begin{countedcomment}
-One line
-Two line
-Three line
-\end{countedcomment}
-last line of text
-
-Let's test paragraphs:
-\begin{notthisone}
-This one is missing.
-
-As is this one.
-\end{notthisone}
-For starters.
-
-On the other hand:
-\begin{thisone}
-This is one is present.
-
-As is this one.
-\end{thisone}
-And that's it.
-
-\begin{comment} % future project
-\maybethis 0
-Level zero.
-\endmaybethis
-\maybethis 1
-Level one.
-\endmaybethis
-\maybethis 2
-Level two.
-\endmaybethis
-\end{comment}
-
-\end{document}
diff --git a/Master/texmf-dist/doc/latex/comment/comment.pdf b/Master/texmf-dist/doc/latex/comment/comment.pdf
new file mode 100644
index 00000000000..cbf24fa173e
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/comment/comment.pdf
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}