pmix.sty

% This is pmix.sty, the preamble and style definitions for the PMIx specification.
%
% This specification file, and latex structure was derived from/inspired by the OpenMP specification. So some similarity between the two latex files is expected.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Quick list of the environments, commands and macros supported.
% Search below for more details.
%
% Formatting Text:
%   -----------------------
%   \notestart            - "Note:" Callout section
%   \noteheader           - \noteheader is optional "Note:" prefix for text
%     ...
%   \noteend
%   -----------------------
%   \rationalestart       - "Rationale" Callout section
%     ...
%   \rationaleend
%   -----------------------
%   \adviceuserstart      - "Advice to users" Callout section
%     ...
%   \adviceuserend
%   -----------------------
%   \adviceimplstart      - "Advice to PMIx library implementers" Callout section
%     ...
%   \adviceimplend
%   -----------------------
%   \advicermstart      - "Advice to PMIx server hosts" Callout section
%     ...
%   \advicermend
%   -----------------------
%
% Formatting Code:
%   \code{}               - Code text
%   \var{}                - Variable
%   -----------------------
%   \begin{codepar}       - Section of generic code
%     ...                 - use language specific macro if language specific code
%   \end[codepar}
%   -----------------------
%   \cspecificstart       - C specific code block
%     ...
%   \cspecificend
%   -----------------------
%
% Attributes:
%   \refAttributeItem{}   - Cross reference
%   \refattr{}            - Same as above
%   \pasteAttributeItem{} - Paste full description
%
% Structures:
%   \refstruct{}          - Reference a structure
%   \structref{}          - Same as above
%   \specrefstruct{}      - Reference a structure by section number and page
%
% APIs:
%   \refapi{}             - Reference an API function
%   \refconst{}           - Constant reference
%   \refarg{} / \argref{} - Reference an argument to an API function
%
% Cross referencing:
%   \chapterref{}         - Reference a Chapter by number and page
%   \specref{}            - Reference a Section by number and page
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{comment}            % allow use of \begin{comment}
\usepackage{ifpdf,ifthen}       % allow conditional tests in LaTeX definitions
\usepackage{makecell}           % Allows common formatting in cells with \thread & \makecell

\usepackage[T1]{fontenc}        % Allow us to use underscore freely in the document
\catcode`\_=12                  % Use \sb for subscripts
\usepackage{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Document data
%
\author{}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Fonts

\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{courier}
\usepackage{helvet}
\usepackage[utf8]{inputenc}
\usepackage{textgreek}

% Main body serif font:
\usepackage{tgtermes}
\usepackage[T1]{fontenc}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Graphic elements

\usepackage{graphicx}
\usepackage{framed}    % for making boxes with \begin{framed}
\usepackage{tikz}      % for flow charts, diagrams, arrows


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Page formatting

\usepackage[paperwidth=7.5in, paperheight=9in,
            top=0.75in, bottom=1.0in, left=1.4in, right=0.6in]{geometry}

\usepackage{changepage}   % allows left/right-page margin readjustments

\setlength{\oddsidemargin}{0.185in}
\setlength{\evensidemargin}{0.185in}
\raggedbottom


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Paragraph formatting

\usepackage{setspace}     % allows use of \singlespacing, \onehalfspacing
\usepackage{needspace}    % allows use of \needspace to keep lines together
\usepackage{parskip}      % removes paragraph indenting

\raggedright
\usepackage[raggedrightboxes]{ragged2e}  % is this needed?

\lefthyphenmin=60         % only hyphenate if the left part is >= this many chars
\righthyphenmin=60        % only hyphenate if the right part is >= this many chars


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Bulleted (itemized) lists
%    Align bullets with section header
%    Align text left
%    Small bullets
%    \compactitem for single-spaced lists (used in the Examples doc)

\usepackage{enumitem}     % for setting margins on lists
\setlist{leftmargin=*}    % don't indent bullet items
\renewcommand{\labelitemi}{{\normalsize$\bullet$}} % bullet size

% There is a \compactitem defined in package parlist (and perhaps others), however,
% we'll define our own version of compactitem in terms of package enumitem that
% we already use:
\newenvironment{compactitem}
{\begin{itemize}[itemsep=-1.2ex]}
{\end{itemize}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Floating version
%\usepackage[showboxes]{textpos}
\usepackage{textpos}

\setlength{\TPHorizModule}{1pt}%
\setlength{\TPVertModule}{\TPHorizModule}%
\TPMargin{1pt}%

\newcommand{\versionMarker}[1]{%
 % y is 8 = \parskip
 \begin{textblock}{50}(-55,8)%
   \textit{PMIx v#1}%
   \raggedright
 \end{textblock}%
}
% Alternative is to make a box inline, but that gets tricky when positioning close
% to codepar's
% \makebox[-7pt][r]{\textit{PMIx #4}\raggedright}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Enumerated list with lowercase alphabet lettering
%    \alphaenum for default-spaced lists
%    \compactalphaenum for single-spaced lists

% There is a \compactitem defined in package parlist (and perhaps others), however,
% we'll define our own version of compactitem in terms of package enumitem that
% we already use:
\newenvironment{alphaenum}
{\begin{enumerate}[label=\alph*)]}
{\end{enumerate}}

\newenvironment{compactalphaenum}
{\begin{enumerate}[label=\alph*),itemsep=-1.2ex]}
{\end{enumerate}}

% Argument list for an interface, for use in a \begin{arglist} section
% \argin      Input argument
% \argout     Output argument
% \arginout   Input/Output argument
% \argreturn  Value returned
%%% Old Method using tables.... line numbers didn't work if a cell wrapped...
%\newlength\argdesclen
%\setlength\argdesclen{\dimexpr \linewidth -13em -4\tabcolsep}
%\newenvironment{arglist}{%
%    \begin{edtable}{tabular}{p{3em}p{10em}p{\argdesclen}}}
%    {\end{edtable}\vspace{.25em}}
%
%\newcommand{\argin}[2]{\textbf{IN} & \code{#1} & #2\\}
%\newcommand{\argout}[2]{\textbf{OUT} & \code{#1} & #2\\}
%\newcommand{\arginout}[2]{\textbf{INOUT} & \code{#1} & #2\\}

\newenvironment{arglist}
{\begin{description}[style=nextline,labelindent=\parindent,leftmargin=*,itemindent=\dimexpr-17pt-\labelsep\relax,itemsep=-1.3ex]}
{\end{description}}

\newcommand{\argin}[2]{\item[IN ~~~~\code{#1}] #2}
\newcommand{\argout}[2]{\item[OUT ~~~\code{#1}] #2}
\newcommand{\arginout}[2]{\item[INOUT ~\code{#1}] #2}

% Constant list
%   \declareconstitem  Declare constant with description
\newenvironment{constantdesc}
{\begin{description}[itemsep=-1.3ex,itemindent=\dimexpr-17pt-\labelsep\relax]}
{\end{description}}

\newcommand{\declareconstitem}[1]{\item[\code{#1}] \index{#1} \label{const:#1} \hspace{1em}}
\newcommand{\declareconstitemvalue}[2]{\item[\code{#1}] \index{#1} \hspace{0.25em} \code{#2}  \hspace{1em}}
\newcommand{\declareconstitemDEP}[2]{\item[\code{#1} (Deprecated in PMIx #2)] \index{#1} \label{const:#1} \hspace{1em}}
\newcommand{\declareconstitemNEW}[1]{\item[\color{magenta}\code{#1}] \index{#1} \label{const:#1} \hspace{1em}}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Tables

% This allows tables to flow across page breaks, headers on each new page, etc.
\usepackage{supertabular}
\usepackage{caption}
\usepackage{longtable}
\usepackage{pdflscape} % for 'landscape' environment

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Line numbering

\usepackage[pagewise,edtable]{lineno}       % for line numbers on left side of the page
\pagewiselinenumbers
\setlength\linenumbersep{6em}
\renewcommand\linenumberfont{\normalfont\small\sffamily}
\nolinenumbers            % start with line numbers off


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Footers

\usepackage{fancyhdr}     % makes right/left footers
\pagestyle{fancy}
\fancyhead{} % clear all header fields
\cfoot{}
\renewcommand{\headrulewidth}{0pt}

% Left side on even pages:
% This requires that \footerText be defined in the master document:
\fancyfoot[LE]{\bfseries \thepage \mdseries \hspace{2em} \footerText}
\fancyhfoffset[E]{4em}

% Right side on odd pages:
\fancyfoot[RO]{\mdseries  \leftmark \hspace{2em} \bfseries \thepage}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Section header format - we use five levels: \chapter \section \subsection \subsubsection

\usepackage{titlesec}     % format headers with \titleformat{}

% Format and spacing for chapter, section, subsection, and subsubsection headers:

\setcounter{secnumdepth}{5}          % show numbers down to subsubsection level

\titleformat{\chapter}[display]%
{\normalfont\sffamily\upshape\Huge\bfseries\nolinenumbers\fontsize{20}{20}\selectfont}%
{\normalfont\sffamily\scshape\large\bfseries\nolinenumbers \hspace{-0.7in} \MakeUppercase%
    {\chaptertitlename} \thechapter}%
{0em}{}[\vspace{1.0em}\hrule]
% {<left>}{<before-sep>}{<after-sep>}
\titlespacing{\chapter}{0ex}{0em plus 1em minus 1em}{1em plus 1em minus 1em}[10em]

\titleformat{\section}[hang]{\huge\bfseries\sffamily\fontsize{16}{16}\selectfont}{\thesection}{1.0em}{}
% {<left>}{<before-sep>}{<after-sep>}
\titlespacing{\section}{-5em}{2em plus 1em minus 1em}{1em plus 0.5em minus 0em}[10em]

\titleformat{\subsection}[hang]{\LARGE\bfseries\sffamily\fontsize{14}{14}\selectfont}{\thesubsection}{1.0em}{}
\titlespacing{\subsection}{-5em}{2em plus 1em minus 2.0em}{0.75em plus 0.5em minus 0em}[10em]

\titleformat{\subsubsection}[hang]{\needspace{1\baselineskip}%
\Large\bfseries\sffamily\fontsize{12}{12}\selectfont}{\thesubsubsection}{1.0em}{}
\titlespacing{\subsubsection}{-5em}{0.5em plus 1em minus 1em}{0.5em plus 0.5em minus 0em}[10em]


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Macros for minor headers: Summary, Syntax, Description, etc.
% These headers are defined in terms of \paragraph

\titleformat{\paragraph}[block]{\large\bfseries\sffamily\fontsize{11}{11}\selectfont}{}{}{}
\titlespacing{\paragraph}{0em}{1.0em plus 0.55em minus 0.5em}{0.0em plus 0.55em minus 0.0em}

% Use one of the convenience macros below, or \littleheader{} for an arbitrary header
\newcommand{\littleheader}[1] {\paragraph*{#1}}

\newcommand{\comments} {\littleheader{Comments}}
\newcommand{\descr} {\littleheader{Description}}
\newcommand{\format} {\littleheader{Format}}
\newcommand{\summary} {\littleheader{Summary}}
\newcommand{\history} {\littleheader{History}}
\newcommand{\priattr} {\littleheader{PRI Attributes}}
\newcommand{\reqattr} {\littleheader{\ac{RM} Required Attributes}}
\newcommand{\optattr} {\littleheader{\ac{RM} Optional Attributes}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Clipboard
%
% \StdCopy{TAG}{BODY}
% \StdPaste{TAG}
%
% Inspired by this thread:
%   https://tex.stackexchange.com/questions/150790/how-to-make-text-be-copied-to-another-part-of-a-document
\makeatletter
\newcommand\StdCopy              [2] {
  \immediate\write\@auxout{\unexpanded{\global\long\@namedef{clipbrd@#1}{#2}}}
}
\newcommand\StdCopyEcho          [2] {
  \StdCopy{#1}{#2}%
  #2
}
\newcommand\StdPaste             [1] {%
  \ifcsname clipbrd@#1\endcsname
    \@nameuse{clipbrd@#1}%
  \else
    ??unknown??
  \fi
}
\makeatother


% Attributes
%   \declareAttribute       Declare an attribute with a description
%   \pasteAttributeItem     Paste the attribute description here
%   \refAttributeItem       Reference the original definition of the attribute
%
\newcommand{\declareAttribute}[4]{%
    \code{#1} ~~\code{#2}~~(\code{#3})%
    \index{#1!Definition|textbf} \label{attr:#1}%
    \StdCopy{str:#1}{\code{#2}}%
    \StdCopy{attr:#1}{\code{#3}}%
    \vspace{-1.3ex}%
      \expandafter\begin{adjustwidth}{.95cm}{}%
      \StdCopyEcho{#1}{#4}%
    \end{adjustwidth}%
  \vspace{-1.3ex}%
}

\newcommand{\declareNewAttribute}[4]{%
   {\color{magenta}\code{#1}} ~~\code{#2}~~(\code{#3})%
    \index{#1!Definition|textbf} \label{attr:#1}%
    \StdCopy{str:#1}{\code{#2}}%
    \StdCopy{attr:#1}{\code{#3}}%
    \vspace{-1.3ex}%
      \expandafter\begin{adjustwidth}{.95cm}{}%
      \StdCopyEcho{#1}{#4}%
    \end{adjustwidth}%
  \vspace{-1.3ex}%
}

\newcommand{\declareDepAttribute}[4]{%
   {\color{green!80!black}\code{#1}} ~~\code{#2}~~(\code{#3})%
    \index{#1!Definition|textbf} \label{attr:#1}%
    \StdCopy{str:#1}{\code{#2}}%
    \StdCopy{attr:#1}{\code{#3}}%
    \vspace{-1.3ex}%
      \expandafter\begin{adjustwidth}{.95cm}{}%
      \StdCopyEcho{#1}{#4}%
    \end{adjustwidth}%
  \vspace{-1.3ex}%
}

\newcommand{\pasteAttributeItemBegin}[1]{
  \refAttributeItem{#1} ~~\StdPaste{str:#1}~~(\StdPaste{attr:#1})
  \vspace{-1.3ex}
   \expandafter
   \begin{adjustwidth}{.95cm}{}
    \StdPaste{#1}
}
\newcommand{\pasteAttributeItemEnd}{
   \end{adjustwidth}
}
\newcommand{\pasteAttributeItem}[1]{
	\pasteAttributeItemBegin{#1}
	\pasteAttributeItemEnd{}
}
\newcommand{\refAttributeItem}[1]{\index{#1} \hyperref[attr:#1]{\code{#1}} }
\newcommand{\refattr}[1]{\refAttributeItem{#1}}

\newcommand{\refPRIAttributeItem}[1]{\index{#1} \hyperref[attr:#1]{\color{red}\code{#1}} }

\newcommand{\pastePRIAttributeItemBegin}[1]{
  \refPRIAttributeItem{#1} ~~\StdPaste{str:#1}~~(\StdPaste{attr:#1})
  \vspace{-1.3ex}
   \expandafter
   \begin{adjustwidth}{.95cm}{}
    \StdPaste{#1}
}
\newcommand{\pastePRIAttributeItemEnd}{
   \end{adjustwidth}
}

\newcommand{\pastePRIAttributeItem}[1]{
    \pastePRIAttributeItemBegin{#1}
    \pastePRIAttributeItemEnd{}
}

\newcommand{\refPRRTEAttributeItem}[1]{\index{#1} \hyperref[attr:#1]{\color{green!60!black}\code{#1}} }

\newcommand{\pastePRRTEAttributeItemBegin}[1]{
  \refPRRTEAttributeItem{#1} ~~\StdPaste{str:#1}~~(\StdPaste{attr:#1})
  \vspace{-1.3ex}
   \expandafter
   \begin{adjustwidth}{.95cm}{}
    \StdPaste{#1}
}
\newcommand{\pastePRRTEAttributeItemEnd}{
   \end{adjustwidth}
}

\newcommand{\pastePRRTEAttributeItem}[1]{
    \pastePRRTEAttributeItemBegin{#1}
    \pastePRRTEAttributeItemEnd{}
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Code and placeholder semantic tagging.
%
% When possible, prefer semantic tags instead of typographic tags. The
% following semantics tags are defined here:
%
%     \code{}     % for bold monospace keywords, code, operators, etc.
%     \plc{}      % for italic placeholder names, grammar, etc.
%
% For function prototypes or other code snippets, you can use \code{} as
% the outer wrapper, and use \plc{{} inside. Example:
%
%     \code{\#pragma omp directive ( \plc{some-placeholder-identifier} :}
%
% To format text in italics for emphasis (rather than text as a placeholder),
% use the generic \emph{} command. Example:
%
%     This sentence \emph{emphasizes some non-placeholder words}.

% Enable \alltt{} for formatting blocks of code:
\usepackage{alltt}

% This sets the default \code{} font to tt (monospace) and bold:
\newcommand{\code}[1]{{\texttt{\textbf{#1}}}}
\newcommand{\var}[1] {{\textrm{\textmd{\itshape{#1}}}}}


% Environment for a paragraph of literal code, single-spaced, no outline, no indenting:
\newenvironment{codepar}[1]
{\begin{alltt}\bfseries #1}
{\end{alltt}}

\usepackage{setspace}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Macros for the black and blue lines and arrows delineating language-specific
% and notes sections. Example:
%
%   \fortranspecificstart
%   This is text that applies to Fortran.
%   \fortranspecificend

% local parameters for use \linewitharrows and \notelinewitharrows:
\newlength{\sbsz}\setlength{\sbsz}{0.05in}  % size of arrows
\newlength{\sblw}\setlength{\sblw}{1.35pt}  % line width (thickness)
\newlength{\sbtw}                           % text width
\newlength{\sblen}                          % total width of horizontal rule
\newlength{\sbht}                           % height of arrows
\newlength{\sbhadj}                         % vertical adjustment for aligning arrows with the line
\newlength{\sbns}\setlength{\sbns}{7\baselineskip}       % arg for \needspace for downward arrows

% \notelinewitharrows is a helper command that makes a black Note marker:
%     arg 1 = 1 or -1 for up or down arrows
%     arg 2 = solid or dashed or loosely dashed, etc.
\newcommand{\notelinewitharrows}[2]{%
    \needspace{0.1\baselineskip}%
    \vbox{\begin{tikzpicture}%
        \setlength{\sblen}{\linewidth}%
        \setlength{\sbht}{#1\sbsz}\setlength{\sbht}{1.4\sbht}%
        \setlength{\sbhadj}{#1\sblw}\setlength{\sbhadj}{0.25\sbhadj}%
        \filldraw (\sblen, 0) -- (\sblen - \sbsz, \sbht) -- (\sblen - 2\sbsz, 0) -- (\sblen, 0);
        \draw[line width=\sblw, #2] (2\sbsz - \sblw, \sbhadj) -- (\sblen - 2\sbsz + \sblw, \sbhadj);
        \filldraw (0, 0) -- (\sbsz, \sbht) -- (0 + 2\sbsz, 0) -- (0, 0);
    \end{tikzpicture}}}

% \adviceuserline is a helper command that makes a red horizontal line, up or down arrows, and some text:
% arg 1 = 1 or -1 for up or down arrows
% arg 2 = solid or dashed or loosely dashed, etc.
% arg 3 = text
% arg 4 = text width
\newcommand{\adviceuserline}[4]{%
    \needspace{0.1\baselineskip}%
    \vbox to 1\baselineskip {\begin{tikzpicture}%
        \setlength{\sbtw}{#4}%
        \setlength{\sblen}{\linewidth}%
        \setlength{\sbht}{#1\sbsz}\setlength{\sbht}{1.4\sbht}%
        \setlength{\sbhadj}{#1\sblw}\setlength{\sbhadj}{0.25\sbhadj}%
        \filldraw[color=red!80!black] (\sblen, 0) -- (\sblen - \sbsz, \sbht) -- (\sblen - 2\sbsz, 0) -- (\sblen, 0);
        \draw[line width=\sblw, color=red!80!black, #2] (2\sbsz - \sblw, \sbhadj) -- (0.5\sblen - 0.5\sbtw, \sbhadj);
        \draw[line width=\sblw, color=red!80!black, #2] (0.5\sblen + 0.5\sbtw, \sbhadj) -- (\sblen - 2\sbsz + \sblw, \sbhadj);
        \filldraw[color=red!80!black] (0, 0) -- (\sbsz, \sbht) -- (0 + 2\sbsz, 0) -- (0, 0);
        \node[color=red!80!black] at (0.5\sblen, 0) {\large  \textsf{\textup{#3}}};
    \end{tikzpicture}}}

% \adviceimpline is a helper command that makes a green horizontal line, up or down arrows, and some text:
% arg 1 = 1 or -1 for up or down arrows
% arg 2 = solid or dashed or loosely dashed, etc.
% arg 3 = text
% arg 4 = text width
\newcommand{\adviceimpline}[4]{%
    \needspace{0.1\baselineskip}%
    \vbox to 1\baselineskip {\begin{tikzpicture}%
        \setlength{\sbtw}{#4}%
        \setlength{\sblen}{\linewidth}%
        \setlength{\sbht}{#1\sbsz}\setlength{\sbht}{1.4\sbht}%
        \setlength{\sbhadj}{#1\sblw}\setlength{\sbhadj}{0.25\sbhadj}%
        \filldraw[color=green!60!black] (\sblen, 0) -- (\sblen - \sbsz, \sbht) -- (\sblen - 2\sbsz, 0) -- (\sblen, 0);
        \draw[line width=\sblw, color=green!60!black, #2] (2\sbsz - \sblw, \sbhadj) -- (0.5\sblen - 0.5\sbtw, \sbhadj);
        \draw[line width=\sblw, color=green!60!black, #2] (0.5\sblen + 0.5\sbtw, \sbhadj) -- (\sblen - 2\sbsz + \sblw, \sbhadj);
        \filldraw[color=green!60!black] (0, 0) -- (\sbsz, \sbht) -- (0 + 2\sbsz, 0) -- (0, 0);
        \node[color=green!60!black] at (0.5\sblen, 0) {\large  \textsf{\textup{#3}}};
    \end{tikzpicture}}}

% \advicermline is a helper command that makes an orange horizontal line, up or down arrows, and some text:
% arg 1 = 1 or -1 for up or down arrows
% arg 2 = solid or dashed or loosely dashed, etc.
% arg 3 = text
% arg 4 = text width
\newcommand{\advicermline}[4]{%
    \needspace{0.1\baselineskip}%
    \vbox to 1\baselineskip {\begin{tikzpicture}%
        \setlength{\sbtw}{#4}%
        \setlength{\sblen}{\linewidth}%
        \setlength{\sbht}{#1\sbsz}\setlength{\sbht}{1.4\sbht}%
        \setlength{\sbhadj}{#1\sblw}\setlength{\sbhadj}{0.25\sbhadj}%
        \filldraw[color=orange!60!black] (\sblen, 0) -- (\sblen - \sbsz, \sbht) -- (\sblen - 2\sbsz, 0) -- (\sblen, 0);
        \draw[line width=\sblw, color=orange!60!black, #2] (2\sbsz - \sblw, \sbhadj) -- (0.5\sblen - 0.5\sbtw, \sbhadj);
        \draw[line width=\sblw, color=orange!60!black, #2] (0.5\sblen + 0.5\sbtw, \sbhadj) -- (\sblen - 2\sbsz + \sblw, \sbhadj);
        \filldraw[color=orange!60!black] (0, 0) -- (\sbsz, \sbht) -- (0 + 2\sbsz, 0) -- (0, 0);
        \node[color=orange!60!black] at (0.5\sblen, 0) {\large  \textsf{\textup{#3}}};
    \end{tikzpicture}}}

% \ratline is a helper command that makes a purple horizontal line, up or down arrows, and some text:
% arg 1 = 1 or -1 for up or down arrows
% arg 2 = solid or dashed or loosely dashed, etc.
% arg 3 = text
% arg 4 = text width
\newcommand{\ratline}[4]{%
    \needspace{0.1\baselineskip}%
    \vbox to 1\baselineskip {\begin{tikzpicture}%
        \setlength{\sbtw}{#4}%
        \setlength{\sblen}{\linewidth}%
        \setlength{\sbht}{#1\sbsz}\setlength{\sbht}{1.4\sbht}%
        \setlength{\sbhadj}{#1\sblw}\setlength{\sbhadj}{0.25\sbhadj}%
        \filldraw[color=purple!40] (\sblen, 0) -- (\sblen - \sbsz, \sbht) -- (\sblen - 2\sbsz, 0) -- (\sblen, 0);
        \draw[line width=\sblw, color=purple!40, #2] (2\sbsz - \sblw, \sbhadj) -- (0.5\sblen - 0.5\sbtw, \sbhadj);
        \draw[line width=\sblw, color=purple!40, #2] (0.5\sblen + 0.5\sbtw, \sbhadj) -- (\sblen - 2\sbsz + \sblw, \sbhadj);
        \filldraw[color=purple!40] (0, 0) -- (\sbsz, \sbht) -- (0 + 2\sbsz, 0) -- (0, 0);
        \node[color=purple!90] at (0.5\sblen, 0) {\large  \textsf{\textup{#3}}};
    \end{tikzpicture}}}

% \linewitharrows is a helper command that makes a blue horizontal line, up or down arrows, and some text:
% arg 1 = 1 or -1 for up or down arrows
% arg 2 = solid or dashed or loosely dashed, etc.
% arg 3 = text
% arg 4 = text width
\newcommand{\linewitharrows}[4]{%
    \needspace{0.1\baselineskip}%
    \vbox to 1\baselineskip {\begin{tikzpicture}%
        \setlength{\sbtw}{#4}%
        \setlength{\sblen}{\linewidth}%
        \setlength{\sbht}{#1\sbsz}\setlength{\sbht}{1.4\sbht}%
        \setlength{\sbhadj}{#1\sblw}\setlength{\sbhadj}{0.25\sbhadj}%
        \filldraw[color=blue!40] (\sblen, 0) -- (\sblen - \sbsz, \sbht) -- (\sblen - 2\sbsz, 0) -- (\sblen, 0);
        \draw[line width=\sblw, color=blue!40, #2] (2\sbsz - \sblw, \sbhadj) -- (0.5\sblen - 0.5\sbtw, \sbhadj);
        \draw[line width=\sblw, color=blue!40, #2] (0.5\sblen + 0.5\sbtw, \sbhadj) -- (\sblen - 2\sbsz + \sblw, \sbhadj);
        \filldraw[color=blue!40] (0, 0) -- (\sbsz, \sbht) -- (0 + 2\sbsz, 0) -- (0, 0);
        \node[color=blue!90] at (0.5\sblen, 0) {\large  \textsf{\textup{#3}}};
    \end{tikzpicture}}}

\newcommand{\VSPb}{\vspace{0.5ex plus 5ex minus 0.25ex}}
\newcommand{\VSPa}{\vspace{0.25ex plus 5ex minus 0.25ex}}

% C
\newcommand{\cspecificstart}{\needspace{\sbns}\linewitharrows{-1}{solid}{C}{3em}}
\newcommand{\cspecificend}{\linewitharrows{1}{solid}{C}{3em}\VSPa}

% Fortran
\newcommand{\fortranspecificstart}{\VSPb\linewitharrows{-1}{solid}{Fortran}{6em}\VSPa}
\newcommand{\fortranspecificend}{\VSPb\linewitharrows{1}{solid}{Fortran}{6em}\VSPa}

% Python
\newcommand{\pyspecificstart}{\needspace{\sbns}\linewitharrows{-1}{solid}{Python}{6em}}
\newcommand{\pyspecificend}{\linewitharrows{1}{solid}{Python}{6em}\VSPa}

% Note
\newcommand{\notestart}{\VSPb\notelinewitharrows{-1}{solid}\VSPa}
\newcommand{\noteend}{\VSPb\notelinewitharrows{1}{solid}\VSPa}
% convenience macro for formatting the word "Note:" at the beginning of note blocks:
\newcommand{\noteheader}{{\textrm{\textsf{\textbf\textup\normalsize{{{{Note: }}}}}}}}

% Rationale
\newcommand{\rationalestart}{\VSPb\ratline{-1}{dashed}{Rationale}{7em}\VSPa}
\newcommand{\rationaleend}{\VSPb\ratline{1}{dashed}{}{0em}\VSPa}

% Advice to users
\newcommand{\adviceuserstart}{\VSPb\adviceuserline{-1}{solid}{Advice to users}{10em}\VSPa}
\newcommand{\adviceuserend}{\VSPb\adviceuserline{1}{solid}{}{0em}\VSPa}

% Advice to implementers
\newcommand{\adviceimplstart}{\VSPb\adviceimpline{-1}{solid}{Advice to PMIx library implementers}{20em}\VSPa}
\newcommand{\adviceimplend}{\VSPb\adviceimpline{1}{solid}{}{0em}\VSPa}

% Advice to hosts
\newcommand{\advicermstart}{\VSPb\advicermline{-1}{solid}{Advice to PMIx server hosts}{16em}\VSPa}
\newcommand{\advicermend}{\VSPb\advicermline{1}{solid}{}{0em}\VSPa}

% Required attributes
\newcommand{\reqattrstart}{\VSPb\adviceuserline{-1}{dashed}{Required Attributes}{16em}\VSPa}
\newcommand{\reqattrend}{\VSPb\adviceuserline{1}{dashed}{}{0em}\VSPa}

% Optional attributes
\newcommand{\optattrstart}{\VSPb\adviceimpline{-1}{dashed}{Optional Attributes}{16em}\VSPa}
\newcommand{\optattrend}{\VSPb\adviceimpline{1}{dashed}{}{0em}\VSPa}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Glossary formatting

\newcommand{\glossaryterm}[1]{\needspace{1ex}
\begin{adjustwidth}{-0.75in}{0.0in}
\nolinenumbers\parbox[b][-0.95\baselineskip][t]{1.4in}{\flushright \textbf{#1}}
\end{adjustwidth}\linenumbers}

\newcommand{\glossarydefstart}{
\begin{adjustwidth}{0.79in}{0.0in}}

\newcommand{\glossarydefend}{
\end{adjustwidth}\vspace{-1.5\baselineskip}}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Indexing and Table of Contents

\usepackage{imakeidx}
\usepackage[nodotinlabels]{titletoc}   % required for its [nodotinlabels] option

% Clickable links in TOC and index:
\usepackage[hyperindex=true,linktocpage=true]{hyperref}
\hypersetup{
  bookmarksnumbered = true,
  bookmarksopen     = false,
  colorlinks  = true, % Colors links instead of red boxes
  urlcolor    = blue, % Color for external links
  linkcolor   = blue  % Color for internal links
}

% \url styled in Roman font.
\urlstyle{rm}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Cross reference macros
% This defines:
%     \specref          cross reference label as "Section X on page Y"
%     \refsection       Link this label to a specific section label in the document
%
%     \declarstruct     Mark the declaration of a structure
%     \refstruct        Reference the structure declaration
%
%     \declareapi       Mark the declaration of an API function
%     \refapi           Reference the API declaration
%
%     \declaremacro     Mark the declaration of a user-level macro
%     \refmacro         Reference the macro declaration
%

\newcommand{\chapterref}[1]{Chapter~\ref{#1} on page~\pageref{#1}}
\newcommand{\specref}[1]{Section~\ref{#1} on page~\pageref{#1}}

\newcommand{\refsection}[2]{\hyperref[#1]{#2}}

\newcommand{\declarestruct}[1]{\index{#1!Definition|textbf} \label{struct:#1}}
\newcommand{\refstruct}[1]{\index{#1} \hyperref[struct:#1]{\code{#1} }}
\newcommand{\structref}[1] {\refstruct{#1}}
\newcommand{\specrefstruct}[1]{Section~\ref{struct:#1} on page~\pageref{struct:#1}}

\newcommand{\declareapi}[1]{\index{#1!Definition|textbf} \label{api:#1}}
\newcommand{\refapi}[1]{\index{#1} \hyperref[api:#1]{\code{#1} }}
\newcommand{\argapi}[1] {\refapi{#1}}

\newcommand{\refconst}[1]{\hyperref[const:#1]{\code{#1} }}

\newcommand{\declareattr}[1]{\index{#1!Definition|textbf} \label{attr:#1}}

\newcommand{\refarg}[1] {{\textrm{\textmd{\itshape{#1}}}}}
\newcommand{\argref}[1] {\refarg{#1}}

\newcommand{\declaremacro}[1]{\index{#1!Definition|textbf} \label{macro:#1}}
\newcommand{\refmacro}[1]{\index{#1} \hyperref[macro:#1]{\code{#1} }}

\newcommand{\declareterm}[1]{\index{#1!Definition|textbf} \label{macro:#1}}
\newcommand{\refterm}[1]{\index{#1} \hyperref[macro:#1]{\code{#1} }}

% Place in text for in-text questions during review
\newcommand{\rcomment}[1]{(REVIEW COMMENT: \textbf{#1})}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Set default fonts:
\rmfamily\mdseries\upshape\normalsize

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Define a divider for splitting implementer vs host attribute requirements/options
\newcommand{\divider}{\noindent\makebox[\linewidth]{\rule{\linewidth}{0.8pt}}}


\newcounter{pycounter}
\newcommand{\pylabel}[1]{\refstepcounter{pycounter} \label{appB:#1}}
\newcommand{\refpy}[1]{\hyperref[appB:#1]{\code{#1} }}