comment (24jan14)

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

1 files changed, 143 insertions, 145 deletions

diff --git a/Master/texmf-dist/tex/latex/comment/comment.sty b/Master/texmf-dist/tex/latex/comment/comment.sty
index 658686fb80b..7f7c2be5a98 100644
--- a/Master/texmf-dist/tex/latex/comment/comment.sty
+++ b/Master/texmf-dist/tex/latex/comment/comment.sty
@@ -1,5 +1,6 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Comment.sty   version 3.6, October 1999
+% Comment.sty   version 3.7, July 2009
+% copyright 1998-2009 Victor Eijkhout
 %
 % Purpose:
 % selectively in/exclude pieces of text: the user can define new
@@ -9,10 +10,9 @@
 %
 % Author
 %    Victor Eijkhout
-%    Department of Computer Science
-%    University of Tennessee
-%    107 Ayres Hall
-%    Knoxville TN 37996
+%    Texas Advanced Computing Center
+%    The University of Texas at Austin
+%    Austin TX 78758
 %    USA
 %
 %    victor@eijkhout.net
@@ -34,12 +34,11 @@
 % http://www.gnu.org/copyleft/gpl.html
 %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% This style can be used with plain TeX or LaTeX, and probably
-% most other packages too.
 %
 % Usage: all text included between
-%    \comment ... \endcomment
-% or \begin{comment} ... \end{comment}
+%   \begin{comment}
+%   ...
+%   \end{comment}
 % is discarded. 
 %
 % The opening and closing commands should appear on a line
@@ -53,16 +52,23 @@
 % \excludecoment{versionb}
 %
 % These environments are used as
-% \versiona ... \endversiona
-% or \begin{versiona} ... \end{versiona}
+% \begin{versiona} ... \end{versiona}
 % with the opening and closing commands again on a line of 
 % their own.
 %
-% LaTeX users note: for an included comment, the
+% This is not a LaTeX environment: for an included comment, the
 % \begin and \end lines act as if they don't exist.
 % In particular, they don't imply grouping, so assignments 
 % &c are not local.
 %
+%%
+%% Guide to special effects
+%%
+% To understand what happens here, you need to know just a bit about
+% the implementation. Lines inside a comment are scooped up one at a
+% time, and written to an external file. This file can then be
+% included, or ignored. Or you can do stuff with it as you'll see now.
+%
 % Special comments are defined as
 % \specialcomment{name}{before commands}{after commands}
 % where the second and third arguments are executed before
@@ -73,18 +79,45 @@
 % ex:
 % \specialcomment{smalltt}
 %     {\begingroup\ttfamily\footnotesize}{\endgroup}
-% You do *not* have to do an additional
+% Of course, in this case you could probably have used the standard
+% LaTeX \newenvironment.
+%
+% With \specialcomment you do *not* have to do an additional
 % \includecomment{smalltt}
 % To remove 'smalltt' blocks, give \excludecomment{smalltt}
 % after the definition.
 %
-% Processing comments can apply processing to each line.
-% \processcomment{name}{each-line commands}%
-%    {before commands}{after commands}
+% The comment environments use two auxiliary commands. You can get
+% nifty special effects by redefining them.
+% 1/ the commented text is written to an external file. Default definition:
+%   \def\CommentCutFile{comment.cut}
+% 2/ included comments are processed like this:
+%   \def\ProcessCutFile{\input{\CommentCutFile}\relax}
+% and excluded files have
+%   \def\ProcessCutFile{}
+%
+% Fun use of special comments: the inclusion of the comment is done
+% by \ProcessCutFile, so you can redefine that:
+% \specialcomment{mathexamplewithcode}
+%  {\begingroup\def\ProcessCutFile{}} %1
+%  {\verbatiminput{\CommentCutFile}   %2
+%   \endgroup
+%   This gives:
+%   \begin{equation} \input{\CommentCutFile} \end{equation}
+%  }
+% 1: do not standard include the file
+% 2: input it verbatim, then again inside display math
+%
+% You can also apply processing to each line.
 % By defining a control sequence 
 % \def\Thiscomment##1{...} 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
+% specify what is to be done with each comment line. If something 
+% needs to be written to file, use \WriteCommentLine{the stuff}
+% Example:
+% \specialcomment{underlinecomment}
+%  {\def\ThisComment##1{\WriteCommentLine{\string\underline{##1}\string\par}}
+%   \par}
+%  {\par}
 %
 % Trick for short in/exclude macros (such as \maybe{this snippet}):
 %\includecomment{cond}
@@ -93,16 +126,27 @@
 %\renewcommand{\maybe}[1]{#1}
 %\end{cond}
 %
-% 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 \CommentCutFile (default "comment.cut"), which is
-% then included.
-% In plain TeX (and other formats) both the opening and
-% closing comands are defined as noop.
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Changes in 3.7
+% - only LaTeX support from now on
+% - code cleanup, and improvements on \specialcomment
+% - cleanup of the docs.
+% Changed in 3.6
+% - documentation update
+% - comment file inclusion is now a customizable command
+% Changes in 3.5
+% - corrected typo in header.
+% - changed author email
+% - corrected \specialcomment yet again.
+% - fixed excludecomment of an earlier defined environment.
+% Changes in 3.4
+% - added GNU public license
+% - added \processcomment, because Ivo's fix (above) brought an
+%   inconsistency to light.
+% Changes in 3.3
+% - updated author's address again
+% - parametrised \CommentCutFile
+% Changes in 3.2
+% - \specialcomment brought up to date (thanks to Ivo Welch).
 % Changes in version 3.1
 % - updated author's address
 % - cleaned up some code
@@ -115,163 +159,117 @@
 %   \end{env}
 %  Isn't that something ...
 % - included comments are written to file and input again.
-% Changes in 3.2
-% - \specialcomment brought up to date (thanks to Ivo Welch).
-% Changes in 3.3
-% - updated author's address again
-% - parametrised \CommentCutFile
-% Changes in 3.4
-% - added GNU public license
-% - added \processcomment, because Ivo's fix (above) brought an
-%   inconsistency to light.
-% Changes in 3.5
-% - corrected typo in header.
-% - changed author email
-% - corrected \specialcomment yet again.
-% - fixed excludecomment of an earlier defined environment.
-% Changes in 3.6
-% - The 'cut' file is now written more verbatim, using \meaning;
-%   some people reported having trouble with ISO latin 1, or umlaute.sty.
-% - removed some \newif statements.
-%   Has this suddenly become \outer again?
 %
 % Known bugs:
 % - excludecomment leads to one superfluous space
-% - processcomment leads to a superfluous line break
+% - processcomment leads to a superfluous line break at the start
 %
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
 \def\makeinnocent#1{\catcode`#1=12 }
 \def\csarg#1#2{\expandafter#1\csname#2\endcsname}
 \def\latexname{lplain}\def\latexename{LaTeX2e}
 \newwrite\CommentStream
-\def\CommentCutFile{comment.cut}
+\def\DefaultCutFileName{\def\CommentCutFile{comment.cut}}
+\DefaultCutFileName
 
+% begin / end processing
+%
+% this contains the only real begin/endgroup commands, to keep the
+% catcode changes local.
 \def\ProcessComment#1% start it all of
-   {\begingroup
-    \def\CurrentComment{#1}%
+   {\def\CurrentComment{#1}%
+    \begingroup
     \let\do\makeinnocent \dospecials 
     \makeinnocent\^^L% and whatever other special cases
-    \endlinechar`\^^M \catcode`\^^M=12 \xComment}
-%\def\ProcessCommentWithArg#1#2% to be used in \leveledcomment
-%   {\begingroup
-%    \def\CurrentComment{#1}%
-%    \let\do\makeinnocent \dospecials 
-%    \makeinnocent\^^L% and whatever other special cases
-%    \endlinechar`\^^M \catcode`\^^M=12 \xComment}
+    \endlinechar`\^^M\relax \catcode`\^^M=12\relax \xComment}
 {\catcode`\^^M=12 \endlinechar=-1 %
- \gdef\xComment#1^^M{%
-    \expandafter\ProcessCommentLine}
+ \gdef\xComment#1^^M{\ProcessCommentLine}
  \gdef\ProcessCommentLine#1^^M{\def\test{#1}
       \csarg\ifx{End\CurrentComment Test}\test
-          \edef\next{\noexpand\EndOfComment{\CurrentComment}}%
+          \edef\next{\endgroup\noexpand\EndOfComment{\CurrentComment}}%
       \else \ThisComment{#1}\let\next\ProcessCommentLine
       \fi \next}
 }
 
-\def\CSstringmeaning#1{\expandafter\CSgobblearrow\meaning#1}
-\def\CSstringcsnoescape#1{\expandafter\CSgobbleescape\string#1}
-{\escapechar-1
-\expandafter\expandafter\expandafter\gdef
-  \expandafter\expandafter\expandafter\CSgobblearrow
-    \expandafter\string\csname macro:->\endcsname{}
-}
-\def\CSgobbleescape#1{\ifnum`\\=`#1 \else #1\fi}
-\def\WriteCommentLine#1{\def\CStmp{#1}%
-    \immediate\write\CommentStream{\CSstringmeaning\CStmp}}
-
-% 3.1 change: in LaTeX and LaTeX2e prevent grouping
-\if 0%
-\ifx\fmtname\latexename 
-    0%
-\else \ifx\fmtname\latexname 
-          0%
-      \else 
-          1%
-\fi   \fi
-%%%%
-%%%% definitions for LaTeX
-%%%%
-\def\AfterIncludedComment
+%%
+%% Initial action: SetUpCutFile opens the CommentCutFile
+%%
+\def\SetUpCutFile
+   {\immediate\openout\CommentStream=\CommentCutFile}
+%%
+%% Each line action: ThisComment, default: WriteCommentLine on line contents
+%%
+\long\def\WriteCommentLine#1{\immediate\write\CommentStream{#1}}
+\let\ThisComment\WriteCommentLine
+%%
+%% Final action: ProcessCutFile
+\def\ProcessCutFile
+   {\message{Straight input of \CommentCutFile.}%
+    \input{\CommentCutFile}\relax}
+\def\CloseAndInputCutFile
    {\immediate\closeout\CommentStream
-    \input{\CommentCutFile}\relax
-    }%
-\def\TossComment{\immediate\closeout\CommentStream}
-\def\BeforeIncludedComment
-   {\immediate\openout\CommentStream=\CommentCutFile
-    \let\ThisComment\WriteCommentLine}
+    \ProcessCutFile}
+
+%%
+%% Define the different comment types
+%%
+% included comments: all the default actions
 \def\includecomment
  #1{\message{Include comment '#1'}%
-    \csarg\let{After#1Comment}\AfterIncludedComment
-    \csarg\def{#1}{\BeforeIncludedComment
-        \ProcessComment{#1}}%
+    \csarg\def{After#1Comment}{\CloseAndInputCutFile}
+    \csarg\def{#1}{\endgroup \message{Including '#1' comment.}%
+        \DefaultCutFileName \SetUpCutFile \ProcessComment{#1}}%
+    \CommentEndDef{#1}}
+% excluded comment: also default
+\def\excludecomment
+ #1{\message{Excluding comment '#1'}%
+    \csarg\def{#1}{\endgroup \message{Excluding '#1' comment.}%
+        \begingroup
+           \DefaultCutFileName \def\ProcessCutFile{}%
+           \def\ThisComment####1{}\ProcessComment{#1}}%
+    \csarg\def{After#1Comment}{\CloseAndInputCutFile \endgroup}
     \CommentEndDef{#1}}
+% special comment
 \long\def\specialcomment
  #1#2#3{\message{Special comment '#1'}%
-    % note: \AfterIncludedComment does \input, so #2 goes here!
-    \csarg\def{After#1Comment}{#2\AfterIncludedComment#3}%
-    \csarg\def{#1}{\BeforeIncludedComment\relax
+    \csarg\def{#1}{\endgroup  \message{Processing '#1' comment.}%
+                   \DefaultCutFileName 
+                   #2\relax \SetUpCutFile
+                   % #2 before SetUp, so we can do renaming.
+          \message{Comment '#1' writing to \CommentCutFile.}%
           \ProcessComment{#1}}%
+    \csarg\def{After#1Comment}{\CloseAndInputCutFile #3}%
+    \CommentEndDef{#1}}
+\long\def\generalcomment
+ #1#2#3{\message{General comment '#1'}%
+    \csarg\def{#1}{\endgroup % counter the environment open of LaTeX
+          #2 \relax \SetUpCutFile \ProcessComment{#1}}%
+    \csarg\def{After#1Comment}{\CloseAndInputCutFile #3}%
     \CommentEndDef{#1}}
 \long\def\processcomment
  #1#2#3#4{\message{Lines-Processing comment '#1'}%
-    \csarg\def{After#1Comment}{#3\AfterIncludedComment#4}%
-    \csarg\def{#1}{\BeforeIncludedComment#2\relax
+    \csarg\def{#1}{\endgroup \SetUpCutFile #2\relax
           \ProcessComment{#1}}%
+    \csarg\def{After#1Comment}{#3\CloseAndInputCutFile #4}%
     \CommentEndDef{#1}}
 \def\leveledcomment
  #1#2{\message{Include comment '#1' up to level '#2'}%
+    %\csarg\newif{if#1IsStreamingComment}
+    %\csarg\newif{if#1IsLeveledComment}
     %\csname #1IsLeveledCommenttrue\endcsname
-    \csarg\let{After#1Comment}\AfterIncludedComment
-    \csarg\def{#1}{\BeforeIncludedComment
+    \csarg\let{After#1Comment}\CloseAndInputCutFile
+    \csarg\def{#1}{\SetUpCutFile
         \ProcessCommentWithArg{#1}}%
     \CommentEndDef{#1}}
-\else 
-%%%%
-%%%%plain TeX and other formats
-%%%%
-\def\includecomment
- #1{\message{Including comment '#1'}%
-    \csarg\def{#1}{}%
-    \csarg\def{end#1}{}}
-\long\def\specialcomment
- #1#2#3{\message{Special comment '#1'}%
-    \csarg\def{#1}{\def\ThisComment{}\def\AfterComment{#3}#2%
-           \ProcessComment{#1}}%
-    \CommentEndDef{#1}}
-\fi
 
-%%%%
-%%%% general definition of skipped comment
-%%%%
-\def\excludecomment
- #1{\message{Excluding comment '#1'}%
-    \csarg\def{#1}{\let\AfterComment\relax
-           \def\ThisComment####1{}\ProcessComment{#1}}%
-    \csarg\let{After#1Comment}\TossComment
-    \CommentEndDef{#1}}
-
-\if 0%
-\ifx\fmtname\latexename 
-    0%
-\else \ifx\fmtname\latexname 
-          0%
-      \else 
-          1%
-\fi   \fi
-% latex & latex2e:
-\def\EndOfComment#1{\endgroup\end{#1}%
-    \csname After#1Comment\endcsname}
+\makeatletter
+\def\EndOfComment#1{%
+    \csname After#1Comment\endcsname
+    % sabotage LaTeX's environment testing
+    \begingroup\def\@currenvir{#1}\end{#1}}
 \def\CommentEndDef#1{{\escapechar=-1\relax
     \csarg\xdef{End#1Test}{\string\\end\string\{#1\string\}}%
     }}
-\else
-% plain & other
-\def\EndOfComment#1{\endgroup\AfterComment}
-\def\CommentEndDef#1{{\escapechar=-1\relax
-    \csarg\xdef{End#1Test}{\string\\end#1}%
-    }}
-\fi
+\makeatother
 
 \excludecomment{comment}