diff options
Diffstat (limited to 'crypto/krb5/doc/pdf/sphinxlatexobjects.sty')
| -rw-r--r-- | crypto/krb5/doc/pdf/sphinxlatexobjects.sty | 247 |
1 files changed, 206 insertions, 41 deletions
diff --git a/crypto/krb5/doc/pdf/sphinxlatexobjects.sty b/crypto/krb5/doc/pdf/sphinxlatexobjects.sty index e00881e53af3..5d9b69b77ae8 100644 --- a/crypto/krb5/doc/pdf/sphinxlatexobjects.sty +++ b/crypto/krb5/doc/pdf/sphinxlatexobjects.sty @@ -1,7 +1,7 @@ %% MODULE RELEASE DATA AND OBJECT DESCRIPTIONS % % change this info string if making any custom modification -\ProvidesFile{sphinxlatexobjects.sty}[2021/01/27 documentation environments] +\ProvidesFile{sphinxlatexobjects.sty}[2023/07/23 documentation environments] % Provides support for this output mark-up from Sphinx latex writer: % @@ -77,41 +77,206 @@ % Signatures, possibly multi-line % +% For legacy reasons Sphinx uses LaTeX \list and \item's for signatures +% This is delicate: +% - the actual item label is not typeset immediately by \item but later as part +% of the \everypar which will be triggered by either next paragraph or a manual +% \leavevmode, or if nothing in-between by the next \item, +% - \begingroup <set-up>\item[foo] <setup>\endgroup leads to errors, +% - vertical space depends on \parskip and \itemsep values in somewhat +% subtle manners. +% +% Since the 2022/01/13 version things are simpler as \parskip is simply set +% to zero during execution of \pysigline/\pysiglinewithargsret +% +% Parameter for separation via \itemsep of multiple signatures with common desc +\newlength\sphinxsignaturesep +\setlength\sphinxsignaturesep{\smallskipamount} +% latex.py outputs mark-up like this: +% \pysigstartsignatures <signatures> \pysigstopsignatures <actual desc> +\newcommand{\pysigstartsignatures}{% + % store current \parskip and \itemsep + \edef\pysig@restore@itemsep@and@parskip{% + \itemsep\the\itemsep\relax + \parskip\the\parskip\relax + }% + % set them to control the spacing between signatures sharing common desc + \parskip\z@skip + \itemsep\sphinxsignaturesep +} +\newcommand{\pysigstopsignatures}{% +% 1) encourage a pagebreak in an attempt to try to avoid last +% signature ending up separated from description (due to voodoo next) +\penalty-100 +% 2) some voodoo to separate last signature from description in a manner +% robust with respect to the latter being itself a LaTeX list object +\leavevmode\par\kern-\baselineskip\item[\strut] +% + \leavevmode + % it is important \leavevmode was issued before the \parskip reset, and + % it is also needed for the case of an object desc itself a LaTeX \list + % now restore \itemsep and \parskip + \pysig@restore@itemsep@and@parskip +} +% Each signature is rendered as NAME<SPACE>[TPLIST]<SPACE>(ARGLIST) where the +% size of <SPACE> is parametrized by \sphinxsignaturelistskip (0pt by default). +\newlength\sphinxsignaturelistskip +\setlength\sphinxsignaturelistskip{0pt} +\newcommand{\pysigtypelistopen}{\hskip\sphinxsignaturelistskip\sphinxcode{[}} +\newcommand{\pysigtypelistclose}{\sphinxcode{]}} +\newcommand{\pysigarglistopen}{\hskip\sphinxsignaturelistskip\sphinxcode{(}} +\newcommand{\pysigarglistclose}{\sphinxcode{)}} +% +% Use a \parbox to accommodate long argument list in signatures +% LaTeX did not imagine that an \item label could need multi-line rendering \newlength{\py@argswidth} \newcommand{\py@sigparams}[2]{% - % The \py@argswidth has been computed in \pysiglinewithargsret to make this - % occupy full available width on line. - \parbox[t]{\py@argswidth}{\raggedright #1\sphinxcode{)}#2\strut}% - % final strut is to help get correct vertical separation in case of multi-line - % box with the item contents. + % The \py@argswidth has been computed in \pysiglinewithargsret to make the + % argument list use full available width + \parbox[t]{\py@argswidth}{\raggedright #1\pysigarglistclose#2\strut}% + % final strut is to help get correct vertical separation +} +\newcommand{\py@sigparamswithtypelist}[3]{% + % similar to \py@sigparams but with different delimiters and an additional + % type parameters list given as #1, the argument list as #2 and the return + % annotation as #3 + \parbox[t]{\py@argswidth}{% + \raggedright #1\pysigtypelistclose% + \pysigarglistopen#2\pysigarglistclose% + #3\strut}% } + \newcommand{\pysigline}[1]{% -% the \py@argswidth is available we use it despite its name (no "args" here) -% the \relax\relax is because \py@argswidth is a "skip" variable and the first -% \relax only ends its "dimen" part + % as \py@argswidth is available, we use it but no "args" here + % the \relax\relax is because \py@argswidth is a "skip" variable + % this will make the label occupy the full available linewidth \py@argswidth=\dimexpr\linewidth+\labelwidth\relax\relax \item[{\parbox[t]{\py@argswidth}{\raggedright #1\strut}}] -% contrarily to \pysiglinewithargsret, we do not do this: -% \leavevmode\par\nobreak\vskip-\parskip\prevdepth\dp\strutbox -% which would give exact vertical spacing if item parbox is multi-line, -% as it affects negatively more common situation of \pysigline -% used twice or more in a row for labels sharing common description, -% due to bad interaction with the \phantomsection in the mark-up + \pysigadjustitemsep } \newcommand{\pysiglinewithargsret}[3]{% - \settowidth{\py@argswidth}{#1\sphinxcode{(}}% + % as #1 may contain a footnote using \label we need to make \label + % a no-op here to avoid LaTeX complaining about duplicates +\let\spx@label\label\let\label\@gobble + \settowidth{\py@argswidth}{#1\pysigarglistopen}% +\let\label\spx@label + \py@argswidth=\dimexpr\linewidth+\labelwidth-\py@argswidth\relax\relax + \item[{#1\pysigarglistopen\py@sigparams{#2}{#3}\strut}] + \pysigadjustitemsep +} +\newcommand{\pysiglinewithargsretwithtypelist}[4]{ +% #1 = name, #2 = typelist, #3 = arglist, #4 = retann +\let\spx@label\label\let\label\@gobble + \settowidth{\py@argswidth}{#1\pysigtypelistopen}% +\let\label\spx@label \py@argswidth=\dimexpr\linewidth+\labelwidth-\py@argswidth\relax\relax - \item[{#1\sphinxcode{(}\py@sigparams{#2}{#3}}] -% this strange incantation is because at its root LaTeX in fact did not -% imagine a multi-line label, it is always wrapped in a horizontal box at core -% LaTeX level and we have to find tricks to get correct interline distances. - \leavevmode\par\nobreak\vskip-\parskip\prevdepth\dp\strutbox} -\newcommand{\pysigstartmultiline}{% - \def\pysigstartmultiline{\vskip\smallskipamount\parskip\z@skip\itemsep\z@skip}% - \edef\pysigstopmultiline - {\noexpand\leavevmode\parskip\the\parskip\relax\itemsep\the\itemsep\relax}% - \parskip\z@skip\itemsep\z@skip + \item[{#1\pysigtypelistopen\py@sigparamswithtypelist{#2}{#3}{#4}\strut}] + \pysigadjustitemsep +} + +\def\sphinxoptionalextraspace{0.5mm} +\newcommand{\pysigwithonelineperarg}[3]{% + % render each argument on its own line + \item[#1\pysigarglistopen\strut] + \leavevmode\par\nopagebreak + % this relies on \pysigstartsignatures having set \parskip to zero + \begingroup + \let\sphinxparamcomma\sphinxparamcommaoneperline + \def\sphinxoptionalhook{\ifvmode\else\kern\sphinxoptionalextraspace\relax\fi}% + % The very first \sphinxparam should not emit a \par hence a complication + % with a group and global definition here as it may occur in a \sphinxoptional + \global\let\spx@sphinxparam\sphinxparam + \gdef\sphinxparam{\gdef\sphinxparam{\par\spx@sphinxparam}\spx@sphinxparam}% + #2\par + \endgroup + \global\let\sphinxparam\spx@sphinxparam + % fulllineitems sets \labelwidth to be like \leftmargin + \nopagebreak\noindent\kern-\labelwidth\pysigarglistclose{#3} + \pysigadjustitemsep +} +\newcommand{\pysigwithonelineperargwithonelinepertparg}[4]{ + % #1 = name, #2 = typelist, #3 = arglist, #4 = retann + % render each type parameter and argument on its own line + \item[#1\pysigtypelistopen\strut] + \leavevmode\par\nopagebreak + \begingroup + \let\sphinxparamcomma\sphinxparamcommaoneperline + % \sphinxtypeparam is treated similarly to \sphinxparam but since + % \sphinxoptional is not accepted in a type parameters list, we do + % not need the hook or the global definition + \let\spx@sphinxtypeparam\sphinxtypeparam + \def\sphinxtypeparam{\def\sphinxtypeparam{\par\spx@sphinxtypeparam}\spx@sphinxtypeparam}% + #2\par + \endgroup + \nopagebreak\noindent\kern-\labelwidth\pysigtypelistclose% + % render the rest of the signature like in \pysigwithonelineperarg + \pysigarglistopen\strut\par\nopagebreak + \begingroup + \let\sphinxparamcomma\sphinxparamcommaoneperline + \def\sphinxoptionalhook{\ifvmode\else\kern\sphinxoptionalextraspace\relax\fi}% + \global\let\spx@sphinxparam\sphinxparam + \gdef\sphinxparam{\gdef\sphinxparam{\par\spx@sphinxparam}\spx@sphinxparam}% + #3\par + \endgroup + \global\let\sphinxparam\spx@sphinxparam + \nopagebreak\noindent\kern-\labelwidth\pysigarglistclose{#4} + \pysigadjustitemsep +} +\newcommand{\pysiglinewithargsretwithonelinepertparg}[4]{ + % #1 = name, #2 = typelist, #3 = arglist, #4 = retann + % render each type parameter on its own line but the arguments list inline + \item[#1\pysigtypelistopen\strut] + \leavevmode\par\nopagebreak + \begingroup + \let\sphinxparamcomma\sphinxparamcommaoneperline + % \sphinxtypeparam is treated similarly to \sphinxparam but since + % \sphinxoptional is not accepted in a type parameters list, we do + % not need the hook or the global definition + \let\spx@sphinxtypeparam\sphinxtypeparam + \def\sphinxtypeparam{\def\sphinxtypeparam{\par\spx@sphinxtypeparam}\spx@sphinxtypeparam}% + #2\par + \endgroup + \nopagebreak\noindent\kern-\labelwidth\pysigtypelistclose% + % render the arguments list on one line + \pysigarglistopen#3\pysigarglistclose#4\strut + \pysigadjustitemsep +} +\newcommand{\pysigwithonelineperargwithtypelist}[4]{ + % #1 = name, #2 = typelist, #3 = arglist, #4 = retann + % render the type parameters list on one line, but each argument is rendered on its own line +\let\spx@label\label\let\label\@gobble + \settowidth{\py@argswidth}{#1\pysigtypelistopen}% +\let\label\spx@label + \py@argswidth=\dimexpr\linewidth+\labelwidth-\py@argswidth\relax\relax + \item[{#1\pysigtypelistopen\parbox[t]{\py@argswidth}{% + \raggedright #2\pysigtypelistclose\pysigarglistopen\strut}\strut}] + % render the rest of the signature like in \pysigwithonelineperarg + \begingroup + \let\sphinxparamcomma\sphinxparamcommaoneperline + \def\sphinxoptionalhook{\ifvmode\else\kern\sphinxoptionalextraspace\relax\fi}% + \global\let\spx@sphinxparam\sphinxparam + \gdef\sphinxparam{\gdef\sphinxparam{\par\spx@sphinxparam}\spx@sphinxparam}% + #3\par + \endgroup + \global\let\sphinxparam\spx@sphinxparam + \nopagebreak\noindent\kern-\labelwidth\pysigarglistclose{#4} + \pysigadjustitemsep +} +\newcommand{\pysigadjustitemsep}{% + % adjust \itemsep to control the separation with the next signature + % sharing common description + \ifsphinxsigismultiline + % inside a multiline signature, no extra vertical spacing + % ("multiline" here does not refer to possibly long + % list of arguments, but to a cpp domain feature) + \itemsep\z@skip + \else + \itemsep\sphinxsignaturesep + \fi } +\newif\ifsphinxsigismultiline +\newcommand{\pysigstartmultiline}{\sphinxsigismultilinetrue}% +\newcommand{\pysigstopmultiline}{\sphinxsigismultilinefalse\itemsep\sphinxsignaturesep}% % Production lists % @@ -145,22 +310,22 @@ \newcommand{\optionlistlabel}[1]{\normalfont\bfseries #1 \hfill}% \bf deprecated \newenvironment{optionlist}[1] {\begin{list}{} - {\setlength{\labelwidth}{#1} - \setlength{\rightmargin}{1cm} - \setlength{\leftmargin}{\rightmargin} - \addtolength{\leftmargin}{\labelwidth} - \addtolength{\leftmargin}{\labelsep} - \renewcommand{\makelabel}{\optionlistlabel}} + {\setlength{\labelwidth}{#1}% + \setlength{\rightmargin}{1cm}% + \setlength{\leftmargin}{\rightmargin}% + \addtolength{\leftmargin}{\labelwidth}% + \addtolength{\leftmargin}{\labelsep}% + \renewcommand{\makelabel}{\optionlistlabel}}% }{\end{list}} \newlength{\lineblockindentation} \setlength{\lineblockindentation}{2.5em} \newenvironment{lineblock}[1] {\begin{list}{} - {\setlength{\partopsep}{\parskip} - \addtolength{\partopsep}{\baselineskip} + {\setlength{\partopsep}{\parskip}% + \addtolength{\partopsep}{\baselineskip}% \topsep0pt\itemsep0.15\baselineskip\parsep0pt - \leftmargin#1\relax} + \leftmargin#1\relax}% \raggedright} {\end{list}} @@ -186,12 +351,12 @@ \DUprovidelength{\DUlineblockindent}{2.5em} \ifdefined\DUlineblock\else \newenvironment{DUlineblock}[1]{% - \list{}{\setlength{\partopsep}{\parskip} - \addtolength{\partopsep}{\baselineskip} - \setlength{\topsep}{0pt} - \setlength{\itemsep}{0.15\baselineskip} - \setlength{\parsep}{0pt} - \setlength{\leftmargin}{#1}} + \list{}{\setlength{\partopsep}{\parskip}% + \addtolength{\partopsep}{\baselineskip}% + \setlength{\topsep}{0pt}% + \setlength{\itemsep}{0.15\baselineskip}% + \setlength{\parsep}{0pt}% + \setlength{\leftmargin}{#1}}% \raggedright } {\endlist} |