X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/ca2023b8567b5e012b373eff8544be7920ce5c17..82567ea97e4f9374e8a3d586ea49ad9bf3dff3dc:/doc/sod.sty diff --git a/doc/sod.sty b/doc/sod.sty index 457dcad..69b4d3d 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. @@ -106,7 +114,7 @@ %% 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,64 @@ \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;} + +%% 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. -%% 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. +%% Main guts of `prog' and `nprog'. \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} + +%% 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,80 +216,87 @@ \def\@progcr@ii#1{\csname @progcr@#1\endcsname\ignorespaces} \@namedef{@progcr@+}{\prog@@cr[\medskipamount]} \@namedef{@progcr@-}{\prog@@cr*[\jot]} -\def\macsl{\`\textbackslash\hskip\leftmargin} +{\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} -%% 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{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} - +%% Modifier methods for the default empty modifier. \@namedef{modcat/}#1{#1} \@namedef{modlabel/}#1{#1} \@namedef{modindex/}#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*}} +%% 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}} +%% Category-kind methods for plain categories. \@namedef{descargs/plain}#1{#1{}} \@namedef{desclabel/plain}#1#2#3{#1:\@mod@dispatch{modlabel}{#2}{#3}} \@namedef{descindex/plain}#1#2#3{% @@ -246,19 +304,10 @@ \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}% -} - -\def\q@{\q@} -\def\@setf{setf} - -\def\fmtspecs#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}% @@ -276,12 +325,28 @@ \expandafter\@fmtspecs@i% \fi% } +\@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}% +} -%% \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} @@ -325,6 +390,10 @@ % {NEXT}{CAT}{{...}...}{SYNOPSIS}:NAME\q@ #1{kwd}{#2}{#3}{#5}{#4}} +%% \dhead[MOD]{CAT}{...}...[NAME]{SYNOPSIS} +%% +%% Typeset a description head. Use this within the first argument of +%% `describe*'; see `describe' for the details. \newif\if@dheadfirst \def\dhead{\parse@dhd\dhead@} \def\dhead@#1#2#3#4#5{% {MOD}{CAT}{{...}...}{NAME}{SYNOPSIS} @@ -346,6 +415,8 @@ #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{}% @@ -362,26 +433,110 @@ } \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*': selects NAME, without the earmuffs, and defaults MOD to +%% `muffs'. +%% +%% * `:NAME': selects NAME, withtout the colon, and defaults MOD to `kwd'. \def\describe{\parse@dhd\desc@} \def\desc@#1#2#3#4#5{\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{% +%% \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 + +%% \descref{CAT}{...}...{LABEL}[TEXT] +%% \descref*{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 precise rules for how the LABEL matches the name in the description +%% depend on the description's modifier: +%% +%% * `plain': the LABEL is the same as the NAME. +%% * `setf': the LABEL should be `setf/NAME'. +%% * `muffs': the LABEL should be `*NAME*', i.e., with the earmuffs +%% restored. +%% * `kwd: the LABEL should be `:NAME', i.e., with the colon restored. +%% +%% 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{% \begingroup% \let\protect\@empty% \def\@uscore{-\@gobble}% \edef\@tempa##1{% \endgroup% - \noexpand\hyperref[#3:#1]% + \noexpand\hyperref[#4:#5]% ##1% - \noexpand\autopageref{#3:#1}% + #2{#4:#5}% }% - \@tempa{{\code{#1}}#2 (})% + \@tempa{{\code{#5}}#6#1}#3% } +%% 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