macros.tex

%!TEX root = std.tex
% Definitions and redefinitions of special commands

%%--------------------------------------------------
%% Difference markups
\definecolor{addclr}{rgb}{0,.6,.6}
\definecolor{newclr}{rgb}{.6,.6,0}
\definecolor{oldclr}{rgb}{.6,0,.6}
\definecolor{newnewclr}{rgb}{.6,.6,0}
\definecolor{oldoldclr}{rgb}{.6,0,.6}
\definecolor{remclr}{rgb}{1,0,0}
\definecolor{noteclr}{rgb}{0,0,1}

\renewcommand{\added}[1]{\textcolor{addclr}{\uline{#1}}}
\newcommand{\removed}[1]{\textcolor{remclr}{\sout{#1}}}
\renewcommand{\changed}[2]{\removed{#1}\added{#2}}

% Mark-up text that is unique to the Ranges TS
% (\oldtxt{X} gets deleted in next draft, \newtxt{X} becomes \added{X}.)
\newcommand{\oldtxt}[1]{\textcolor{oldclr}{\sout{#1}}}
\newcommand{\newtxt}[1]{\textcolor{newclr}{\uline{#1}}}

% Mark-up text that is in the C++14 standard
% (\newnewtxt{X} becomes \added{X}.)
\newcommand{\newnewtxt}[1]{\newtxt{#1}}
% (\oldoldtxt{X} becomes \removed{X}.)
\newcommand{\oldoldtxt}[1]{\oldtxt{#1}}

\newcommand{\nbc}[1]{[#1]\ }
\newcommand{\addednb}[2]{\added{\nbc{#1}#2}}
\newcommand{\removednb}[2]{\removed{\nbc{#1}#2}}
\newcommand{\changednb}[3]{\removednb{#1}{#2}\added{#3}}
\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}
}

%%--------------------------------------------------
%% Sectioning macros.
% Each section has a depth, an automatically generated section
% 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.)


% The basic sectioning command.  Example:
%    \Sec1[intro.scope]{Scope}
% defines a first-level section whose name is "Scope" and whose short
% tag is intro.scope.  The square brackets are mandatory.
\def\Sec#1[#2]#3{%
\ifcase#1\let\s=\chapter
      \or\let\s=\section
      \or\let\s=\subsection
      \or\let\s=\subsubsection
      \or\let\s=\paragraph
      \or\let\s=\subparagraph
      \fi%
\s[#3]{#3\hfill[#2]}\label{#2}}

% A convenience feature (mostly for the convenience of the Project
% Editor, to make it easy to move around large blocks of text):
% the \rSec macro is just like the \Sec macro, except that depths
% relative to a global variable, SectionDepthBase.  So, for example,
% if SectionDepthBase is 1,
%   \rSec1[temp.arg.type]{Template type arguments}
% is equivalent to
%   \Sec2[temp.arg.type]{Template type arguments}
\newcounter{SectionDepthBase}
\newcounter{scratch}

\def\rSec#1[#2]#3{%
\setcounter{scratch}{#1}
\addtocounter{scratch}{\value{SectionDepthBase}}
\Sec{\arabic{scratch}}[#2]{#3}}

\newcommand{\synopsis}[1]{\textbf{#1}}

%%--------------------------------------------------
% Indexing

% locations
\newcommand{\indextext}[1]{\index[generalindex]{#1}}
\newcommand{\indexlibrary}[1]{\index[libraryindex]{#1}}
\newcommand{\indexgram}[1]{\index[grammarindex]{#1}}
\newcommand{\indeximpldef}[1]{\index[impldefindex]{#1}}

\newcommand{\indexdefn}[1]{\indextext{#1}}
\newcommand{\indexgrammar}[1]{\indextext{#1}\indexgram{#1}}
\newcommand{\impldef}[1]{\indeximpldef{#1}implementation-defined}

% appearance
\newcommand{\idxcode}[1]{#1@\tcode{#1}}
\newcommand{\idxhdr}[1]{#1@\tcode{<#1>}}
\newcommand{\idxgram}[1]{#1@\textit{#1}}

%%--------------------------------------------------
% General code style
\newcommand{\CodeStyle}{\ttfamily}
\newcommand{\CodeStylex}[1]{\texttt{#1}}

% Code and definitions embedded in text.
\newcommand{\tcode}[1]{\CodeStylex{#1}}
\newcommand{\techterm}[1]{\textit{#1}\xspace}
\newcommand{\defnx}[2]{\indexdefn{#2}\textit{#1}\xspace}
\newcommand{\defn}[1]{\defnx{#1}{#1}}
\newcommand{\term}[1]{\textit{#1}\xspace}
\newcommand{\grammarterm}[1]{\textit{#1}\xspace}
\newcommand{\placeholder}[1]{\textit{#1}\xspace}

%%--------------------------------------------------
%% allow line break if needed for justification
\newcommand{\brk}{\discretionary{}{}{}}
%  especially for scope qualifier
\newcommand{\colcol}{\brk::\brk}

%%--------------------------------------------------
%% Macros for funky text
\newcommand{\Rplus}{\protect\hspace{-.1em}\protect\raisebox{.35ex}{\smaller{\smaller\textbf{+}}}}
% \newcommand{\Rplus}{+}
\newcommand{\Cpp}{\mbox{C\Rplus\Rplus}\xspace}
\newcommand{\CppIII}{\Cpp 2003\xspace}
\newcommand{\CppXI}{\Cpp 2011\xspace}
\newcommand{\opt}{{\ensuremath{_\mathit{opt}}}\xspace}
\newcommand{\shl}{<{<}}
\newcommand{\shr}{>{>}}
\newcommand{\dcr}{-{-}}
\newcommand{\exor}{\^{}}
\newcommand{\bigoh}[1]{\ensuremath{\mathcal{O}(#1)}}

% Make all tildes a little larger to avoid visual similarity with hyphens.
% FIXME: Remove \tilde in favour of \~.
\renewcommand{\tilde}{\textasciitilde}
\renewcommand{\~}{\textasciitilde}
\let\OldTextAsciiTilde\textasciitilde
\renewcommand{\textasciitilde}{\protect\raisebox{-0.17ex}{\larger\OldTextAsciiTilde}}

%%--------------------------------------------------
%% States and operators
\newcommand{\state}[2]{\tcode{#1}\ensuremath{_{#2}}}
\newcommand{\bitand}{\ensuremath{\, \mathsf{bitand} \,}}
\newcommand{\bitor}{\ensuremath{\, \mathsf{bitor} \,}}
\newcommand{\xor}{\ensuremath{\, \mathsf{xor} \,}}
\newcommand{\rightshift}{\ensuremath{\, \mathsf{rshift} \,}}
\newcommand{\leftshift}[1]{\ensuremath{\, \mathsf{lshift}_#1 \,}}

%% Notes and examples
\newcommand{\EnterBlock}[1]{[\,\textit{#1:}\xspace}
\newcommand{\ExitBlock}[1]{\textit{\,---\,end #1}\,]\xspace}
\newcommand{\enternote}{\EnterBlock{Note}}
\newcommand{\exitnote}{\ExitBlock{note}}
\newcommand{\enterexample}{\EnterBlock{Example}}
\newcommand{\exitexample}{\ExitBlock{example}}

%% Library function descriptions
\newcommand{\Fundescx}[1]{\textit{#1}\xspace}
\newcommand{\Fundesc}[1]{\Fundescx{#1:}}
\newcommand{\required}{\Fundesc{Required behavior}}
\newcommand{\requires}{\Fundesc{Requires}}
\newcommand{\effects}{\Fundesc{Effects}}
\newcommand{\postconditions}{\Fundesc{Postconditions}}
\newcommand{\postcondition}{\Fundesc{Postcondition}}
\newcommand{\preconditions}{\requires}
\newcommand{\precondition}{\requires}
\newcommand{\returns}{\Fundesc{Returns}}
\newcommand{\throws}{\Fundesc{Throws}}
\newcommand{\default}{\Fundesc{Default behavior}}
\newcommand{\complexity}{\Fundesc{Complexity}}
\newcommand{\remark}{\Fundesc{Remark}}
\newcommand{\remarks}{\Fundesc{Remarks}}
\newcommand{\note}{\remark}
\newcommand{\notes}{\remarks}
\newcommand{\realnote}{\Fundesc{Note}}
\newcommand{\realnotes}{\Fundesc{Notes}}
\newcommand{\errors}{\Fundesc{Error conditions}}
\newcommand{\sync}{\Fundesc{Synchronization}}
\newcommand{\implimits}{\Fundesc{Implementation limits}}
\newcommand{\replaceable}{\Fundesc{Replaceable}}
\newcommand{\exceptionsafety}{\Fundesc{Exception safety}}
\newcommand{\returntype}{\Fundesc{Return type}}
\newcommand{\cvalue}{\Fundesc{Value}}
\newcommand{\ctype}{\Fundesc{Type}}
\newcommand{\ctypes}{\Fundesc{Types}}
\newcommand{\dtype}{\Fundesc{Default type}}
\newcommand{\ctemplate}{\Fundesc{Class template}}
\newcommand{\templalias}{\Fundesc{Alias template}}

%% Cross reference
\newcommand{\xref}{\textsc{See also:}\xspace}
\newcommand{\xsee}{\textsc{See:}\xspace}

%% NTBS, etc.
\newcommand{\NTS}[1]{\textsc{#1}\xspace}
\newcommand{\ntbs}{\NTS{ntbs}}
\newcommand{\ntmbs}{\NTS{ntmbs}}
\newcommand{\ntwcs}{\NTS{ntwcs}}
\newcommand{\ntcxvis}{\NTS{ntc16s}}
\newcommand{\ntcxxxiis}{\NTS{ntc32s}}

%% Code annotations
\newcommand{\EXPO}[1]{\textit{#1}}
\newcommand{\expos}{\EXPO{exposition only}}
\newcommand{\impdef}{\EXPO{implementation-defined}}
\newcommand{\impdefx}[1]{\indeximpldef{#1}\EXPO{implementation-defined}}
\newcommand{\notdef}{\EXPO{not defined}}

\newcommand{\UNSP}[1]{\textit{\texttt{#1}}}
\newcommand{\unspec}{\UNSP{unspecified}\xspace}
\newcommand{\unspecbool}{\UNSP{unspecified-bool-type}}
\newcommand{\seebelow}{\UNSP{see below}}
\newcommand{\unspecuniqtype}{\UNSP{unspecified unique type}}
\newcommand{\unspecalloctype}{\UNSP{unspecified allocator type}}

%% Double underscore
\newcommand{\ungap}{\kern.5pt}
\newcommand{\unun}{\_\ungap\_}
\newcommand{\xname}[1]{\unun\ungap#1}
\newcommand{\mname}[1]{\tcode{\unun\ungap#1\ungap\unun}}

%% Ranges
\newcommand{\Range}[4]{\tcode{#1\brk{}#3,\brk{}#4\brk{}#2}\xspace}
\newcommand{\crange}[2]{\Range{[}{]}{#1}{#2}}
\newcommand{\brange}[2]{\Range{(}{]}{#1}{#2}}
\newcommand{\orange}[2]{\Range{(}{)}{#1}{#2}}
\newcommand{\range}[2]{\Range{[}{)}{#1}{#2}}

%% Change descriptions
\newcommand{\diffdef}[1]{\hfill\break\textbf{#1:}\xspace}
\newcommand{\change}{\diffdef{Change}}
\newcommand{\rationale}{\diffdef{Rationale}}
\newcommand{\effect}{\diffdef{Effect on original feature}}
\newcommand{\difficulty}{\diffdef{Difficulty of converting}}
\newcommand{\howwide}{\diffdef{How widely used}}

%% Miscellaneous
\newcommand{\uniquens}{\textrm{\textit{\textbf{unique}}} }
\newcommand{\stage}[1]{\item{\textbf{Stage #1:}}\xspace}
\newcommand{\doccite}[1]{\textit{#1}\xspace}
\newcommand{\cvqual}[1]{\textit{#1}}
\newcommand{\cv}{\cvqual{cv}}
\renewcommand{\emph}[1]{\textit{#1}\xspace}
\newcommand{\numconst}[1]{\textsl{#1}\xspace}
\newcommand{\logop}[1]{{\footnotesize #1}\xspace}

%%--------------------------------------------------
%% 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
% don't get special treatment.

\lstset{language=C++,
        basicstyle=\small\CodeStyle,
        keywordstyle=,
        stringstyle=,
        xleftmargin=1em,
        showstringspaces=false,
        commentstyle=\itshape\rmfamily,
        columns=flexible,
        keepspaces=true,
        texcl=true}

% Our usual abbreviation for 'listings'.  Comments are in
% italics.  Arbitrary TeX commands can be used if they're
% surrounded by @ signs.
\newcommand{\CodeBlockSetup}{
 \lstset{escapechar=@}
 \renewcommand{\tcode}[1]{\textup{\CodeStylex{##1}}}
 \renewcommand{\techterm}[1]{\textit{\CodeStylex{##1}}}
 \renewcommand{\term}[1]{\textit{##1}}
 \renewcommand{\grammarterm}[1]{\textit{##1}}
}
\lstnewenvironment{codeblock}{\CodeBlockSetup}{}

% A code block in which single-quotes are digit separators
% rather than character literals.
\lstnewenvironment{codeblockdigitsep}{
 \CodeBlockSetup
 \lstset{deletestring=[b]{'}}
}{}

% Permit use of '@' inside codeblock blocks (don't ask)
\makeatletter
\newcommand{\atsign}{@}
\makeatother

%%--------------------------------------------------
%% Indented text
\newenvironment{indented}
{\list{}{}\item\relax}
{\endlist}

%%--------------------------------------------------
%% Library item descriptions
\lstnewenvironment{itemdecl}
{
 \lstset{escapechar=@,
 xleftmargin=0em,
 aboveskip=2ex,
 belowskip=0ex	% leave this alone: it keeps these things out of the
				% footnote area
 }
}
{
}

\newenvironment{itemdescr}
{
 \begin{indented}}
{
 \end{indented}
}


%%--------------------------------------------------
%% Bnf environments
\newlength{\BnfIndent}
\setlength{\BnfIndent}{\leftmargini}
\newlength{\BnfInc}
\setlength{\BnfInc}{\BnfIndent}
\newlength{\BnfRest}
\setlength{\BnfRest}{2\BnfIndent}
\newcommand{\BnfNontermshape}{\small\rmfamily\itshape}
\newcommand{\BnfTermshape}{\small\ttfamily\upshape}
\newcommand{\nonterminal}[1]{{\BnfNontermshape #1}}

\newenvironment{bnfbase}
 {
 \newcommand{\nontermdef}[1]{\nonterminal{##1}\indexgrammar{\idxgram{##1}}:}
 \newcommand{\terminal}[1]{{\BnfTermshape ##1}\xspace}
 \newcommand{\descr}[1]{\normalfont{##1}}
 \newcommand{\bnfindentfirst}{\BnfIndent}
 \newcommand{\bnfindentinc}{\BnfInc}
 \newcommand{\bnfindentrest}{\BnfRest}
 \begin{minipage}{.9\hsize}
 \newcommand{\br}{\hfill\\}
 \frenchspacing
 }
 {
 \nonfrenchspacing
 \end{minipage}
 }

\newenvironment{BnfTabBase}[1]
{
 \begin{bnfbase}
 #1
 \begin{indented}
 \begin{tabbing}
 \hspace*{\bnfindentfirst}\=\hspace{\bnfindentinc}\=\hspace{.6in}\=\hspace{.6in}\=\hspace{.6in}\=\hspace{.6in}\=\hspace{.6in}\=\hspace{.6in}\=\hspace{.6in}\=\hspace{.6in}\=\hspace{.6in}\=\hspace{.6in}\=\kill}
{
 \end{tabbing}
 \end{indented}
 \end{bnfbase}
}

\newenvironment{bnfkeywordtab}
{
 \begin{BnfTabBase}{\BnfTermshape}
}
{
 \end{BnfTabBase}
}

\newenvironment{bnftab}
{
 \begin{BnfTabBase}{\BnfNontermshape}
}
{
 \end{BnfTabBase}
}

\newenvironment{simplebnf}
{
 \begin{bnfbase}
 \BnfNontermshape
 \begin{indented}
}
{
 \end{indented}
 \end{bnfbase}
}

\newenvironment{bnf}
{
 \begin{bnfbase}
 \list{}
	{
	\setlength{\leftmargin}{\bnfindentrest}
	\setlength{\listparindent}{-\bnfindentinc}
	\setlength{\itemindent}{\listparindent}
	}
 \BnfNontermshape
 \item\relax
}
{
 \endlist
 \end{bnfbase}
}

% non-copied versions of bnf environments
\newenvironment{ncbnftab}
{
 \begin{bnftab}
}
{
 \end{bnftab}
}

\newenvironment{ncsimplebnf}
{
 \begin{simplebnf}
}
{
 \end{simplebnf}
}

\newenvironment{ncbnf}
{
 \begin{bnf}
}
{
 \end{bnf}
}

%%--------------------------------------------------
%% Drawing environment
%
% usage: \begin{drawing}{UNITLENGTH}{WIDTH}{HEIGHT}{CAPTION}
\newenvironment{drawing}[4]
{
\newcommand{\mycaption}{#4}
\begin{figure}[h]
\setlength{\unitlength}{#1}
\begin{center}
\begin{picture}(#2,#3)\thicklines
}
{
\end{picture}
\end{center}
\caption{\mycaption}
\end{figure}
}

%%--------------------------------------------------
%% Environment for imported graphics
% usage: \begin{importgraphic}{CAPTION}{TAG}{FILE}

\newenvironment{importgraphic}[3]
{%
\newcommand{\cptn}{#1}
\newcommand{\lbl}{#2}
\begin{figure}[htp]\centering%
\includegraphics[scale=.35]{#3}
}
{
\caption{\cptn}\label{\lbl}%
\end{figure}}

%% enumeration display overrides
% enumerate with lowercase letters
\newenvironment{enumeratea}
{
 \renewcommand{\labelenumi}{\alph{enumi})}
 \begin{enumerate}
}
{
 \end{enumerate}
}

% enumerate with arabic numbers
\newenvironment{enumeraten}
{
 \renewcommand{\labelenumi}{\arabic{enumi})}
 \begin{enumerate}
}
{
 \end{enumerate}
}

%%--------------------------------------------------
%% Cross references.
\newcommand{\addxref}[1]{\glossary[xrefindex]{#1}{(\ref{#1})}}

%%--------------------------------------------------
%% Definitions section for "Terms and definitions"
\newcommand{\nocontentsline}[3]{}
\newcommand{\definitionx}[3]{%
\addxref{#3}%
\let\oldcontentsline\addcontentsline%
\let\addcontentsline\nocontentsline%
#1[#2]{\hfill[#3]}\vspace{-.3\onelineskip}\label{#3} \textbf{#2}\\*%
\let\addcontentsline\oldcontentsline%
}
\newcommand{\defncontext}[1]{\textlangle#1\textrangle}