[macros] Separate sections a bit more cleanly, document macro length

The macro length hints help align comments on codeblocks even in the
presence of macro use, by providing the relevant offset between real
and effective column number.

Author: tkoeppe

source/macros.tex

@@ -1,8 +1,25 @@
 %!TEX root = std.tex
+
 % Definitions and redefinitions of special commands
+%
+% For macros that are likely to appear inside code blocks, we may provide a
+% "macro length" correction value, which can be used to determine the effective
+% column number where an emitted character appears, by adding the macro length,
+% plus 2 for the escape-'@'s, plus 2 for the braces, to the real column number.
+%
+% For example:
+%
+% \newcommand{\foo[1]{#1}  % macro length: 4
+%
+% \begin{codeblock}
+% int a = 10;         // comment on column 20
+% int b = @\foo{x}@;          // comment also on effective column 20
+%
+% Here the real column of the second comment start is offset by 8 (4 + macro length).
 
 %%--------------------------------------------------
 %% Difference markups
+%%--------------------------------------------------
 \definecolor{addclr}{rgb}{0,.6,.6}
 \definecolor{remclr}{rgb}{1,0,0}
 \definecolor{noteclr}{rgb}{0,0,1}
@@ -18,25 +35,13 @@
 \newcommand{\remitem}[1]{\item\removed{#1}}
 
 \newcommand{\ednote}[1]{\textcolor{noteclr}{[Editor's note: #1] }}
-% \newcommand{\ednote}[1]{}
 
-\newenvironment{addedblock}
-{
-\color{addclr}
-}
-{
-\color{black}
-}
-\newenvironment{removedblock}
-{
-\color{remclr}
-}
-{
-\color{black}
-}
+\newenvironment{addedblock}{\color{addclr}}{\color{black}}
+\newenvironment{removedblock}{\color{remclr}}{\color{black}}
 
 %%--------------------------------------------------
 %% Grammar extraction.
+%%--------------------------------------------------
 \def\gramSec[#1]#2{}
 
 \makeatletter
@@ -50,12 +55,14 @@
 
 %%--------------------------------------------------
 % Escaping for index entries. Replaces ! with "! throughout its argument.
+%%--------------------------------------------------
 \def\indexescape#1{\doindexescape#1\stopindexescape!\doneindexescape}
 \def\doindexescape#1!{#1"!\doindexescape}
 \def\stopindexescape#1\doneindexescape{}
 
 %%--------------------------------------------------
 %% Cross references.
+%%--------------------------------------------------
 \newcommand{\addxref}[1]{%
  \glossary[xrefindex]{\indexescape{#1}}{(\ref{\indexescape{#1}})}%
 }
@@ -66,6 +73,7 @@
 % number, a name, and a short tag.  The depth is an integer in
 % the range [0,5].  (If it proves necessary, it wouldn't take much
 % programming to raise the limit from 5 to something larger.)
+%%--------------------------------------------------
 
 % Set the xref label for a clause to be "Clause n", not just "n".
 \makeatletter
@@ -112,6 +120,7 @@
 
 %%--------------------------------------------------
 % Indexing
+%%--------------------------------------------------
 
 % Layout of general index
 \newcommand{\rSecindex}[2]{\section*{#2}\pdfbookmark[1]{#2}{pdf.idx.#1.#2}\label{idx.#1.#2}}
@@ -201,6 +210,7 @@
 
 %%--------------------------------------------------
 % General code style
+%%--------------------------------------------------
 \newcommand{\CodeStyle}{\ttfamily}
 \newcommand{\CodeStylex}[1]{\texttt{#1}}
 
@@ -214,14 +224,14 @@
 \newcommand{\term}[1]{\textit{#1}}
 \newcommand{\gterm}[1]{\GrammarStylex{#1}}
 \newcommand{\fakegrammarterm}[1]{\gterm{#1}}
-\newcommand{\keyword}[1]{\tcode{#1}\indextext{\idxcode{#1}}}
+\newcommand{\keyword}[1]{\tcode{#1}\indextext{\idxcode{#1}}}                % macro length: 8
 \newcommand{\grammarterm}[1]{\indexgram{\idxgram{#1}}\gterm{#1}}
 \newcommand{\grammartermnc}[1]{\indexgram{\idxgram{#1}}\gterm{#1\nocorr}}
 \newcommand{\regrammarterm}[1]{\textit{#1}}
-\newcommand{\placeholder}[1]{\textit{#1}}
-\newcommand{\placeholdernc}[1]{\textit{#1\nocorr}}
-\newcommand{\exposid}[1]{\tcode{\placeholder{#1}}}
-\newcommand{\exposidnc}[1]{\tcode{\placeholdernc{#1}}\itcorr[-1]}
+\newcommand{\placeholder}[1]{\textit{#1}}                                   % macro length: 12
+\newcommand{\placeholdernc}[1]{\textit{#1\nocorr}}                          % macro length: 14
+\newcommand{\exposid}[1]{\tcode{\placeholder{#1}}}                          % macro length: 8
+\newcommand{\exposidnc}[1]{\tcode{\placeholdernc{#1}}\itcorr[-1]}           % macro length: 10
 \newcommand{\defnxname}[1]{\indextext{\idxxname{#1}}\xname{#1}}
 \newcommand{\defnlibxname}[1]{\indexlibrary{\idxxname{#1}}\xname{#1}}
 
@@ -238,10 +248,12 @@
 
 %%--------------------------------------------------
 %% allow line break if needed for justification
+%%--------------------------------------------------
 \newcommand{\brk}{\discretionary{}{}{}}
 
 %%--------------------------------------------------
 %% Macros for funky text
+%%--------------------------------------------------
 \newcommand{\Cpp}{\texorpdfstring{C\kern-0.05em\protect\raisebox{.35ex}{\textsmaller[2]{+\kern-0.05em+}}}{C++}}
 \newcommand{\CppIII}{\Cpp{} 2003}
 \newcommand{\CppXI}{\Cpp{} 2011}
@@ -259,6 +271,7 @@
 
 %%--------------------------------------------------
 %% States and operators
+%%--------------------------------------------------
 \newcommand{\state}[2]{\tcode{#1}\ensuremath{_{#2}}}
 \newcommand{\bitand}{\ensuremath{\mathbin{\mathsf{bitand}}}}
 \newcommand{\bitor}{\ensuremath{\mathbin{\mathsf{bitor}}}}
@@ -462,10 +475,11 @@
 
 %%--------------------------------------------------
 %% Environments for code listings.
+%%--------------------------------------------------
 
-% We use the 'listings' package, with some small customizations.  The
-% most interesting customization: all TeX commands are available
-% within comments.  Comments are set in italics, keywords and strings
+% We use the 'listings' package, with some small customizations.
+% The most interesting customization: all TeX commands are available
+% within comments. Comments are set in italics, keywords and strings
 % don't get special treatment.
 
 \lstset{language=C++,
@@ -530,12 +544,14 @@
 
 %%--------------------------------------------------
 %% Indented text
+%%--------------------------------------------------
 \newenvironment{indented}[1][]
 {\begin{indenthelper}[#1]\item\relax}
 {\end{indenthelper}}
 
 %%--------------------------------------------------
 %% Library item descriptions
+%%--------------------------------------------------
 \lstnewenvironment{itemdecl}
 {
  \lstset{escapechar=@,
@@ -562,6 +578,7 @@
 
 %%--------------------------------------------------
 %% Bnf environments
+%%--------------------------------------------------
 \newlength{\BnfIndent}
 \setlength{\BnfIndent}{\leftmargini}
 \newlength{\BnfInc}
@@ -636,6 +653,7 @@
 
 %%--------------------------------------------------
 %% Environment for imported graphics
+%%--------------------------------------------------
 % usage: \begin{importgraphic}{CAPTION}{TAG}{FILE}
 
 \newenvironment{importgraphic}[3]
@@ -651,6 +669,7 @@
 
 %%--------------------------------------------------
 %% Definitions section for "Terms and definitions"
+%%--------------------------------------------------
 \newcommand{\nocontentsline}[3]{}
 \newcommand{\definition}[2]{%
 \addxref{#2}%