X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/4effe5759a1229be4ce152db87172119ddcb45bb..12949379840101e2d65883f29c5e8f0f6de49e9c:/doc/sod.sty diff --git a/doc/sod.sty b/doc/sod.sty index 9c9aaf8..9da7def 100644 --- a/doc/sod.sty +++ b/doc/sod.sty @@ -25,9 +25,19 @@ \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. \def\Cplusplus{C\kern-\p@++} \def\Csharp{C\#} @@ -57,18 +67,28 @@ %% Listings don't need to be small. \let\listingsize\relax +%% Notes for later. +\def\fixme#1{\leavevmode\marginpar{FIXME}\index{FIXME}[FIXME: #1]} + +%% Diagram settings. +\tikzset{ + every picture/.style={>=stealth, thick}, + lit/.style={font=\sffamily} +} + %% Metavariables are italics without decoration. \def\syntleft{\normalfont\itshape} \let\syntright\empty %% Literal code is in sans face. -\let\codeface\sffamily +\def\codeface{\upshape\sffamily} \DeclareRobustCommand\code[1]{% \ifmmode\hbox\else\leavevmode\fi% {\normalfont\codeface\/#1\/}% } \def\ulitleft{\normalfont\codeface} \let\ulitright\empty +\def\lit@i#1#2#3{\ifmmode\leavevmode\hbox\fi{#1{#3\/}#2}} %% Conditionally enter maths mode. Can't use \ensuremath here because we %% aren't necessarily sure where the maths will actually end. @@ -79,22 +99,22 @@ \atdef <#1>{\synt{#1}\@scripts} \atdef "#1"{\lit*{#1}\@scripts} \atdef `#1'{\lit{#1}\@scripts} -\atdef |#1|{\textsf{#1}\@scripts} +\atdef |#1|{\lit*{#1}\@scripts} %% A handy abbreviation; `\\' itself is too good to steal. \atdef \\{\textbackslash} %% 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} @@ -104,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. @@ -114,24 +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. -\atdef ;#1\\{\normalfont\itshape;#1\\} +\def\comment#1{\mbox{\normalfont\itshape\/#1\/}} +\atdef /*#1*/{/*\comment{#1}*/} +\def\@semis;{\@ifnextchar@preserve;{;\@semis}\@semicomment} +\def\@semicomment#1\\{\comment{#1}\\} +\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}} \def\@progcr@i{% \ifx\@tempa\@sptoken\let\next@\@progcr@sp\else \if1\ifx\@tempa[1\else @@ -148,79 +225,245 @@ \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 -%% 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% +%% 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} + +%% \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. -\def\definedescribecategory#1#2{\@namedef{cat!#1}{#2}} -\def\describecategoryname#1{% - \expandafter\let\expandafter\@tempa\csname cat!#1\endcsname% - \ifx\@tempa\relax#1\else\@tempa\fi} -\definedescribecategory{sym}{symbol} -\definedescribecategory{fun}{function} -\definedescribecategory{gf}{generic function} -\definedescribecategory{msg}{message} -\definedescribecategory{var}{variable} -\definedescribecategory{modvar}{module variable} -\definedescribecategory{const}{constant} -\definedescribecategory{meth}{primary method} -\definedescribecategory{ar-meth}{around method} -\definedescribecategory{be-meth}{before method} -\definedescribecategory{af-meth}{after method} -\definedescribecategory{cls}{class} -\definedescribecategory{ty}{type} -\definedescribecategory{type}{type} -\definedescribecategory{mac}{macro} -\definedescribecategory{lmac}{local 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} +%%%-------------------------------------------------------------------------- +%%% 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% + \endcsname% +} + +%% 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{\@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{\@gobble#1@\noexpand\code{#1}} + +%% Category-kind methods for plain categories. +\@namedef{descargs/plain}#1{#1{}} +\@namedef{desclabel/plain}#1#2#3{#2:\@mod@dispatch{modlabel}{#1}{#3}} +\@namedef{descindex/plain}#1#2#3{% + \@mod@dispatch{modindex}{#1}{#3}!% + \protect\describecategoryname[#1]{#2}% +} + +%% 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,{% + \def\@tempa{#1}% + \ifx\@tempa\q@% + \ifcase\count@(no args?!)% + \or% nothin' doin + \or \space and % + \else, and % + \fi% + \the\toks@% + \else% + \ifnum\count@>\@ne, \fi% + \the\toks@% + \toks@{\code{#1}}\advance\count@\@ne% + \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}% +} + +%% Some magic strings. \def\q@{\q@} -\def\parse@dhd#1{\@ifnextchar[{\parse@dhd@a{#1}}{\parse@dhd@c{#1}}} -\def\parse@dhd@a#1[#2]{#1{#2}} -\def\parse@dhd@c#1#2#3{\parse@dhd@cc{#1}{#2}{#3}#3 \q@} -\def\parse@dhd@cc#1#2#3#4 #5\q@{#1{#4}{#2}{#3}} +\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} + \@desc@dispatch{descargs}{#3}{\parse@dhd@ab{#1}{#2}{#3}}} +\def\parse@dhd@ab#1#2#3#4{% {NEXT}{MOD}{CAT}{{...}...} + \@ifnextchar[{\parse@dhd@ac{#1}{#2}{#3}{#4}}{\parse@dhd@ad{#1}{#2}{#3}{#4}}} +\def\parse@dhd@ac#1#2#3#4[#5]#6{% {NEXT}{MOD}{CAT}{{...}...}[NAME]{SYNOPSIS} + #1{#2}{#3}{#4}{#5}{#6}} +\def\parse@dhd@ad#1#2#3#4#5{% {NEXT}{MOD}{CAT}{{...}...}{NAME [ARGS...]} + \parse@dhd@ae{#1}{#2}{#3}{#4}{#5}#5 \q@} +\def\parse@dhd@ae#1#2#3#4#5#6 #7\q@{% + % {NEXT}{MOD}{CAT}{{...}...}{SYNSOPSIS}NAME [ARGS...]\q@ + #1{#2}{#3}{#4}{#6}{#5}} +\def\parse@dhd@c#1#2{% {NEXT}{CAT} + \@desc@dispatch{descargs}{#2}{\parse@dhd@cb{#1}{#2}}} +\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{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@{% + % {NEXT}{CAT}{{...}...}{SYNOPSIS}NAME [ARGS...]\q@ + \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@{#1{muffs}{#2}{#3}{#5}{#4}}% + \else\def\temp@##1##2\q@{\def\temp@{##1}}\temp@#5\q@% + \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}} + +%% \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@} -\def\dhead@#1#2#3{% - \if@dheadfirst\global\@dheadfirstfalse\else\relax\\[\smallskipamount]\fi% - {\let\protect\@empty\def\@uscore{_\@gobble}\message{#2:#1}% - \def\@uscore{-\@gobble}\edef\@tempa{\noexpand\label{#2:#1}}\@tempa}% - {\begingroup\lccode`\~=`\_\lowercase{\endgroup\def~{_}}% - \protected@edef\@tempa##1{% - \noexpand\index{% - #1@{\noexpand\code{#1}}!% - \csname cat!#2\endcsname% - ##1% - }% - }% - \@tempa{|(}% - \toks@\expandafter{\after@desc}% - \toks\tw@\expandafter{\@tempa{|)}}% - \xdef\after@desc{\the\toks@\the\toks\tw@}}% +\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% + \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{#2}]}}% - #3% + [\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{}% @@ -237,20 +480,177 @@ } \def\desc@end{\endlist\after@desc\global\let\after@desc\saved@after@desc} -\@namedef{describe*}#1{\desc@begin{#1}} -\expandafter\let\csname enddescribe*\endcsname\desc@end +%% \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{\desc@begin{\dhead@{#1}{#2}{#3}}} +\def\desc@#1#2#3#4#5{% + \global\@dheadindextrue% + \desc@begin{\dhead@{#1}{#2}{#3}{#4}{#5}}% +} \let\enddescribe\desc@end -\def\descref#1{\@ifnextchar[{\descref@i{#1}}{\descref@ii{#1}{}}} -\def\descref@i#1[#2]{\descref@ii{#1}{ #2}} -\def\descref@ii#1#2#3{% - \code{#1}#2 (page~% - {\let\protect\@empty% - \def\@uscore{-\@gobble}\edef\@tempa{\noexpand\pageref{#3:#1}}\@tempa}% - )% +%% \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 + +%% \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% + {\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\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