1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/Tools/isac/Doc/comment.sty Wed Mar 11 15:25:52 2020 +0100
1.3 @@ -0,0 +1,278 @@
1.4 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1.5 +% Comment.sty version 3.6, October 1999
1.6 +%
1.7 +% Purpose:
1.8 +% selectively in/exclude pieces of text: the user can define new
1.9 +% comment versions, and each is controlled separately.
1.10 +% Special comments can be defined where the user specifies the
1.11 +% action that is to be taken with each comment line.
1.12 +%
1.13 +% Author
1.14 +% Victor Eijkhout
1.15 +% Department of Computer Science
1.16 +% University of Tennessee
1.17 +% 107 Ayres Hall
1.18 +% Knoxville TN 37996
1.19 +% USA
1.20 +%
1.21 +% victor@eijkhout.net
1.22 +%
1.23 +% This program is free software; you can redistribute it and/or
1.24 +% modify it under the terms of the GNU General Public License
1.25 +% as published by the Free Software Foundation; either version 2
1.26 +% of the License, or (at your option) any later version.
1.27 +%
1.28 +% This program is distributed in the hope that it will be useful,
1.29 +% but WITHOUT ANY WARRANTY; without even the implied warranty of
1.30 +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.31 +% GNU General Public License for more details.
1.32 +%
1.33 +% For a copy of the GNU General Public License, write to the
1.34 +% Free Software Foundation, Inc.,
1.35 +% 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA,
1.36 +% or find it on the net, for instance at
1.37 +% http://www.gnu.org/copyleft/gpl.html
1.38 +%
1.39 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1.40 +% This style can be used with plain TeX or LaTeX, and probably
1.41 +% most other packages too.
1.42 +%
1.43 +% Usage: all text included between
1.44 +% \comment ... \endcomment
1.45 +% or \begin{comment} ... \end{comment}
1.46 +% is discarded.
1.47 +%
1.48 +% The opening and closing commands should appear on a line
1.49 +% of their own. No starting spaces, nothing after it.
1.50 +% This environment should work with arbitrary amounts
1.51 +% of comment, and the comment can be arbitrary text.
1.52 +%
1.53 +% Other `comment' environments are defined by
1.54 +% and are selected/deselected with
1.55 +% \includecomment{versiona}
1.56 +% \excludecoment{versionb}
1.57 +%
1.58 +% These environments are used as
1.59 +% \versiona ... \endversiona
1.60 +% or \begin{versiona} ... \end{versiona}
1.61 +% with the opening and closing commands again on a line of
1.62 +% their own.
1.63 +%
1.64 +% LaTeX users note: for an included comment, the
1.65 +% \begin and \end lines act as if they don't exist.
1.66 +% In particular, they don't imply grouping, so assignments
1.67 +% &c are not local.
1.68 +%
1.69 +% Special comments are defined as
1.70 +% \specialcomment{name}{before commands}{after commands}
1.71 +% where the second and third arguments are executed before
1.72 +% and after each comment block. You can use this for global
1.73 +% formatting commands.
1.74 +% To keep definitions &c local, you can include \begingroup
1.75 +% in the `before commands' and \endgroup in the `after commands'.
1.76 +% ex:
1.77 +% \specialcomment{smalltt}
1.78 +% {\begingroup\ttfamily\footnotesize}{\endgroup}
1.79 +% You do *not* have to do an additional
1.80 +% \includecomment{smalltt}
1.81 +% To remove 'smalltt' blocks, give \excludecomment{smalltt}
1.82 +% after the definition.
1.83 +%
1.84 +% Processing comments can apply processing to each line.
1.85 +% \processcomment{name}{each-line commands}%
1.86 +% {before commands}{after commands}
1.87 +% By defining a control sequence
1.88 +% \def\Thiscomment##1{...} in the before commands the user can
1.89 +% specify what is to be done with each comment line.
1.90 +% BUG this does not work quite yet BUG
1.91 +%
1.92 +% Trick for short in/exclude macros (such as \maybe{this snippet}):
1.93 +%\includecomment{cond}
1.94 +%\newcommand{\maybe}[1]{}
1.95 +%\begin{cond}
1.96 +%\renewcommand{\maybe}[1]{#1}
1.97 +%\end{cond}
1.98 +%
1.99 +% Basic approach of the implementation:
1.100 +% to comment something out, scoop up every line in verbatim mode
1.101 +% as macro argument, then throw it away.
1.102 +% For inclusions, in LaTeX the block is written out to
1.103 +% a file \CommentCutFile (default "comment.cut"), which is
1.104 +% then included.
1.105 +% In plain TeX (and other formats) both the opening and
1.106 +% closing comands are defined as noop.
1.107 +%
1.108 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1.109 +% Changes in version 3.1
1.110 +% - updated author's address
1.111 +% - cleaned up some code
1.112 +% - trailing contents on \begin{env} line is always discarded
1.113 +% even if you've done \includecomment{env}
1.114 +% - comments no longer define grouping!! you can even
1.115 +% \includecomment{env}
1.116 +% \begin{env}
1.117 +% \begin{itemize}
1.118 +% \end{env}
1.119 +% Isn't that something ...
1.120 +% - included comments are written to file and input again.
1.121 +% Changes in 3.2
1.122 +% - \specialcomment brought up to date (thanks to Ivo Welch).
1.123 +% Changes in 3.3
1.124 +% - updated author's address again
1.125 +% - parametrised \CommentCutFile
1.126 +% Changes in 3.4
1.127 +% - added GNU public license
1.128 +% - added \processcomment, because Ivo's fix (above) brought an
1.129 +% inconsistency to light.
1.130 +% Changes in 3.5
1.131 +% - corrected typo in header.
1.132 +% - changed author email
1.133 +% - corrected \specialcomment yet again.
1.134 +% - fixed excludecomment of an earlier defined environment.
1.135 +% Changes in 3.6
1.136 +% - The 'cut' file is now written more verbatim, using \meaning;
1.137 +% some people reported having trouble with ISO latin 1, or umlaute.sty.
1.138 +% - removed some \newif statements.
1.139 +% Has this suddenly become \outer again?
1.140 +%
1.141 +% Known bugs:
1.142 +% - excludecomment leads to one superfluous space
1.143 +% - processcomment leads to a superfluous line break
1.144 +%
1.145 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1.146 +
1.147 +\def\makeinnocent#1{\catcode`#1=12 }
1.148 +\def\csarg#1#2{\expandafter#1\csname#2\endcsname}
1.149 +\def\latexname{lplain}\def\latexename{LaTeX2e}
1.150 +\newwrite\CommentStream
1.151 +\def\CommentCutFile{comment.cut}
1.152 +
1.153 +\def\ProcessComment#1% start it all of
1.154 + {\begingroup
1.155 + \def\CurrentComment{#1}%
1.156 + \let\do\makeinnocent \dospecials
1.157 + \makeinnocent\^^L% and whatever other special cases
1.158 + \endlinechar`\^^M \catcode`\^^M=12 \xComment}
1.159 +%\def\ProcessCommentWithArg#1#2% to be used in \leveledcomment
1.160 +% {\begingroup
1.161 +% \def\CurrentComment{#1}%
1.162 +% \let\do\makeinnocent \dospecials
1.163 +% \makeinnocent\^^L% and whatever other special cases
1.164 +% \endlinechar`\^^M \catcode`\^^M=12 \xComment}
1.165 +{\catcode`\^^M=12 \endlinechar=-1 %
1.166 + \gdef\xComment#1^^M{%
1.167 + \expandafter\ProcessCommentLine}
1.168 + \gdef\ProcessCommentLine#1^^M{\def\test{#1}
1.169 + \csarg\ifx{End\CurrentComment Test}\test
1.170 + \edef\next{\noexpand\EndOfComment{\CurrentComment}}%
1.171 + \else \ThisComment{#1}\let\next\ProcessCommentLine
1.172 + \fi \next}
1.173 +}
1.174 +
1.175 +\def\CSstringmeaning#1{\expandafter\CSgobblearrow\meaning#1}
1.176 +\def\CSstringcsnoescape#1{\expandafter\CSgobbleescape\string#1}
1.177 +{\escapechar-1
1.178 +\expandafter\expandafter\expandafter\gdef
1.179 + \expandafter\expandafter\expandafter\CSgobblearrow
1.180 + \expandafter\string\csname macro:->\endcsname{}
1.181 +}
1.182 +\def\CSgobbleescape#1{\ifnum`\\=`#1 \else #1\fi}
1.183 +\def\WriteCommentLine#1{\def\CStmp{#1}%
1.184 + \immediate\write\CommentStream{\CSstringmeaning\CStmp}}
1.185 +
1.186 +% 3.1 change: in LaTeX and LaTeX2e prevent grouping
1.187 +\if 0%
1.188 +\ifx\fmtname\latexename
1.189 + 0%
1.190 +\else \ifx\fmtname\latexname
1.191 + 0%
1.192 + \else
1.193 + 1%
1.194 +\fi \fi
1.195 +%%%%
1.196 +%%%% definitions for LaTeX
1.197 +%%%%
1.198 +\def\AfterIncludedComment
1.199 + {\immediate\closeout\CommentStream
1.200 + \input{\CommentCutFile}\relax
1.201 + }%
1.202 +\def\TossComment{\immediate\closeout\CommentStream}
1.203 +\def\BeforeIncludedComment
1.204 + {\immediate\openout\CommentStream=\CommentCutFile
1.205 + \let\ThisComment\WriteCommentLine}
1.206 +\def\includecomment
1.207 + #1{\message{Include comment '#1'}%
1.208 + \csarg\let{After#1Comment}\AfterIncludedComment
1.209 + \csarg\def{#1}{\BeforeIncludedComment
1.210 + \ProcessComment{#1}}%
1.211 + \CommentEndDef{#1}}
1.212 +\long\def\specialcomment
1.213 + #1#2#3{\message{Special comment '#1'}%
1.214 + % note: \AfterIncludedComment does \input, so #2 goes here!
1.215 + \csarg\def{After#1Comment}{#2\AfterIncludedComment#3}%
1.216 + \csarg\def{#1}{\BeforeIncludedComment\relax
1.217 + \ProcessComment{#1}}%
1.218 + \CommentEndDef{#1}}
1.219 +\long\def\processcomment
1.220 + #1#2#3#4{\message{Lines-Processing comment '#1'}%
1.221 + \csarg\def{After#1Comment}{#3\AfterIncludedComment#4}%
1.222 + \csarg\def{#1}{\BeforeIncludedComment#2\relax
1.223 + \ProcessComment{#1}}%
1.224 + \CommentEndDef{#1}}
1.225 +\def\leveledcomment
1.226 + #1#2{\message{Include comment '#1' up to level '#2'}%
1.227 + %\csname #1IsLeveledCommenttrue\endcsname
1.228 + \csarg\let{After#1Comment}\AfterIncludedComment
1.229 + \csarg\def{#1}{\BeforeIncludedComment
1.230 + \ProcessCommentWithArg{#1}}%
1.231 + \CommentEndDef{#1}}
1.232 +\else
1.233 +%%%%
1.234 +%%%%plain TeX and other formats
1.235 +%%%%
1.236 +\def\includecomment
1.237 + #1{\message{Including comment '#1'}%
1.238 + \csarg\def{#1}{}%
1.239 + \csarg\def{end#1}{}}
1.240 +\long\def\specialcomment
1.241 + #1#2#3{\message{Special comment '#1'}%
1.242 + \csarg\def{#1}{\def\ThisComment{}\def\AfterComment{#3}#2%
1.243 + \ProcessComment{#1}}%
1.244 + \CommentEndDef{#1}}
1.245 +\fi
1.246 +
1.247 +%%%%
1.248 +%%%% general definition of skipped comment
1.249 +%%%%
1.250 +\def\excludecomment
1.251 + #1{\message{Excluding comment '#1'}%
1.252 + \csarg\def{#1}{\let\AfterComment\relax
1.253 + \def\ThisComment####1{}\ProcessComment{#1}}%
1.254 + \csarg\let{After#1Comment}\TossComment
1.255 + \CommentEndDef{#1}}
1.256 +
1.257 +\if 0%
1.258 +\ifx\fmtname\latexename
1.259 + 0%
1.260 +\else \ifx\fmtname\latexname
1.261 + 0%
1.262 + \else
1.263 + 1%
1.264 +\fi \fi
1.265 +% latex & latex2e:
1.266 +\def\EndOfComment#1{\endgroup\end{#1}%
1.267 + \csname After#1Comment\endcsname}
1.268 +\def\CommentEndDef#1{{\escapechar=-1\relax
1.269 + \csarg\xdef{End#1Test}{\string\\end\string\{#1\string\}}%
1.270 + }}
1.271 +\else
1.272 +% plain & other
1.273 +\def\EndOfComment#1{\endgroup\AfterComment}
1.274 +\def\CommentEndDef#1{{\escapechar=-1\relax
1.275 + \csarg\xdef{End#1Test}{\string\\end#1}%
1.276 + }}
1.277 +\fi
1.278 +
1.279 +\excludecomment{comment}
1.280 +
1.281 +\endinput