summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/comment/comment.sty
blob: 84aa9074e553d71a9a77b108452e32cd28d18df4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Comment.sty   version 3.8, July 2016
% copyright 1998-2016 Victor Eijkhout
%
% 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.
%
% Author
%    Victor Eijkhout
%    Texas Advanced Computing Center
%    The University of Texas at Austin
%    Austin TX 78758
%    USA
%
%    victor@eijkhout.net
%
% This program is free software; you can redistribute it and/or
% modify it under the terms of the GNU General Public License
% as published by the Free Software Foundation; either version 2
% of the License, or (at your option) any later version.
% 
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% For a copy of the GNU General Public License, write to the 
% Free Software Foundation, Inc.,
% 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA,
% or find it on the net, for instance at
% http://www.gnu.org/copyleft/gpl.html
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Usage: all text included between
%   \begin{comment}
%   ...
%   \end{comment}
% 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 `comment' environments are defined by
% and are selected/deselected with
% \includecomment{versiona}
% \excludecoment{versionb}
%
% These environments are used as
% \begin{versiona} ... \end{versiona}
% with the opening and closing commands again on a line of 
% their own.
%
% 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
% and after each comment block. You can use this for global
% formatting commands.
% To keep definitions &c local, you can include \begingroup
% in the `before commands' and \endgroup in the `after commands'.
% ex:
% \specialcomment{smalltt}
%     {\begingroup\ttfamily\footnotesize}{\endgroup}
% 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.
%
% 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. If something 
% needs to be written to file, use \WriteCommentLine{the stuff}
% Example:
% \specialcomment{underlinecomment}
%  {\def\ThisComment##1{\WriteCommentLine{\underline{##1}\par}}
%   \par}
%  {\par}
%
% Trick for short in/exclude macros (such as \maybe{this snippet}):
%\includecomment{cond}
%\newcommand{\maybe}[1]{}
%\begin{cond}
%\renewcommand{\maybe}[1]{#1}
%\end{cond}
%
% Changes in 3.8
% - utf8 is now correctly handled, at least if you use eTeX.
%   (Thanks Henry Gregory for the solution)
% 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
% - trailing contents on \begin{env} line is always discarded
%  even if you've done \includecomment{env}
% - comments no longer define grouping!! you can even
%   \includecomment{env}
%   \begin{env}
%   \begin{itemize}
%   \end{env}
%  Isn't that something ...
% - included comments are written to file and input again.
%
% Known bugs:
% - excludecomment leads to one superfluous space
% - 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\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
   {\def\CurrentComment{#1}%
    \begingroup
    \let\do\makeinnocent \dospecials 
    \makeinnocent\^^L% and whatever other special cases
    \endlinechar`\^^M\relax \catcode`\^^M=12\relax \xComment}
{\catcode`\^^M=12 \endlinechar=-1 %
 \gdef\xComment#1^^M{\ProcessCommentLine}
 \gdef\ProcessCommentLine#1^^M{\def\test{#1}
      \csarg\ifx{End\CurrentComment Test}\test
          \edef\next{\endgroup\noexpand\EndOfComment{\CurrentComment}}%
      \else \ThisComment{#1}\let\next\ProcessCommentLine
      \fi \next}
}

%%
%% Initial action: SetUpCutFile opens the CommentCutFile
%% hook for initial actions: PrepareCutFile, default null
%%
\def\SetUpCutFile
   {\immediate\openout\CommentStream=\CommentCutFile
    \PrepareCutFile}
\def\PrepareCutFile{}

%%
%% Each line action: ThisComment,
%% default: WriteCommentLine on line contents
%% version 3.8: write unexpanded if using eTeX
%%
\expandafter\ifx\csname eTeXversion\endcsname\relax
    \long\def\WriteCommentLine#1{\immediate\write\CommentStream{#1}}
\else
    \long\def\WriteCommentLine#1{\immediate\write\CommentStream{\unexpanded{#1}}}
\fi
\let\ThisComment\WriteCommentLine

%%
%% Final action: ProcessCutFile
%% hook for final action before file closing: FinalizeCutFile, default null
%%
\def\ProcessCutFile
   {\message{Straight input of \CommentCutFile.}%
    \input{\CommentCutFile}\relax}
\def\CloseAndInputCutFile
   {\FinalizeCutFile
    \immediate\closeout\CommentStream
    \ProcessCutFile}
\def\FinalizeCutFile{}

%%
%% Define the different comment types
%%
% included comments: all the default actions
\def\includecomment
 #1{\message{Include comment '#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'}%
    \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{#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}\CloseAndInputCutFile
    \csarg\def{#1}{\SetUpCutFile
        \ProcessCommentWithArg{#1}}%
    \CommentEndDef{#1}}

\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\}}%
    }}
\makeatother

\excludecomment{comment}

\endinput