lib/texinputs/comment.sty
author wenzelm
Wed Dec 06 15:46:35 2017 +0100 (17 months ago)
changeset 67146 909dcdec2122
parent 55224 197c36bb30ad
permissions -rw-r--r--
more embedded cartouche arguments;
more uniform LaTeX output for control symbols;
     1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     2 % Comment.sty   version 3.6, October 1999
     3 %
     4 % Purpose:
     5 % selectively in/exclude pieces of text: the user can define new
     6 % comment versions, and each is controlled separately.
     7 % Special comments can be defined where the user specifies the
     8 % action that is to be taken with each comment line.
     9 %
    10 % Author
    11 %    Victor Eijkhout
    12 %    Department of Computer Science
    13 %    University of Tennessee
    14 %    107 Ayres Hall
    15 %    Knoxville TN 37996
    16 %    USA
    17 %
    18 %    victor@eijkhout.net
    19 %
    20 % This program is free software; you can redistribute it and/or
    21 % modify it under the terms of the GNU General Public License
    22 % as published by the Free Software Foundation; either version 2
    23 % of the License, or (at your option) any later version.
    24 % 
    25 % This program is distributed in the hope that it will be useful,
    26 % but WITHOUT ANY WARRANTY; without even the implied warranty of
    27 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    28 % GNU General Public License for more details.
    29 %
    30 % For a copy of the GNU General Public License, write to the 
    31 % Free Software Foundation, Inc.,
    32 % 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA,
    33 % or find it on the net, for instance at
    34 % http://www.gnu.org/copyleft/gpl.html
    35 %
    36 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    37 % This style can be used with plain TeX or LaTeX, and probably
    38 % most other packages too.
    39 %
    40 % Usage: all text included between
    41 %    \comment ... \endcomment
    42 % or \begin{comment} ... \end{comment}
    43 % is discarded. 
    44 %
    45 % The opening and closing commands should appear on a line
    46 % of their own. No starting spaces, nothing after it.
    47 % This environment should work with arbitrary amounts
    48 % of comment, and the comment can be arbitrary text.
    49 %
    50 % Other `comment' environments are defined by
    51 % and are selected/deselected with
    52 % \includecomment{versiona}
    53 % \excludecoment{versionb}
    54 %
    55 % These environments are used as
    56 % \versiona ... \endversiona
    57 % or \begin{versiona} ... \end{versiona}
    58 % with the opening and closing commands again on a line of 
    59 % their own.
    60 %
    61 % LaTeX users note: for an included comment, the
    62 % \begin and \end lines act as if they don't exist.
    63 % In particular, they don't imply grouping, so assignments 
    64 % &c are not local.
    65 %
    66 % Special comments are defined as
    67 % \specialcomment{name}{before commands}{after commands}
    68 % where the second and third arguments are executed before
    69 % and after each comment block. You can use this for global
    70 % formatting commands.
    71 % To keep definitions &c local, you can include \begingroup
    72 % in the `before commands' and \endgroup in the `after commands'.
    73 % ex:
    74 % \specialcomment{smalltt}
    75 %     {\begingroup\ttfamily\footnotesize}{\endgroup}
    76 % You do *not* have to do an additional
    77 % \includecomment{smalltt}
    78 % To remove 'smalltt' blocks, give \excludecomment{smalltt}
    79 % after the definition.
    80 %
    81 % Processing comments can apply processing to each line.
    82 % \processcomment{name}{each-line commands}%
    83 %    {before commands}{after commands}
    84 % By defining a control sequence 
    85 % \def\Thiscomment##1{...} in the before commands the user can
    86 % specify what is to be done with each comment line.
    87 % BUG this does not work quite yet BUG
    88 %
    89 % Trick for short in/exclude macros (such as \maybe{this snippet}):
    90 %\includecomment{cond}
    91 %\newcommand{\maybe}[1]{}
    92 %\begin{cond}
    93 %\renewcommand{\maybe}[1]{#1}
    94 %\end{cond}
    95 %
    96 % Basic approach of the implementation:
    97 % to comment something out, scoop up  every line in verbatim mode
    98 % as macro argument, then throw it away.
    99 % For inclusions, in LaTeX the block is written out to
   100 % a file \CommentCutFile (default "comment.cut"), which is
   101 % then included.
   102 % In plain TeX (and other formats) both the opening and
   103 % closing comands are defined as noop.
   104 %
   105 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   106 % Changes in version 3.1
   107 % - updated author's address
   108 % - cleaned up some code
   109 % - trailing contents on \begin{env} line is always discarded
   110 %  even if you've done \includecomment{env}
   111 % - comments no longer define grouping!! you can even
   112 %   \includecomment{env}
   113 %   \begin{env}
   114 %   \begin{itemize}
   115 %   \end{env}
   116 %  Isn't that something ...
   117 % - included comments are written to file and input again.
   118 % Changes in 3.2
   119 % - \specialcomment brought up to date (thanks to Ivo Welch).
   120 % Changes in 3.3
   121 % - updated author's address again
   122 % - parametrised \CommentCutFile
   123 % Changes in 3.4
   124 % - added GNU public license
   125 % - added \processcomment, because Ivo's fix (above) brought an
   126 %   inconsistency to light.
   127 % Changes in 3.5
   128 % - corrected typo in header.
   129 % - changed author email
   130 % - corrected \specialcomment yet again.
   131 % - fixed excludecomment of an earlier defined environment.
   132 % Changes in 3.6
   133 % - The 'cut' file is now written more verbatim, using \meaning;
   134 %   some people reported having trouble with ISO latin 1, or umlaute.sty.
   135 % - removed some \newif statements.
   136 %   Has this suddenly become \outer again?
   137 %
   138 % Known bugs:
   139 % - excludecomment leads to one superfluous space
   140 % - processcomment leads to a superfluous line break
   141 %
   142 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   143 
   144 \def\makeinnocent#1{\catcode`#1=12 }
   145 \def\csarg#1#2{\expandafter#1\csname#2\endcsname}
   146 \def\latexname{lplain}\def\latexename{LaTeX2e}
   147 \newwrite\CommentStream
   148 \def\CommentCutFile{comment.cut}
   149 
   150 \def\ProcessComment#1% start it all of
   151    {\begingroup
   152     \def\CurrentComment{#1}%
   153     \let\do\makeinnocent \dospecials 
   154     \makeinnocent\^^L% and whatever other special cases
   155     \endlinechar`\^^M \catcode`\^^M=12 \xComment}
   156 %\def\ProcessCommentWithArg#1#2% to be used in \leveledcomment
   157 %   {\begingroup
   158 %    \def\CurrentComment{#1}%
   159 %    \let\do\makeinnocent \dospecials 
   160 %    \makeinnocent\^^L% and whatever other special cases
   161 %    \endlinechar`\^^M \catcode`\^^M=12 \xComment}
   162 {\catcode`\^^M=12 \endlinechar=-1 %
   163  \gdef\xComment#1^^M{%
   164     \expandafter\ProcessCommentLine}
   165  \gdef\ProcessCommentLine#1^^M{\def\test{#1}
   166       \csarg\ifx{End\CurrentComment Test}\test
   167           \edef\next{\noexpand\EndOfComment{\CurrentComment}}%
   168       \else \ThisComment{#1}\let\next\ProcessCommentLine
   169       \fi \next}
   170 }
   171 
   172 \def\CSstringmeaning#1{\expandafter\CSgobblearrow\meaning#1}
   173 \def\CSstringcsnoescape#1{\expandafter\CSgobbleescape\string#1}
   174 {\escapechar-1
   175 \expandafter\expandafter\expandafter\gdef
   176   \expandafter\expandafter\expandafter\CSgobblearrow
   177     \expandafter\string\csname macro:->\endcsname{}
   178 }
   179 \def\CSgobbleescape#1{\ifnum`\\=`#1 \else #1\fi}
   180 \def\WriteCommentLine#1{\def\CStmp{#1}%
   181     \immediate\write\CommentStream{\CSstringmeaning\CStmp}}
   182 
   183 % 3.1 change: in LaTeX and LaTeX2e prevent grouping
   184 \if 0%
   185 \ifx\fmtname\latexename 
   186     0%
   187 \else \ifx\fmtname\latexname 
   188           0%
   189       \else 
   190           1%
   191 \fi   \fi
   192 %%%%
   193 %%%% definitions for LaTeX
   194 %%%%
   195 \def\AfterIncludedComment
   196    {\immediate\closeout\CommentStream
   197     \input{\CommentCutFile}\relax
   198     }%
   199 \def\TossComment{\immediate\closeout\CommentStream}
   200 \def\BeforeIncludedComment
   201    {\immediate\openout\CommentStream=\CommentCutFile
   202     \let\ThisComment\WriteCommentLine}
   203 \def\includecomment
   204  #1{\message{Include comment '#1'}%
   205     \csarg\let{After#1Comment}\AfterIncludedComment
   206     \csarg\def{#1}{\BeforeIncludedComment
   207         \ProcessComment{#1}}%
   208     \CommentEndDef{#1}}
   209 \long\def\specialcomment
   210  #1#2#3{\message{Special comment '#1'}%
   211     % note: \AfterIncludedComment does \input, so #2 goes here!
   212     \csarg\def{After#1Comment}{#2\AfterIncludedComment#3}%
   213     \csarg\def{#1}{\BeforeIncludedComment\relax
   214           \ProcessComment{#1}}%
   215     \CommentEndDef{#1}}
   216 \long\def\processcomment
   217  #1#2#3#4{\message{Lines-Processing comment '#1'}%
   218     \csarg\def{After#1Comment}{#3\AfterIncludedComment#4}%
   219     \csarg\def{#1}{\BeforeIncludedComment#2\relax
   220           \ProcessComment{#1}}%
   221     \CommentEndDef{#1}}
   222 \def\leveledcomment
   223  #1#2{\message{Include comment '#1' up to level '#2'}%
   224     %\csname #1IsLeveledCommenttrue\endcsname
   225     \csarg\let{After#1Comment}\AfterIncludedComment
   226     \csarg\def{#1}{\BeforeIncludedComment
   227         \ProcessCommentWithArg{#1}}%
   228     \CommentEndDef{#1}}
   229 \else 
   230 %%%%
   231 %%%%plain TeX and other formats
   232 %%%%
   233 \def\includecomment
   234  #1{\message{Including comment '#1'}%
   235     \csarg\def{#1}{}%
   236     \csarg\def{end#1}{}}
   237 \long\def\specialcomment
   238  #1#2#3{\message{Special comment '#1'}%
   239     \csarg\def{#1}{\def\ThisComment{}\def\AfterComment{#3}#2%
   240            \ProcessComment{#1}}%
   241     \CommentEndDef{#1}}
   242 \fi
   243 
   244 %%%%
   245 %%%% general definition of skipped comment
   246 %%%%
   247 \def\excludecomment
   248  #1{\message{Excluding comment '#1'}%
   249     \csarg\def{#1}{\let\AfterComment\relax
   250            \def\ThisComment####1{}\ProcessComment{#1}}%
   251     \csarg\let{After#1Comment}\TossComment
   252     \CommentEndDef{#1}}
   253 
   254 \if 0%
   255 \ifx\fmtname\latexename 
   256     0%
   257 \else \ifx\fmtname\latexname 
   258           0%
   259       \else 
   260           1%
   261 \fi   \fi
   262 % latex & latex2e:
   263 \def\EndOfComment#1{\endgroup\end{#1}%
   264     \csname After#1Comment\endcsname}
   265 \def\CommentEndDef#1{{\escapechar=-1\relax
   266     \csarg\xdef{End#1Test}{\string\\end\string\{#1\string\}}%
   267     }}
   268 \else
   269 % plain & other
   270 \def\EndOfComment#1{\endgroup\AfterComment}
   271 \def\CommentEndDef#1{{\escapechar=-1\relax
   272     \csarg\xdef{End#1Test}{\string\\end#1}%
   273     }}
   274 \fi
   275 
   276 \excludecomment{comment}
   277 
   278 \endinput