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

%%--------------------------------------------------
%% Difference markups
\definecolor{addclr}{rgb}{0,.6,.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}}

\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{\mathscr{O}(#1)}}
% \renewcommand{\tilde}{{\smaller\ensuremath{\sim}}}    % extra level of braces is necessary
\renewcommand{\tilde}{\protect\raisebox{-.5ex}{\larger\textasciitilde}}

%%--------------------------------------------------
%% 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{\unun}{\_\,\_}
\newcommand{\xname}[1]{\unun\,#1}
\newcommand{\mname}[1]{\tcode{\unun\,#1\,\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.
\lstnewenvironment{codeblock}
{
 \lstset{escapechar=@}
 \renewcommand{\tcode}[1]{\textup{\CodeStylex{##1}}}
 \renewcommand{\techterm}[1]{\textit{\CodeStylex{##1}}}
 \renewcommand{\term}[1]{\textit{##1}}
 \renewcommand{\grammarterm}[1]{\textit{##1}}
}
{
}

% 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]{\indexgrammar{\idxgram{##1}}\nonterminal{##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\\}
 }
 {
 \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}
}

%%--------------------------------------------------
%% Definitions section
% usage: \definition{name}{xref}
%\newcommand{\definition}[2]{\rSec2[#2]{#1}}
% for ISO format, use:
\newcommand{\definition}[2]
 {\hfill\vspace{.25ex plus .5ex minus .2ex}\\
 \addtocounter{subsection}{1}%
 \textbf{\thesubsection\hfill\relax[#2]}\\
 \textbf{#1}\label{#2}\\
 }
