Debian Codegraph @

texmf-dist/source/latex/phfcc/phfcc.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2021 by Philippe Faist, [email protected]
4 % -------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3 or later is part of all distributions of LaTeX
14 % version 2005/12/01 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{phfcc.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
23 %<package>\ProvidesPackage{phfcc}
24 %<*package>
25 [2021/10/06 v2.0 phfcc package]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage{xcolor}
31 \usepackage{lipsum}
32 \usepackage[preset=xpkgdoc]{phfnote}
33 \usepackage{phfcc}
34
35 \usepackage{needspace}
36
37 \usepackage[normalem]{ulem}
38
39 \def\eqsign@{=}
40 \def\eqsign{\protect\eqsign@}
41 \robustify\eqsign
42 \makeatother
43
44 \def\RevTeX{{\small R\raise-0.2ex\hbox{\textsc{ev}}}\TeX}
45
46 \EnableCrossrefs
47 \CodelineIndex
48 \RecordChanges
49
50 \begin{document}
51 \DocInput{phfcc.dtx}
52 \end{document}
53 %</driver>
54 % \fi
55 %
56 % \CheckSum{0}
57 %
58 % \CharacterTable
59 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
60 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
61 % Digits \0\1\2\3\4\5\6\7\8\9
62 % Exclamation \! Double quote \" Hash (number) \#
63 % Dollar \$ Percent \% Ampersand \&
64 % Acute accent \' Left paren \( Right paren \)
65 % Asterisk \* Plus \+ Comma \,
66 % Minus \- Point \. Solidus \/
67 % Colon \: Semicolon \; Less than \<
68 % Equals \= Greater than \> Question mark \?
69 % Commercial at \@ Left bracket \[ Backslash \\
70 % Right bracket \] Circumflex \^ Underscore \_
71 % Grave accent \` Left brace \{ Vertical bar \|
72 % Right brace \} Tilde \~}
73 %
74 %
75 % \changes{v1.0}{2020/04/02}{Initial version}
76 %
77 % \GetFileInfo{phfcc.dtx}
78 %
79 % \iffalse Bypass indexing for following commands: \fi
80 % \DoNotIndex{\newcommand,\newenvironment,\renewcommand,\long,\def,\edef,\gdef,\xdef,\if,\else,\fi,\par,\relax,\vspace,\vskip,\hspace,\hskip,\vbox,\hbox}
81 %
82 % \title{\phfqitltxPkgTitle{phfcc}}
83 % \author{Philippe Faist\quad\email{[email protected]}}
84 % \date{\pkgfmtdate\filedate}
85 % \maketitle
86 %
87 % \begin{abstract}
88 % \pkgname{phfcc}---A handy \LaTeX{} package for inline commenting in
89 % collaborative LaTeX documents.
90 % \end{abstract}
91 %
92 % \phantomsection\label{sec:toc}
93 % \inlinetoc
94 %
95 % \section{Introduction}
96 %
97 % When elaborating documents, especially collaborative documents with multiple
98 % authors, it is useful to leave inline comments and be able to mark text
99 % changes. Often, authors will choose a text color and define a simple macro,
100 % like this:
101 % \begin{verbatim}
102 % \newcommand{\phf}[1]{{\color{blue}Ph.F.: #1}} % Philippe Faist's comments
103 % \end{verbatim}
104 %
105 % This rudimentary approach has a few drawbacks. The main drawback is when
106 % highlighting long blocks of text. First of all, it can be hard to visually
107 % find the matching closing brace in your editor. Then, the synchronization
108 % between your viewer and the TeX source (|synctex|) will no longer point to the
109 % correct source line within the highlighted block of text; you will always be
110 % pointed at the beginning or the end of the entire block. The reason for this
111 % behavior is that the entire text is passed as a macro argument to |\phf|, so
112 % |synctex| only sees a single macro call. The fact that a long block of text
113 % is passed as a macro argument can also lead to other issues, such as errors
114 % with |\verb+...+|-type constructs.
115 %
116 % Also, it is occasionally desirable to make the difference between sections of
117 % text that were added by an author, and an inline off-hand remark, which is not
118 % part of the text itself. For instance, with the above macro, we could enclose
119 % remarks in ``|[|'' and ``|]|'': %
120 % \newcommand{\phfold}[1]{{\color{blue}(Ph.F.:) #1}}
121 % \newcommand{\phfoldb}[1]{{\color{blue}\relax #1}}
122 % \begin{verbatim}
123 % ... \phf{Observe that $A\geq 0$ by definition.}
124 % \phf{[I added this sentence because I felt that it wasn't
125 % clear from the context that $A\geq 0$]} ...
126 % \end{verbatim}
127 % to obtain:
128 %
129 % {\itshape%
130 % ... \phfold{Observe that $A\geq 0$ by definition.}
131 % \phfold{[I added this sentence because I felt that it wasn't
132 % clear from the context that $A\geq 0$]} ...
133 % }
134 %
135 % Observe how the off-hand remark blends with the text. Wouldn't it be nicer
136 % if it stood out clearly, and if the initials were perhaps \emph{inside} the
137 % brackets, like so?
138 %
139 % {\itshape%
140 % ... \phfoldb{Ph.F.: Observe that $A\geq 0$ by definition.}
141 % \phfoldb{\sffamily\bfseries [(Ph.F.:) I added this sentence because
142 % I felt that it wasn't
143 % clear from the context that $A\geq 0$]} ...
144 % }
145 %
146 % \relax
147 %
148 % Of course, we could have defined a different macro for the off-hand remark,
149 % say |\phfremark|. But typing a different macro name is not convenient,
150 % Wouldn't it be nicer if the off-hand remark could be typed with the syntax
151 % |\phf[...]|, using square brackets?
152 %
153 % Also the initials don't have to be repeated at every macro call, it suffice to
154 % associate the color to the author perhaps once per page or so. They could
155 % also be displayed in the margin, to avoid cluttering the text.
156 %
157 % Furthermore, to avoid the aforementioned issues with long blocks of text, we
158 % could imagine marking text with the syntax |\begin{phf} ... \end{phf}| or even
159 % |\phf ... \endphf|.
160 %
161 % And while we're at it, wouldn't it be cool to mark text removals, as well?
162 % We could use the syntax |\phf*{text to be removed}|.
163 %
164 % And because I definitely didn't have time to spare but still got distracted
165 % into programming \LaTeX{} macros to implement the above features, I have the
166 % pleasure to present:
167 %
168 % \textit{\bfseries Introducing \ldots\ the \pkgname{phfcc} package.}\par
169 %
170 % With \pkgname{phfcc}, you simply define your multi-functional commenting
171 % command using the |\phfMakeCommentingCommand| macro.
172 %
173 % \phfMakeCommentingCommand[initials={A.E.}]{AlE}%
174 % \phfMakeCommentingCommand[initials={J.B.}]{JB}%
175 % \phfMakeCommentingCommand[initials={PhF}]{phf}%
176 % Let's start with a simple example. Suppose two authors, Albert Einstein and
177 % John Bell, are commenting on the same document. They might define the
178 % commenting commands |\AlE| and |\JB|:
179 % \begin{verbatim}
180 % \phfMakeCommentingCommand[initials={A.E.}]{AlE}
181 % \phfMakeCommentingCommand[initials={J.B.}]{JB}
182 % \end{verbatim}
183 % Suppose they edit a paragraph of text, with multiple rounds of editing by both
184 % authors; they mark their latest changes while leaving comments for the other
185 % author as follows:
186 % \begin{verbatim}
187 % Quantum mechanics developed quickly in the 1920's thanks to the
188 % works of Schr\"odinger, Heisenberg, and Dirac, who drew inspiration
189 % from earlier ideas by Planck \AlE{and Einstein} \AlE[@JB, you forgot
190 % about me!]. Quantum mechanics appears to allow spooky action at a
191 % distance via some strange thing called ``entanglement,'' \JB*{but
192 % this can be explained with hidden variables}\JB{which has
193 % revolutionized our understanding of local realism.} \JB[@Albert,
194 % we talked about this...]
195 % \end{verbatim}
196 % which gives:
197 %
198 % {\itshape%
199 % Quantum mechanics developed quickly in the 1920's thanks to the
200 % works of Schr\"odinger, Heisenberg, and Dirac, who drew inspiration
201 % from earlier ideas by Planck \AlE{and Einstein} \AlE[@JB, you forgot
202 % about me!]. Quantum mechanics appears to allow spooky action at a
203 % distance via some strange thing called ``entanglement,'' \JB*{but
204 % this can be explained with hidden variables}\JB{which has
205 % revolutionized our understanding of local realism.} \JB[@Albert,
206 % we talked about this...]%
207 % }
208 %
209 % Read on to learn more about how these commands can be used, what their main
210 % features are, how to customize them, and more.
211 %
212 % As an alternative to \pkgname{phfcc}, you can consider the package
213 % \pkgname{todonotes}\footnote{\url{https://ctan.org/pkg/todonotes}}. The
214 % commands defined in this package are designed for minimal effort by the
215 % commenter (e.g., they only have to type |\phf{...}| or |\phf[...]|). On the
216 % other hand \pkgname{todonotes} offers pretty boxes and more flexibility.
217 %
218 %
219 % \section{Syntax of commenting commands}
220 %
221 % Here is the full syntax of the commenting commands generated with
222 % |\phfMakeCommentingCommand|. Suppose the command |\AlE| was defined by
223 % issuing |\phfMakeCommentingCommand[initials={A.E.}]{AlE}|. You can write:
224 %
225 %
226 % |\AlE{some text here}| --- \AlE{some text here} --- typeset the given text in
227 % color, perhaps to mark an addition by author |AlE| to the document. By
228 % default, the initials associated with the command (here, ``A.E.'') will be
229 % issued in the margin once per page.
230 %
231 % |\AlE[please revise this]| --- \AlE[please revise this] --- typeset an inline
232 % comment in a different font. This is meant for comments that are not a
233 % portion of document text itself but rather an inline remark that refers to the
234 % text around it.
235 %
236 % You can use the |footcomments| style to have your comment typeset as a
237 % footnote. (See also \autoref{sec:styles} below.)
238 %
239 % |\AlE*{text to be removed}| --- \AlE*{text to be removed} --- typeset the
240 % given text in a way to indicate that the text should be suppressed.
241 %
242 % If you use Lua\LaTeX, you can get proper text strikethrough accross entire
243 % chunks of text by using the argument |style={rmstrikethrough}| to
244 % |\phfMakeCommentingCommand|. (See also \autoref{sec:styles} below.)
245 %
246 % |\AlE!{important piece of text}| --- \AlE!{important piece of text}
247 % --- typeset the given text marking it as important.
248 %
249 % |\AlE![a really important comment]| --- \AlE![a really important comment] ---
250 % typeset the given comment and mark it as important.
251 %
252 % In each of these cases (except for comments in square brackets),
253 % you can use the syntax |\AlE .... \endAlE| instead of specifying the
254 % argument using curly brackets:\\
255 % |\AlE text here\endAlE| --- \AlE text here\endAlE \\
256 % |\AlE! important\endAlE| --- \AlE! important\endAlE \\
257 % |\AlE* remove\endAlE| --- \AlE* remove\endAlE
258 %
259 % For simple text, you can also use the |\begin|/|\end| syntax:\\
260 % |\begin{AlE} text here\end{AlE}| --- \begin{AlE} text here\end{AlE}
261 %
262 % \begin{pkgtip}
263 % Note that in contrast to optional arguments in many LaTeX macros, the
264 % argument is allowed to contain matching square brackets, for instance
265 % \relax%
266 % |\AlE[inner brackets [like this] work as you'd expect]| \AlE[inner brackets
267 % [like this] work as you'd expect]
268 %
269 % In any case you can protect the argument as usual with curly braces:
270 % |\AlE[{this is [weird}]| \AlE[{this is [weird}]
271 % \end{pkgtip}
272 %
273 % \section{Defining your commenting command}
274 %
275 % Now let's see exactly how to define your customized |\AlE| command.
276 % \DescribeMacro{\phfMakeCommentingCommand} The command
277 % |\phfMakeCommentingCommand| takes the following syntax:
278 %
279 % |\phfMakeCommentingCommand|\oarg{key=value,key2=value2,...}\marg{cmd name}
280 %
281 % The \marg{command name} should be given as a text name (e.g.,
282 % |{AlE}|), and not as a macro. They key-value pairs may be one of the following:
283 %
284 %
285 % \phfMakeCommentingCommand[color=phfcolor,initials={PhF},formatinitials=box]{phfbox}
286 % \phfMakeCommentingCommand[color=phfcolor,initials={PhF},formatinitials=nobox]{phfnobox}
287 % \phfMakeCommentingCommand[color=phfcolor,initials={PhF},formatinitials=hide]{phfhideinitials}
288 % \phfMakeCommentingCommand[color=green!50!blue,initials={Philippe Faist},formatinitials=footnote]{phffootnote}
289 %
290 % \begin{cmdoptions}
291 % \item[color=\marg{color specification}] The color of the comments generated by
292 % the new commenting command. By default, a new suitable color is chosen for
293 % each new commenting command defined.
294 %
295 % The color specification may be a name such as |red|, |green|, etc., but also
296 % a mixture like |blue!40!green| (\textcolor{blue!40!green}{which stands for
297 % 40\% of blue and 60\% of green}). You can specify any argument you could
298 % specify to |\colorlet| from the \pkgname{xcolor} package. (The
299 % \pkgname{xcolor} package is automatically loaded.)
300 %
301 % \item[initials=\marg{your initials}] Your name initials, which will by typeset
302 % at the beginning of a comment (typically in a small box in the margin),
303 % allowing to identify different comment colors with different people. By
304 % default, the initials are set to the name of the command itself.
305 %
306 % \item[formatinitials=\meta{keyword or command}] The command that will be used
307 % to format the initials. By default (|formatinitials=default| or
308 % |formatinitials=margin|), the initials are displayed on the margin of the
309 % paragraph the first time the change occurs on a given page \phf[like this
310 % and like in the examples above]. You may also specify |formatinitials=box|
311 % to typeset the initials inline immediately before your annotation
312 % \phfbox[like this]. Specify |formatinitials=nobox| to remove the frame
313 % \phfnobox[like this]. Or specify |formatinitials=hide| to hide the initials
314 % altogether \phfhideinitials[like this]. You can also specify
315 % |formatinitials=footnote| to hide the initials at the point of text but with
316 % a footnote to associate colored comments with the name (for this to work
317 % more nicely, specify your full name as argument to |initials={...}|)
318 % \phffootnote[Here is an example]. [See
319 % \autoref{sec:customize-initials-formatting} for customizing the formatting of
320 % the margin initials for the |margin| style or for changing the text in the
321 % footnote in the |footnote| style.]
322 %
323 % You may also specify as a value to the |formatinitials=| option any \LaTeX{}
324 % command, which will then be used to format the initials. The macro should
325 % accept a single argument, the initials.
326 %
327 % The default initials formatting style (|formatinitials=margin|) requires the
328 % \pkgname{marginnote} package, which is loaded automatically. If you do not
329 % want to load the \pkgname{marginnote} package, specify the package option
330 % |usemarginnote=false| and set a different |formatinitials=...| style.
331 %
332 % \item[style=\marg{style name(s)}] Load one or more existing style(s) for the
333 % commenting command. The styles must either be predefined, or must have been
334 % defined using |\phfDefineCommentingStyle|. Separate style names with a
335 % comma.
336 %
337 % \item[font=\marg{LaTeX commands}] The font commands to invoke when typesetting
338 % annotations, regardless of type. By default, \phf{the font is unchanged
339 % other than having the author-specific color set}. Also, the font is not
340 % reset, so if you type an annotation somewhere where the font is large, the
341 % annotation's font will match that font by default. (Different annotation
342 % types may set their own font, see below.)
343 % \item[spacing=\meta{length}] Spacing to add around normal annotations. This
344 % amount of horizontal space is added before and after the annotation.
345 % \item[begin=\marg{LaTeX text and/or commands}] Stuff to typeset at the
346 % beginning of a general annotation. Nothing is typeset by default.
347 % \item[end=\marg{LaTeX text and/or commands}] Stuff to typeset at the end of a
348 % general annotation. Nothing is typeset by default.
349 %
350 % \item[cfont=\marg{LaTeX commands}] The font commands to invoke when
351 % typesetting an in-line comment. By default, use \phf[the default sans serif
352 % typeface, like this].
353 % \item[cspacing=\meta{length}] Spacing to add around comments. This amount of
354 % horizontal space is added before and after the comment.
355 % \item[cbegin=\marg{LaTeX text and/or commands}] Stuff to typeset at
356 % the beginning of a commment. By default, an opening square
357 % bracket (with some spacing adjustments).
358 % \item[cend=\marg{LaTeX text and/or commands}] Stuff to typeset at
359 % the end of a commment. By default, a closing square bracket (with
360 % some spacing adjustments).
361 %
362 % \item[rmfont=\marg{LaTeX commands}] The font commands to issue when
363 % typesetting text that is to be removed. \phf*{By default, the text is in
364 % italics like this} (If you're using Lua\LaTeX, it's recommended to use the
365 % |rmstrikethrough| style for proper strikethrough text; see
366 % \autoref{sec:styles}.)
367 % \item[rmspacing=\meta{length}] Spacing to add around text that is marked to be
368 % removed. This amount of horizontal space is added before and after.
369 % \item[rmbegin=\marg{LaTeX text and/or commands}] Stuff to typeset at the
370 % beginning of a piece of text to be removed. By default, a line overlapping
371 % with the text, to suggest removal.
372 % \item[rmend=\marg{LaTeX text and/or commands}] Stuff to typeset at the end of
373 % a piece of text to be removed. By default, a line overlapping with the
374 % text, to suggest removal.
375 %
376 % \item[ifont=\marg{LaTeX commands}] The font commands to issue when
377 % typesetting important text. \phf!{By default, the text is in
378 % larger boldface format like this}
379 % \item[ispacing=\meta{length}] Spacing to add around important text. This
380 % amount of horizontal space is added before and after.
381 % \item[ibegin=\marg{LaTeX text and/or commands}] Stuff to typeset at
382 % the beginning of a piece of important text. By default, three
383 % exclamation marks.
384 % \item[iend=\marg{LaTeX text and/or commands}] Stuff to typeset at
385 % the end of a piece of important text. By default, three
386 % exclamation marks.
387 % \end{cmdoptions}
388 %
389 % After invoking |\phfMakeCommentingCommand|, the colors |xxxcolor|,
390 % |xxxrmcolor| and |xxxrmcolorlink| are automatically defined (where |xxx| is to
391 % be replaced by your commenting macro name). These are used respectively for
392 % a usual comment color, text to be removed, and for links in text to be
393 % removed. You may redefine these colors afterwards with |\colorlet| if you
394 % wish:
395 % \begin{verbatim}
396 % \colorlet{AlErmcolor}{gray}
397 % \end{verbatim}
398 %
399 % \DescribeMacro{\phfDisableCommentingCommands}
400 % The command |\phfDisableCommentingCommands| disables all commenting commands,
401 % and causes them to emit an error. Use this command when approaching the final
402 % version of a long document to ensure that no commenting commands are left in
403 % the document.
404 %
405 % \subsection{Commenting Styles}
406 % \label{sec:styles}
407 %
408 % \emph{Styles} regroup a collection of definitions that alter the overall
409 % behavior and appearance of commenting commands issued with
410 % |\phfMakeCommentingCommand|. You can assign one or more styles to a
411 % commenting command definition by using the |style=| keyword:
412 % \begin{verbatim}
413 % \phfMakeCommentingCommand[style={footcomments}]{JD} % \JD
414 % \end{verbatim}
415 %
416 % You can combine style names with commas, for instance:
417 %
418 % \begin{verbatim}
419 % \phfMakeCommentingCommand[style={rmstrikethrough,footcomments}]{JD} % \JD
420 % \end{verbatim}
421 %
422 % \phfMakeCommentingCommand[rmbegin={},rmend={},rmspacing=2pt,initials={ZZ}]{dummycmd}
423 % \phfMakeCommentingCommand[style={footcomments},initials={YY}]{dummyYY}
424 % The following styles are predefined:
425 % \begin{itemize}
426 % \item \leavevmode\PrintMarginLabel{footcomments} The |footcomments| style
427 % arranges for in-line comments to be typeset as footnotes.
428 %
429 % \begin{verbatim}
430 % \phfMakeCommentingCommand[style={footcomments}]{YY}
431 %
432 % For instance, \YY[This would be an example of a comment
433 % typeset as a footnote.] this text might be suitable to
434 % comment on.
435 % \end{verbatim}
436 % gives:
437 %
438 % ``For instance, \dummyYY[This would be an example of a comment typeset as a
439 % footnote.] this text might be suitable to comment on.''
440 %
441 % This style can be convenient to place comments without interrupting the
442 % natural flow of the text.
443 %
444 % You can redefine |\phfccfootcommentwrapfnmark{..}| to customize the
445 % appearance of the footnote mark, and |\phfccfootcommenttextstyle| to get
446 % some handle on the commands issued within the footnote contents.
447 % \begin{verbatim}
448 % \renewcommand\phfccfootcommentwrapfnmark[1]{[[#1]]}
449 % \renewcommand\phfccfootcommenttextstyle{\bfseries}
450 % \end{verbatim}
451 %
452 % \item \leavevmode\PrintMarginLabel{rmstrikethrough} For Lua\LaTeX\ users, the
453 % style |rmstrikethrough| is available to make text marked for removal drawn
454 % in strikethrough font, \dummycmd*{\sout{kind of like this}}. You can cross
455 % out entire paragraphs of text which include display equations. Simply use:
456 % \begin{verbatim}
457 % \phfMakeCommentingCommand[style=rmstrikethrough]{ZZ} % requires LuaLaTeX
458 %
459 % ... \ZZ*{text to be removed} ... or also ... \ZZ* more
460 % text that I want to remove\endZZ ...
461 % \end{verbatim}
462 %
463 % The implementation uses the |lua-ul| package, which requires Lua\LaTeX. To
464 % apply this style to all definitions, use
465 % |\phfSetDefaultCommentingStyle{style=rmstrikethrough}| (see below).
466 %
467 % (We do not support strikethrough for regular \LaTeX\ because we weren't able
468 % to find an implementation that worked reliably even for large blocks of
469 % text. For instance, using the |\sout| from the \pkgname{ulem} package, you
470 % cannot strikethrough multiple paragraphs with displayed equations. Plus, to
471 % support the extended syntax of |\phfcc|'s commenting commands, we need the
472 % strikethrough to be implemented by a state change macro (like |\itshape|) or
473 % an environment, and not by a macro that accepts an argument.)
474 %
475 % \item We'll probably add more predefined styles in the future.
476 % \end{itemize}
477 %
478 % \DescribeMacro{\phfDefineCommentingStyle}
479 % You can define a style using |\phfDefineCommentingStyle|:
480 % \begin{verbatim}
481 % \phfDefineCommentingStyle{mystyle}{
482 % font={\fontfamily{phv}\selectfont}, % phv = Helvetica
483 % cfont={\bfseries\large},
484 % cbegin={{\ensuremath{\bigl\langle}}~},
485 % cend={{~\ensuremath{\bigr\rangle}}}
486 % }
487 % \end{verbatim}
488 % You can then define your commenting command invoking this style:
489 % \begin{verbatim}
490 % \phfMakeCommentingCommand[style=mystyle]{me}
491 % \end{verbatim}
492 %
493 % \phfDefineCommentingStyle{mystyle}{
494 % font={\fontfamily{phv}\selectfont},
495 % cfont={\bfseries\large},
496 % cbegin={{\ensuremath{\bigl\langle}}~},
497 % cend={{~\ensuremath{\bigr\rangle}}}
498 % }
499 % \phfMakeCommentingCommand[style=mystyle]{me}
500 %
501 % Then \me{for example}, (which was typeset using |\me{for example}|,) the code
502 % |\me[A comment]| becomes: \me[A comment].
503 %
504 % Styles are loaded in the order they are specified (separate style names with
505 % commas). Style definitions may themselves contain |style=...| keys to load
506 % other styles. Styles are always loaded before user keys, regardless of where
507 % the `|style|' key appears in the definition. When styles are loaded, and when
508 % the users' keys are set, later keys are overwrite earlier
509 % ones.\footnote{Except for an as-of-yet undocumented \phfverb{startcmds} and
510 % \phfverb{endcmds} keys which might be relevant if you'd like to develop a
511 % style which requires you to issue definitions at the beginning of every
512 % annotation.}
513 %
514 % \DescribeMacro{\phfSetDefaultCommentingStyle} Instead of defining named styles
515 % which have to be invoked explicitly, you can also preset the style of all
516 % future calls of |\phfMakeCommentingCommand|. You can achieve this result with
517 % the |\phfSetDefaultCommentingStyle| command:
518 % \begin{verbatim}
519 % \phfSetDefaultCommentingStyle{
520 % font={\large}
521 % }
522 % % all annotations defined from here on will appear larger
523 % \phfMakeCommentingCommand{AB}
524 % \end{verbatim}
525 %
526 % You can also use |\phfMakeCommentingCommand| to set one or more default
527 % style(s) for all future commenting command definitions:
528 % \begin{verbatim}
529 % \phfSetDefaultCommentingStyle{
530 % style={rmstrikethrough,footcomments}
531 % }
532 % % all annotations defined from here on will have these styles set
533 % \phfMakeCommentingCommand{AB}
534 % \end{verbatim}
535 %
536 % \subsection{Customizing the formatting of the initials label}
537 % \label{sec:customize-initials-formatting}
538 %
539 % \paragraph{For the \phfverb{formatinitials=margin} style:}
540 %
541 % You can customize the appearance of the initials in the margin when using the
542 % |formatinitials=margin| initials style by redefining the following macros.
543 % Changes affect all margin labels (i.e., changes affect all commenting commands
544 % using the |margin| initials formatting style).
545 %
546 % \DescribeMacro{\phfccformatmargininitials} The |\phfccformatmargininitials| is
547 % used to format the initials in the margin. You can redefine it if you'd like
548 % the initials to appear differently. Adapt the following, which contains the
549 % default definition, to your liking:
550 % \begin{verbatim}
551 % \renewcommand{\phfccformatmargininitials}[1]{%
552 % \fbox{\normalfont\sffamily\footnotesize #1}%
553 % }
554 % \end{verbatim}
555 % (Technical note: the |\fboxsep| length has been set to |1pt| prior to calling
556 % this macro.)
557 %
558 % \DescribeMacro{\phfccmargininitialssep} The |\phfccmargininitialssep| length
559 % is the minimal vertical separation between two initials labels. This is a
560 % length, so you should change it with |\setlength|:
561 % \begin{verbatim}
562 % \setlength{\phfccmargininitialssep}{2pt}
563 % \end{verbatim}
564 %
565 % \paragraph{For the \phfverb{formatinitials=box} and
566 % \phfverb{formatinitials=nobox} styles:}
567 %
568 % \DescribeMacro{\phfccformatboxinitials} For the |formatinitials=box| and
569 % |formatinitials=nobox| initials style, you can redefine the command
570 % |\phfccformatboxinitials| to typeset the initials, like so:
571 % \begin{verbatim}
572 % \renewcommand{\phfccformatboxinitials}[1]{%
573 % \normalfont\sffamily\tiny#1%
574 % }
575 % \end{verbatim}
576 %
577 % \paragraph{For the \phfverb{formatinitials=footnote} style:}
578 %
579 % \DescribeMacro{\phfCCChangesBy} When using the |formatinitials=footnote|
580 % initials formatting style, you may redefine |\phfCCChangesBy| to change the
581 % text in the footnote:
582 % \begin{verbatim}
583 % \renewcommand{\phfCCChangesBy}[1]{Changes in this color are by #1}
584 % \end{verbatim}
585 %
586 % \section{Package Options}
587 %
588 % This package requires the \pkgname{marginnote} package to generate initials
589 % labels when using the |margin| initials style (the default style). If you do
590 % not want to load the \pkgname{marginnote} package, you may use the package
591 % option |usemarginnote=false| (but then you cannot use the |margin| initials
592 % style):
593 % \begin{verbatim}
594 % \usepackage[usemarginnote=false]{phfcc}
595 % \end{verbatim}
596 %
597 % \section{Known limitations}
598 %
599 % There are some cases where it's hard to get everything right. The
600 % \pkgname{phfcc} commands do their best to get stuff right and to avoid
601 % generating obscure \LaTeX{} errors, but there might be times where not
602 % everything works as expected.
603 %
604 % \begin{itemize}
605 % \item If you place a comment inside certain contructs that are processed twice
606 % by \LaTeX{} (e.g., a figure caption when using e.g. the \pkgname{caption}
607 % package, etc.) then the margin initials will not appear even if the comment
608 % is the first of the page. This is because the margin label is produced the
609 % first time they are typeset, per page; if that happened to be in a temporary
610 % \TeX{} box that was then discarded, the margin note gets discarded along
611 % with it.
612 %
613 % In the case of AMS equations, there's a hack that make the labels appear
614 % right. Feel free to send pull requests to address other cases.
615 %
616 % \phf[FIXME: A better solution might be to write to the AUX file at each
617 % comment, so that the information is written when the comment is actually
618 % typeset, and then process where to put margin labels on the second run of
619 % \LaTeX{}.
620 %
621 % As a bonus, this would enable stuff like ``list of comments'' like the
622 % \pkgname{todonotes} package does. Even though I don't think it's necessary
623 % for the standard use case of this package.]
624 %
625 % \item Initials in the margin might overlap in some edge cases. See my
626 % comments and footnotes in the implementation documentation below.
627 %
628 % \item Initials in the margin might not appear if the comment immediately
629 % follows a page break, because the comment might have been processed while
630 % \LaTeX{} was on the previous page before deciding to start a new page. See
631 % my comments and footnotes in the implementation doc below.
632 % \end{itemize}
633 %
634 %
635 %
636 % \StopEventually{\PrintChangesAndIndex}
637 %
638 % \section{Implementation}
639 %
640 % Load these internally required packages.
641 %
642 % \begin{macrocode}
643 \RequirePackage{xkeyval}
644 \RequirePackage{kvoptions}
645 \RequirePackage{etoolbox}
646 \RequirePackage{xparse}
647 % \end{macrocode}
648 %
649 % Ensure we have the \pkgname{xcolor} package to manage text colors. We need
650 % \pkgname{xcolor} and not \pkgname{color} because we use |\colorlet|.
651 % \begin{macrocode}
652 \RequirePackage{xcolor}
653 % \end{macrocode}
654 %
655 %
656 % \subsection{Set up default settings}
657 %
658 % \begin{macro}{\phfCommentingDefault...}
659 % Provide sensible defaults for commenting formatting.
660 %
661 % Bold or semibold CFont sounds like a good idea, but comments would seem more
662 % aggressive like that, so keep them normal by default.
663 % \begin{macrocode}
664 \def\phfCommentingDefaultStartCmds{}
665 \def\phfCommentingDefaultEndCmds{}
666 \def\phfCommentingDefaultFont{}
667 \def\phfCommentingDefaultSpacing{0pt}
668 \def\phfCommentingDefaultBegin{}
669 \def\phfCommentingDefaultEnd{}
670 \def\phfCommentingDefaultCFont{\normalfont\sffamily}
671 \def\phfCommentingDefaultCSpacing{0.2em}
672 \def\phfCommentingDefaultCBegin{[\,}
673 \def\phfCommentingDefaultCEnd{\,]}
674 \def\phfCommentingDefaultRmFont{\small\itshape}%\itshape\notesmaller[0.9]}
675 \def\phfCommentingDefaultRmSpacing{.3em}
676 \def\phfCommentingDefaultRmBegin{%
677 \mbox{}\vrule height .55ex depth -.45ex width 1.4em\relax\hspace*{0.2em}%
678 \vrule height .55ex depth -.45ex width 0.6em\relax
679 \hspace*{-2em}}
680 \def\phfCommentingDefaultRmEnd{%
681 \hspace*{-2em}%
682 \vrule height .55ex depth -.45ex width 0.6em\relax\hspace*{0.2em}%
683 \vrule height .55ex depth -.45ex width 1.4em\relax}
684 \def\phfCommentingDefaultIFont{\large\bfseries}
685 \def\phfCommentingDefaultISpacing{0.25em}
686 \def\phfCommentingDefaultIBegin{!\hspace*{0.1em}!\hspace*{0.1em}!~}
687 \def\phfCommentingDefaultIEnd{~!\hspace*{0.1em}!\hspace*{0.1em}!}
688 % \end{macrocode}
689 % \end{macro}
690 %
691 % A default list of colors for commenting, and a minimal tool to select the next
692 % available color. The macro |\phf@cc@usedcolors| stores a
693 % vertical-bar-separated list of color names that have been already used and
694 % which should not be used again.
695 % \begin{macrocode}
696 \definecolor{phfcc0}{RGB}{0,148,240} % blue-y
697 \definecolor{phfcc1}{RGB}{242,108,13} % orange-brown-y
698 \definecolor{phfcc2}{RGB}{65,149,42} % green-y
699 \definecolor{phfcc3}{RGB}{128,55,134} % purple-y
700 \definecolor{phfcc4}{RGB}{0,129,129} % blue-green-y
701 \definecolor{phfcc5}{RGB}{148,7,24} % dark red / burgundy
702 \definecolor{phfcc6}{RGB}{160,120,0} % brownish
703 \definecolor{phfcc7}{RGB}{35,195,155} % aqua-ish
704 \csdef{phf@cc@presetcolor@0}{phfcc0}
705 \csdef{phf@cc@presetcolor@1}{phfcc1}
706 \csdef{phf@cc@presetcolor@2}{phfcc2}
707 \csdef{phf@cc@presetcolor@3}{phfcc3}
708 \csdef{phf@cc@presetcolor@4}{phfcc4}
709 \csdef{phf@cc@presetcolor@5}{phfcc5}
710 \csdef{phf@cc@presetcolor@6}{phfcc6}
711 \csdef{phf@cc@presetcolor@7}{phfcc7}
712 \def\phf@cc@usedcolors{|}
713 \def\phf@cc@nextcolor@#1{%
714 \ifcsname phf@cc@presetcolor@#1\endcsname% try preset
715 \edef\phf@tmp@testxx{%
716 \noexpand\in@{|\csname phf@cc@presetcolor@#1\endcsname|}{\phf@cc@usedcolors}}%
717 \phf@tmp@testxx
718 \ifin@% color already used, try next
719 \expandafter\phf@cc@nextcolor@\expandafter{\the\numexpr#1+1\relax}%
720 \else
721 \def\phf@cc@thecolor{\csname phf@cc@presetcolor@#1\endcsname}% good, use
722 \fi
723 \else% out of colors, fallback to red
724 \def\phf@cc@thecolor{red}%
725 \fi
726 }
727 % \end{macrocode}
728 % Read the argument. If non-empty, set |\phf@cc@thecolor| to the argument
729 % value. If empty, choose the next available preset color and set
730 % |\phf@cc@thecolor| to that.
731 % \begin{macrocode}
732 \def\phf@cc@getcolor#1{%
733 \edef\phf@tmp@xyz{#1}%
734 \if\relax\detokenize\expandafter{\phf@tmp@xyz}\relax
735 \phf@cc@nextcolor@{0}%
736 \else
737 \edef\phf@cc@thecolor{#1}%
738 \fi}
739 % \end{macrocode}
740 %
741 %
742 %
743 % Define the keys for |\setkeys| with \pkgname{xkeyval} package, and set the
744 % overall defaults.
745 % \begin{macrocode}
746 \def\phfcc@hook@phfmkccstyle@setstyle@noop#1{}
747 \let\phfcc@hook@phfmkccstyle@setstyle\phfcc@hook@phfmkccstyle@setstyle@noop
748 \define@cmdkey{phfmkccstyle}{style}{\phfcc@hook@phfmkccstyle@setstyle{#1}}
749
750 \define@cmdkey{phfmkcc}{color}{}
751 \define@cmdkey{phfmkcc}{initials}{}
752 \define@cmdkey{phfmkcc}{formatinitials}{}
753 \newtoks\cmdKV@phfmkcc@startcmds
754 \newtoks\cmdKV@phfmkcc@endcmds
755 \define@key{phfmkcc}{startcmds}{%
756 \cmdKV@phfmkcc@startcmds=\expandafter{\the\cmdKV@phfmkcc@startcmds#1}%
757 }
758 \define@key{phfmkcc}{endcmds}{%
759 \edef\x{\unexpanded{#1}\the\cmdKV@phfmkcc@endcmds}%
760 \cmdKV@phfmkcc@endcmds=\expandafter{\x}%
761 }
762 \define@cmdkey{phfmkcc}{font}{}
763 \define@cmdkey{phfmkcc}{spacing}{}
764 \define@cmdkey{phfmkcc}{begin}{}
765 \define@cmdkey{phfmkcc}{end}{}
766 \define@cmdkey{phfmkcc}{cfont}{}
767 \define@cmdkey{phfmkcc}{cspacing}{}
768 \define@cmdkey{phfmkcc}{cbegin}{}
769 \define@cmdkey{phfmkcc}{cend}{}
770 \define@cmdkey{phfmkcc}{rmfont}{}
771 \define@cmdkey{phfmkcc}{rmspacing}{}
772 \define@cmdkey{phfmkcc}{rmbegin}{}
773 \define@cmdkey{phfmkcc}{rmend}{}
774 \define@cmdkey{phfmkcc}{ifont}{}
775 \define@cmdkey{phfmkcc}{ispacing}{}
776 \define@cmdkey{phfmkcc}{ibegin}{}
777 \define@cmdkey{phfmkcc}{iend}{}
778 \define@cmdkey{phfmkcc}{groupcmd}{}
779 % \end{macrocode}
780 %
781 % Factory defaults refer to the |\phfCommentingDefault***| commands.
782 % \begin{macrocode}
783 \presetkeys{phfmkcc}{%
784 color={},%
785 initials={},%
786 formatinitials={default},%
787 startcmds={\phfCommentingDefaultStartCmds},%
788 endcmds={\phfCommentingDefaultEndCmds},%
789 font={\phfCommentingDefaultFont},%
790 spacing={\phfCommentingDefaultSpacing},%
791 begin={\phfCommentingDefaultBegin},%
792 end={\phfCommentingDefaultEnd},%
793 cfont={\phfCommentingDefaultCFont},%
794 cspacing={\phfCommentingDefaultCSpacing},%
795 cbegin={\phfCommentingDefaultCBegin},%
796 cend={\phfCommentingDefaultCEnd},%
797 rmfont={\phfCommentingDefaultRmFont},%
798 rmspacing={\phfCommentingDefaultRmSpacing},%
799 rmbegin={\phfCommentingDefaultRmBegin},%
800 rmend={\phfCommentingDefaultRmEnd},%
801 ifont={\phfCommentingDefaultIFont},%
802 ispacing={\phfCommentingDefaultISpacing},%
803 ibegin={\phfCommentingDefaultIBegin},%
804 iend={\phfCommentingDefaultIEnd},%
805 groupcmd={\@firstofone}%
806 }{}
807 % \end{macrocode}
808 %
809 % \subsection{Helpers and handlers for styles}
810 %
811 % \begin{macro}{\phfDefineCommentingStyle}
812 % User interface for defining custom comment styles.
813 % \begin{macrocode}
814 \newcommand\phfDefineCommentingStyle[2]{%
815 \csdef{phfcc@style@#1}{#2}%
816 }
817 % \end{macrocode}
818 % \end{macro}
819 % \begin{macro}{\phfSetDefaultCommentingStyle}
820 % User interface for defining the default settings for all commenting commands
821 % declared from now on. Keep note of |style=| keywords separately (in
822 % |\phfcc@default@style|), because we cannot place them as |\presetkeys| in
823 % the main options family.
824 % \begin{macrocode}
825 \def\phfcc@default@style{}
826 \def\phfcc@hook@phfmkccstyle@setstyle@savestyle#1{%
827 \xdef\phfcc@default@style{#1}%
828 }
829 \newcommand\phfSetDefaultCommentingStyle[1]{%
830 \let\phfcc@hook@phfmkccstyle@setstyle\phfcc@hook@phfmkccstyle@setstyle@savestyle
831 \setkeys*{phfmkccstyle}{#1}%
832 \let\phfcc@hook@phfmkccstyle@setstyle\phfcc@hook@phfmkccstyle@setstyle@noop
833 \edef\x{\noexpand\presetkeys{phfmkcc}{\expandonce\XKV@rm}{}}%
834 \x
835 }
836 % \end{macrocode}
837 % \end{macro}
838 %
839 % \subsubsection{Internal helpers for loading styles}
840 %
841 % \begin{macro}{\phfcc@expandstylekeys}
842 % Helpers to expand style= instructions in a set of key=vals.
843 %
844 % The helper macro |\phfcc@expandstylekeys| accepts two arguments. The
845 % argument |#1| is a list of style names and |#2| is a collection of key=value
846 % pairs. This macro computes all the key=value settings that should be
847 % applied from the style definitions, plus all the remaining user key=value
848 % settings. We will recursively look for style=... keywords so that styles
849 % can load other styles.
850 %
851 % The final expanded key=value pairs is set in the token register
852 % |\phfcc@val@expanded@keyval|.
853 % \begin{macrocode}
854 \newtoks\phfcc@val@expanded@keyval
855 \def\phfcc@expandstylekeys#1#2{%
856 \def\phfcc@val@expanded@preexpandstyles{#1}%
857 \phfcc@val@expanded@keyval={#2}%
858 \loop
859 \phfcc@expandstylekeys@once
860 \def\phfcc@val@expanded@preexpandstyles{}%
861 \ifnum\phfcc@val@expanded@needmore=1\repeat
862 }
863 % \end{macrocode}
864 %
865 % The implementation of |\phfcc@expandstylekeys| proceeds by iterating single
866 % expansions until there are no more |style={}| values left. A single iteration
867 % is implemented here. The following macro reads its input from
868 % |\phfcc@val@expanded@preexpandstyles| and |\phfcc@val@expanded@keyval|, and it
869 % sets the macros |\phfcc@val@expanded@keyval| and
870 % |\phfcc@val@expanded@needmore|.
871 % \begin{macrocode}
872 \def\phfcc@expandstylekeys@once{%
873 \def\cmdKV@phfmkccstyle@style{}
874 \edef\x{\noexpand\setkeys*{phfmkccstyle}{\the\phfcc@val@expanded@keyval}}%
875 \x
876 % \end{macrocode}
877 % The |style={...}| values is stored in the macro |\cmdKV@phfmkccstyle@style|.
878 % If it is empty, there is no style to set and we're done.
879 % \begin{macrocode}
880 \if\relax\detokenize\expandafter{\cmdKV@phfmkccstyle@style}\relax
881 \def\phfcc@val@expanded@needmore{0}%
882 \else
883 \def\phfcc@val@expanded@needmore{1}%
884 \fi
885 % \end{macrocode}
886 % We might have one or more styles to expand. Iterate over the comma-separated
887 % list of styles and we'll append the collected style-specific key=value
888 % definitions in the macro |\phfcc@val@fullstylekeyvals| for now. Include also
889 % the predefined style names to expand before the user-specified styles.
890 % \begin{macrocode}
891 \def\phfcc@val@fullstylekeyvals{}%
892 \edef\phfcc@tmp@thestylelist{%
893 \phfcc@val@expanded@preexpandstyles,\cmdKV@phfmkccstyle@style}%
894 \@for\phfcc@tmp@next:=\phfcc@tmp@thestylelist \do{%
895 % \end{macrocode}
896 % At this point we're requested to expand the style whose name is stored in
897 % |\phfcc@tmp@next|. Collect the key=value definitions in the macro named
898 % |\phfcc@style@STYLENAME| or produce an error if such macro does not exist.
899 % Also, if the style provides a macro named |\phfcc@styleused@STYLENAME|, then
900 % invoke it at this point, in case the style would like to load any additional
901 % packages or execute any other preamble-time setup steps. In the following
902 % |\phfcc@tmp@stylekeyvals| is defined so that its immediate expansion yields
903 % the styles' key=value definitions.
904 % \begin{macrocode}
905 \ifcsname phfcc@style@\phfcc@tmp@next \endcsname
906 \ifcsname phfcc@styleused@\phfcc@tmp@next \endcsname
907 \csname phfcc@styleused@\phfcc@tmp@next \endcsname
908 \fi
909 \edef\phfcc@tmp@stylekeyvals{%
910 \expandafter\expandonce\csname phfcc@style@\phfcc@tmp@next \endcsname}%
911 \edef\phfcc@val@fullstylekeyvals{%
912 \expandonce\phfcc@val@fullstylekeyvals,%
913 \expandonce\phfcc@tmp@stylekeyvals}%
914 \else
915 \if\relax\detokenize\expandafter{\phfcc@tmp@next}\relax
916 \else
917 \PackageError{phfcc}{Requested commenting style `\phfcc@tmp@next' %
918 is not defined}{}%
919 \fi
920 \fi
921 }%
922 % \end{macrocode}
923 % Now we can collect the definitions from the styles and merge them with the
924 % remaining non-style-related user key/values. The macro |\XKV@rm| is set by
925 % \pkgname{xkeyval} to those key/values not processed by |\setkeys*|.
926 % \begin{macrocode}
927 \edef\x{\noexpand\phfcc@val@expanded@keyval={%
928 \expandonce\phfcc@val@fullstylekeyvals,%
929 \expandonce\XKV@rm}}%
930 \x
931 }
932 % \end{macrocode}
933 % \end{macro}
934 %
935 %
936 % \subsubsection{The \phfverb{rmstrikethrough} predefined style}
937 %
938 % \begin{macro}{\phfcc@style@rmstrikethrough}
939 % The definition of the |rmstrikethrough| style is fairly straightforward.
940 % \begin{macrocode}
941 \gdef\phfcc@styleused@rmstrikethrough{%
942 \RequirePackage{lua-ul}
943 \newunderlinetype\beginPhfccStrikeThrough{%
944 \leaders\vrule height .55ex depth -.45ex}
945 \gdef\phfcc@styleused@rmstrikethrough{}% auto-destruct/only run once
946 }
947 \def\phfcc@style@rmstrikethrough{%
948 rmfont={\beginPhfccStrikeThrough},
949 rmbegin={},
950 rmend={},
951 rmspacing={2pt}
952 }
953 % \end{macrocode}
954 % \end{macro}
955 %
956 % \subsubsection{The \phfverb{footcomments} predefined style}
957 %
958 % \begin{macro}{\phfcc@style@footcomments}
959 % The |footcomments| style uses |startcmds| and |endcmds| to collect material
960 % and then typeset it into a footnote.
961 % \begin{macrocode}
962 \def\phfcc@style@footcomments{%
963 startcmds={\phfcc@collectcommentfootnote},
964 endcmds={\phfcc@endcollectcommentfootnote},
965 }
966 % \end{macrocode}
967 % \end{macro}
968 % \begin{macro}{\phfccfootcommenttextstyle}
969 % The macro |\phfccfootcommenttextstyle| can be redefined to customize the
970 % footnote text appearance.
971 % \begin{macrocode}
972 \def\phfccfootcommenttextstyle{\footnotesize}
973 % \end{macrocode}
974 % \end{macro}
975 %
976 % Now we define helpers to collect the contents of the footnote, and then
977 % typeset it.
978 %
979 % \begin{macro}{\phfcc@collectcommentfootnote}
980 % \begin{macro}{\phfcc@endcollectcommentfootnote}
981 % The entry point to these helpers are the macros
982 % |\phfcc@collectcommentfootnote| and |\phfcc@endcollectcommentfootnote|: They
983 % check whether this annotation is a comment and then call our main helpers if
984 % that's the case.
985 % \begin{macrocode}
986 \def\phfcc@collectcommentfootnote{%
987 \if@phfcc@iscomment
988 \expandafter\phfcc@collectfootnote
989 \fi}
990 \def\phfcc@endcollectcommentfootnote{%
991 \if@phfcc@iscomment
992 \expandafter\phfcc@endcollectfootnote
993 \fi}
994 % \end{macrocode}
995 % \end{macro}
996 % \end{macro}
997 %
998 % \begin{macro}{\phfcc@collectfootnote}
999 % \begin{macro}{\phfcc@endcollectfootnote}
1000 % \begin{macro}{\phfcc@startfootnote}
1001 % The helper |\phfcc@collectfootnote| collects the material and builds the
1002 % footnote. I had to copy some footnote-building code from |latex.ltx|
1003 % unfortunately: We can't call |\footnote{}| because it requires a macro
1004 % argument; we need begin/end macros to feed all the footnote contents and
1005 % material as \TeX\ parses it. Recall that \LaTeX's |\footnote| basically (1)
1006 % steps the footnote counter (the counter name is stored in |\@mpfn| and the
1007 % printable value is given by |\thempfn|) and prints the footnote mark
1008 % (|\@footnotemark|), and (2) collects material in the |\insert| called
1009 % |\footins|. The code relevant to (1) is collected in
1010 % |\phfcc@startfootnote|. The code relevant to (2) is collected and adapted
1011 % below between |\phfcc@collectfootnote| and |\phfcc@endcollectfootnote|.
1012 % \begin{macrocode}
1013 \def\phfcc@collectfootnote{%
1014 \phfcc@startfootnote
1015 \insert\footins\bgroup%
1016 \reset@font\footnotesize
1017 \interlinepenalty\interfootnotelinepenalty
1018 \splittopskip\footnotesep
1019 \splitmaxdepth \dp\strutbox \floatingpenalty \@MM
1020 \hsize\columnwidth \@parboxrestore
1021 \protected@edef\@currentlabel{%
1022 \csname p@footnote\endcsname\@thefnmark
1023 }%
1024 \color@begingroup
1025 \@makefntext{%
1026 \rule\z@\footnotesep\@finalstrut\strutbox\phfcc@hackrevtex@skippar}%
1027 \ignorespaces
1028 \footnotesize
1029 \color{\phf@cc@val@cur color}%
1030 \phfccfootcommenttextstyle
1031 }
1032 \def\phfcc@endcollectfootnote{%
1033 \unskip
1034 \color@endgroup
1035 \egroup
1036 }
1037 \def\phfcc@startfootnote{%
1038 \stepcounter\@mpfn
1039 \protected@xdef\@thefnmark{\thempfn}%
1040 \phfccfootcommentwrapfnmark{\@footnotemark}%
1041 }
1042 \def\phfccfootcommentwrapfnmark#1{%
1043 [#1]%
1044 }
1045 % \end{macrocode}
1046 % Above, we used the class-provided |\@makefntext| macro to make comment
1047 % footnotes look like the other document-provided footnotes, but we invoke that
1048 % macro with dummy content because remember, we haven't collected the footnote
1049 % contents yet. But some latex classes, like Rev\TeX, this macro add a
1050 % paragraph; so we need to eliminate that paragraph break that would otherwise
1051 % appear at the beginning of the footnote:
1052 % \begin{macrocode}
1053 \def\phfcc@hackrevtex@skippar{%
1054 \@ifnextchar\par\@gobble\relax
1055 }
1056 % \end{macrocode}
1057 % \end{macro}
1058 % \end{macro}
1059 % \end{macro}
1060 %
1061 %
1062 % \subsection{Define styles for initials formatting}
1063 %
1064 % Define the implementations for the different initials formatting. These are
1065 % by default the small boxes that appear in the margin that match color to
1066 % comment owner.
1067 %
1068 % Define the |margin| initials style as the default:
1069 % \begin{macrocode}
1070 \def\phf@cc@formatinitialsstyle@default{\phf@cc@formatinitialsstyle@margin}
1071 % \end{macrocode}
1072 %
1073 % \subsubsection{Define styles \phfverb{hide}, \phfverb{box}, \phfverb{nobox}}
1074 %
1075 % \begin{macro}{\phf@cc@formatinitialsstyle@hide}
1076 % Define the no-op |hide| style first.
1077 % \begin{macrocode}
1078 \def\phf@cc@formatinitialsstyle@hide#1{}
1079 % \end{macrocode}
1080 % \end{macro}
1081 %
1082 % \begin{macro}{\phf@cc@formatinitialsstyle@box}
1083 % \begin{macro}{\phf@cc@formatinitialsstyle@nobox}
1084 % Define the |box|, and |nobox| styles. In either cases, the label can be
1085 % customized by redefining |\phfccformatboxinitials|.
1086 % \begin{macrocode}
1087 \def\phf@cc@formatinitialsstyle@box#1{%
1088 \hspace{0.25em}\relax
1089 \raisebox{1pt}{{\fboxsep=1pt\relax\fbox{\phfccformatboxinitials{#1}}}}%
1090 \hspace{0.25em}}
1091 \def\phf@cc@formatinitialsstyle@nobox#1{%
1092 \hspace{0.25em}\relax
1093 {\phfccformatboxinitials{#1}}%
1094 \hspace{0.25em}}
1095 % \end{macrocode}
1096 % \end{macro}
1097 % \end{macro}
1098 % \begin{macro}{\phfccformatboxinitials}
1099 % \begin{macrocode}
1100 \def\phfccformatboxinitials#1{%
1101 \normalfont\sffamily\tiny#1%
1102 }
1103 % \end{macrocode}
1104 % \end{macro}
1105 %
1106 % \subsubsection{Define the style \phfverb{footnote}}
1107 %
1108 % Define the |footnote| style. Note you can redefine |\phfCCChangesBy| to
1109 % whatever you please, and it can even take the name as |#1| argument.
1110 % \begin{macrocode}
1111 \def\phf@cc@formatinitialsstyle@footnote#1{%
1112 \ifcsname phf@cc@valfmtinitialsfootnote@intlspage@\phf@cc@val@cur @\roman{page}\endcsname
1113 % already displayed on this page, don't repeat
1114 \else
1115 \csgdef{phf@cc@valfmtinitialsfootnote@intlspage@\phf@cc@val@cur @\roman{page}}{1}%
1116 \def\phf@cc@tmp@zz{\gdef\@thefnmark{}\@footnotetext}%
1117 \expandafter\phf@cc@tmp@zz\expandafter{\expandafter{%
1118 \expandafter\color\expandafter{\phf@cc@val@cur color}\phfCCChangesBy{#1}}}%
1119 \fi
1120 }
1121 \robustify\phf@cc@formatinitialsstyle@footnote
1122 \def\phfCCChangesBy{Changes by\ }
1123 % \end{macrocode}
1124 %
1125 % \subsubsection{Define the style \phfverb{margin}}
1126 %
1127 % \begin{macro}{\phf@cc@formatinitialsstyle@margin}
1128 % Define the |margin| style now. This one is a little tricky.
1129 % \begin{macrocode}
1130 \def\phf@cc@formatinitialsstyle@margin#1{%
1131 % \end{macrocode}
1132 %
1133 % First thing, we define an auxiliary global macro to remember whenever we've
1134 % already displayed the margin note on a given page. If the label was already
1135 % displayed on this page (as witnessed by the following test macro being
1136 % defined), don't repeat the label display and skip altogether.\footnote{There
1137 % are some edge cases here I'm not sure I want to spend the effort to fix. For
1138 % instance, if the comment appears right after a page break, it might have been
1139 % processed by \TeX\space while on the previous page and this test might get the
1140 % page number wrong. Oh well, the label was on last page already so you should
1141 % know whose comment this is.}
1142 % \begin{macrocode}
1143 \ifcsname phf@cc@valfmtinitialsmargin@intlspage@\phf@cc@val@cur
1144 @\roman{page}\endcsname
1145 \else
1146 % \end{macrocode}
1147 %
1148 % Check for any other reasons why we shouldn't emit a margin note (e.g. for some
1149 % known two-pass environments); this is done by |\phf@cc@margin@ifchecks|. Then
1150 % actually create the margin note with |\phf@cc@margin@emit|.
1151 % \begin{macrocode}
1152 \phf@cc@margin@ifchecks{%
1153 \phf@cc@margin@emit{#1}%
1154 }%
1155 \fi
1156 }
1157 \robustify\phf@cc@formatinitialsstyle@margin
1158 % \end{macrocode}
1159 % \end{macro}
1160 %
1161 % \begin{macro}{\phf@cc@margin@ifchecks}
1162 % Detects if we're in a first pass in an AMS equation, for instance, to only
1163 % emit the label in the second pass (actual typesetting).
1164 % \begin{macrocode}
1165 \def\phf@cc@margin@ifchecks#1{%
1166 \phf@cc@ififexists{ifmeasuring@}{%
1167 \message{Detected first pass in environment, not emitting margin
1168 initials label this time.}%
1169 }{%
1170 \phf@cc@ififexists{if@inlabel}{%
1171 \message{Detected comment in latex item label, not emitting margin
1172 initials at this time to avoid messing up everything.}%
1173 }{%
1174 #1%
1175 }%
1176 }%
1177 }
1178 % \end{macrocode}
1179 % \end{macro}
1180 %
1181 % \begin{macro}{\phf@cc@ififexists}
1182 % A helper macro. The |\phf@cc@ififexists|\marg{if-cs-name}\marg{commands if
1183 % true}\marg{commands if false} macro checks if the command |\ifXXXX| exists,
1184 % where the name |ifXXXX| is the first argument of |\phf@cc@ififexists|. If it
1185 % exists, then it checks that ``if'' condition and executes \marg{commands if
1186 % true} or \marg{commands if false} as appropriate. If the ``if'' macro doesn't
1187 % exist, then executes \marg{commands if false}.
1188 % \begin{macrocode}
1189 \def\phf@cc@ififexists#1#2#3{%
1190 \ifcsname #1\endcsname
1191 \def\x{\phf@cc@ififexists@{#1}{#2}{#3}}%
1192 \else
1193 \def\x{#3}%
1194 \fi
1195 \x
1196 }
1197 \def\phf@cc@ififexists@#1#2#3{%
1198 \csname #1\endcsname
1199 #2%
1200 \else
1201 #3%
1202 \fi
1203 }
1204 % \end{macrocode}
1205 % \end{macro}
1206 %
1207 % At this point, we are all set to display the initials in the margin. It seems
1208 % like there should be nothing wrong with simply emitting a |\marginpar|, but
1209 % those don't work in footnotes and figure captions, where one would also like
1210 % to be able to introduce comments. One could use the \pkgname{marginnote}
1211 % package instead, which is more reliable, but then we can get overlapping
1212 % margin labels which are not very nice.
1213 %
1214 % {\itshape On the subject of |\marginnote| vs |\marginpar|:} The strategy here
1215 % is use |\marginnote| all the time. Originally I used |\marginpar|, but it
1216 % doesn't work in footnotes and figure captions, where one often wants to
1217 % comment things. It's really hard to detect all cases where |\marginpar| is
1218 % problematic. (|\ifinner| detects minipages/equations, value of |\@captype|
1219 % detects figure captions, but I didn't manage to detect footnotes reliably, and
1220 % I anticipate other problematic situations coming up). So I use
1221 % \pkgname{marginnote} instead, which is more reliable. We could have some
1222 % complex process to decide whether to use |\marginpar| or |\marginnote|, but
1223 % only if we can find a really reliable algorithm. When collaborators are
1224 % commenting on a document in the final hours before a deadline, we really don't
1225 % want to generate obscure LaTeX errors because they happened to hit an edge
1226 % case by placing a comment somewhere I hadn't anticipated. So for now,
1227 % universally use |\marginnote|. If you don't want to load the
1228 % \pkgname{marginnote} package for whatever reason, use a different initials
1229 % label style and specify the |usemarginnote=false| package option.
1230 %
1231 % To avoid margin notes overlapping with \pkgname{marginnote}, we use custom
1232 % code with a simple algorithm to shift the margin notes vertically so that they
1233 % don't overlap. The code is a bit ugly, but it seems to work and it doesn't
1234 % rely on too specific hacks, so it is hopefully not too prone to edge cases.
1235 %
1236 % \begin{macro}{\phf@cc@margin@emit}
1237 % This is the macro that actually creates the margin note. First we create a
1238 % |\hbox| with the label so that we can measure its height. Then we defer to
1239 % |\phf@cc@createmarginnote| to produce the margin note with the formatted
1240 % initials.
1241 % \begin{macrocode}
1242 \newbox\phf@cc@margin@labelbox
1243 \newdimen\phf@cc@margin@labelboxhgt
1244 \def\phf@cc@margin@emit#1{%
1245 \setbox\phf@cc@margin@labelbox=\hbox{\strut
1246 \expandafter\color\expandafter{\phf@cc@val@cur color}%
1247 \fboxsep=1pt\relax
1248 \phfccformatmargininitials{#1}}%
1249 \phf@cc@margin@labelboxhgt=\ht\phf@cc@margin@labelbox
1250 \phf@cc@createmarginnote
1251 \csgdef{phf@cc@valfmtinitialsmargin@intlspage@\phf@cc@val@cur%
1252 @\roman{page}}{1}%
1253 }%
1254 % \end{macrocode}
1255 % \end{macro}
1256 %
1257 % \begin{macro}{\phfccformatmargininitials}
1258 % The |\phfccformatmargininitials|\marg{initials} can be redefined to change the
1259 % appearance of the margin intials box.
1260 % \begin{macrocode}
1261 \def\phfccformatmargininitials#1{%
1262 \fbox{\normalfont\sffamily\footnotesize #1}%
1263 }
1264 % \end{macrocode}
1265 % \end{macro}
1266 %
1267 % \begin{macro}{\phf@cc@createmarginnote}
1268 % The tricky thing with \pkgname{marginnote} is that labels will overlap if
1269 % they are emitted on the same line. Here we use a workaround: We check
1270 % |\pdflastypos| and add some vertical spacing if we are too close to the last
1271 % note's y position on the same page. But the issue is that |\pdfsavepos| and
1272 % |\pdflatexypos| only work while shipping out, so basically all we can do is
1273 % write the values to the AUX file and use them next time latex is run. Here
1274 % we use the same mechanism as \pkgname{marginnote}: define a new \LaTeX\space
1275 % label printing a |\newphfccmarginnote| in the AUX file with the relevant
1276 % meta-info. We use the internal counters |\@mn@thispage| (current absolute
1277 % page number) and |\@mn@atthispage| (number of note on current page) because
1278 % we also need to track which notes are on which page, and there's no use
1279 % duplicating all that code (I do hope those counters don't change, though).
1280 % \begin{macrocode}
1281 \def\phf@cc@createmarginnote{%
1282 \marginnote[{\copy\phf@cc@margin@labelbox}]{\copy\phf@cc@margin@labelbox}[%
1283 \phf@cc@marginextractvshift]%
1284 \phf@cc@savepos
1285 \protected@write\@auxout{}{%
1286 \string\newphfccmarginnote{%
1287 {\@mn@thispage}%
1288 {\@mn@atthispage}%
1289 {\noexpand\number\phf@cc@lastypos sp}%
1290 {\number\phf@cc@margin@labelboxhgt sp}%
1291 }%
1292 }%
1293 }
1294 \ifcsname pdfsavepos\endcsname
1295 \let\phf@cc@savepos\pdfsavepos
1296 \let\phf@cc@lastypos\pdflastypos
1297 \else
1298 \ifcsname savepos\endcsname
1299 \let\phf@cc@savepos\savepos
1300 \let\phf@cc@lastypos\lastypos
1301 \else
1302 \PackageError{phfcc}{Cannot find appropriate \string\pdfsavepos\space
1303 command, neither \string\pdfsavepos\space nor\string\savepos\space
1304 are defined.}{}
1305 \fi
1306 \fi
1307 % \end{macrocode}
1308 % \end{macro}
1309 %
1310 % \begin{macro}{\phf@cc@marginextractvshift}
1311 % The macro |\phf@cc@marginextractvshift| is responsible for extracting the
1312 % required vertical shift from the corresponding label created from the
1313 % information saved in the AUX file. \emph{This macro is fully expandable,
1314 % and is meant to be used as the value of the optional vertical-shift argument
1315 % in \phfverb{\marginnote}.} The current note is identified by the internal
1316 % \pkgname{marginnote} counters |\@mn@thispage| (current absolute page number)
1317 % and |\@mn@atthispage| (current note number on this page).
1318 %
1319 % The label |\csname phfccmn@\@mn@thispage.\@mn@atthispage\endcsname|
1320 % generated by |\newphfccmarginnote| expands to |{|\marg{pdf y-pos of the
1321 % point in text}\marg{label box height}|}|\relax |{|\marg{requried vertical
1322 % shift to adjust this note}|}|. The first group of fields are the two last
1323 % arguments specified to |\newphfccmarginnote| written to the AUX file (the
1324 % two first are already in the label/macro name), and the second group
1325 % contains the values (only one currently) computed when calling
1326 % |\newphfccmarginnote|.
1327 %
1328 % Used as |\marginnote|'s vertical shift length. Expands to the vertical
1329 % shift needed to correct the current note. Remember: no assignments in here,
1330 % this command must be fully expandable.
1331 % \begin{macrocode}
1332 \def\phf@cc@marginextractvshift{%
1333 \ifcsname phfccmn@\@mn@thispage.\@mn@atthispage\endcsname
1334 \expandafter\expandafter\expandafter\expandafter\expandafter
1335 \expandafter\expandafter\@firstofone
1336 \expandafter\expandafter\expandafter\@secondoftwo
1337 \csname phfccmn@\@mn@thispage.\@mn@atthispage\endcsname
1338 \else
1339 \z@
1340 \fi
1341 }
1342 % \end{macrocode}
1343 % \end{macro}
1344 %
1345 % \begin{macro}{\newphfccmarginnote}
1346 % The |\newphfccmarginnote| command defines the margin label in the AUX file.
1347 % It's not meant as public API, it's only written in the AUX file to be
1348 % re-read on next run. Here is where all the calculations are done.
1349 %
1350 % In this macro we get the page number, y position, and box height of a margin
1351 % note written by the previous run of \LaTeX. We need to compute the vertical
1352 % shift to avoid overlapping with other boxes.
1353 %
1354 % The algorithm is pretty dumb. For each margin note, we loop over all
1355 % already-processed margin notes on the same page. If an overlap is detected,
1356 % we advance the y-position of the margin note according to the height of the
1357 % existing overlapping margin note, and re-start the loop.
1358 %
1359 % This is also the main entry point into our vertical shift calculating
1360 % algorithm. Set the |\phf@cc@marginvshift| to zero, this is where the
1361 % calculated total vertical shift will be stored. Then call our algorithm
1362 % main routine unless we're the first note on the page.\footnote{There's an
1363 % edge case here that I haven't dealt with: In the case of footnotes or figure
1364 % captions, the notes can appear out of order in the AUX file. Our algorithm
1365 % only checks for overlap with note numbers that are less than the current
1366 % note number. So if note 1.1 appears in the AUX file after note 1.2, then
1367 % first 1.2 is processed, no shift is added (it ignores the fact that 1.1
1368 % doesn't exist yet), then 1.1 is processed and thinks it's the first note so
1369 % doesn't add a shift either. If this ends up really being a problem there
1370 % are ways to fix this but now I don't feel it's worth the effort. So you
1371 % might have a note in a figure caption somehow overlapping with another note
1372 % if they happen to be in different environments and yet on the same line.}
1373 % \begin{macrocode}
1374 \def\phf@cc@marginlastmarginnoteypos{}
1375 \newdimen\phf@cc@marginvshift
1376 \def\newphfccmarginnote#1{\newphfccmarginnote@#1}
1377 \def\newphfccmarginnote@#1#2#3#4{%
1378 \phf@cc@marginvshift=\z@
1379 \ifnum#2>0\relax
1380 \phf@cc@margin@calculatevshift{#1}{#2}{#3}{#4}%
1381 \else\fi
1382 \csxdef{phfccmn@#1.#2}{%
1383 {{#3}{#4}}{\number\phf@cc@marginvshift sp}%
1384 }%
1385 }
1386 % \end{macrocode}
1387 % \end{macro}
1388 %
1389 %
1390 % \begin{macro}{\phfccmargininitialssep}
1391 % The dimension |\phfccmargininitialssep| is the minimum vertical separation
1392 % between two margin notes initials. Redefine this length to whatever you
1393 % like (e.g., |\phfccmargininitialssep=1mm\relax| or
1394 % |\setlength{\phfccmargininitialssep}{1mm}|).
1395 % \begin{macrocode}
1396 \newdimen\phfccmargininitialssep
1397 \phfccmargininitialssep=2\p@
1398 % \end{macrocode}
1399 % \end{macro}
1400 %
1401 % \begin{macro}{\phf@cc@margin@calculatevshift}
1402 % This is our note vertical-shifting algorithm. Compute the vertical shift by
1403 % looping through existing notes on the present page. The temporary counter
1404 % |\phf@cc@tmp@cntiter| is the iteration counter and iterates over the notes
1405 % on the present page up to the current note. (If a note with earlier note is
1406 % undefined, skip it, this can happen if the note is in a footnote or figure
1407 % caption; see earlier footnote.)
1408 %
1409 % The total vertical shift that needs to be applied to the present note
1410 % (positive shift = downwards shift) is stored in the dimen
1411 % |\phf@cc@marginvshift|, to be picked up by |\newphfccmarginnote|. Here
1412 % |#1|=absolute page no., |#2|=current note no., |#3|=current note y position,
1413 % |#4|=current note box height.
1414 % \begin{macrocode}
1415 \newcount\phf@cc@tmp@cntiter
1416 \def\phf@cc@margin@calculatevshift#1#2#3#4{%
1417 \phf@cc@marginvshift=\z@
1418 \phf@cc@tmp@cntiter=0
1419 \phf@cc@margin@calculatevshift@{#1}{#2}{#3}{#4}%
1420 }
1421 \def\phf@cc@margin@calculatevshift@#1#2#3#4{%
1422 \ifnum\phf@cc@tmp@cntiter<#2\relax
1423 \ifcsname phfccmn@#1.\the\phf@cc@tmp@cntiter\endcsname
1424 \expandafter\let\expandafter
1425 \phf@cc@tmp\csname phfccmn@#1.\the\phf@cc@tmp@cntiter\endcsname
1426 \edef\phf@cc@tmp@otherypos{%
1427 \expandafter\expandafter\expandafter\@firstoftwo
1428 \expandafter\@firstoftwo \phf@cc@tmp}%
1429 \edef\phf@cc@tmp@otherhgt{%
1430 \expandafter\expandafter\expandafter\@secondoftwo
1431 \expandafter\@firstoftwo \phf@cc@tmp}%
1432 \edef\phf@cc@tmp@othervshift{%
1433 \expandafter\expandafter\expandafter\@firstofone
1434 \expandafter\@secondoftwo \phf@cc@tmp}%
1435 \ifdim\dimexpr\phf@cc@tmp@otherypos-\phf@cc@tmp@othervshift
1436 >\dimexpr#3-#4-\phf@cc@marginvshift\relax
1437 \ifdim\dimexpr\phf@cc@tmp@otherypos-\phf@cc@tmp@otherhgt-\phf@cc@tmp@othervshift
1438 <\dimexpr#3-\phf@cc@marginvshift\relax
1439 % \end{macrocode}
1440 % At this point, an overlap is detected between the current note that we're
1441 % adjusting (note number |#2| on page |#1|) and an earlier processed note (note
1442 % number |\phf@cc@tmp@cntiter| on the same page). So we shift the current note
1443 % so that it appears below the other note. The vertical shift is accumulated in
1444 % the |\phf@cc@marginvshift| dimen, this will be stored into the label after
1445 % we're done computing. Note: the y-position reported by |\pdflastypos| is from
1446 % the \emph{bottom}, not the top, so ``higher on the page than'' is ``|>|''; but
1447 % a positive margin vertical shift in \pkgname{marginnote} shifts the margin
1448 % note \emph{downwards}.
1449 %
1450 % Then reset the iteration counter to zero, so that we re-loop over all existing
1451 % notes on the same page to re-check (with the new vertical shift) that we
1452 % didn't generate an overlap with any earlier note (e.g., could happen on a
1453 % two-column page with comments in both columns).
1454 % \begin{macrocode}
1455 \@tempdima=\dimexpr
1456 \phfccmargininitialssep
1457 +(#3-\phf@cc@marginvshift)%
1458 -(\phf@cc@tmp@otherypos-\phf@cc@tmp@otherhgt-\phf@cc@tmp@othervshift)%
1459 \relax
1460 %\message{*** phfcc DEBUG: overlap detected of note #1.#2 with
1461 % note #1.\the\phf@cc@tmp@cntiter, increasing vshift of note
1462 % number #2 on page #1 by \the\@tempdima \space ***}%
1463 \advance\phf@cc@marginvshift \@tempdima
1464 \phf@cc@tmp@cntiter=\z@\relax
1465 \else\fi
1466 \else\fi
1467 \else\fi
1468 \advance\phf@cc@tmp@cntiter 1\relax
1469 \phf@cc@margin@calculatevshift@{#1}{#2}{#3}{#4}%
1470 \fi
1471 }
1472 % \end{macrocode}
1473 % \end{macro}
1474 %
1475 %
1476 % \subsection{The main \phfverb{\phfMakeCommentingCommand} macro}
1477 %
1478 % \begin{macro}{\phfMakeCommentingCommand}
1479 % Implementation of |\phfMakeCommentingCommand|. See main package
1480 % documentation for usage details. The inner command definitions are kinda
1481 % tricky because of all the possible syntax options.
1482 % |\phfMakeCommentingCommand|\oarg{color=blue,...}\marg{cmdname}
1483 % \begin{macrocode}
1484 \newcommand\phfMakeCommentingCommand[2][]{%
1485 \cmdKV@phfmkcc@startcmds={}%
1486 \cmdKV@phfmkcc@endcmds={}%
1487 \edef\x{\noexpand\phfcc@expandstylekeys{\phfcc@default@style}{\unexpanded{#1}}}%
1488 \x
1489 %\setrmkeys{phfmkcc}%
1490 \edef\x{\noexpand\setkeys{phfmkcc}{\the\phfcc@val@expanded@keyval}}%
1491 \x
1492 \phf@cc@getcolor{\cmdKV@phfmkcc@color}%
1493 \colorlet{#2color}{\phf@cc@thecolor}%
1494 \edef\phf@tmp@xxappcmd{\noexpand\appto\noexpand\phf@cc@usedcolors{\phf@cc@thecolor|}}%
1495 \phf@tmp@xxappcmd
1496 \colorlet{#2rmcolor}{#2color!70!gray!55!white}%
1497 \colorlet{#2rmcolorlink}{blue!40!#2rmcolor}%
1498 \edef\phf@tmp@xxx{\cmdKV@phfmkcc@initials}%
1499 \if\relax\detokenize\expandafter{\phf@tmp@xxx}\relax
1500 \csedef{phf@cc@val@#2@initials}{#2}%
1501 \else
1502 \csedef{phf@cc@val@#2@initials}{\cmdKV@phfmkcc@initials}%
1503 \fi
1504 \ifcsname phf@cc@formatinitialsstyle@%
1505 \detokenize\expandafter{\cmdKV@phfmkcc@formatinitials}\endcsname%
1506 \expandafter\def\expandafter\phf@cc@tmp@xzx\expandafter{%
1507 \csname phf@cc@formatinitialsstyle@%
1508 \detokenize\expandafter{\cmdKV@phfmkcc@formatinitials}\endcsname}%
1509 \csedef{phf@cc@val@#2@formatinitials}{\expandonce\phf@cc@tmp@xzx}%
1510 \else
1511 \csedef{phf@cc@val@#2@formatinitials}{\expandonce\cmdKV@phfmkcc@formatinitials}%
1512 \fi
1513 \csedef{phf@cc@val@#2@startcmds}{\the\cmdKV@phfmkcc@startcmds}%
1514 \csedef{phf@cc@val@#2@endcmds}{\the\cmdKV@phfmkcc@endcmds}%
1515 %\message{***** STARTCMDS ARE \detokenize\expandafter{\the\cmdKV@phfmkcc@startcmds} *****}%
1516 %\message{***** ENDCMDS ARE \detokenize\expandafter{\the\cmdKV@phfmkcc@endcmds} *****}%
1517 \csedef{phf@cc@val@#2@font}{\expandonce\cmdKV@phfmkcc@font}%
1518 \csedef{phf@cc@val@#2@spacing}{\expandonce\cmdKV@phfmkcc@spacing}%
1519 \csedef{phf@cc@val@#2@begin}{\expandonce\cmdKV@phfmkcc@begin}%
1520 \csedef{phf@cc@val@#2@end}{\expandonce\cmdKV@phfmkcc@end}%
1521 \csedef{phf@cc@val@#2@cfont}{\expandonce\cmdKV@phfmkcc@cfont}%
1522 \csedef{phf@cc@val@#2@cspacing}{\expandonce\cmdKV@phfmkcc@cspacing}%
1523 \csedef{phf@cc@val@#2@cbegin}{\expandonce\cmdKV@phfmkcc@cbegin}%
1524 \csedef{phf@cc@val@#2@cend}{\expandonce\cmdKV@phfmkcc@cend}%
1525 \csedef{phf@cc@val@#2@rmfont}{\expandonce\cmdKV@phfmkcc@rmfont}%
1526 \csedef{phf@cc@val@#2@rmspacing}{\expandonce\cmdKV@phfmkcc@rmspacing}%
1527 \csedef{phf@cc@val@#2@rmbegin}{\expandonce\cmdKV@phfmkcc@rmbegin}%
1528 \csedef{phf@cc@val@#2@rmend}{\expandonce\cmdKV@phfmkcc@rmend}%
1529 \csedef{phf@cc@val@#2@ifont}{\expandonce\cmdKV@phfmkcc@ifont}%
1530 \csedef{phf@cc@val@#2@ispacing}{\expandonce\cmdKV@phfmkcc@ispacing}%
1531 \csedef{phf@cc@val@#2@ibegin}{\expandonce\cmdKV@phfmkcc@ibegin}%
1532 \csedef{phf@cc@val@#2@iend}{\expandonce\cmdKV@phfmkcc@iend}%
1533 \csedef{phf@cc@val@#2@groupcmd}{\expandonce\cmdKV@phfmkcc@groupcmd}%
1534 % \end{macrocode}
1535 %
1536 % Once all the information was gathered and stored, define the commenting command
1537 % itself (as well as its |\end*| counterpart). Make them robust.
1538 % \begin{macrocode}
1539 \csdef{#2}{\phf@cc@do{#2}}%
1540 \expandafter\robustify\csname #2\endcsname%
1541 \csdef{end#2}{\phf@cc@end}%
1542 \expandafter\robustify\csname end#2\endcsname%
1543 }
1544 % \end{macrocode}
1545 % \end{macro}
1546 %
1547 % \begin{macro}{\phfDisableCommentingCommands}
1548 % This command causes any commenting command declared with
1549 % |\phfMakeCommentingCommand| to emit an error.
1550 % \begin{macrocode}
1551 \newif\ifphf@cc@disabled
1552 \phf@cc@disabledfalse
1553 \def\phfDisableCommentingCommands{%
1554 \phf@cc@disabledtrue
1555 }
1556 % \end{macrocode}
1557 % \end{macro}
1558 %
1559 % \subsection{Implementation of the commenting commands}
1560 %
1561 % Overall, the implementation of a commenting command goes as follows. First,
1562 % gather all the info about the command invocation (e.g., important? starred?
1563 % comment?) and then ultimately call |\phf@cc@begin| and |\phf@cc@end| which
1564 % execute the formatting options.
1565 %
1566 % Within each comment, the following flags are set by the parsing mechanism.
1567 % \begin{macrocode}
1568 \newif\if@phfcc@iscomment
1569 \newif\if@phfcc@isremoved
1570 \newif\if@phfcc@isimportant
1571 % \end{macrocode}
1572 %
1573 % Everything happens within |\begingroup|\ldots|\endgroup|. The group is opened
1574 % at |\phf@cc@do| (the commenting command itself), and is closed by |\phf@cc@end|.
1575 %
1576 % \begin{macro}{\phf@cc@begin}
1577 % The helper macro |\phf@cc@begin| is responsible for issuing all the
1578 % necessary definitions for the comment to be typeset correctly, including
1579 % initials, depending on whether it is a regular text addition, a text removal
1580 % comment, an important comment, a commenting comment, etc. It inspects
1581 % |\if@phfcc@iscomment|, |\if@phfcc@isremoved|, and |\if@phfcc@isimportant| to
1582 % determine the comment type.
1583 %
1584 % This is not the main comment entry point, the main entropy point is
1585 % |\phf@cc@do| and |\phf@cc@begin| is called internally from there. {\itshape
1586 % Execution is already enclosed in a local \TeX\ group; a |\begingroup| has
1587 % already been issued by |\phf@cc@do|.}
1588 % \begin{macrocode}
1589 \def\phf@cc@begin{%
1590 % \end{macrocode}
1591 %
1592 % First, we set the author's color so that by default everything we do will use
1593 % that color.
1594 % \begin{macrocode}
1595 \color{\phf@cc@val@cur color}%
1596 % \end{macrocode}
1597 %
1598 % Issuing \phfverb\leavevmode\ here is annoying because it adds vertical space
1599 % if the command is issued in vertical mode right before an equation or theorem;
1600 % but it is needed immediately after section and paragraph headings so that the
1601 % comment style (eg sans font along with color etc.) is not applied to the
1602 % section/paragraph heading itself.
1603 % \begin{macrocode}
1604 \leavevmode% beurk, see above
1605 % \end{macrocode}
1606 %
1607 % The comment typesetting is constructed in layers, each time adding commands to
1608 % execute at the start and corresponding commmands to execute at the end. The
1609 % start commands are executed in the specified order, with the end commands in
1610 % the reverse order at the end. We use the |\phf@cc@helper@pushgrpcmds| helper
1611 % to this effect.
1612 %
1613 % Introducing the necessary spacing, and issuing the initials. The amount of
1614 % spacing will depend on the type of comment; |\phf@cc@val@spacing| will be set
1615 % appropriately below when setting comment-type specific settings.
1616 % \begin{macrocode}
1617 \phf@cc@helper@pushgrpcmds{%
1618 \csname phf@cc@val@\phf@cc@val@cur @startcmds\endcsname
1619 \hspace{\phf@cc@val@spacing}%
1620 \phf@cc@showinitials%
1621 }{%
1622 \hspace{\phf@cc@val@spacing}%
1623 \csname phf@cc@val@\phf@cc@val@cur @endcmds\endcsname
1624 }%
1625 % \end{macrocode}
1626 %
1627 % See what comment type we're dealing with, and set the appropriate settings.
1628 %
1629 % First, check if we have a commenting-comment. If so, see whether or not it is
1630 % additionally marked as important and issue the relevant commands. Also set
1631 % the relevant spacing.
1632 % \begin{macrocode}
1633 \if@phfcc@iscomment
1634 \if@phfcc@isimportant
1635 \phf@cc@helper@pushgrpcmdsX{%
1636 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @font\endcsname
1637 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @cfont\endcsname
1638 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @ifont\endcsname
1639 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @cbegin\endcsname
1640 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @ibegin\endcsname
1641 }{%
1642 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @iend\endcsname
1643 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @cend\endcsname
1644 }%
1645 \edef\phf@cc@val@spacing{\csname phf@cc@val@\phf@cc@val@cur @ispacing\endcsname}%
1646 \else
1647 \phf@cc@helper@pushgrpcmdsX{%
1648 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @font\endcsname
1649 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @cfont\endcsname
1650 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @cbegin\endcsname
1651 }{%
1652 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @cend\endcsname
1653 }%
1654 \edef\phf@cc@val@spacing{\csname phf@cc@val@\phf@cc@val@cur @cspacing\endcsname}%
1655 \fi
1656 \else
1657 % \end{macrocode}
1658 % Now check if we have an important comment (which is not a commenty-comment).
1659 % \begin{macrocode}
1660 \if@phfcc@isimportant
1661 \phf@cc@helper@pushgrpcmdsX{%
1662 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @font\endcsname
1663 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @ifont\endcsname
1664 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @ibegin\endcsname
1665 }{%
1666 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @iend\endcsname
1667 }%
1668 \edef\phf@cc@val@spacing{%
1669 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @ispacing\endcsname%
1670 }%
1671 \else
1672 % \end{macrocode}
1673 % Not a comment, not important. Could be a piece of text marked for removal.
1674 % \begin{macrocode}
1675 \if@phfcc@isremoved
1676 \phf@cc@helper@pushgrpcmdsX{%
1677 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @font\endcsname
1678 \noexpand\color{\phf@cc@val@cur rmcolor}%
1679 \noexpand\colorlet{docnotelinkcolor}{\phf@cc@val@cur rmcolorlink}%
1680 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @rmfont\endcsname
1681 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @rmbegin\endcsname
1682 }{%
1683 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @rmend\endcsname
1684 }%
1685 \edef\phf@cc@val@spacing{\csname phf@cc@val@\phf@cc@val@cur @rmspacing\endcsname}%
1686 \else
1687 % \end{macrocode}
1688 % We've got just a plain, old, inline marked text.
1689 % \begin{macrocode}
1690 \phf@cc@helper@pushgrpcmdsX{%
1691 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @font\endcsname
1692 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @begin\endcsname
1693 }{%
1694 \expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @end\endcsname
1695 }%
1696 \edef\phf@cc@val@spacing{\csname phf@cc@val@\phf@cc@val@cur @spacing\endcsname}%
1697 \fi
1698 \fi
1699 \fi
1700 % \end{macrocode}
1701 %
1702 % Actually issue these commmands and kick off the typesetting of the comment.
1703 % \begin{macrocode}
1704 \phf@cc@val@grpcmds
1705 }
1706 \def\phf@cc@helper@pushgrpcmds#1#2{%
1707 \appto\phf@cc@val@grpcmds{#1}%
1708 \preto\phf@cc@val@grpendcmds{#2}%
1709 }
1710 \def\phf@cc@helper@pushgrpcmdsX#1#2{% expands arguments with edef
1711 \edef\phfcc@tmp@x{\noexpand\phf@cc@helper@pushgrpcmds{#1}{#2}}%
1712 \phfcc@tmp@x
1713 }
1714 % \end{macrocode}
1715 % \end{macro}
1716 %
1717 %
1718 % \begin{macro}{\phf@cc@end}
1719 % Here we execute closing commands and close the group. |\phf@cc@end| is the
1720 % last macro executed when the user invokes a comment, in any case.
1721 % \begin{macrocode}
1722 \def\phf@cc@end{%
1723 \phf@cc@val@grpendcmds
1724 \endgroup
1725 }
1726 % \end{macrocode}
1727 % \end{macro}
1728 %
1729 % \begin{macro}{\phf@cc@showinitials}
1730 % This helper macro prints out the initials, if any.
1731 % \begin{macrocode}
1732 \def\phf@cc@showinitials{%
1733 \edef\phf@cc@tmpx{%
1734 \expandafter\expandonce\csname phf@cc@val@\phf@cc@val@cur @initials\endcsname}%
1735 \expandafter\notblank\expandafter{\phf@cc@tmpx}{%
1736 \csname phf@cc@val@\phf@cc@val@cur @formatinitials%
1737 \expandafter\endcsname\expandafter{\phf@cc@tmpx}}{}%
1738 }
1739 % \end{macrocode}
1740 % \end{macro}
1741 %
1742 %
1743 % \begin{macro}{\phf@cc@do}
1744 % {\bfseries The macro |\phf@cc@do| is the main entry point of a commenting
1745 % command.} Actually, the user-instantiated commenting commands are an alias
1746 % of this command, with the user macro name as first argument. So the |\AlE|
1747 % command defined in the main documentation of this package was in fact
1748 % defined as an alias to |\phf@cc@do{AlE}|. This is were everything starts.
1749 % \begin{macrocode}
1750 \def\phf@cc@do#1{%
1751 % \end{macrocode}
1752 % First, we need to check if commenting commands were disabled with
1753 % |\phfDisableCommentingCommands|. If this is the case, generate an error.
1754 % \begin{macrocode}
1755 \ifphf@cc@disabled
1756 \PackageError{phfcc}{Commenting commands have been disabled
1757 with \string\phfDisableCommentingCommands.}{}%
1758 \fi
1759 % \end{macrocode}
1760 % Now we start for real. First, we open the \TeX\ group. Then we start parsing
1761 % the invocation syntax.
1762 %
1763 % \begin{macrocode}
1764 \begingroup
1765 \@phfcc@iscommentfalse
1766 \@phfcc@isremovedfalse
1767 \@phfcc@isimportantfalse
1768 % \end{macrocode}
1769 %
1770 % The macros |\phf@cc@val@grp*cmds| store the commands to be executed in
1771 % |\phf@cc@begin| and |\phf@cc@end|. By default, they are empty. They are
1772 % filled by relevant code when parsing the command invocation.
1773 %
1774 % By default, there are no commands at group begin (|\phf@cc@val@grpcmds|), no
1775 % commands at group end (|\phf@cc@val@grpendcmds|), and no spacing on either
1776 % side of the typeset comment (|\phf@cc@val@spacing|).
1777 % \begin{macrocode}
1778 \def\phf@cc@val@grpcmds{}%
1779 \def\phf@cc@val@grpendcmds{}%
1780 \def\phf@cc@val@spacing{0pt}%
1781 % \end{macrocode}
1782 %
1783 % Store the name of the commenting command so we can look up the relevant
1784 % comment settings. This is the name that was given to the commenting command
1785 % itself, e.g. |phf|.
1786 % \begin{macrocode}
1787 \edef\phf@cc@val@cur{#1}%
1788 % \end{macrocode}
1789 %
1790 % Here we start the parsing of the type of comment. First, check for a star
1791 % (e.g., |\phf*{...}|) to see if we're dealing with a removed block of text.
1792 % \begin{macrocode}
1793 \@ifstar\phf@cc@star\phf@cc@nostar%
1794 }
1795 % \end{macrocode}
1796 %
1797 % If we don't have a star, continue parsing to see if we have an important piece
1798 % of text or comment (|\phf!| sytnax).
1799 % \begin{macrocode}
1800 \def\phf@cc@nostar{\@ifnextchar!\phf@cc@important\phf@cc@grp}
1801 % \end{macrocode}
1802 %
1803 % At this point, we have determined whether the invocation is starred (removed
1804 % text) or important. The next execution points are |\phf@cc@star|,
1805 % |\phf@cc@important|, or |\phf@cc@grp|.
1806 % \end{macro}
1807 %
1808 % \begin{macro}{\phf@cc@star}
1809 % \begin{macro}{\phf@cc@important}
1810 % If starred or if important, set up the inner group execution commands to the
1811 % corresponding settings, and defer to |\phf@cc@grp|.
1812 % \begin{macrocode}
1813 \long\def\phf@cc@star{%
1814 \@phfcc@isremovedtrue
1815 \phf@cc@grp}
1816 \long\def\phf@cc@important!{%
1817 \@phfcc@isimportanttrue
1818 \phf@cc@grp}
1819 % \end{macrocode}
1820 % \end{macro}
1821 % \end{macro}
1822 %
1823 % \begin{macro}{\phf@cc@grp}
1824 % The command |\phf@cc@grp| parses how the argument content is given. Is it a
1825 % comment (``|[ ... ]|''), a single \LaTeX{} argument group (``|{ ... }|''),
1826 % or should we expect it to end with |\endXXX|?
1827 % \begin{macrocode}
1828 \def\phf@cc@grp{%
1829 \@ifnextchar[\phf@cc@comment\phf@cc@grpnocomment%]
1830 }
1831 \def\phf@cc@grpnocomment{%
1832 \@ifnextchar\bgroup{\phf@cc@grpwarg}{\phf@cc@begin}}
1833 % \end{macrocode}
1834 % \end{macro}
1835 %
1836 % The main commenting command has already defined the |\endXXX| command as an
1837 % alias of |\phf@cc@end|, so in the case of the syntax |\AlE ... \endAlE| we can
1838 % call |\phf@cc@begin| directly.
1839 %
1840 % Now at this point we have determined how the argument is given, and we are
1841 % calling one of |\phf@cc@comment|, |\phf@cc@grpwarg| (with argument), or
1842 % |\phf@cc@begin| directly.
1843 %
1844 % \begin{macro}{\phf@cc@grpwarg}
1845 % Format a simple comment specified as a normal \LaTeX{} block, i.e., provided
1846 % as an argument to the commenting command. (Like |\AlE{text here}| or
1847 % |\AlE!{important text}| or |\AlE*{some stuff to remove}|.)
1848 % \begin{macrocode}
1849 \long\def\phf@cc@grpwarg#1{%
1850 \phf@cc@begin
1851 \csname phf@cc@val@\phf@cc@val@cur @groupcmd\endcsname
1852 {#1}%
1853 \phf@cc@end
1854 }
1855 % \end{macrocode}
1856 % \end{macro}
1857 %
1858 % \begin{macro}{\phf@cc@comment}
1859 % If the argument is a comment, set up the comment font, begin/end chars, and
1860 % go. Use |xparse| to get the argument in square brackets to ensure that the
1861 % argument itself can contain matched square brackets.
1862 % \begin{macrocode}
1863 \NewDocumentCommand\phf@cc@comment{+O{}}{%
1864 \@phfcc@iscommenttrue
1865 \phf@cc@begin%
1866 #1%
1867 \phf@cc@end%
1868 }
1869 % \end{macrocode}
1870 % \end{macro}
1871 %
1872 %
1873 % \subsection{Process package options}
1874 %
1875 % Initialization code for \pkgname{kvoptions} for our package options.
1876 % \begin{macrocode}
1877 \SetupKeyvalOptions{
1878 family=phfcc,
1879 prefix=phfcc@opt@
1880 }
1881 \DeclareBoolOption[true]{usemarginnote}
1882 % \end{macrocode}
1883 %
1884 % Process package options.
1885 % \begin{macrocode}
1886 \ProcessKeyvalOptions*
1887 % \end{macrocode}
1888 %
1889 % Load the \pkgname{marginnote} package unless requested not to. This package
1890 % is required for the |margin| initials style.
1891 % \begin{macrocode}
1892 \ifphfcc@opt@usemarginnote
1893 \RequirePackage{marginnote}
1894 \fi
1895 % \end{macrocode}
1896 %
1897 %\Finale
1898 \endinput