preamble-saildoc-macros.tex

\makeatletter
\newcommand{\makesailcmds@core}[2]{%
  \input{#2/commands.tex}
  \ea\newcommand\csname #1code\endcsname[1]{%
    \csname #1fcl##1execute\endcsname%
    \bigskip%
  }%
  \ea\WithSuffix\ea\newcommand\csname #1code\endcsname*[1]{%
    \csname #1fcl##1execute\endcsname%
  }%
  \ea\newcommand\csname #1valandfun\endcsname[1]{%
    \csname #1##1\endcsname \csname #1fn#1\endcsname%
  }%
}

% We could have sail macro call us back for more formatting flexibility.
%\newcommand{\saildescribe}[2]{
%  \lstinputlisting[language=sail]{#2}
%
%  \hangindent=\parindent #1
%}

% The following macros define how we would like sail code to be documented.
% There is one per category of sail top-level (val spec, typedef, function, function clause etc)
% currently we only use val and fcl.
% They are called by latex generated by sail with
% #1 the latex for any doc-comment from the sail
% #2 a lstinputlisting invocation that
\newcommand{\saildocval}[2]{%
#2%
\par%
\hangindent=\parindent #1%
\medskip%
}
\newcommand{\saildocfcl}[2]{%
#1 #2%
}
\newcommand{\saildocfn}[2]{%
#1 #2%
}
\newcommand{\saildoctype}[2]{%
#1 #2%
}

\newcommand{\@saildoclabelled@capture}[2]{%
  \global\def\@saildoclabelled@name{#1}%
  \global\def\@saildoclabelled@body{#2}%
}

\newcommand{\@saildocfcl@capture}[2]{%
  \global\def\@saildocfcl@doc{#1}%
  \global\def\@saildocfcl@fcl{#2}%
}

\newcommand{\@saildoc@makeerrcmd}[1]{%
  \ea\def\csname #1@error\endcsname{%
    \GenericError{[saildoc] }{Missing definition}{%
      [saildoc] \@backslashchar#1 should have been defined.\MessageBreak%
      Check your Sail version if you re-generated the LaTeX.%
    }{}%
  }%
}

\@saildoc@makeerrcmd{@saildoclabelled@name}
\@saildoc@makeerrcmd{@saildoclabelled@body}
\@saildoc@makeerrcmd{@saildocfcl@doc}
\@saildoc@makeerrcmd{@saildocfcl@fcl}

\newcommand{\@saildoc@makeforbiddenseccmd}[1]{%
  \ea\def\csname @saildoc@#1\ea\endcsname{%
    \GenericError{[saildoc] }{Forbidden command}{%
      [saildoc] \@backslashchar#1 is not allowed.%
    }{}%
  }%
}

% Always use starred variant
\newcommand{\@saildoc@makenestedseccmd}[2]{%
  \ea\def\csname @saildoc@#1\endcsname{%
    \@ifstar{}{}\csname #2\endcsname*%
  }%
}

\@saildoc@makeforbiddenseccmd{part}
\@saildoc@makeforbiddenseccmd{chapter}
\@saildoc@makeforbiddenseccmd{section}
% subsection is special (but still maps to subsubsection); see below
\@saildoc@makenestedseccmd{subsubsection}{paragraph}
\@saildoc@makenestedseccmd{paragraph}{subparagraph}
\@saildoc@makeforbiddenseccmd{subparagraph}

\let\@saildoc@subsection@allowed\@empty
\newcommand{\@saildoc@subsection@allow}[1]{%
  \ea\def\ea\@saildoc@subsection@allowed\ea{%
    \@saildoc@subsection@allowed%
    \@saildoc@subsection@allowed@iter{#1}%
  }%
}
\@saildoc@subsection@allow{Description}
\@saildoc@subsection@allow{Exceptions}
\@saildoc@subsection@allow{Notes}

\newcommand{\@saildoc@subsection@valid}[1]{}

\newcommand{\@saildoc@subsection@invalid}[1]{%
  \GenericError{[saildoc] }{Invalid subsection}{%
    [saildoc] `#1' is not a valid subsection.%
  }{}%
}

\newcommand{\@saildoc@subsection@duplicate}[1]{%
  \GenericError{[saildoc] }{Duplicate subsection}{%
    [saildoc] `#1' is defined more than once.%
  }{}%
}

\newcommand{\@saildoc@subsection@validate}[1]{{%
  \def\@saildoc@subsection@allowed@iter##1{%
    \ifthenelse{\equal{#1}{##1}}{%
      \let\@saildoc@subsection@validate@action\@saildoc@subsection@valid%
    }{%
    }%
  }%
  \ea\ifx\csname @saildoc@subsection@body@#1\endcsname\relax%
    \let\@saildoc@subsection@validate@action\@saildoc@subsection@invalid%
    \@saildoc@subsection@allowed%
  \else%
    \let\@saildoc@subsection@validate@action\@saildoc@subsection@duplicate%
  \fi%
  \@saildoc@subsection@validate@action{#1}%
}}

\NewEnviron{@saildoc@subsection}[1]{%
  \@saildoc@subsection@validate{#1}%
  \ea\ea\ea\global\ea\ea\ea\def\ea\csname @saildoc@subsection@body@#1\ea\endcsname\ea{\BODY}%
}

\newcommand{\@saildoc@subsection@print}[1]{%
  \ea\ifx\csname @saildoc@subsection@body@#1\endcsname\relax%
  \else%
    \ea\ifx\csname @saildoc@subsection@body@#1\endcsname\@empty%
    \else%
      \subsubsection*{#1}%
      \csname @saildoc@subsection@body@#1\endcsname%
    \fi%
  \fi%
}

\newcommand{\@saildoc@subsection@clear}{{%
  \def\@saildoc@subsection@allowed@iter##1{%
    \ea\global\ea\let\csname @saildoc@subsection@body@##1\endcsname\@undefined%
  }%
  \@saildoc@subsection@allowed%
}}

\newcommand{\@saildoc@xpatchcmd@repeat}[3]{%
  \xpatchcmd{#1}{#2}{#3}{\@saildoc@xpatchcmd@repeat{#1}{#2}{#3}}{}%
}

\newcommand{\@saildoc@environ@guard}[2]{%
  % See \makesailcmds for why this space is needed
  #1{#2} %
}

\newcommand{\@saildoc@textbf}[1]{%
  \ifcsname @capperm@\detokenize{#1}\endcsname%
    \csname @capperm@\detokenize{#1}\endcsname%
  \else%
    \textbf{#1}%
  \fi%
}

\newcommand{\makesailcmds}[2]{%
  \makesailcmds@core{#1}{#2}%
  \ea\newcommand\csname #1isarefbody\endcsname[1]{{%
    %
    % Given:
    %
    %   \saildoclabelled{foo}{\saildocfcl{bar}{baz}}
    %
    % we expand to capture foo, and expand the second argument again to capture
    % bar and baz.
    %
    \global\let\@saildoclabelled@name\@saildoclabelled@name@error%
    \global\let\@saildoclabelled@body\@saildoclabelled@body@error%
    \global\let\@saildocfcl@doc\@saildocfcl@doc@error%
    \global\let\@saildocfcl@fcl\@saildocfcl@fcl@error%
    %
    \let\saildoclabelled\@saildoclabelled@capture%
    \let\saildocfcl\@saildocfcl@capture%
    %
    \csname #1code\endcsname*{##1}%
    \@saildoclabelled@body%
    %
    \ea\ea\ea\ifx\ea\ea\ea\relax\ea\detokenize\ea{\@saildocfcl@doc}\relax%
      \GenericWarning{}{#1 Warning: `##1` is not documented}%
    \fi%
    %
    % Now for the fcl body, rewrite:
    %
    %   Foo
    %   \subsection*{Exceptions}
    %   Bar
    %   \subsection*{Notes}
    %   Baz
    %
    % to:
    %
    %   \@saildoc@environ@guard{\begin{@saildoc@subsection}}{Description}
    %   Foo
    %   \end{@saildoc@subsection}
    %   \@saildoc@environ@guard{\begin{@saildoc@subsection}}{Exceptions}
    %   Bar
    %   \end{@saildoc@subsection}
    %   \@saildoc@environ@guard{\begin{@saildoc@subsection}}{Notes}
    %   Baz
    %   \end{@saildoc@subsection}
    %
    % as well as using \@saildoc@subsubsection etc for all the other section
    % commands. We allow the non-starred \subsection too.
    %
    % The extra space inserted by \@saildoc@environ@guard is required to avoid:
    %
    %   \begin{@saildoc@subsection}{Foo}\end{@saildoc@subsection}
    %
    % as the lack of a token before \end confuses environ and makes it split
    % Foo into argument "F" and body "oo". The space gets stripped away so
    % \BODY will be empty.
    %
    \xpretocmd{\@saildocfcl@doc}{\@saildoc@environ@guard{\begin{@saildoc@subsection}}{Description}}{}{}%
    \@saildoc@xpatchcmd@repeat{\@saildocfcl@doc}{\part}{\@saildoc@part}%
    \@saildoc@xpatchcmd@repeat{\@saildocfcl@doc}{\chapter}{\@saildoc@chapter}%
    \@saildoc@xpatchcmd@repeat{\@saildocfcl@doc}{\section}{\@saildoc@section}%
    \@saildoc@xpatchcmd@repeat{\@saildocfcl@doc}{\subsection*}{\end{@saildoc@subsection}\@saildoc@environ@guard{\begin{@saildoc@subsection}}}%
    \@saildoc@xpatchcmd@repeat{\@saildocfcl@doc}{\subsection}{\end{@saildoc@subsection}\@saildoc@environ@guard{\begin{@saildoc@subsection}}}%
    \@saildoc@xpatchcmd@repeat{\@saildocfcl@doc}{\subsubsection}{\@saildoc@subsubsection}%
    \@saildoc@xpatchcmd@repeat{\@saildocfcl@doc}{\paragraph}{\@saildoc@paragraph}%
    \@saildoc@xpatchcmd@repeat{\@saildocfcl@doc}{\subparagraph}{\@saildoc@subparagraph}%
    \xapptocmd{\@saildocfcl@doc}{\end{@saildoc@subsection}}{}{}%
    %
    % We also want to format various special names in our own way, all of which
    % currently use \textbf in the saildoc output.
    %
    \@saildoc@xpatchcmd@repeat{\@saildocfcl@doc}{\textbf}{\@saildoc@textbf}%
    %
    % Now we have the right \begin and \end macros, with the latter directly
    % visible to environ without any expansion, we can capture their contents
    % by expanding again.
    %
    \@saildocfcl@doc%
    %
    % Finally reassemble the documentation in the right order with the Sail in
    % the right place. We use \csuse to avoid having to pre-initialise
    % everything to \@empty.
    %
    % Also add a label so that instruction references from saildoc resolve
    % correctly. This label is not added by the saildoc generator so we insert
    % it manually here using the sail mangling: <prefix>z<insnname>. This is
    % really a valspec mangling, which allows us to link to the description
    % rather than the function body and so saildoc's inability to reference
    % function clauses in markdown turns out to be useful.
    %
    \label{#1z##1}%
    \@saildoc@subsection@print{Description}%
    %
    \subsubsection*{Semantics}%
    \phantomsection%
    \label{\@saildoclabelled@name}%
    \noindent\@saildocfcl@fcl%
    %
    \@saildoc@subsection@print{Exceptions}%
    %
    \@saildoc@subsection@print{Notes}%
    %
    % Reset state for next time
    %
    \@saildoc@subsection@clear%
  }}%
}
\makeatother