diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/comment/comment.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/comment/comment.tex | 211 |
1 files changed, 140 insertions, 71 deletions
diff --git a/Master/texmf-dist/doc/latex/comment/comment.tex b/Master/texmf-dist/doc/latex/comment/comment.tex index 0c1f3597896..e6f3d5422c5 100644 --- a/Master/texmf-dist/doc/latex/comment/comment.tex +++ b/Master/texmf-dist/doc/latex/comment/comment.tex @@ -1,4 +1,4 @@ -\documentclass[parskip=false, DIV=8, headings=normal, pagesize=auto]{scrartcl} +\documentclass[parskip=false, DIV=8, headings=normal, pagesize=auto]{artikel3}%{scrartcl} \usepackage{fixltx2e} \usepackage{etex} @@ -27,11 +27,12 @@ \newcommand*{\meta}[1]{\textlangle\textsl{#1}\textrangle} \newcommand*{\marg}[1]{\texttt{\{}\meta{#1}\texttt{\}}} -\addtokomafont{title}{\rmfamily} +%\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} +\title{The \pkg{comment} package\thanks{This manual corresponds to + \pkg{comment}~v3.8 of July 2016.}} +% +\author{Victor Eijkhout\\\mail{victor@eijkhout.net}} \date{August 2016} \begin{document} @@ -40,27 +41,25 @@ \section{Purpose:} -selectively in/exclude pieces of text: the user can define new +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. +Plain \TeX\ support has been phased out. +As of 3.8 the package will increasingly use e\TeX\ features, for +instance to solve Unicode support issues. \section{Usage:} +The `\env{comment}' environment is defined by default: all text included between % \begin{verbatim} -\comment ... \endcomment -\end{verbatim} -% -or -% -\begin{verbatim} -\begin{comment} ... \end{comment} +\begin{comment} + ... +\end{comment} \end{verbatim} % is discarded. @@ -81,27 +80,32 @@ and are selected/deselected with These environments are used as % \begin{verbatim} -\versiona ... \endversiona -\end{verbatim} -% -or -% -\begin{verbatim} -\begin{versiona} ... \end{versiona} +\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 +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] +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{Special comments} + +It is possible to make highly customized versions of the comment environment. Special comments are defined as % \begin{noverb} @@ -111,63 +115,131 @@ Special comments are defined as 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: + +Example: % \begin{verbatim} \specialcomment{smalltt} {\begingroup\ttfamily\footnotesize}{\endgroup} \end{verbatim} % -You do \emph{not} have to do an additional -% +Special comments are automatically included. + +The comment environments use two auxiliary commands. You can get +nifty special effects by redefining them. + +\subsection{The cutfile} + +The commented text is written to an external file, the `cutfile'. Default definition: \begin{verbatim} -\includecomment{smalltt} + \def\CommentCutFile{comment.cut} \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 -% +Included comments are processed like this: \begin{verbatim} -\def\Thiscomment##1{...} + \def\ProcessCutFile{\input{\CommentCutFile}\relax} +\end{verbatim} + and excluded files have +\begin{verbatim} + \def\ProcessCutFile{} +\end{verbatim} + +\begin{itemize} +\item By redefining the name of the cutfile, the value of the macro + \cmd{CommentCutFile}, it becomes possible to have nested comment environments. +\item If you are writing a textbook, you could have the answers to + exercises in your source, but write them to file rather than + formatting them: +\begin{verbatim} +\generalcomment{answer} + {\begingroup + \edef\tmp{\def\noexpand\CommentCutFile + {answers/\chapshortname-an\noexpand\arabic{excounter}.tex}}\tmp + \def\ProcessCutFile{}} + {\ifIncludeAnswers \begin{quote} + \leavevmode + \hbox{\kern-\unitindent + \textbf Solution to exercise \arabic{chapter}.\arabic{excounter}.\hspace{1em}}% + \ignorespaces\it + \input{\CommentCutFile} + \end{quote}\fi + \endgroup} +\end{verbatim} +\end{itemize} + +\subsection{Comment inclusion} + +The inclusion of the comment is done +by \cmd{\ProcessCutFile}, so you can redefine that: +\begin{verbatim} + \specialcomment + {mathexamplewithcode} + {\begingroup\def\ProcessCutFile{}} % arg1 + {\verbatiminput{\CommentCutFile} % arg2 + \endgroup + This gives: + \begin{equation} \input{\CommentCutFile} \end{equation} + } +\end{verbatim} +The idea here is to disable inclusion of the file, +but include it in the after commands, in display math. + +\subsection{Processing each line} + +You can also apply processing to each line. +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 +specify what is to be done with each comment line. If something +needs to be written to file, use \verb+\WriteCommentLine{the stuff}+ +Example: +\begin{verbatim} + \specialcomment + {underlinecomment} + {\def\ThisComment##1{\WriteCommentLine{\underline{##1}\par}} + \par} + {\par} +\end{verbatim} + +\subsection{More examples} -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} +\newcount\comlines +\specialcomment{countedcomment} + {\comlines=0\relax \def\ProcessCutFile{}% + \def\ThisComment##1{\global\advance\comlines1\relax}} + {**Comment: \number\comlines\ line(s) removed**} \end{verbatim} +\begin{verbatim} +\specialcomment + {underlinecomment} + {% + \def\ProcessCutFile{\input{\CommentCutFile}\relax} + \def\ThisComment##1{\WriteCommentLine{u: \underline{##1}\par}} + \par + } + {\par} +\end{verbatim} -\section{Basic approach of the implementation:} +\section{Unicode support} -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. +Unicode support works if you use e\TeX, which is for instance the case +if you use pdflatex. You need the following lines: +\begin{verbatim} +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\end{verbatim} +in your preamble. +\section{Change log} -\section{Changes in version 3.1} +\subsection{Changes in version 3.1} \begin{itemize} \item updated author's address @@ -188,14 +260,14 @@ closing comands are defined as noop. \end{itemize} -\section{Changes in 3.2} +\subsection{Changes in 3.2} \begin{itemize} \item \cmd{\specialcomment} brought up to date (thanks to Ivo Welch). \end{itemize} -\section{Changes in 3.3} +\subsection{Changes in 3.3} \begin{itemize} \item updated author's address again @@ -203,7 +275,7 @@ closing comands are defined as noop. \end{itemize} -\section{Changes in 3.4} +\subsection{Changes in 3.4} \begin{itemize} \item added GNU public license @@ -212,7 +284,7 @@ closing comands are defined as noop. \end{itemize} -\section{Changes in 3.5} +\subsection{Changes in 3.5} \begin{itemize} \item corrected typo in header. @@ -222,7 +294,7 @@ closing comands are defined as noop. \end{itemize} -\section{Changes in 3.6} +\subsection{Changes in 3.6} \begin{itemize} \item The `cut' file is now written more verbatim, using \cmd{\meaning}; @@ -232,11 +304,8 @@ closing comands are defined as noop. \end{itemize} -\section{Known bugs:} +\subsection{Changes in 3.8} -\begin{itemize} -\item \texttt{excludecomment} leads to one superfluous space -\item \texttt{processcomment} leads to a superfluous line break -\end{itemize} +T1 font encoding is now supported. See t1test.tex. \end{document} |