X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/558e70ee837c7456495f5399c7e62504206ea99b..12949379840101e2d65883f29c5e8f0f6de49e9c:/doc/sod.sty diff --git a/doc/sod.sty b/doc/sod.sty index 531fce0..9da7def 100644 --- a/doc/sod.sty +++ b/doc/sod.sty @@ -25,9 +25,17 @@ \ProvidesPackage{sod} +%%%-------------------------------------------------------------------------- +%%% Basic style things. + %% More reference types. \defxref{p}{part} +%% A gadget to include in `\xref': call as +%% +%% \xref[\instead{THING}]{LABEL} +%% +%% to replace the usual `section' or whatever with THING. \def\instead#1#2{#1} %% Other languages with special typesetting. @@ -98,15 +106,15 @@ %% Intercept grammar typesetting and replace the vertical bar with the %% maths-font version. -\let\@@grammar\grammar -\def\grammar{\def\textbar{\hbox{$|$}}\@@grammar} +\let\@@syn@shorts\syn@shorts +\def\syn@shorts{\def\textbar{\hbox{$|$}}\@@syn@shorts} %% Collect super- and subscripts. (Note that underscores are active for the %% most part.) When we're done, end maths mode if we entered it %% conditionally. \def\@scripts{\futurelet\@ch\@scripts@i} \begingroup\lccode`\~=`\_\lowercase{\endgroup -\def\@scripts@i{\if1\ifx\@ch~1\else\ifx\@ch^1\else0\fi\fi% +\def\@scripts@i{\if1\ifx\@ch~1\else\ifx\@ch_1\else\ifx\@ch^1\else0\fi\fi\fi% \expandafter\@scripts@ii\else\expandafter\m@maybe@end\fi}} \def\@scripts@ii#1#2{\m@maybe#1{#2}\@scripts} @@ -116,6 +124,14 @@ \expandafter\@firstoftwo\expandafter\@scripts% \else\@tempa\expandafter\@scripts\fi} +%% Lookahead without eating spaces. +\def\@ifnextchar@preserve#1#2#3{% + \let\want@= #1\def\@tempa{#2}\def\@tempb{#3}% + \futurelet\nch@\@ifnch@p% +} +\def\@ifnch@p{% + \ifx\want@\nch@\expandafter\@tempa\else\expandafter\@tempb\fi} + %% Extra syntax for Lisp templates. These produce the maths-font versions of %% characters, which should contrast well against the sans face used for %% literals. @@ -126,29 +142,73 @@ \atdef ({\m@maybe(\@scripts} \atdef ){\m@maybe)\@scripts} \atdef !{\m@maybe|\@scripts} + \def\returns{\m@maybe\longrightarrow\m@maybe@end\hspace{0.5em}\ignorespaces} +\def\nlret{\\\hspace{4em}\returns} \atdef >{\leavevmode\unskip\hspace{0.5em}\returns} -\atdef -#1{\if>#1\hbox{--\raisebox{.4pt}{>}}\penalty200\relax\fi} + +%% Extra syntax for common tokens. +\atdef ~{\textasciitilde} +\atdef -{\leavevmode\hbox\bgroup\futurelet\ch@\@dash} +\def\@dash{% + \ifx\ch@>% + --\raisebox{.4pt}{>}% + \def\next@{\@firstoftwo{\egroup\penalty200\relax}}% + \else\ifx\ch@-% + --\,% + \def\next@{\@firstoftwo{\futurelet\ch@\@dash}}% + \else% + --% + \let\next@\egroup% + \fi\fi + \next@% +} %% Comment setting. \def\comment#1{\mbox{\normalfont\itshape\/#1\/}} \atdef /*#1*/{/*\comment{#1}*/} -\def\@semis{\@ifnextchar;{;\@semis}\@semicomment} +\def\@semis;{\@ifnextchar@preserve;{;\@semis}\@semicomment} \def\@semicomment#1\\{\comment{#1}\\} -\atdef ;#1\\{;\@semis} +\atdef ;{;\@semis;} -%% Environment for setting programs. Newlines are explicit, because -%% otherwise I need comments in weird places to make the vertical spacing -%% come out properly. You can write `\obeylines' if you really want to. -\def\@prog{\let\prog@@cr\@tabcr\let\@tabcr\@progcr\codeface\tabbing} -\def\prog{\quote\@prog} -\def\endprog{\endtabbing\endquote} -\let\nprog\@prog -\let\endnprog\endtabbing -\def\ind{\quad\=\+\kill} +%% Put a chunk of text in a box. +\newenvironment{boxy}[1][\q@]{% + \savenotes% + \dimen@\linewidth\advance\dimen@-1.2pt\advance\dimen@-2ex% + \medskip% + \vbox\bgroup\hrule\hbox\bgroup\vrule% + \vbox\bgroup\vskip1ex\hbox\bgroup\hskip1ex\minipage\dimen@% + \def\@temp{#1}\ifx\@temp\q@\else\leavevmode{\headfam\bfseries#1\quad}\fi% +}{% + \endminipage\hskip1ex\egroup\vskip1ex\egroup% + \vrule\egroup\hrule\egroup% + \medskip% + \spewnotes% +} + +%%%-------------------------------------------------------------------------- +%%% Environment for setting programs. + +%% Save `\kill' so that `longtable' won't clobber it. +\let\prog@@kill\kill + +%% Main guts of `prog' and `nprog'. +\def\@prog{% + \let\prog@@cr\@tabcr% + \let\@tabcr\@progcr% + \let\kill\prog@@kill% + \codeface% + \tabbing% +} + +%% Newlines: called by `\\' within a `prog'. +%% +%% \\ newline without following break +%% \\[SKIP] newline /with/ break and vertical glue +%% \\*[SKIP] newline without break, with optional glue +%% \\+ newline with break and a vertical gap +%% \\- newline without break, with a tiny gap \def\@progcr{\futurelet\@tempa\@progcr@i} -{\def\:{\gdef\@progcr@sp}\: {\@progcr}} -\atdef~{\textasciitilde} \def\@progcr@i{% \ifx\@tempa\@sptoken\let\next@\@progcr@sp\else \if1\ifx\@tempa[1\else @@ -165,103 +225,136 @@ \def\@progcr@ii#1{\csname @progcr@#1\endcsname\ignorespaces} \@namedef{@progcr@+}{\prog@@cr[\medskipamount]} \@namedef{@progcr@-}{\prog@@cr*[\jot]} +{\def\:{\gdef\@progcr@sp}\: {\@progcr}} % \@progcr@sp eats space and recurses + +%% Set a program in `codeface', with implicit tabbing and other toys. +%% Newlines are explicit, because otherwise I need comments in weird places +%% to make the vertical spacing come out properly. You can write +%% `\obeylines' if you really want to. +\def\prog{\quote\@prog} +\def\endprog{\endtabbing\endquote} + +%% Like `prog', but without indenting the code. Use this within environments +%% which already set their contents out from the body text in some +%% distinctive way. +\let\nprog\@prog +\let\endnprog\endtabbing + +%% Indent the following material. Cancel using `\-'. +\def\ind{\quad\=\+\kill} + +%% Show a backslash by the right-hand margin; for multiline macros etc. \def\macsl{\`\textbackslash\hskip\leftmargin} -%% Put a chunk of text in a box. -\newenvironment{boxy}[1][\q@]{% - \savenotes - \dimen@\linewidth\advance\dimen@-1.2pt\advance\dimen@-2ex% - \medskip% - \vbox\bgroup\hrule\hbox\bgroup\vrule% - \vbox\bgroup\vskip1ex\hbox\bgroup\hskip1ex\minipage\dimen@% - \def\@temp{#1}\ifx\@temp\q@\else\leavevmode{\headfam\bfseries#1\quad}\fi% -}{% - \endminipage\hskip1ex\egroup\vskip1ex\egroup% - \vrule\egroup\hrule\egroup% - \medskip% - \spewnotes% +%% \maplist{THING}{{ITEM}...}: Invoke THING{ITEM} for each ITEM in turn. +\def\maplist#1#2{\map@i{#1}#2\q@} +\def\map@i#1{\def\next@{\map@ii{#1}}\futurelet\ch@\next@} +\def\map@ii#1{\ifx\ch@\q@\expandafter\@gobble% + \else\def\next@{\map@iii{#1}}\expandafter\next@\fi} +\def\map@iii#1#2{#1{#2}\map@i{#1}} + +%% \crossproduct{THING}{{LIST}...} where each LIST is {ITEM}... +%% For each possible way of selecting one ITEM from each LIST, in order, +%% invoke THING{{ITEM}...} +\toksdef\cprod@new=0 +\toksdef\cprod@old=2 +\toksdef\cprod@head=4 +\toksdef\cprod@tail=6 +\def\crossproduct#1#2{% + \cprod@new{{}}% + \maplist{\cprod@f{#1}}{#2}% + \cprod@head{#1}% + \edef\next@{\noexpand\maplist{\the\cprod@head}{\the\cprod@new}} + \next@% +} +\def\cprod@f#1#2{% + \cprod@old\cprod@new\cprod@new{}% + \maplist\cprod@g{#2}% +} +\def\cprod@g#1{% + \cprod@head{#1}% + \expandafter\maplist\expandafter\cprod@h\expandafter{\the\cprod@old}% +} +\def\cprod@h#1{% + \cprod@tail{#1}% + \cprod@new\expandafter{\the\expandafter\cprod@new\expandafter{% + \the\expandafter\cprod@tail\the\cprod@head}}% } -%% Lisp documentation machinery. +%%%-------------------------------------------------------------------------- +%%% Machinery for describing functions, etc. + +%% \definedescribecategory{CAT}[KIND]{NAME} +%% +%% Define a category of things to document. CAT is a short label identifying +%% the category to `\describe', `\descref', and friends. The NAME is the +%% text to show in the description headline; it is a macro body which is +%% passed an argument `#1' that applies a modifier to some portion of the +%% text. +%% +%% The KIND allows additional arguments to be collected, included in label +%% strings, and mentioned in the index. The default is `plain'. \def\definedescribecategory#1{% \@ifnextchar[{\def@desc{#1}}{\def@desc{#1}[plain]}} \def\def@desc#1[#2]#3{\@namedef{cat!#1}##1{#3}\@namedef{catsw!#1}{#2}} + +%% \describecategoryname[MOD]{CAT} +%% +%% Typeset the category name for CAT, modified by MOD. \def\describecategoryname{\@ifnextchar[\@descname@i{\@descname@i[]}} \def\@descname@i[#1]#2{% \expandafter\let\expandafter\@tempa\csname cat!#2\endcsname% \expandafter\let\expandafter\@tempb\csname modcat/#1\endcsname% \ifx\@tempa\relax\@tempb{#2}\else\@tempa\@tempb\fi} + +%% Call a modifier method. \def\@mod@dispatch#1#2{\csname #1/#2\endcsname} + +%% Call a description method given the category. \def\@desc@dispatch#1#2{% \csname #1/% - \expandafter\ifx\csname catsw!#2\endcsname\relax plain% - \else \csname catsw!#2\endcsname \fi% + \expandafter\ifx\csname catsw!#2\endcsname\relax plain% + \else \csname catsw!#2\endcsname \fi% \endcsname% } -\definedescribecategory{sym}{symbol} -\definedescribecategory{fun}{#1{function}} -\definedescribecategory{gf}{generic #1{function}} -\definedescribecategory{msg}{message} -\definedescribecategory{var}{variable} -\definedescribecategory{modvar}{module variable} -\definedescribecategory{const}{constant} -\definedescribecategory{meth}[method]{primary #1{method}} -\definedescribecategory{ar-meth}[method]{\code{:around} #1{method}} -\definedescribecategory{be-meth}[method]{\code{:before} #1{method}} -\definedescribecategory{af-meth}[method]{\code{:after} #1{method}} -\definedescribecategory{cls}{class} -\definedescribecategory{rst}{restart} -\definedescribecategory{ty}{type} -\definedescribecategory{type}{type} -\definedescribecategory{mac}{#1{macro}} -\definedescribecategory{feat}{feature macro} -\definedescribecategory{lmac}{local #1{macro}} -\definedescribecategory{parse}{parser spec} -\definedescribecategory{parseform}{parser form} -\definedescribecategory{opt}{option handler} -\definedescribecategory{optmac}{option macro} -\definedescribecategory{plug}{pluggable parser} -\def\nlret{\\\hspace{4em}\returns} - -\@namedef{modcat/}#1{#1} -\@namedef{modlabel/}#1{#1} -\@namedef{modindex/}#1{#1@\noexpand\code{#1}} +%% Modifier methods for the default `plain' modifier. +\@namedef{modcat/plain}#1{#1} +\@namedef{modlabel/plain}#1{#1} +\@namedef{modindex/plain}#1{#1@\noexpand\code{#1}} +%% Modifier methods for `setf'. The name text prefixes the relevant word +%% with `setf-'. \@namedef{modcat/setf}#1{\code{setf}-#1} \@namedef{modlabel/setf}#1{setf/#1} \@namedef{modindex/setf}#1{#1@\noexpand\code{#1}} +%% Modifier methods for words with *earmuffs*. Sort into the index without +%% the earmuffs. \@namedef{modcat/muffs}#1{#1} -\@namedef{modlabel/muffs}#1{*#1*} -\@namedef{modindex/muffs}#1{#1@\noexpand\code{*#1*}} +\@namedef{modlabel/muffs}#1{#1} +\@namedef{modindex/muffs}#1{\@unmuff#1@\noexpand\code{#1}} +\def\@unmuff*#1*{#1} +%% Modifier methods for :keywords. Sort into the index without the `:'. \@namedef{modcat/kwd}#1{#1} -\@namedef{modlabel/kwd}#1{:#1} -\@namedef{modindex/kwd}#1{#1@\noexpand\code{:#1}} +\@namedef{modlabel/kwd}#1{#1} +\@namedef{modindex/kwd}#1{\@gobble#1@\noexpand\code{#1}} +%% Category-kind methods for plain categories. \@namedef{descargs/plain}#1{#1{}} -\@namedef{desclabel/plain}#1#2#3{#1:\@mod@dispatch{modlabel}{#2}{#3}} +\@namedef{desclabel/plain}#1#2#3{#2:\@mod@dispatch{modlabel}{#1}{#3}} \@namedef{descindex/plain}#1#2#3{% - \@mod@dispatch{modindex}{#2}{#3}!% - \protect\describecategoryname[#2]{#1}% -} - -\@namedef{descargs/method}#1#2{#1{{#2}}} -\@namedef{desclabel/method}#1#2#3#4% - {#1:\@mod@dispatch{modlabel}{#2}{#3}(#4)} -\@namedef{descindex/method}#1#2#3#4{% - \@mod@dispatch{modindex}{#2}{#3}!% - \protect\describecategoryname[#2]{#1}% - \protect\fmtspecs{ specialized at }{#4}% + \@mod@dispatch{modindex}{#1}{#3}!% + \protect\describecategoryname[#1]{#2}% } -\def\q@{\q@} -\def\@setf{setf} - +%% Category-kind methods for `method' categories. Collect an extra argument +%% listing the specializers: include them in the label, and typeset them in +%% the index. \def\fmtspecs#1#2{% - \if!#2!\else\count@\z@\toks@{}#1\@fmtspecs@i#2,\q@,\fi} -\def\@fmtspecs@i#1,{% + \if!#2!\else\count@\z@\toks@{}#1\fmtspecs@i#2,\q@,\fi} +\def\fmtspecs@i#1,{% \def\@tempa{#1}% \ifx\@tempa\q@% \ifcase\count@(no args?!)% @@ -274,15 +367,31 @@ \ifnum\count@>\@ne, \fi% \the\toks@% \toks@{\code{#1}}\advance\count@\@ne% - \expandafter\@fmtspecs@i% + \expandafter\fmtspecs@i% \fi% } +\@namedef{descargs/method}#1#2{#1{{#2}}} +\@namedef{desclabel/method}#1#2#3#4% + {#2:\@mod@dispatch{modlabel}{#1}{#4}(#3)} +\@namedef{descindex/method}#1#2#3#4{% + \@mod@dispatch{modindex}{#1}{#4}!% + \protect\describecategoryname[#1]{#2}% + \protect\fmtspecs{ specialized at }{#3}% +} -%% \parse@dhd{NEXT}[MOD]{CAT}{...}...[NAME]{SYNOPSIS} -%% call NEXT{MOD}{CAT}{{...}...}{NAME}{SYNOPSIS} -%% #1 #2 #3 #4 #5 +%% Some magic strings. +\def\q@{\q@} \def\@setf{setf} \def\@starstar{**} + +%% \parse@dhd{NEXT}[MOD]{CAT}{...}...[NAME]{SYNOPSIS} +%% +%% Parse the arguments for a description header, and call +%% +%% NEXT{MOD}{CAT}{{...}...}{NAME}{SYNOPSIS} +%% +%% Here, {...}... represents the additional category-kind arguments. See +%% `describe' for what all of this means. \def\parse@dhd#1{% {NEXT} \@ifnextchar[{\parse@dhd@a{#1}}{\parse@dhd@c{#1}}} \def\parse@dhd@a#1[#2]#3{% {NEXT}[MOD]{CAT} @@ -302,7 +411,7 @@ \def\parse@dhd@cb#1#2#3{% {NEXT}{CAT}{{...}...} \@ifnextchar[{\parse@dhd@cc{#1}{#2}{#3}}{\parse@dhd@cd{#1}{#2}{#3}}} \def\parse@dhd@cc#1#2#3[#4]#5{% {NEXT}{CAT}{{...}...}[NAME]{SYNOPSIS} - #1{}{#2}{#3}{#4}{#5}} + #1{plain}{#2}{#3}{#4}{#5}} \def\parse@dhd@cd#1#2#3#4{% {NEXT}{CAT}{{...}...}{SYNOPSIS} \parse@dhd@ce{#1}{#2}{#3}{#4}#4 \q@} \def\parse@dhd@ce#1#2#3#4#5 #6\q@{% @@ -310,43 +419,51 @@ \def\temp@{#5}% \ifx\@setf\temp@\def\next@{\parse@dhd@csetf{#1}{#2}{#3}{#4}#6 \q@}% \else\def\temp@##1##2*##3\q@{\def\temp@{##1##3}}\temp@#5*\q@% - \ifx\temp@\@starstar\def\next@{\parse@dhd@cmuffs{#1}{#2}{#3}{#4}#5}% + \ifx\temp@\@starstar\def\next@{#1{muffs}{#2}{#3}{#5}{#4}}% \else\def\temp@##1##2\q@{\def\temp@{##1}}\temp@#5\q@% - \if:\temp@\def\next@{\parse@dhd@ckwd{#1}{#2}{#3}{#4}#5\q@}% - \else\def\next@{#1{}{#2}{#3}{#5}{#4}}\fi\fi\fi% + \if:\temp@\def\next@{#1{kwd}{#2}{#3}{#5}{#4}}% + \else\def\next@{#1{plain}{#2}{#3}{#5}{#4}}\fi\fi\fi% \next@% } \def\parse@dhd@csetf#1#2#3#4(#5 #6\q@{% % {NEXT}{CAT}{{...}...}{SYNOPSIS}(NAME [ARGS...])\q@ #1{setf}{#2}{#3}{#5}{#4}} -\def\parse@dhd@cmuffs#1#2#3#4*#5*{% - % {NEXT}{CAT}{{...}...}{SYNOPSIS}*NAME* - #1{muffs}{#2}{#3}{#5}{#4}} -\def\parse@dhd@ckwd#1#2#3#4:#5\q@{% - % {NEXT}{CAT}{{...}...}{SYNOPSIS}:NAME\q@ - #1{kwd}{#2}{#3}{#5}{#4}} +%% \dhead[MOD]{CAT}{...}...[NAME]{SYNOPSIS} +%% \dhead*[MOD]{CAT}{...}...[NAME]{SYNOPSIS} +%% +%% Typeset a description head. Use this within the first argument of +%% `describe*'; see `describe' for the details. +%% +%% With `*', don't set labels or add items to the index. \newif\if@dheadfirst -\def\dhead{\parse@dhd\dhead@} +\newif\if@dheadindex +\def\dhead{\@ifstar% + {\parse@dhd{\global\@dheadindexfalse\dhead@}}% + {\parse@dhd{\global\@dheadindextrue\dhead@}}} \def\dhead@#1#2#3#4#5{% {MOD}{CAT}{{...}...}{NAME}{SYNOPSIS} \if@dheadfirst\global\@dheadfirstfalse\else\relax\\*[\smallskipamount]\fi% - \phantomsection% - {\let\protect\@empty\let\@uscore\relax% - \edef\temp@{\@desc@dispatch{desclabel}{#2}{#2}{#1}{#4}#3}% - \def\@uscore{_\@gobble}\expandafter\message\expandafter{\temp@}% - \def\@uscore{-\@gobble}\expandafter\label\expandafter{\temp@}}% - {\begingroup\lccode`\~=`\_\lowercase{\endgroup\def~{_}}% - \protected@edef\@tempa##1{% - \noexpand\index{\@desc@dispatch{descindex}{#2}{#2}{#1}{#4}#3##1}}% - \toks@\expandafter{\@tempa{|)}}% - \toks\tw@\expandafter{\after@desc}% - \xdef\after@desc{\the\toks\tw@\the\toks@}% - \@tempa{|(}}% + \if@dheadindex% + \phantomsection% + {\let\protect\@empty\let\@uscore\relax% + \edef\temp@{\@desc@dispatch{desclabel}{#2}{#1}{#2}#3{#4}}% + \def\@uscore{_\@gobble}\expandafter\message\expandafter{\temp@}% + \def\@uscore{-\@gobble}\expandafter\label\expandafter{\temp@}}% + {\begingroup\lccode`\~=`\_\lowercase{\endgroup\def~{_}}% + \protected@edef\@tempa##1{% + \noexpand\index{\@desc@dispatch{descindex}{#2}{#1}{#2}#3{#4}##1}}% + \toks@\expandafter{\@tempa{|)}}% + \toks\tw@\expandafter{\after@desc}% + \xdef\after@desc{\the\toks\tw@\the\toks@}% + \@tempa{|(}}% + \fi% \rlap{\hb@xt@\linewidth{\hfil\normalfont\bfseries [\describecategoryname[#1]{#2}]}}% #5% } +%% Main guts of a description environment. The argument here typesets the +%% header line(s). \def\desc@begin#1{% \let\saved@after@desc\after@desc% \gdef\after@desc{}% @@ -363,38 +480,177 @@ } \def\desc@end{\endlist\after@desc\global\let\after@desc\saved@after@desc} -\def\@ifnextchar@preserve#1#2#3{% - \let\want@= #1\def\@tempa{#2}\def\@tempb{#3}% - \futurelet\nch@\@ifnch@p% +%% \begin{describe}[MOD]{CAT}{...}...[NAME]{SYNOPSIS} +%% ... +%% \end{describe} +%% +%% Describe some kind of program object. The CAT names the category of thing +%% being described -- this will be shown in the header, and index. The +%% SYNOPSIS is an implicit `prog' environment in which invoking the thing can +%% be summarized. +%% +%% The {...}... are any additional arguments required by the category's kind +%% (e.g., method specializers). +%% +%% The NAME is the name of the thing, which ends up in the index and +%% cross-reference label. If omitted, it defaults to the first word of the +%% SYNOPSIS, except that there are some special cases. +%% +%% The MOD is the modifier to apply. If omitted, it will usually default to +%% `plain', but in the absence of a NAME, some kinds of synopses are +%% recognized specially: +%% +%% * `setf (NAME ...) ...': selects NAME, and defaults MOD to `setf'. +%% +%% * `*NAME*': defaults MOD to `muffs'. +%% +%% * `:NAME': defaults MOD to `kwd'. +\def\describe{\parse@dhd\desc@} +\def\desc@#1#2#3#4#5{% + \global\@dheadindextrue% + \desc@begin{\dhead@{#1}{#2}{#3}{#4}{#5}}% } -\def\@ifnch@p{% - \ifx\want@\nch@\expandafter\@tempa\else\expandafter\@tempb\fi} +\let\enddescribe\desc@end +%% \begin{describe*} +%% {\dhead[MOD]{CAT}{...}...[NAME]{SYNOPSIS} +%% ...} +%% ... +%% \end{describe*} +%% +%% This is the fancy form of `describe' for describing several different +%% things at once. \@namedef{describe*}#1{\desc@begin{#1}} \expandafter\let\csname enddescribe*\endcsname\desc@end -\def\describe{\parse@dhd\desc@} -\def\desc@#1#2#3#4#5{\desc@begin{\dhead@{#1}{#2}{#3}{#4}{#5}}} -\let\enddescribe\desc@end +%% \parse@dlbl{NEXT}[MOD]{CAT}{...}...{LABEL} +%% +%% Parse a description label, and call +%% +%% NEXT{MOD}{CAT}{{...}...}{LABEL} +%% +%% This handles defaulting the MOD correctly, based on the LABEL text. See +%% `\descref' for the details. +\def\parse@dlbl#1{\@ifnextchar[{\parse@dlbl@a{#1}}{\parse@dlbl@c{#1}}} +\def\parse@dlbl@a#1[#2]#3{\@desc@dispatch{descargs}{#3}{#1{#2}{#3}}} +\def\parse@dlbl@c#1#2% + {\@desc@dispatch{descargs}{#2}{\parse@dlbl@cb{#1}{#2}}} +\def\parse@dlbl@cb#1#2#3#4{% + \def\temp@##1##2*##3\q@{\def\temp@{##1##3}}\temp@#4*\q@% + \ifx\temp@\@starstar\def\next@{#1{muffs}{#2}{#3}{#4}}% + \else\def\temp@##1##2\q@{\def\temp@{##1}}\temp@#4\q@% + \if:\temp@\def\next@{#1{kwd}{#2}{#3}{#4}} + \else\def\next@{#1{plain}{#2}{#3}{#4}}\fi\fi% + \next@% +} + +%% \descref[MOD]{CAT}{...}...{LABEL}[TEXT] +%% \descref*[MOD]{CAT}{...}...{LABEL} +%% +%% Typesets a cross-reference to a described thing. The CAT names the +%% category of thing being described, and the LABEL names the specific thing. +%% +%% The {...}... are any additional arguments required by the category's kind +%% (e.g., method specializers). +%% +%% The MOD is the modifier to apply, similar (but subtly different from) to +%% the `describe' environment. If omitted, it will usually default to +%% `plain', but in the absence of a NAME, some kinds of synopses are +%% recognized specially: +%% +%% * `*NAME*': defaults MOD to `muffs'. +%% +%% * `:NAME': defaults MOD to `kwd'. +%% +%% (`setf' is /not/ specially detected here. Write an explicit `setf' +%% modifier if necessary, because it's no more typing.) +%% +%% Usually a page-number cross-reference is included, so as to help readers +%% of a dead-tree copy; this is suppressed by the `*' version. \def\descref{\@ifstar% - {\descref@i{}\@gobble{}}% - {\descref@i{ (}{\noexpand\autopageref}{)}}} -\def\descref@i#1#2#3#4#5{\@ifnextchar@preserve[% - {\descref@ii{#1}{#2}{#3}{#4}{#5}}% - {\descref@iii{#1}{#2}{#3}{#4}{#5}{}}} -\def\descref@ii#1#2#3#4#5[#6]{\descref@iii{#1}{#2}{#3}{#4}{#5}{ #6}} -\def\descref@iii#1#2#3#4#5#6{% + {\parse@dlbl{\descref@i\relax\@gobble\relax}}% + {\parse@dlbl{\descref@i{ (}\autopageref)}}} +\def\descref@i#1#2#3#4#5#6#7{\@ifnextchar@preserve[% + % {PGA}{PGB}{PGC}{MOD}{CAT}{{...}...}{LABEL} + {\descref@ii{#1}{#2}{#3}{#4}{#5}{#6}{#7}}% + {\descref@iii{#1}{#2}{#3}{#4}{#5}{#6}{#7}{}}} +\def\descref@ii#1#2#3#4#5#6#7[#8]% + % {PGA}{PGB}{PGC}{MOD}{CAT}{{...}...}{LABEL}[AFTER] + {\descref@iii{#1}{#2}{#3}{#4}{#5}{#6}{#7}{ #8}} +\def\descref@iii#1#2#3#4#5#6#7#8{% + % {PGA}{PGB}{PGC}{MOD}{CAT}{{...}...}{LABEL}{AFTER} \begingroup% - \let\protect\@empty% - \def\@uscore{-\@gobble}% - \edef\@tempa##1{% - \endgroup% - \noexpand\hyperref[#4:#5]% - ##1% - #2{#4:#5}% - }% - \@tempa{{\code{#5}}#6#1}#3% + \let\protect\@empty\def\@uscore{-\@gobble}% + \edef\temp@{\@desc@dispatch{desclabel}{#5}{#4}{#5}#6{#7}}% + \edef\next@##1##2##3{\endgroup% + \noexpand\hyperref[\temp@]{##1}##2{\temp@}##3}% + \next@{\code{#7}}{#8#1#2}{#3}% +} + +%% \descindex[MOD]{CAT}{...}...{LABEL}[SUFFIX] +%% +%% Set a label and index entry here, as if for a description. The CAT names +%% the category of thing being described, and the LABEL names the specific +%% thing, as for `\descref'. The {...}... are any additional arguments +%% required by the category's kind (e.g., method specializers). The MOD is +%% the modifier to apply; see `\descref' for the details. +%% +%% The SUFFIX is appended to the index-entry text; by default it is empty. +%% Useful values are `|(' and `|)' to set ranges. +\def\descindex{\parse@dlbl\descindex@i} +\def\descindex@i#1#2#3#4{\@ifnextchar[% + {\descindex@ii{#1}{#2}{#3}{#4}}% + {\descindex@ii{#1}{#2}{#3}{#4}[]}} +\def\descindex@ii#1#2#3#4[#5]{% + {\begingroup\lccode`\~=`\_\lowercase{\endgroup\def~{_}}% + \protected@edef\@tempa{% + \noexpand\index{\@desc@dispatch{descindex}{#2}{#1}{#2}#3{#4}#5}}% + \@tempa}% } +%% \desclabel[MOD]{CAT}{...}...{LABEL}[INDEX-SUFFIX] +%% +%% Set a label and index entry here, as if for a description. The CAT names +%% the category of thing being described, and the LABEL names the specific +%% thing, as for `\descref'. The {...}... are any additional arguments +%% required by the category's kind (e.g., method specializers). The MOD is +%% the modifier to apply; see `\descref' for the details. +%% +%% This will also add an index entry, as for `\descindex'; the INDEX-SUFFIX +%% argument has the same effect as its SUFFIX argument. +\def\desclabel{\parse@dlbl\desclabel@i} +\def\desclabel@i#1#2#3#4{% + \begingroup% + \let\protect\@empty\def\@uscore{-\@gobble}% + \edef\@tempa{\@desc@dispatch{desclabel}{#2}{#1}{#2}#3{#4}}% + \phantomsection\label{\@tempa}% + \endgroup% + \descindex@i{#1}{#2}{#3}{#4}% +} + +%% Description categories. +\definedescribecategory{sym}{symbol} +\definedescribecategory{fun}{#1{function}} +\definedescribecategory{gf}{generic #1{function}} +\definedescribecategory{msg}{message} +\definedescribecategory{var}{variable} +\definedescribecategory{modvar}{module variable} +\definedescribecategory{const}{constant} +\definedescribecategory{meth}[method]{primary #1{method}} +\definedescribecategory{ar-meth}[method]{\code{:around} #1{method}} +\definedescribecategory{be-meth}[method]{\code{:before} #1{method}} +\definedescribecategory{af-meth}[method]{\code{:after} #1{method}} +\definedescribecategory{cls}{class} +\definedescribecategory{rst}{restart} +\definedescribecategory{ty}{type} +\definedescribecategory{mac}{#1{macro}} +\definedescribecategory{feat}{feature macro} +\definedescribecategory{lmac}{local #1{macro}} +\definedescribecategory{parse}{parser spec} +\definedescribecategory{parseform}{parser form} +\definedescribecategory{opt}{option handler} +\definedescribecategory{optmac}{option macro} +\definedescribecategory{plug}{pluggable parser} + %%%----- That's all, folks -------------------------------------------------- \endinput