% \iffalse meta-comment
%
% Copyright (C) 2021 by Philippe Faist, philippe.faist@bluewin.ch
% -------------------------------------------------------
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in:
%
% http://www.latex-project.org/lppl.txt
%
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{phfcc.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
%<package>\ProvidesPackage{phfcc}
%<*package>
[2021/10/06 v2.0 phfcc package]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{xcolor}
\usepackage{lipsum}
\usepackage[preset=xpkgdoc]{phfnote}
\usepackage{phfcc}
\usepackage{needspace}
\usepackage[normalem]{ulem}
\def\eqsign@{=}
\def\eqsign{\protect\eqsign@}
\robustify\eqsign
\makeatother
\def\RevTeX{{\small R\raise-0.2ex\hbox{\textsc{ev}}}\TeX}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
\DocInput{phfcc.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
% {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
% 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
% Digits \0\1\2\3\4\5\6\7\8\9
% Exclamation \! Double quote \" Hash (number) \#
% Dollar \$ Percent \% Ampersand \&
% Acute accent \' Left paren \( Right paren \)
% Asterisk \* Plus \+ Comma \,
% Minus \- Point \. Solidus \/
% Colon \: Semicolon \; Less than \<
% Equals \= Greater than \> Question mark \?
% Commercial at \@ Left bracket \[ Backslash \\
% Right bracket \] Circumflex \^ Underscore \_
% Grave accent \` Left brace \{ Vertical bar \|
% Right brace \} Tilde \~}
%
%
% \changes{v1.0}{2020/04/02}{Initial version}
%
% \GetFileInfo{phfcc.dtx}
%
% \iffalse Bypass indexing for following commands: \fi
% \DoNotIndex{\newcommand,\newenvironment,\renewcommand,\long,\def,\edef,\gdef,\xdef,\if,\else,\fi,\par,\relax,\vspace,\vskip,\hspace,\hskip,\vbox,\hbox}
%
% \title{\phfqitltxPkgTitle{phfcc}}
% \author{Philippe Faist\quad\email{philippe.faist@bluewin.ch}}
% \date{\pkgfmtdate\filedate}
% \maketitle
%
% \begin{abstract}
% \pkgname{phfcc}---A handy \LaTeX{} package for inline commenting in
% collaborative LaTeX documents.
% \end{abstract}
%
% \phantomsection\label{sec:toc}
% \inlinetoc
%
% \section{Introduction}
%
% When elaborating documents, especially collaborative documents with multiple
% authors, it is useful to leave inline comments and be able to mark text
% changes. Often, authors will choose a text color and define a simple macro,
% like this:
% \begin{verbatim}
% \newcommand{\phf}[1]{{\color{blue}Ph.F.: #1}} % Philippe Faist's comments
% \end{verbatim}
%
% This rudimentary approach has a few drawbacks. The main drawback is when
% highlighting long blocks of text. First of all, it can be hard to visually
% find the matching closing brace in your editor. Then, the synchronization
% between your viewer and the TeX source (|synctex|) will no longer point to the
% correct source line within the highlighted block of text; you will always be
% pointed at the beginning or the end of the entire block. The reason for this
% behavior is that the entire text is passed as a macro argument to |\phf|, so
% |synctex| only sees a single macro call. The fact that a long block of text
% is passed as a macro argument can also lead to other issues, such as errors
% with |\verb+...+|-type constructs.
%
% Also, it is occasionally desirable to make the difference between sections of
% text that were added by an author, and an inline off-hand remark, which is not
% part of the text itself. For instance, with the above macro, we could enclose
% remarks in ``|[|'' and ``|]|'': %
% \newcommand{\phfold}[1]{{\color{blue}(Ph.F.:) #1}}
% \newcommand{\phfoldb}[1]{{\color{blue}\relax #1}}
% \begin{verbatim}
% ... \phf{Observe that $A\geq 0$ by definition.}
% \phf{[I added this sentence because I felt that it wasn't
% clear from the context that $A\geq 0$]} ...
% \end{verbatim}
% to obtain:
%
% {\itshape%
% ... \phfold{Observe that $A\geq 0$ by definition.}
% \phfold{[I added this sentence because I felt that it wasn't
% clear from the context that $A\geq 0$]} ...
% }
%
% Observe how the off-hand remark blends with the text. Wouldn't it be nicer
% if it stood out clearly, and if the initials were perhaps \emph{inside} the
% brackets, like so?
%
% {\itshape%
% ... \phfoldb{Ph.F.: Observe that $A\geq 0$ by definition.}
% \phfoldb{\sffamily\bfseries [(Ph.F.:) I added this sentence because
% I felt that it wasn't
% clear from the context that $A\geq 0$]} ...
% }
%
% \relax
%
% Of course, we could have defined a different macro for the off-hand remark,
% say |\phfremark|. But typing a different macro name is not convenient,
% Wouldn't it be nicer if the off-hand remark could be typed with the syntax
% |\phf[...]|, using square brackets?
%
% Also the initials don't have to be repeated at every macro call, it suffice to
% associate the color to the author perhaps once per page or so. They could
% also be displayed in the margin, to avoid cluttering the text.
%
% Furthermore, to avoid the aforementioned issues with long blocks of text, we
% could imagine marking text with the syntax |\begin{phf} ... \end{phf}| or even
% |\phf ... \endphf|.
%
% And while we're at it, wouldn't it be cool to mark text removals, as well?
% We could use the syntax |\phf*{text to be removed}|.
%
% And because I definitely didn't have time to spare but still got distracted
% into programming \LaTeX{} macros to implement the above features, I have the
% pleasure to present:
%
% \textit{\bfseries Introducing \ldots\ the \pkgname{phfcc} package.}\par
%
% With \pkgname{phfcc}, you simply define your multi-functional commenting
% command using the |\phfMakeCommentingCommand| macro.
%
% \phfMakeCommentingCommand[initials={A.E.}]{AlE}%
% \phfMakeCommentingCommand[initials={J.B.}]{JB}%
% \phfMakeCommentingCommand[initials={PhF}]{phf}%
% Let's start with a simple example. Suppose two authors, Albert Einstein and
% John Bell, are commenting on the same document. They might define the
% commenting commands |\AlE| and |\JB|:
% \begin{verbatim}
% \phfMakeCommentingCommand[initials={A.E.}]{AlE}
% \phfMakeCommentingCommand[initials={J.B.}]{JB}
% \end{verbatim}
% Suppose they edit a paragraph of text, with multiple rounds of editing by both
% authors; they mark their latest changes while leaving comments for the other
% author as follows:
% \begin{verbatim}
% Quantum mechanics developed quickly in the 1920's thanks to the
% works of Schr\"odinger, Heisenberg, and Dirac, who drew inspiration
% from earlier ideas by Planck \AlE{and Einstein} \AlE[@JB, you forgot
% about me!]. Quantum mechanics appears to allow spooky action at a
% distance via some strange thing called ``entanglement,'' \JB*{but
% this can be explained with hidden variables}\JB{which has
% revolutionized our understanding of local realism.} \JB[@Albert,
% we talked about this...]
% \end{verbatim}
% which gives:
%
% {\itshape%
% Quantum mechanics developed quickly in the 1920's thanks to the
% works of Schr\"odinger, Heisenberg, and Dirac, who drew inspiration
% from earlier ideas by Planck \AlE{and Einstein} \AlE[@JB, you forgot
% about me!]. Quantum mechanics appears to allow spooky action at a
% distance via some strange thing called ``entanglement,'' \JB*{but
% this can be explained with hidden variables}\JB{which has
% revolutionized our understanding of local realism.} \JB[@Albert,
% we talked about this...]%
% }
%
% Read on to learn more about how these commands can be used, what their main
% features are, how to customize them, and more.
%
% As an alternative to \pkgname{phfcc}, you can consider the package
% \pkgname{todonotes}\footnote{\url{https://ctan.org/pkg/todonotes}}. The
% commands defined in this package are designed for minimal effort by the
% commenter (e.g., they only have to type |\phf{...}| or |\phf[...]|). On the
% other hand \pkgname{todonotes} offers pretty boxes and more flexibility.
%
%
% \section{Syntax of commenting commands}
%
% Here is the full syntax of the commenting commands generated with
% |\phfMakeCommentingCommand|. Suppose the command |\AlE| was defined by
% issuing |\phfMakeCommentingCommand[initials={A.E.}]{AlE}|. You can write:
%
%
% |\AlE{some text here}| --- \AlE{some text here} --- typeset the given text in
% color, perhaps to mark an addition by author |AlE| to the document. By
% default, the initials associated with the command (here, ``A.E.'') will be
% issued in the margin once per page.
%
% |\AlE[please revise this]| --- \AlE[please revise this] --- typeset an inline
% comment in a different font. This is meant for comments that are not a
% portion of document text itself but rather an inline remark that refers to the
% text around it.
%
% You can use the |footcomments| style to have your comment typeset as a
% footnote. (See also \autoref{sec:styles} below.)
%
% |\AlE*{text to be removed}| --- \AlE*{text to be removed} --- typeset the
% given text in a way to indicate that the text should be suppressed.
%
% If you use Lua\LaTeX, you can get proper text strikethrough accross entire
% chunks of text by using the argument |style={rmstrikethrough}| to
% |\phfMakeCommentingCommand|. (See also \autoref{sec:styles} below.)
%
% |\AlE!{important piece of text}| --- \AlE!{important piece of text}
% --- typeset the given text marking it as important.
%
% |\AlE![a really important comment]| --- \AlE![a really important comment] ---
% typeset the given comment and mark it as important.
%
% In each of these cases (except for comments in square brackets),
% you can use the syntax |\AlE .... \endAlE| instead of specifying the
% argument using curly brackets:\\
% |\AlE text here\endAlE| --- \AlE text here\endAlE \\
% |\AlE! important\endAlE| --- \AlE! important\endAlE \\
% |\AlE* remove\endAlE| --- \AlE* remove\endAlE
%
% For simple text, you can also use the |\begin|/|\end| syntax:\\
% |\begin{AlE} text here\end{AlE}| --- \begin{AlE} text here\end{AlE}
%
% \begin{pkgtip}
% Note that in contrast to optional arguments in many LaTeX macros, the
% argument is allowed to contain matching square brackets, for instance
% \relax%
% |\AlE[inner brackets [like this] work as you'd expect]| \AlE[inner brackets
% [like this] work as you'd expect]
%
% In any case you can protect the argument as usual with curly braces:
% |\AlE[{this is [weird}]| \AlE[{this is [weird}]
% \end{pkgtip}
%
% \section{Defining your commenting command}
%
% Now let's see exactly how to define your customized |\AlE| command.
% \DescribeMacro{\phfMakeCommentingCommand} The command
% |\phfMakeCommentingCommand| takes the following syntax:
%
% |\phfMakeCommentingCommand|\oarg{key=value,key2=value2,...}\marg{cmd name}
%
% The \marg{command name} should be given as a text name (e.g.,
% |{AlE}|), and not as a macro. They key-value pairs may be one of the following:
%
%
% \phfMakeCommentingCommand[color=phfcolor,initials={PhF},formatinitials=box]{phfbox}
% \phfMakeCommentingCommand[color=phfcolor,initials={PhF},formatinitials=nobox]{phfnobox}
% \phfMakeCommentingCommand[color=phfcolor,initials={PhF},formatinitials=hide]{phfhideinitials}
% \phfMakeCommentingCommand[color=green!50!blue,initials={Philippe Faist},formatinitials=footnote]{phffootnote}
%
% \begin{cmdoptions}
% \item[color=\marg{color specification}] The color of the comments generated by
% the new commenting command. By default, a new suitable color is chosen for
% each new commenting command defined.
%
% The color specification may be a name such as |red|, |green|, etc., but also
% a mixture like |blue!40!green| (\textcolor{blue!40!green}{which stands for
% 40\% of blue and 60\% of green}). You can specify any argument you could
% specify to |\colorlet| from the \pkgname{xcolor} package. (The
% \pkgname{xcolor} package is automatically loaded.)
%
% \item[initials=\marg{your initials}] Your name initials, which will by typeset
% at the beginning of a comment (typically in a small box in the margin),
% allowing to identify different comment colors with different people. By
% default, the initials are set to the name of the command itself.
%
% \item[formatinitials=\meta{keyword or command}] The command that will be used
% to format the initials. By default (|formatinitials=default| or
% |formatinitials=margin|), the initials are displayed on the margin of the
% paragraph the first time the change occurs on a given page \phf[like this
% and like in the examples above]. You may also specify |formatinitials=box|
% to typeset the initials inline immediately before your annotation
% \phfbox[like this]. Specify |formatinitials=nobox| to remove the frame
% \phfnobox[like this]. Or specify |formatinitials=hide| to hide the initials
% altogether \phfhideinitials[like this]. You can also specify
% |formatinitials=footnote| to hide the initials at the point of text but with
% a footnote to associate colored comments with the name (for this to work
% more nicely, specify your full name as argument to |initials={...}|)
% \phffootnote[Here is an example]. [See
% \autoref{sec:customize-initials-formatting} for customizing the formatting of
% the margin initials for the |margin| style or for changing the text in the
% footnote in the |footnote| style.]
%
% You may also specify as a value to the |formatinitials=| option any \LaTeX{}
% command, which will then be used to format the initials. The macro should
% accept a single argument, the initials.
%
% The default initials formatting style (|formatinitials=margin|) requires the
% \pkgname{marginnote} package, which is loaded automatically. If you do not
% want to load the \pkgname{marginnote} package, specify the package option
% |usemarginnote=false| and set a different |formatinitials=...| style.
%
% \item[style=\marg{style name(s)}] Load one or more existing style(s) for the
% commenting command. The styles must either be predefined, or must have been
% defined using |\phfDefineCommentingStyle|. Separate style names with a
% comma.
%
% \item[font=\marg{LaTeX commands}] The font commands to invoke when typesetting
% annotations, regardless of type. By default, \phf{the font is unchanged
% other than having the author-specific color set}. Also, the font is not
% reset, so if you type an annotation somewhere where the font is large, the
% annotation's font will match that font by default. (Different annotation
% types may set their own font, see below.)
% \item[spacing=\meta{length}] Spacing to add around normal annotations. This
% amount of horizontal space is added before and after the annotation.
% \item[begin=\marg{LaTeX text and/or commands}] Stuff to typeset at the
% beginning of a general annotation. Nothing is typeset by default.
% \item[end=\marg{LaTeX text and/or commands}] Stuff to typeset at the end of a
% general annotation. Nothing is typeset by default.
%
% \item[cfont=\marg{LaTeX commands}] The font commands to invoke when
% typesetting an in-line comment. By default, use \phf[the default sans serif
% typeface, like this].
% \item[cspacing=\meta{length}] Spacing to add around comments. This amount of
% horizontal space is added before and after the comment.
% \item[cbegin=\marg{LaTeX text and/or commands}] Stuff to typeset at
% the beginning of a commment. By default, an opening square
% bracket (with some spacing adjustments).
% \item[cend=\marg{LaTeX text and/or commands}] Stuff to typeset at
% the end of a commment. By default, a closing square bracket (with
% some spacing adjustments).
%
% \item[rmfont=\marg{LaTeX commands}] The font commands to issue when
% typesetting text that is to be removed. \phf*{By default, the text is in
% italics like this} (If you're using Lua\LaTeX, it's recommended to use the
% |rmstrikethrough| style for proper strikethrough text; see
% \autoref{sec:styles}.)
% \item[rmspacing=\meta{length}] Spacing to add around text that is marked to be
% removed. This amount of horizontal space is added before and after.
% \item[rmbegin=\marg{LaTeX text and/or commands}] Stuff to typeset at the
% beginning of a piece of text to be removed. By default, a line overlapping
% with the text, to suggest removal.
% \item[rmend=\marg{LaTeX text and/or commands}] Stuff to typeset at the end of
% a piece of text to be removed. By default, a line overlapping with the
% text, to suggest removal.
%
% \item[ifont=\marg{LaTeX commands}] The font commands to issue when
% typesetting important text. \phf!{By default, the text is in
% larger boldface format like this}
% \item[ispacing=\meta{length}] Spacing to add around important text. This
% amount of horizontal space is added before and after.
% \item[ibegin=\marg{LaTeX text and/or commands}] Stuff to typeset at
% the beginning of a piece of important text. By default, three
% exclamation marks.
% \item[iend=\marg{LaTeX text and/or commands}] Stuff to typeset at
% the end of a piece of important text. By default, three
% exclamation marks.
% \end{cmdoptions}
%
% After invoking |\phfMakeCommentingCommand|, the colors |xxxcolor|,
% |xxxrmcolor| and |xxxrmcolorlink| are automatically defined (where |xxx| is to
% be replaced by your commenting macro name). These are used respectively for
% a usual comment color, text to be removed, and for links in text to be
% removed. You may redefine these colors afterwards with |\colorlet| if you
% wish:
% \begin{verbatim}
% \colorlet{AlErmcolor}{gray}
% \end{verbatim}
%
% \DescribeMacro{\phfDisableCommentingCommands}
% The command |\phfDisableCommentingCommands| disables all commenting commands,
% and causes them to emit an error. Use this command when approaching the final
% version of a long document to ensure that no commenting commands are left in
% the document.
%
% \subsection{Commenting Styles}
% \label{sec:styles}
%
% \emph{Styles} regroup a collection of definitions that alter the overall
% behavior and appearance of commenting commands issued with
% |\phfMakeCommentingCommand|. You can assign one or more styles to a
% commenting command definition by using the |style=| keyword:
% \begin{verbatim}
% \phfMakeCommentingCommand[style={footcomments}]{JD} % \JD
% \end{verbatim}
%
% You can combine style names with commas, for instance:
%
% \begin{verbatim}
% \phfMakeCommentingCommand[style={rmstrikethrough,footcomments}]{JD} % \JD
% \end{verbatim}
%
% \phfMakeCommentingCommand[rmbegin={},rmend={},rmspacing=2pt,initials={ZZ}]{dummycmd}
% \phfMakeCommentingCommand[style={footcomments},initials={YY}]{dummyYY}
% The following styles are predefined:
% \begin{itemize}
% \item \leavevmode\PrintMarginLabel{footcomments} The |footcomments| style
% arranges for in-line comments to be typeset as footnotes.
%
% \begin{verbatim}
% \phfMakeCommentingCommand[style={footcomments}]{YY}
%
% For instance, \YY[This would be an example of a comment
% typeset as a footnote.] this text might be suitable to
% comment on.
% \end{verbatim}
% gives:
%
% ``For instance, \dummyYY[This would be an example of a comment typeset as a
% footnote.] this text might be suitable to comment on.''
%
% This style can be convenient to place comments without interrupting the
% natural flow of the text.
%
% You can redefine |\phfccfootcommentwrapfnmark{..}| to customize the
% appearance of the footnote mark, and |\phfccfootcommenttextstyle| to get
% some handle on the commands issued within the footnote contents.
% \begin{verbatim}
% \renewcommand\phfccfootcommentwrapfnmark[1]{[[#1]]}
% \renewcommand\phfccfootcommenttextstyle{\bfseries}
% \end{verbatim}
%
% \item \leavevmode\PrintMarginLabel{rmstrikethrough} For Lua\LaTeX\ users, the
% style |rmstrikethrough| is available to make text marked for removal drawn
% in strikethrough font, \dummycmd*{\sout{kind of like this}}. You can cross
% out entire paragraphs of text which include display equations. Simply use:
% \begin{verbatim}
% \phfMakeCommentingCommand[style=rmstrikethrough]{ZZ} % requires LuaLaTeX
%
% ... \ZZ*{text to be removed} ... or also ... \ZZ* more
% text that I want to remove\endZZ ...
% \end{verbatim}
%
% The implementation uses the |lua-ul| package, which requires Lua\LaTeX. To
% apply this style to all definitions, use
% |\phfSetDefaultCommentingStyle{style=rmstrikethrough}| (see below).
%
% (We do not support strikethrough for regular \LaTeX\ because we weren't able
% to find an implementation that worked reliably even for large blocks of
% text. For instance, using the |\sout| from the \pkgname{ulem} package, you
% cannot strikethrough multiple paragraphs with displayed equations. Plus, to
% support the extended syntax of |\phfcc|'s commenting commands, we need the
% strikethrough to be implemented by a state change macro (like |\itshape|) or
% an environment, and not by a macro that accepts an argument.)
%
% \item We'll probably add more predefined styles in the future.
% \end{itemize}
%
% \DescribeMacro{\phfDefineCommentingStyle}
% You can define a style using |\phfDefineCommentingStyle|:
% \begin{verbatim}
% \phfDefineCommentingStyle{mystyle}{
% font={\fontfamily{phv}\selectfont}, % phv = Helvetica
% cfont={\bfseries\large},
% cbegin={{\ensuremath{\bigl\langle}}~},
% cend={{~\ensuremath{\bigr\rangle}}}
% }
% \end{verbatim}
% You can then define your commenting command invoking this style:
% \begin{verbatim}
% \phfMakeCommentingCommand[style=mystyle]{me}
% \end{verbatim}
%
% \phfDefineCommentingStyle{mystyle}{
% font={\fontfamily{phv}\selectfont},
% cfont={\bfseries\large},
% cbegin={{\ensuremath{\bigl\langle}}~},
% cend={{~\ensuremath{\bigr\rangle}}}
% }
% \phfMakeCommentingCommand[style=mystyle]{me}
%
% Then \me{for example}, (which was typeset using |\me{for example}|,) the code
% |\me[A comment]| becomes: \me[A comment].
%
% Styles are loaded in the order they are specified (separate style names with
% commas). Style definitions may themselves contain |style=...| keys to load
% other styles. Styles are always loaded before user keys, regardless of where
% the `|style|' key appears in the definition. When styles are loaded, and when
% the users' keys are set, later keys are overwrite earlier
% ones.\footnote{Except for an as-of-yet undocumented \phfverb{startcmds} and
% \phfverb{endcmds} keys which might be relevant if you'd like to develop a
% style which requires you to issue definitions at the beginning of every
% annotation.}
%
% \DescribeMacro{\phfSetDefaultCommentingStyle} Instead of defining named styles
% which have to be invoked explicitly, you can also preset the style of all
% future calls of |\phfMakeCommentingCommand|. You can achieve this result with
% the |\phfSetDefaultCommentingStyle| command:
% \begin{verbatim}
% \phfSetDefaultCommentingStyle{
% font={\large}
% }
% % all annotations defined from here on will appear larger
% \phfMakeCommentingCommand{AB}
% \end{verbatim}
%
% You can also use |\phfMakeCommentingCommand| to set one or more default
% style(s) for all future commenting command definitions:
% \begin{verbatim}
% \phfSetDefaultCommentingStyle{
% style={rmstrikethrough,footcomments}
% }
% % all annotations defined from here on will have these styles set
% \phfMakeCommentingCommand{AB}
% \end{verbatim}
%
% \subsection{Customizing the formatting of the initials label}
% \label{sec:customize-initials-formatting}
%
% \paragraph{For the \phfverb{formatinitials=margin} style:}
%
% You can customize the appearance of the initials in the margin when using the
% |formatinitials=margin| initials style by redefining the following macros.
% Changes affect all margin labels (i.e., changes affect all commenting commands
% using the |margin| initials formatting style).
%
% \DescribeMacro{\phfccformatmargininitials} The |\phfccformatmargininitials| is
% used to format the initials in the margin. You can redefine it if you'd like
% the initials to appear differently. Adapt the following, which contains the
% default definition, to your liking:
% \begin{verbatim}
% \renewcommand{\phfccformatmargininitials}[1]{%
% \fbox{\normalfont\sffamily\footnotesize #1}%
% }
% \end{verbatim}
% (Technical note: the |\fboxsep| length has been set to |1pt| prior to calling
% this macro.)
%
% \DescribeMacro{\phfccmargininitialssep} The |\phfccmargininitialssep| length
% is the minimal vertical separation between two initials labels. This is a
% length, so you should change it with |\setlength|:
% \begin{verbatim}
% \setlength{\phfccmargininitialssep}{2pt}
% \end{verbatim}
%
% \paragraph{For the \phfverb{formatinitials=box} and
% \phfverb{formatinitials=nobox} styles:}
%
% \DescribeMacro{\phfccformatboxinitials} For the |formatinitials=box| and
% |formatinitials=nobox| initials style, you can redefine the command
% |\phfccformatboxinitials| to typeset the initials, like so:
% \begin{verbatim}
% \renewcommand{\phfccformatboxinitials}[1]{%
% \normalfont\sffamily\tiny#1%
% }
% \end{verbatim}
%
% \paragraph{For the \phfverb{formatinitials=footnote} style:}
%
% \DescribeMacro{\phfCCChangesBy} When using the |formatinitials=footnote|
% initials formatting style, you may redefine |\phfCCChangesBy| to change the
% text in the footnote:
% \begin{verbatim}
% \renewcommand{\phfCCChangesBy}[1]{Changes in this color are by #1}
% \end{verbatim}
%
% \section{Package Options}
%
% This package requires the \pkgname{marginnote} package to generate initials
% labels when using the |margin| initials style (the default style). If you do
% not want to load the \pkgname{marginnote} package, you may use the package
% option |usemarginnote=false| (but then you cannot use the |margin| initials
% style):
% \begin{verbatim}
% \usepackage[usemarginnote=false]{phfcc}
% \end{verbatim}
%
% \section{Known limitations}
%
% There are some cases where it's hard to get everything right. The
% \pkgname{phfcc} commands do their best to get stuff right and to avoid
% generating obscure \LaTeX{} errors, but there might be times where not
% everything works as expected.
%
% \begin{itemize}
% \item If you place a comment inside certain contructs that are processed twice
% by \LaTeX{} (e.g., a figure caption when using e.g. the \pkgname{caption}
% package, etc.) then the margin initials will not appear even if the comment
% is the first of the page. This is because the margin label is produced the
% first time they are typeset, per page; if that happened to be in a temporary
% \TeX{} box that was then discarded, the margin note gets discarded along
% with it.
%
% In the case of AMS equations, there's a hack that make the labels appear
% right. Feel free to send pull requests to address other cases.
%
% \phf[FIXME: A better solution might be to write to the AUX file at each
% comment, so that the information is written when the comment is actually
% typeset, and then process where to put margin labels on the second run of
% \LaTeX{}.
%
% As a bonus, this would enable stuff like ``list of comments'' like the
% \pkgname{todonotes} package does. Even though I don't think it's necessary
% for the standard use case of this package.]
%
% \item Initials in the margin might overlap in some edge cases. See my
% comments and footnotes in the implementation documentation below.
%
% \item Initials in the margin might not appear if the comment immediately
% follows a page break, because the comment might have been processed while
% \LaTeX{} was on the previous page before deciding to start a new page. See
% my comments and footnotes in the implementation doc below.
% \end{itemize}
%
%
%
% \StopEventually{\PrintChangesAndIndex}
%
% \section{Implementation}
%
% Load these internally required packages.
%
% \begin{macrocode}
\RequirePackage{xkeyval}
\RequirePackage{kvoptions}
\RequirePackage{etoolbox}
\RequirePackage{xparse}
% \end{macrocode}
%
% Ensure we have the \pkgname{xcolor} package to manage text colors. We need
% \pkgname{xcolor} and not \pkgname{color} because we use |\colorlet|.
% \begin{macrocode}
\RequirePackage{xcolor}
% \end{macrocode}
%
%
% \subsection{Set up default settings}
%
% \begin{macro}{\phfCommentingDefault...}
% Provide sensible defaults for commenting formatting.
%
% Bold or semibold CFont sounds like a good idea, but comments would seem more
% aggressive like that, so keep them normal by default.
% \begin{macrocode}
\def\phfCommentingDefaultStartCmds{}
\def\phfCommentingDefaultEndCmds{}
\def\phfCommentingDefaultFont{}
\def\phfCommentingDefaultSpacing{0pt}
\def\phfCommentingDefaultBegin{}
\def\phfCommentingDefaultEnd{}
\def\phfCommentingDefaultCFont{\normalfont\sffamily}
\def\phfCommentingDefaultCSpacing{0.2em}
\def\phfCommentingDefaultCBegin{[\,}
\def\phfCommentingDefaultCEnd{\,]}
\def\phfCommentingDefaultRmFont{\small\itshape}%\itshape\notesmaller[0.9]}
\def\phfCommentingDefaultRmSpacing{.3em}
\def\phfCommentingDefaultRmBegin{%
\mbox{}\vrule height .55ex depth -.45ex width 1.4em\relax\hspace*{0.2em}%
\vrule height .55ex depth -.45ex width 0.6em\relax
\hspace*{-2em}}
\def\phfCommentingDefaultRmEnd{%
\hspace*{-2em}%
\vrule height .55ex depth -.45ex width 0.6em\relax\hspace*{0.2em}%
\vrule height .55ex depth -.45ex width 1.4em\relax}
\def\phfCommentingDefaultIFont{\large\bfseries}
\def\phfCommentingDefaultISpacing{0.25em}
\def\phfCommentingDefaultIBegin{!\hspace*{0.1em}!\hspace*{0.1em}!~}
\def\phfCommentingDefaultIEnd{~!\hspace*{0.1em}!\hspace*{0.1em}!}
% \end{macrocode}
% \end{macro}
%
% A default list of colors for commenting, and a minimal tool to select the next
% available color. The macro |\phf@cc@usedcolors| stores a
% vertical-bar-separated list of color names that have been already used and
% which should not be used again.
% \begin{macrocode}
\definecolor{phfcc0}{RGB}{0,148,240} % blue-y
\definecolor{phfcc1}{RGB}{242,108,13} % orange-brown-y
\definecolor{phfcc2}{RGB}{65,149,42} % green-y
\definecolor{phfcc3}{RGB}{128,55,134} % purple-y
\definecolor{phfcc4}{RGB}{0,129,129} % blue-green-y
\definecolor{phfcc5}{RGB}{148,7,24} % dark red / burgundy
\definecolor{phfcc6}{RGB}{160,120,0} % brownish
\definecolor{phfcc7}{RGB}{35,195,155} % aqua-ish
\csdef{phf@cc@presetcolor@0}{phfcc0}
\csdef{phf@cc@presetcolor@1}{phfcc1}
\csdef{phf@cc@presetcolor@2}{phfcc2}
\csdef{phf@cc@presetcolor@3}{phfcc3}
\csdef{phf@cc@presetcolor@4}{phfcc4}
\csdef{phf@cc@presetcolor@5}{phfcc5}
\csdef{phf@cc@presetcolor@6}{phfcc6}
\csdef{phf@cc@presetcolor@7}{phfcc7}
\def\phf@cc@usedcolors{|}
\def\phf@cc@nextcolor@#1{%
\ifcsname phf@cc@presetcolor@#1\endcsname% try preset
\edef\phf@tmp@testxx{%
\noexpand\in@{|\csname phf@cc@presetcolor@#1\endcsname|}{\phf@cc@usedcolors}}%
\phf@tmp@testxx
\ifin@% color already used, try next
\expandafter\phf@cc@nextcolor@\expandafter{\the\numexpr#1+1\relax}%
\else
\def\phf@cc@thecolor{\csname phf@cc@presetcolor@#1\endcsname}% good, use
\fi
\else% out of colors, fallback to red
\def\phf@cc@thecolor{red}%
\fi
}
% \end{macrocode}
% Read the argument. If non-empty, set |\phf@cc@thecolor| to the argument
% value. If empty, choose the next available preset color and set
% |\phf@cc@thecolor| to that.
% \begin{macrocode}
\def\phf@cc@getcolor#1{%
\edef\phf@tmp@xyz{#1}%
\if\relax\detokenize\expandafter{\phf@tmp@xyz}\relax
\phf@cc@nextcolor@{0}%
\else
\edef\phf@cc@thecolor{#1}%
\fi}
% \end{macrocode}
%
%
%
% Define the keys for |\setkeys| with \pkgname{xkeyval} package, and set the
% overall defaults.
% \begin{macrocode}
\def\phfcc@hook@phfmkccstyle@setstyle@noop#1{}
\let\phfcc@hook@phfmkccstyle@setstyle\phfcc@hook@phfmkccstyle@setstyle@noop
\define@cmdkey{phfmkccstyle}{style}{\phfcc@hook@phfmkccstyle@setstyle{#1}}
\define@cmdkey{phfmkcc}{color}{}
\define@cmdkey{phfmkcc}{initials}{}
\define@cmdkey{phfmkcc}{formatinitials}{}
\newtoks\cmdKV@phfmkcc@startcmds
\newtoks\cmdKV@phfmkcc@endcmds
\define@key{phfmkcc}{startcmds}{%
\cmdKV@phfmkcc@startcmds=\expandafter{\the\cmdKV@phfmkcc@startcmds#1}%
}
\define@key{phfmkcc}{endcmds}{%
\edef\x{\unexpanded{#1}\the\cmdKV@phfmkcc@endcmds}%
\cmdKV@phfmkcc@endcmds=\expandafter{\x}%
}
\define@cmdkey{phfmkcc}{font}{}
\define@cmdkey{phfmkcc}{spacing}{}
\define@cmdkey{phfmkcc}{begin}{}
\define@cmdkey{phfmkcc}{end}{}
\define@cmdkey{phfmkcc}{cfont}{}
\define@cmdkey{phfmkcc}{cspacing}{}
\define@cmdkey{phfmkcc}{cbegin}{}
\define@cmdkey{phfmkcc}{cend}{}
\define@cmdkey{phfmkcc}{rmfont}{}
\define@cmdkey{phfmkcc}{rmspacing}{}
\define@cmdkey{phfmkcc}{rmbegin}{}
\define@cmdkey{phfmkcc}{rmend}{}
\define@cmdkey{phfmkcc}{ifont}{}
\define@cmdkey{phfmkcc}{ispacing}{}
\define@cmdkey{phfmkcc}{ibegin}{}
\define@cmdkey{phfmkcc}{iend}{}
\define@cmdkey{phfmkcc}{groupcmd}{}
% \end{macrocode}
%
% Factory defaults refer to the |\phfCommentingDefault***| commands.
% \begin{macrocode}
\presetkeys{phfmkcc}{%
color={},%
initials={},%
formatinitials={default},%
startcmds={\phfCommentingDefaultStartCmds},%
endcmds={\phfCommentingDefaultEndCmds},%
font={\phfCommentingDefaultFont},%
spacing={\phfCommentingDefaultSpacing},%
begin={\phfCommentingDefaultBegin},%
end={\phfCommentingDefaultEnd},%
cfont={\phfCommentingDefaultCFont},%
cspacing={\phfCommentingDefaultCSpacing},%
cbegin={\phfCommentingDefaultCBegin},%
cend={\phfCommentingDefaultCEnd},%
rmfont={\phfCommentingDefaultRmFont},%
rmspacing={\phfCommentingDefaultRmSpacing},%
rmbegin={\phfCommentingDefaultRmBegin},%
rmend={\phfCommentingDefaultRmEnd},%
ifont={\phfCommentingDefaultIFont},%
ispacing={\phfCommentingDefaultISpacing},%
ibegin={\phfCommentingDefaultIBegin},%
iend={\phfCommentingDefaultIEnd},%
groupcmd={\@firstofone}%
}{}
% \end{macrocode}
%
% \subsection{Helpers and handlers for styles}
%
% \begin{macro}{\phfDefineCommentingStyle}
% User interface for defining custom comment styles.
% \begin{macrocode}
\newcommand\phfDefineCommentingStyle[2]{%
\csdef{phfcc@style@#1}{#2}%
}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\phfSetDefaultCommentingStyle}
% User interface for defining the default settings for all commenting commands
% declared from now on. Keep note of |style=| keywords separately (in
% |\phfcc@default@style|), because we cannot place them as |\presetkeys| in
% the main options family.
% \begin{macrocode}
\def\phfcc@default@style{}
\def\phfcc@hook@phfmkccstyle@setstyle@savestyle#1{%
\xdef\phfcc@default@style{#1}%
}
\newcommand\phfSetDefaultCommentingStyle[1]{%
\let\phfcc@hook@phfmkccstyle@setstyle\phfcc@hook@phfmkccstyle@setstyle@savestyle
\setkeys*{phfmkccstyle}{#1}%
\let\phfcc@hook@phfmkccstyle@setstyle\phfcc@hook@phfmkccstyle@setstyle@noop
\edef\x{\noexpand\presetkeys{phfmkcc}{\expandonce\XKV@rm}{}}%
\x
}
% \end{macrocode}
% \end{macro}
%
% \subsubsection{Internal helpers for loading styles}
%
% \begin{macro}{\phfcc@expandstylekeys}
% Helpers to expand style= instructions in a set of key=vals.
%
% The helper macro |\phfcc@expandstylekeys| accepts two arguments. The
% argument |#1| is a list of style names and |#2| is a collection of key=value
% pairs. This macro computes all the key=value settings that should be
% applied from the style definitions, plus all the remaining user key=value
% settings. We will recursively look for style=... keywords so that styles
% can load other styles.
%
% The final expanded key=value pairs is set in the token register
% |\phfcc@val@expanded@keyval|.
% \begin{macrocode}
\newtoks\phfcc@val@expanded@keyval
\def\phfcc@expandstylekeys#1#2{%
\def\phfcc@val@expanded@preexpandstyles{#1}%
\phfcc@val@expanded@keyval={#2}%
\loop
\phfcc@expandstylekeys@once
\def\phfcc@val@expanded@preexpandstyles{}%
\ifnum\phfcc@val@expanded@needmore=1\repeat
}
% \end{macrocode}
%
% The implementation of |\phfcc@expandstylekeys| proceeds by iterating single
% expansions until there are no more |style={}| values left. A single iteration
% is implemented here. The following macro reads its input from
% |\phfcc@val@expanded@preexpandstyles| and |\phfcc@val@expanded@keyval|, and it
% sets the macros |\phfcc@val@expanded@keyval| and
% |\phfcc@val@expanded@needmore|.
% \begin{macrocode}
\def\phfcc@expandstylekeys@once{%
\def\cmdKV@phfmkccstyle@style{}
\edef\x{\noexpand\setkeys*{phfmkccstyle}{\the\phfcc@val@expanded@keyval}}%
\x
% \end{macrocode}
% The |style={...}| values is stored in the macro |\cmdKV@phfmkccstyle@style|.
% If it is empty, there is no style to set and we're done.
% \begin{macrocode}
\if\relax\detokenize\expandafter{\cmdKV@phfmkccstyle@style}\relax
\def\phfcc@val@expanded@needmore{0}%
\else
\def\phfcc@val@expanded@needmore{1}%
\fi
% \end{macrocode}
% We might have one or more styles to expand. Iterate over the comma-separated
% list of styles and we'll append the collected style-specific key=value
% definitions in the macro |\phfcc@val@fullstylekeyvals| for now. Include also
% the predefined style names to expand before the user-specified styles.
% \begin{macrocode}
\def\phfcc@val@fullstylekeyvals{}%
\edef\phfcc@tmp@thestylelist{%
\phfcc@val@expanded@preexpandstyles,\cmdKV@phfmkccstyle@style}%
\@for\phfcc@tmp@next:=\phfcc@tmp@thestylelist \do{%
% \end{macrocode}
% At this point we're requested to expand the style whose name is stored in
% |\phfcc@tmp@next|. Collect the key=value definitions in the macro named
% |\phfcc@style@STYLENAME| or produce an error if such macro does not exist.
% Also, if the style provides a macro named |\phfcc@styleused@STYLENAME|, then
% invoke it at this point, in case the style would like to load any additional
% packages or execute any other preamble-time setup steps. In the following
% |\phfcc@tmp@stylekeyvals| is defined so that its immediate expansion yields
% the styles' key=value definitions.
% \begin{macrocode}
\ifcsname phfcc@style@\phfcc@tmp@next \endcsname
\ifcsname phfcc@styleused@\phfcc@tmp@next \endcsname
\csname phfcc@styleused@\phfcc@tmp@next \endcsname
\fi
\edef\phfcc@tmp@stylekeyvals{%
\expandafter\expandonce\csname phfcc@style@\phfcc@tmp@next \endcsname}%
\edef\phfcc@val@fullstylekeyvals{%
\expandonce\phfcc@val@fullstylekeyvals,%
\expandonce\phfcc@tmp@stylekeyvals}%
\else
\if\relax\detokenize\expandafter{\phfcc@tmp@next}\relax
\else
\PackageError{phfcc}{Requested commenting style `\phfcc@tmp@next' %
is not defined}{}%
\fi
\fi
}%
% \end{macrocode}
% Now we can collect the definitions from the styles and merge them with the
% remaining non-style-related user key/values. The macro |\XKV@rm| is set by
% \pkgname{xkeyval} to those key/values not processed by |\setkeys*|.
% \begin{macrocode}
\edef\x{\noexpand\phfcc@val@expanded@keyval={%
\expandonce\phfcc@val@fullstylekeyvals,%
\expandonce\XKV@rm}}%
\x
}
% \end{macrocode}
% \end{macro}
%
%
% \subsubsection{The \phfverb{rmstrikethrough} predefined style}
%
% \begin{macro}{\phfcc@style@rmstrikethrough}
% The definition of the |rmstrikethrough| style is fairly straightforward.
% \begin{macrocode}
\gdef\phfcc@styleused@rmstrikethrough{%
\RequirePackage{lua-ul}
\newunderlinetype\beginPhfccStrikeThrough{%
\leaders\vrule height .55ex depth -.45ex}
\gdef\phfcc@styleused@rmstrikethrough{}% auto-destruct/only run once
}
\def\phfcc@style@rmstrikethrough{%
rmfont={\beginPhfccStrikeThrough},
rmbegin={},
rmend={},
rmspacing={2pt}
}
% \end{macrocode}
% \end{macro}
%
% \subsubsection{The \phfverb{footcomments} predefined style}
%
% \begin{macro}{\phfcc@style@footcomments}
% The |footcomments| style uses |startcmds| and |endcmds| to collect material
% and then typeset it into a footnote.
% \begin{macrocode}
\def\phfcc@style@footcomments{%
startcmds={\phfcc@collectcommentfootnote},
endcmds={\phfcc@endcollectcommentfootnote},
}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\phfccfootcommenttextstyle}
% The macro |\phfccfootcommenttextstyle| can be redefined to customize the
% footnote text appearance.
% \begin{macrocode}
\def\phfccfootcommenttextstyle{\footnotesize}
% \end{macrocode}
% \end{macro}
%
% Now we define helpers to collect the contents of the footnote, and then
% typeset it.
%
% \begin{macro}{\phfcc@collectcommentfootnote}
% \begin{macro}{\phfcc@endcollectcommentfootnote}
% The entry point to these helpers are the macros
% |\phfcc@collectcommentfootnote| and |\phfcc@endcollectcommentfootnote|: They
% check whether this annotation is a comment and then call our main helpers if
% that's the case.
% \begin{macrocode}
\def\phfcc@collectcommentfootnote{%
\if@phfcc@iscomment
\expandafter\phfcc@collectfootnote
\fi}
\def\phfcc@endcollectcommentfootnote{%
\if@phfcc@iscomment
\expandafter\phfcc@endcollectfootnote
\fi}
% \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\phfcc@collectfootnote}
% \begin{macro}{\phfcc@endcollectfootnote}
% \begin{macro}{\phfcc@startfootnote}
% The helper |\phfcc@collectfootnote| collects the material and builds the
% footnote. I had to copy some footnote-building code from |latex.ltx|
% unfortunately: We can't call |\footnote{}| because it requires a macro
% argument; we need begin/end macros to feed all the footnote contents and
% material as \TeX\ parses it. Recall that \LaTeX's |\footnote| basically (1)
% steps the footnote counter (the counter name is stored in |\@mpfn| and the
% printable value is given by |\thempfn|) and prints the footnote mark
% (|\@footnotemark|), and (2) collects material in the |\insert| called
% |\footins|. The code relevant to (1) is collected in
% |\phfcc@startfootnote|. The code relevant to (2) is collected and adapted
% below between |\phfcc@collectfootnote| and |\phfcc@endcollectfootnote|.
% \begin{macrocode}
\def\phfcc@collectfootnote{%
\phfcc@startfootnote
\insert\footins\bgroup%
\reset@font\footnotesize
\interlinepenalty\interfootnotelinepenalty
\splittopskip\footnotesep
\splitmaxdepth \dp\strutbox \floatingpenalty \@MM
\hsize\columnwidth \@parboxrestore
\protected@edef\@currentlabel{%
\csname p@footnote\endcsname\@thefnmark
}%
\color@begingroup
\@makefntext{%
\rule\z@\footnotesep\@finalstrut\strutbox\phfcc@hackrevtex@skippar}%
\ignorespaces
\footnotesize
\color{\phf@cc@val@cur color}%
\phfccfootcommenttextstyle
}
\def\phfcc@endcollectfootnote{%
\unskip
\color@endgroup
\egroup
}
\def\phfcc@startfootnote{%
\stepcounter\@mpfn
\protected@xdef\@thefnmark{\thempfn}%
\phfccfootcommentwrapfnmark{\@footnotemark}%
}
\def\phfccfootcommentwrapfnmark#1{%
[#1]%
}
% \end{macrocode}
% Above, we used the class-provided |\@makefntext| macro to make comment
% footnotes look like the other document-provided footnotes, but we invoke that
% macro with dummy content because remember, we haven't collected the footnote
% contents yet. But some latex classes, like Rev\TeX, this macro add a
% paragraph; so we need to eliminate that paragraph break that would otherwise
% appear at the beginning of the footnote:
% \begin{macrocode}
\def\phfcc@hackrevtex@skippar{%
\@ifnextchar\par\@gobble\relax
}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
% \subsection{Define styles for initials formatting}
%
% Define the implementations for the different initials formatting. These are
% by default the small boxes that appear in the margin that match color to
% comment owner.
%
% Define the |margin| initials style as the default:
% \begin{macrocode}
\def\phf@cc@formatinitialsstyle@default{\phf@cc@formatinitialsstyle@margin}
% \end{macrocode}
%
% \subsubsection{Define styles \phfverb{hide}, \phfverb{box}, \phfverb{nobox}}
%
% \begin{macro}{\phf@cc@formatinitialsstyle@hide}
% Define the no-op |hide| style first.
% \begin{macrocode}
\def\phf@cc@formatinitialsstyle@hide#1{}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\phf@cc@formatinitialsstyle@box}
% \begin{macro}{\phf@cc@formatinitialsstyle@nobox}
% Define the |box|, and |nobox| styles. In either cases, the label can be
% customized by redefining |\phfccformatboxinitials|.
% \begin{macrocode}
\def\phf@cc@formatinitialsstyle@box#1{%
\hspace{0.25em}\relax
\raisebox{1pt}{{\fboxsep=1pt\relax\fbox{\phfccformatboxinitials{#1}}}}%
\hspace{0.25em}}
\def\phf@cc@formatinitialsstyle@nobox#1{%
\hspace{0.25em}\relax
{\phfccformatboxinitials{#1}}%
\hspace{0.25em}}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\phfccformatboxinitials}
% \begin{macrocode}
\def\phfccformatboxinitials#1{%
\normalfont\sffamily\tiny#1%
}
% \end{macrocode}
% \end{macro}
%
% \subsubsection{Define the style \phfverb{footnote}}
%
% Define the |footnote| style. Note you can redefine |\phfCCChangesBy| to
% whatever you please, and it can even take the name as |#1| argument.
% \begin{macrocode}
\def\phf@cc@formatinitialsstyle@footnote#1{%
\ifcsname phf@cc@valfmtinitialsfootnote@intlspage@\phf@cc@val@cur @\roman{page}\endcsname
% already displayed on this page, don't repeat
\else
\csgdef{phf@cc@valfmtinitialsfootnote@intlspage@\phf@cc@val@cur @\roman{page}}{1}%
\def\phf@cc@tmp@zz{\gdef\@thefnmark{}\@footnotetext}%
\expandafter\phf@cc@tmp@zz\expandafter{\expandafter{%
\expandafter\color\expandafter{\phf@cc@val@cur color}\phfCCChangesBy{#1}}}%
\fi
}
\robustify\phf@cc@formatinitialsstyle@footnote
\def\phfCCChangesBy{Changes by\ }
% \end{macrocode}
%
% \subsubsection{Define the style \phfverb{margin}}
%
% \begin{macro}{\phf@cc@formatinitialsstyle@margin}
% Define the |margin| style now. This one is a little tricky.
% \begin{macrocode}
\def\phf@cc@formatinitialsstyle@margin#1{%
% \end{macrocode}
%
% First thing, we define an auxiliary global macro to remember whenever we've
% already displayed the margin note on a given page. If the label was already
% displayed on this page (as witnessed by the following test macro being
% defined), don't repeat the label display and skip altogether.\footnote{There
% are some edge cases here I'm not sure I want to spend the effort to fix. For
% instance, if the comment appears right after a page break, it might have been
% processed by \TeX\space while on the previous page and this test might get the
% page number wrong. Oh well, the label was on last page already so you should
% know whose comment this is.}
% \begin{macrocode}
\ifcsname phf@cc@valfmtinitialsmargin@intlspage@\phf@cc@val@cur
@\roman{page}\endcsname
\else
% \end{macrocode}
%
% Check for any other reasons why we shouldn't emit a margin note (e.g. for some
% known two-pass environments); this is done by |\phf@cc@margin@ifchecks|. Then
% actually create the margin note with |\phf@cc@margin@emit|.
% \begin{macrocode}
\phf@cc@margin@ifchecks{%
\phf@cc@margin@emit{#1}%
}%
\fi
}
\robustify\phf@cc@formatinitialsstyle@margin
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\phf@cc@margin@ifchecks}
% Detects if we're in a first pass in an AMS equation, for instance, to only
% emit the label in the second pass (actual typesetting).
% \begin{macrocode}
\def\phf@cc@margin@ifchecks#1{%
\phf@cc@ififexists{ifmeasuring@}{%
\message{Detected first pass in environment, not emitting margin
initials label this time.}%
}{%
\phf@cc@ififexists{if@inlabel}{%
\message{Detected comment in latex item label, not emitting margin
initials at this time to avoid messing up everything.}%
}{%
#1%
}%
}%
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\phf@cc@ififexists}
% A helper macro. The |\phf@cc@ififexists|\marg{if-cs-name}\marg{commands if
% true}\marg{commands if false} macro checks if the command |\ifXXXX| exists,
% where the name |ifXXXX| is the first argument of |\phf@cc@ififexists|. If it
% exists, then it checks that ``if'' condition and executes \marg{commands if
% true} or \marg{commands if false} as appropriate. If the ``if'' macro doesn't
% exist, then executes \marg{commands if false}.
% \begin{macrocode}
\def\phf@cc@ififexists#1#2#3{%
\ifcsname #1\endcsname
\def\x{\phf@cc@ififexists@{#1}{#2}{#3}}%
\else
\def\x{#3}%
\fi
\x
}
\def\phf@cc@ififexists@#1#2#3{%
\csname #1\endcsname
#2%
\else
#3%
\fi
}
% \end{macrocode}
% \end{macro}
%
% At this point, we are all set to display the initials in the margin. It seems
% like there should be nothing wrong with simply emitting a |\marginpar|, but
% those don't work in footnotes and figure captions, where one would also like
% to be able to introduce comments. One could use the \pkgname{marginnote}
% package instead, which is more reliable, but then we can get overlapping
% margin labels which are not very nice.
%
% {\itshape On the subject of |\marginnote| vs |\marginpar|:} The strategy here
% is use |\marginnote| all the time. Originally I used |\marginpar|, but it
% doesn't work in footnotes and figure captions, where one often wants to
% comment things. It's really hard to detect all cases where |\marginpar| is
% problematic. (|\ifinner| detects minipages/equations, value of |\@captype|
% detects figure captions, but I didn't manage to detect footnotes reliably, and
% I anticipate other problematic situations coming up). So I use
% \pkgname{marginnote} instead, which is more reliable. We could have some
% complex process to decide whether to use |\marginpar| or |\marginnote|, but
% only if we can find a really reliable algorithm. When collaborators are
% commenting on a document in the final hours before a deadline, we really don't
% want to generate obscure LaTeX errors because they happened to hit an edge
% case by placing a comment somewhere I hadn't anticipated. So for now,
% universally use |\marginnote|. If you don't want to load the
% \pkgname{marginnote} package for whatever reason, use a different initials
% label style and specify the |usemarginnote=false| package option.
%
% To avoid margin notes overlapping with \pkgname{marginnote}, we use custom
% code with a simple algorithm to shift the margin notes vertically so that they
% don't overlap. The code is a bit ugly, but it seems to work and it doesn't
% rely on too specific hacks, so it is hopefully not too prone to edge cases.
%
% \begin{macro}{\phf@cc@margin@emit}
% This is the macro that actually creates the margin note. First we create a
% |\hbox| with the label so that we can measure its height. Then we defer to
% |\phf@cc@createmarginnote| to produce the margin note with the formatted
% initials.
% \begin{macrocode}
\newbox\phf@cc@margin@labelbox
\newdimen\phf@cc@margin@labelboxhgt
\def\phf@cc@margin@emit#1{%
\setbox\phf@cc@margin@labelbox=\hbox{\strut
\expandafter\color\expandafter{\phf@cc@val@cur color}%
\fboxsep=1pt\relax
\phfccformatmargininitials{#1}}%
\phf@cc@margin@labelboxhgt=\ht\phf@cc@margin@labelbox
\phf@cc@createmarginnote
\csgdef{phf@cc@valfmtinitialsmargin@intlspage@\phf@cc@val@cur%
@\roman{page}}{1}%
}%
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\phfccformatmargininitials}
% The |\phfccformatmargininitials|\marg{initials} can be redefined to change the
% appearance of the margin intials box.
% \begin{macrocode}
\def\phfccformatmargininitials#1{%
\fbox{\normalfont\sffamily\footnotesize #1}%
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\phf@cc@createmarginnote}
% The tricky thing with \pkgname{marginnote} is that labels will overlap if
% they are emitted on the same line. Here we use a workaround: We check
% |\pdflastypos| and add some vertical spacing if we are too close to the last
% note's y position on the same page. But the issue is that |\pdfsavepos| and
% |\pdflatexypos| only work while shipping out, so basically all we can do is
% write the values to the AUX file and use them next time latex is run. Here
% we use the same mechanism as \pkgname{marginnote}: define a new \LaTeX\space
% label printing a |\newphfccmarginnote| in the AUX file with the relevant
% meta-info. We use the internal counters |\@mn@thispage| (current absolute
% page number) and |\@mn@atthispage| (number of note on current page) because
% we also need to track which notes are on which page, and there's no use
% duplicating all that code (I do hope those counters don't change, though).
% \begin{macrocode}
\def\phf@cc@createmarginnote{%
\marginnote[{\copy\phf@cc@margin@labelbox}]{\copy\phf@cc@margin@labelbox}[%
\phf@cc@marginextractvshift]%
\phf@cc@savepos
\protected@write\@auxout{}{%
\string\newphfccmarginnote{%
{\@mn@thispage}%
{\@mn@atthispage}%
{\noexpand\number\phf@cc@lastypos sp}%
{\number\phf@cc@margin@labelboxhgt sp}%
}%
}%
}
\ifcsname pdfsavepos\endcsname
\let\phf@cc@savepos\pdfsavepos
\let\phf@cc@lastypos\pdflastypos
\else
\ifcsname savepos\endcsname
\let\phf@cc@savepos\savepos
\let\phf@cc@lastypos\lastypos
\else
\PackageError{phfcc}{Cannot find appropriate \string\pdfsavepos\space
command, neither \string\pdfsavepos\space nor\string\savepos\space
are defined.}{}
\fi
\fi
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\phf@cc@marginextractvshift}
% The macro |\phf@cc@marginextractvshift| is responsible for extracting the
% required vertical shift from the corresponding label created from the
% information saved in the AUX file. \emph{This macro is fully expandable,
% and is meant to be used as the value of the optional vertical-shift argument
% in \phfverb{\marginnote}.} The current note is identified by the internal
% \pkgname{marginnote} counters |\@mn@thispage| (current absolute page number)
% and |\@mn@atthispage| (current note number on this page).
%
% The label |\csname phfccmn@\@mn@thispage.\@mn@atthispage\endcsname|
% generated by |\newphfccmarginnote| expands to |{|\marg{pdf y-pos of the
% point in text}\marg{label box height}|}|\relax |{|\marg{requried vertical
% shift to adjust this note}|}|. The first group of fields are the two last
% arguments specified to |\newphfccmarginnote| written to the AUX file (the
% two first are already in the label/macro name), and the second group
% contains the values (only one currently) computed when calling
% |\newphfccmarginnote|.
%
% Used as |\marginnote|'s vertical shift length. Expands to the vertical
% shift needed to correct the current note. Remember: no assignments in here,
% this command must be fully expandable.
% \begin{macrocode}
\def\phf@cc@marginextractvshift{%
\ifcsname phfccmn@\@mn@thispage.\@mn@atthispage\endcsname
\expandafter\expandafter\expandafter\expandafter\expandafter
\expandafter\expandafter\@firstofone
\expandafter\expandafter\expandafter\@secondoftwo
\csname phfccmn@\@mn@thispage.\@mn@atthispage\endcsname
\else
\z@
\fi
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\newphfccmarginnote}
% The |\newphfccmarginnote| command defines the margin label in the AUX file.
% It's not meant as public API, it's only written in the AUX file to be
% re-read on next run. Here is where all the calculations are done.
%
% In this macro we get the page number, y position, and box height of a margin
% note written by the previous run of \LaTeX. We need to compute the vertical
% shift to avoid overlapping with other boxes.
%
% The algorithm is pretty dumb. For each margin note, we loop over all
% already-processed margin notes on the same page. If an overlap is detected,
% we advance the y-position of the margin note according to the height of the
% existing overlapping margin note, and re-start the loop.
%
% This is also the main entry point into our vertical shift calculating
% algorithm. Set the |\phf@cc@marginvshift| to zero, this is where the
% calculated total vertical shift will be stored. Then call our algorithm
% main routine unless we're the first note on the page.\footnote{There's an
% edge case here that I haven't dealt with: In the case of footnotes or figure
% captions, the notes can appear out of order in the AUX file. Our algorithm
% only checks for overlap with note numbers that are less than the current
% note number. So if note 1.1 appears in the AUX file after note 1.2, then
% first 1.2 is processed, no shift is added (it ignores the fact that 1.1
% doesn't exist yet), then 1.1 is processed and thinks it's the first note so
% doesn't add a shift either. If this ends up really being a problem there
% are ways to fix this but now I don't feel it's worth the effort. So you
% might have a note in a figure caption somehow overlapping with another note
% if they happen to be in different environments and yet on the same line.}
% \begin{macrocode}
\def\phf@cc@marginlastmarginnoteypos{}
\newdimen\phf@cc@marginvshift
\def\newphfccmarginnote#1{\newphfccmarginnote@#1}
\def\newphfccmarginnote@#1#2#3#4{%
\phf@cc@marginvshift=\z@
\ifnum#2>0\relax
\phf@cc@margin@calculatevshift{#1}{#2}{#3}{#4}%
\else\fi
\csxdef{phfccmn@#1.#2}{%
{{#3}{#4}}{\number\phf@cc@marginvshift sp}%
}%
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\phfccmargininitialssep}
% The dimension |\phfccmargininitialssep| is the minimum vertical separation
% between two margin notes initials. Redefine this length to whatever you
% like (e.g., |\phfccmargininitialssep=1mm\relax| or
% |\setlength{\phfccmargininitialssep}{1mm}|).
% \begin{macrocode}
\newdimen\phfccmargininitialssep
\phfccmargininitialssep=2\p@
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\phf@cc@margin@calculatevshift}
% This is our note vertical-shifting algorithm. Compute the vertical shift by
% looping through existing notes on the present page. The temporary counter
% |\phf@cc@tmp@cntiter| is the iteration counter and iterates over the notes
% on the present page up to the current note. (If a note with earlier note is
% undefined, skip it, this can happen if the note is in a footnote or figure
% caption; see earlier footnote.)
%
% The total vertical shift that needs to be applied to the present note
% (positive shift = downwards shift) is stored in the dimen
% |\phf@cc@marginvshift|, to be picked up by |\newphfccmarginnote|. Here
% |#1|=absolute page no., |#2|=current note no., |#3|=current note y position,
% |#4|=current note box height.
% \begin{macrocode}
\newcount\phf@cc@tmp@cntiter
\def\phf@cc@margin@calculatevshift#1#2#3#4{%
\phf@cc@marginvshift=\z@
\phf@cc@tmp@cntiter=0
\phf@cc@margin@calculatevshift@{#1}{#2}{#3}{#4}%
}
\def\phf@cc@margin@calculatevshift@#1#2#3#4{%
\ifnum\phf@cc@tmp@cntiter<#2\relax
\ifcsname phfccmn@#1.\the\phf@cc@tmp@cntiter\endcsname
\expandafter\let\expandafter
\phf@cc@tmp\csname phfccmn@#1.\the\phf@cc@tmp@cntiter\endcsname
\edef\phf@cc@tmp@otherypos{%
\expandafter\expandafter\expandafter\@firstoftwo
\expandafter\@firstoftwo \phf@cc@tmp}%
\edef\phf@cc@tmp@otherhgt{%
\expandafter\expandafter\expandafter\@secondoftwo
\expandafter\@firstoftwo \phf@cc@tmp}%
\edef\phf@cc@tmp@othervshift{%
\expandafter\expandafter\expandafter\@firstofone
\expandafter\@secondoftwo \phf@cc@tmp}%
\ifdim\dimexpr\phf@cc@tmp@otherypos-\phf@cc@tmp@othervshift
>\dimexpr#3-#4-\phf@cc@marginvshift\relax
\ifdim\dimexpr\phf@cc@tmp@otherypos-\phf@cc@tmp@otherhgt-\phf@cc@tmp@othervshift
<\dimexpr#3-\phf@cc@marginvshift\relax
% \end{macrocode}
% At this point, an overlap is detected between the current note that we're
% adjusting (note number |#2| on page |#1|) and an earlier processed note (note
% number |\phf@cc@tmp@cntiter| on the same page). So we shift the current note
% so that it appears below the other note. The vertical shift is accumulated in
% the |\phf@cc@marginvshift| dimen, this will be stored into the label after
% we're done computing. Note: the y-position reported by |\pdflastypos| is from
% the \emph{bottom}, not the top, so ``higher on the page than'' is ``|>|''; but
% a positive margin vertical shift in \pkgname{marginnote} shifts the margin
% note \emph{downwards}.
%
% Then reset the iteration counter to zero, so that we re-loop over all existing
% notes on the same page to re-check (with the new vertical shift) that we
% didn't generate an overlap with any earlier note (e.g., could happen on a
% two-column page with comments in both columns).
% \begin{macrocode}
\@tempdima=\dimexpr
\phfccmargininitialssep
+(#3-\phf@cc@marginvshift)%
-(\phf@cc@tmp@otherypos-\phf@cc@tmp@otherhgt-\phf@cc@tmp@othervshift)%
\relax
%\message{*** phfcc DEBUG: overlap detected of note #1.#2 with
% note #1.\the\phf@cc@tmp@cntiter, increasing vshift of note
% number #2 on page #1 by \the\@tempdima \space ***}%
\advance\phf@cc@marginvshift \@tempdima
\phf@cc@tmp@cntiter=\z@\relax
\else\fi
\else\fi
\else\fi
\advance\phf@cc@tmp@cntiter 1\relax
\phf@cc@margin@calculatevshift@{#1}{#2}{#3}{#4}%
\fi
}
% \end{macrocode}
% \end{macro}
%
%
% \subsection{The main \phfverb{\phfMakeCommentingCommand} macro}
%
% \begin{macro}{\phfMakeCommentingCommand}
% Implementation of |\phfMakeCommentingCommand|. See main package
% documentation for usage details. The inner command definitions are kinda
% tricky because of all the possible syntax options.
% |\phfMakeCommentingCommand|\oarg{color=blue,...}\marg{cmdname}
% \begin{macrocode}
\newcommand\phfMakeCommentingCommand[2][]{%
\cmdKV@phfmkcc@startcmds={}%
\cmdKV@phfmkcc@endcmds={}%
\edef\x{\noexpand\phfcc@expandstylekeys{\phfcc@default@style}{\unexpanded{#1}}}%
\x
%\setrmkeys{phfmkcc}%
\edef\x{\noexpand\setkeys{phfmkcc}{\the\phfcc@val@expanded@keyval}}%
\x
\phf@cc@getcolor{\cmdKV@phfmkcc@color}%
\colorlet{#2color}{\phf@cc@thecolor}%
\edef\phf@tmp@xxappcmd{\noexpand\appto\noexpand\phf@cc@usedcolors{\phf@cc@thecolor|}}%
\phf@tmp@xxappcmd
\colorlet{#2rmcolor}{#2color!70!gray!55!white}%
\colorlet{#2rmcolorlink}{blue!40!#2rmcolor}%
\edef\phf@tmp@xxx{\cmdKV@phfmkcc@initials}%
\if\relax\detokenize\expandafter{\phf@tmp@xxx}\relax
\csedef{phf@cc@val@#2@initials}{#2}%
\else
\csedef{phf@cc@val@#2@initials}{\cmdKV@phfmkcc@initials}%
\fi
\ifcsname phf@cc@formatinitialsstyle@%
\detokenize\expandafter{\cmdKV@phfmkcc@formatinitials}\endcsname%
\expandafter\def\expandafter\phf@cc@tmp@xzx\expandafter{%
\csname phf@cc@formatinitialsstyle@%
\detokenize\expandafter{\cmdKV@phfmkcc@formatinitials}\endcsname}%
\csedef{phf@cc@val@#2@formatinitials}{\expandonce\phf@cc@tmp@xzx}%
\else
\csedef{phf@cc@val@#2@formatinitials}{\expandonce\cmdKV@phfmkcc@formatinitials}%
\fi
\csedef{phf@cc@val@#2@startcmds}{\the\cmdKV@phfmkcc@startcmds}%
\csedef{phf@cc@val@#2@endcmds}{\the\cmdKV@phfmkcc@endcmds}%
%\message{***** STARTCMDS ARE \detokenize\expandafter{\the\cmdKV@phfmkcc@startcmds} *****}%
%\message{***** ENDCMDS ARE \detokenize\expandafter{\the\cmdKV@phfmkcc@endcmds} *****}%
\csedef{phf@cc@val@#2@font}{\expandonce\cmdKV@phfmkcc@font}%
\csedef{phf@cc@val@#2@spacing}{\expandonce\cmdKV@phfmkcc@spacing}%
\csedef{phf@cc@val@#2@begin}{\expandonce\cmdKV@phfmkcc@begin}%
\csedef{phf@cc@val@#2@end}{\expandonce\cmdKV@phfmkcc@end}%
\csedef{phf@cc@val@#2@cfont}{\expandonce\cmdKV@phfmkcc@cfont}%
\csedef{phf@cc@val@#2@cspacing}{\expandonce\cmdKV@phfmkcc@cspacing}%
\csedef{phf@cc@val@#2@cbegin}{\expandonce\cmdKV@phfmkcc@cbegin}%
\csedef{phf@cc@val@#2@cend}{\expandonce\cmdKV@phfmkcc@cend}%
\csedef{phf@cc@val@#2@rmfont}{\expandonce\cmdKV@phfmkcc@rmfont}%
\csedef{phf@cc@val@#2@rmspacing}{\expandonce\cmdKV@phfmkcc@rmspacing}%
\csedef{phf@cc@val@#2@rmbegin}{\expandonce\cmdKV@phfmkcc@rmbegin}%
\csedef{phf@cc@val@#2@rmend}{\expandonce\cmdKV@phfmkcc@rmend}%
\csedef{phf@cc@val@#2@ifont}{\expandonce\cmdKV@phfmkcc@ifont}%
\csedef{phf@cc@val@#2@ispacing}{\expandonce\cmdKV@phfmkcc@ispacing}%
\csedef{phf@cc@val@#2@ibegin}{\expandonce\cmdKV@phfmkcc@ibegin}%
\csedef{phf@cc@val@#2@iend}{\expandonce\cmdKV@phfmkcc@iend}%
\csedef{phf@cc@val@#2@groupcmd}{\expandonce\cmdKV@phfmkcc@groupcmd}%
% \end{macrocode}
%
% Once all the information was gathered and stored, define the commenting command
% itself (as well as its |\end*| counterpart). Make them robust.
% \begin{macrocode}
\csdef{#2}{\phf@cc@do{#2}}%
\expandafter\robustify\csname #2\endcsname%
\csdef{end#2}{\phf@cc@end}%
\expandafter\robustify\csname end#2\endcsname%
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\phfDisableCommentingCommands}
% This command causes any commenting command declared with
% |\phfMakeCommentingCommand| to emit an error.
% \begin{macrocode}
\newif\ifphf@cc@disabled
\phf@cc@disabledfalse
\def\phfDisableCommentingCommands{%
\phf@cc@disabledtrue
}
% \end{macrocode}
% \end{macro}
%
% \subsection{Implementation of the commenting commands}
%
% Overall, the implementation of a commenting command goes as follows. First,
% gather all the info about the command invocation (e.g., important? starred?
% comment?) and then ultimately call |\phf@cc@begin| and |\phf@cc@end| which
% execute the formatting options.
%
% Within each comment, the following flags are set by the parsing mechanism.
% \begin{macrocode}
\newif\if@phfcc@iscomment
\newif\if@phfcc@isremoved
\newif\if@phfcc@isimportant
% \end{macrocode}
%
% Everything happens within |\begingroup|\ldots|\endgroup|. The group is opened
% at |\phf@cc@do| (the commenting command itself), and is closed by |\phf@cc@end|.
%
% \begin{macro}{\phf@cc@begin}
% The helper macro |\phf@cc@begin| is responsible for issuing all the
% necessary definitions for the comment to be typeset correctly, including
% initials, depending on whether it is a regular text addition, a text removal
% comment, an important comment, a commenting comment, etc. It inspects
% |\if@phfcc@iscomment|, |\if@phfcc@isremoved|, and |\if@phfcc@isimportant| to
% determine the comment type.
%
% This is not the main comment entry point, the main entropy point is
% |\phf@cc@do| and |\phf@cc@begin| is called internally from there. {\itshape
% Execution is already enclosed in a local \TeX\ group; a |\begingroup| has
% already been issued by |\phf@cc@do|.}
% \begin{macrocode}
\def\phf@cc@begin{%
% \end{macrocode}
%
% First, we set the author's color so that by default everything we do will use
% that color.
% \begin{macrocode}
\color{\phf@cc@val@cur color}%
% \end{macrocode}
%
% Issuing \phfverb\leavevmode\ here is annoying because it adds vertical space
% if the command is issued in vertical mode right before an equation or theorem;
% but it is needed immediately after section and paragraph headings so that the
% comment style (eg sans font along with color etc.) is not applied to the
% section/paragraph heading itself.
% \begin{macrocode}
\leavevmode% beurk, see above
% \end{macrocode}
%
% The comment typesetting is constructed in layers, each time adding commands to
% execute at the start and corresponding commmands to execute at the end. The
% start commands are executed in the specified order, with the end commands in
% the reverse order at the end. We use the |\phf@cc@helper@pushgrpcmds| helper
% to this effect.
%
% Introducing the necessary spacing, and issuing the initials. The amount of
% spacing will depend on the type of comment; |\phf@cc@val@spacing| will be set
% appropriately below when setting comment-type specific settings.
% \begin{macrocode}
\phf@cc@helper@pushgrpcmds{%
\csname phf@cc@val@\phf@cc@val@cur @startcmds\endcsname
\hspace{\phf@cc@val@spacing}%
\phf@cc@showinitials%
}{%
\hspace{\phf@cc@val@spacing}%
\csname phf@cc@val@\phf@cc@val@cur @endcmds\endcsname
}%
% \end{macrocode}
%
% See what comment type we're dealing with, and set the appropriate settings.
%
% First, check if we have a commenting-comment. If so, see whether or not it is
% additionally marked as important and issue the relevant commands. Also set
% the relevant spacing.
% \begin{macrocode}
\if@phfcc@iscomment
\if@phfcc@isimportant
\phf@cc@helper@pushgrpcmdsX{%
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @font\endcsname
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @cfont\endcsname
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @ifont\endcsname
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @cbegin\endcsname
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @ibegin\endcsname
}{%
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @iend\endcsname
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @cend\endcsname
}%
\edef\phf@cc@val@spacing{\csname phf@cc@val@\phf@cc@val@cur @ispacing\endcsname}%
\else
\phf@cc@helper@pushgrpcmdsX{%
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @font\endcsname
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @cfont\endcsname
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @cbegin\endcsname
}{%
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @cend\endcsname
}%
\edef\phf@cc@val@spacing{\csname phf@cc@val@\phf@cc@val@cur @cspacing\endcsname}%
\fi
\else
% \end{macrocode}
% Now check if we have an important comment (which is not a commenty-comment).
% \begin{macrocode}
\if@phfcc@isimportant
\phf@cc@helper@pushgrpcmdsX{%
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @font\endcsname
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @ifont\endcsname
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @ibegin\endcsname
}{%
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @iend\endcsname
}%
\edef\phf@cc@val@spacing{%
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @ispacing\endcsname%
}%
\else
% \end{macrocode}
% Not a comment, not important. Could be a piece of text marked for removal.
% \begin{macrocode}
\if@phfcc@isremoved
\phf@cc@helper@pushgrpcmdsX{%
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @font\endcsname
\noexpand\color{\phf@cc@val@cur rmcolor}%
\noexpand\colorlet{docnotelinkcolor}{\phf@cc@val@cur rmcolorlink}%
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @rmfont\endcsname
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @rmbegin\endcsname
}{%
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @rmend\endcsname
}%
\edef\phf@cc@val@spacing{\csname phf@cc@val@\phf@cc@val@cur @rmspacing\endcsname}%
\else
% \end{macrocode}
% We've got just a plain, old, inline marked text.
% \begin{macrocode}
\phf@cc@helper@pushgrpcmdsX{%
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @font\endcsname
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @begin\endcsname
}{%
\expandafter\noexpand\csname phf@cc@val@\phf@cc@val@cur @end\endcsname
}%
\edef\phf@cc@val@spacing{\csname phf@cc@val@\phf@cc@val@cur @spacing\endcsname}%
\fi
\fi
\fi
% \end{macrocode}
%
% Actually issue these commmands and kick off the typesetting of the comment.
% \begin{macrocode}
\phf@cc@val@grpcmds
}
\def\phf@cc@helper@pushgrpcmds#1#2{%
\appto\phf@cc@val@grpcmds{#1}%
\preto\phf@cc@val@grpendcmds{#2}%
}
\def\phf@cc@helper@pushgrpcmdsX#1#2{% expands arguments with edef
\edef\phfcc@tmp@x{\noexpand\phf@cc@helper@pushgrpcmds{#1}{#2}}%
\phfcc@tmp@x
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\phf@cc@end}
% Here we execute closing commands and close the group. |\phf@cc@end| is the
% last macro executed when the user invokes a comment, in any case.
% \begin{macrocode}
\def\phf@cc@end{%
\phf@cc@val@grpendcmds
\endgroup
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\phf@cc@showinitials}
% This helper macro prints out the initials, if any.
% \begin{macrocode}
\def\phf@cc@showinitials{%
\edef\phf@cc@tmpx{%
\expandafter\expandonce\csname phf@cc@val@\phf@cc@val@cur @initials\endcsname}%
\expandafter\notblank\expandafter{\phf@cc@tmpx}{%
\csname phf@cc@val@\phf@cc@val@cur @formatinitials%
\expandafter\endcsname\expandafter{\phf@cc@tmpx}}{}%
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\phf@cc@do}
% {\bfseries The macro |\phf@cc@do| is the main entry point of a commenting
% command.} Actually, the user-instantiated commenting commands are an alias
% of this command, with the user macro name as first argument. So the |\AlE|
% command defined in the main documentation of this package was in fact
% defined as an alias to |\phf@cc@do{AlE}|. This is were everything starts.
% \begin{macrocode}
\def\phf@cc@do#1{%
% \end{macrocode}
% First, we need to check if commenting commands were disabled with
% |\phfDisableCommentingCommands|. If this is the case, generate an error.
% \begin{macrocode}
\ifphf@cc@disabled
\PackageError{phfcc}{Commenting commands have been disabled
with \string\phfDisableCommentingCommands.}{}%
\fi
% \end{macrocode}
% Now we start for real. First, we open the \TeX\ group. Then we start parsing
% the invocation syntax.
%
% \begin{macrocode}
\begingroup
\@phfcc@iscommentfalse
\@phfcc@isremovedfalse
\@phfcc@isimportantfalse
% \end{macrocode}
%
% The macros |\phf@cc@val@grp*cmds| store the commands to be executed in
% |\phf@cc@begin| and |\phf@cc@end|. By default, they are empty. They are
% filled by relevant code when parsing the command invocation.
%
% By default, there are no commands at group begin (|\phf@cc@val@grpcmds|), no
% commands at group end (|\phf@cc@val@grpendcmds|), and no spacing on either
% side of the typeset comment (|\phf@cc@val@spacing|).
% \begin{macrocode}
\def\phf@cc@val@grpcmds{}%
\def\phf@cc@val@grpendcmds{}%
\def\phf@cc@val@spacing{0pt}%
% \end{macrocode}
%
% Store the name of the commenting command so we can look up the relevant
% comment settings. This is the name that was given to the commenting command
% itself, e.g. |phf|.
% \begin{macrocode}
\edef\phf@cc@val@cur{#1}%
% \end{macrocode}
%
% Here we start the parsing of the type of comment. First, check for a star
% (e.g., |\phf*{...}|) to see if we're dealing with a removed block of text.
% \begin{macrocode}
\@ifstar\phf@cc@star\phf@cc@nostar%
}
% \end{macrocode}
%
% If we don't have a star, continue parsing to see if we have an important piece
% of text or comment (|\phf!| sytnax).
% \begin{macrocode}
\def\phf@cc@nostar{\@ifnextchar!\phf@cc@important\phf@cc@grp}
% \end{macrocode}
%
% At this point, we have determined whether the invocation is starred (removed
% text) or important. The next execution points are |\phf@cc@star|,
% |\phf@cc@important|, or |\phf@cc@grp|.
% \end{macro}
%
% \begin{macro}{\phf@cc@star}
% \begin{macro}{\phf@cc@important}
% If starred or if important, set up the inner group execution commands to the
% corresponding settings, and defer to |\phf@cc@grp|.
% \begin{macrocode}
\long\def\phf@cc@star{%
\@phfcc@isremovedtrue
\phf@cc@grp}
\long\def\phf@cc@important!{%
\@phfcc@isimportanttrue
\phf@cc@grp}
% \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\phf@cc@grp}
% The command |\phf@cc@grp| parses how the argument content is given. Is it a
% comment (``|[ ... ]|''), a single \LaTeX{} argument group (``|{ ... }|''),
% or should we expect it to end with |\endXXX|?
% \begin{macrocode}
\def\phf@cc@grp{%
\@ifnextchar[\phf@cc@comment\phf@cc@grpnocomment%]
}
\def\phf@cc@grpnocomment{%
\@ifnextchar\bgroup{\phf@cc@grpwarg}{\phf@cc@begin}}
% \end{macrocode}
% \end{macro}
%
% The main commenting command has already defined the |\endXXX| command as an
% alias of |\phf@cc@end|, so in the case of the syntax |\AlE ... \endAlE| we can
% call |\phf@cc@begin| directly.
%
% Now at this point we have determined how the argument is given, and we are
% calling one of |\phf@cc@comment|, |\phf@cc@grpwarg| (with argument), or
% |\phf@cc@begin| directly.
%
% \begin{macro}{\phf@cc@grpwarg}
% Format a simple comment specified as a normal \LaTeX{} block, i.e., provided
% as an argument to the commenting command. (Like |\AlE{text here}| or
% |\AlE!{important text}| or |\AlE*{some stuff to remove}|.)
% \begin{macrocode}
\long\def\phf@cc@grpwarg#1{%
\phf@cc@begin
\csname phf@cc@val@\phf@cc@val@cur @groupcmd\endcsname
{#1}%
\phf@cc@end
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\phf@cc@comment}
% If the argument is a comment, set up the comment font, begin/end chars, and
% go. Use |xparse| to get the argument in square brackets to ensure that the
% argument itself can contain matched square brackets.
% \begin{macrocode}
\NewDocumentCommand\phf@cc@comment{+O{}}{%
\@phfcc@iscommenttrue
\phf@cc@begin%
#1%
\phf@cc@end%
}
% \end{macrocode}
% \end{macro}
%
%
% \subsection{Process package options}
%
% Initialization code for \pkgname{kvoptions} for our package options.
% \begin{macrocode}
\SetupKeyvalOptions{
family=phfcc,
prefix=phfcc@opt@
}
\DeclareBoolOption[true]{usemarginnote}
% \end{macrocode}
%
% Process package options.
% \begin{macrocode}
\ProcessKeyvalOptions*
% \end{macrocode}
%
% Load the \pkgname{marginnote} package unless requested not to. This package
% is required for the |margin| initials style.
% \begin{macrocode}
\ifphfcc@opt@usemarginnote
\RequirePackage{marginnote}
\fi
% \end{macrocode}
%
%\Finale
\endinput