From 87883222727894b13d3d4ce50e413a544a50fe20 Mon Sep 17 00:00:00 2001 From: Mark Wooding Date: Sun, 28 Jul 2019 03:10:23 +0100 Subject: [PATCH] doc/sod.sty, doc/*.tex: Support category-specific arguments. Now description categories can accept arguments and influence labels and indexing. Use this to collect method specializers and report them in the index. --- doc/clang.tex | 17 +++++---- doc/meta.tex | 11 +++--- doc/output.tex | 2 +- doc/parsing.tex | 32 ++++++++++------ doc/sod.sty | 112 ++++++++++++++++++++++++++++++++++++++------------------ 5 files changed, 113 insertions(+), 61 deletions(-) diff --git a/doc/clang.tex b/doc/clang.tex index 08aac24..b572fe4 100644 --- a/doc/clang.tex +++ b/doc/clang.tex @@ -208,12 +208,12 @@ argument lists for methods. This is done by @|c-type-equal-p|. The generic function @|c-type-equal-p| uses the @|and| method combination. - \begin{describe}{meth}{c-type-equal-p @_1 @_2} + \begin{describe}{meth}{t,t}{c-type-equal-p @_1 @_2} A default primary method for @|c-type-equal-p| is defined. It simply returns @|nil|. This way, methods can specialize on both arguments without fear that a call will fail because no methods are applicable. \end{describe} - \begin{describe}{ar-meth}{c-type-equal-p @_1 @_2} + \begin{describe}{ar-meth}{}{c-type-equal-p @_1 @_2} A default around-method for @|c-type-equal-p| is defined. It returns true if @_1 and @_2 are @|eql|; otherwise it delegates to the primary methods. Since several common kinds of C types are interned, @@ -270,7 +270,7 @@ argument lists for methods. This is done by @|c-type-equal-p|. Every concrete subclass of @|c-type| is expected to provide a primary method on this function. There is no default primary method. - \begin{describe}{ar-meth}{pprint-c-type @ @ @} + \begin{describe}{ar-meth}{}{pprint-c-type @ @ @} A default around method is defined on @|pprint-c-type| which `canonifies' non-function @ arguments. In particular: \begin{itemize} @@ -375,7 +375,8 @@ methods to \descref{c-qualifier-keyword}{gf}. methods exist for qualifier keywords which need special handling, such as @|:atomic|; they are not listed here explicitly. - \begin{describe}{meth}{c-qualifier-keyword @ @> @} + \begin{describe}{meth}{keyword} + {c-qualifier-keyword @ @> @} Returns the @'s print-name, in lower case. This is sufficient for the standard qualifiers @|:const|, @|:restrict|, and @|:volatile|. \end{describe} @@ -844,11 +845,13 @@ function type is the type of the function's return value. including file from defining such names as macros. This generic function is used to convert names into a safe form. - \begin{describe}{meth}{commentify-argument-name (@ null) @> nil} + \begin{describe}{meth}{null} + {commentify-argument-name (@ null) @> nil} Returns nil: if the argument name is already omitted, it's safe for use in a header file. \end{describe} - \begin{describe}{meth}{commentify-argument-name (@ t) @> @} + \begin{describe}{meth}{t} + {commentify-argument-name (@ t) @> @} Returns the print form of @ wrapped in a C comment, as @`/*@*/'. \end{describe} @@ -1164,7 +1167,7 @@ Temporary names are represented by objects which implement a simple protocol. subclasses, but is also usable on its own. \end{describe} -\begin{describe}{meth} +\begin{describe}{meth}{temporary-name} {commentify-argument-name (@ temporary-name) @> nil} \end{describe} diff --git a/doc/meta.tex b/doc/meta.tex index 66d4e67..05a6fc0 100644 --- a/doc/meta.tex +++ b/doc/meta.tex @@ -334,10 +334,10 @@ \end{describe} \begin{describe}{gf}{check-class-initializer @ @} - \begin{describe}{meth} + \begin{describe}{meth}{effective-slot,sod-class} {check-class-initializer (@ effective-slot) (@ sod-class)} \end{describe} - \begin{describe}{meth} + \begin{describe}{meth}{sod-class-effective-slot,sod-class} {check-class-initializer (@ sod-class-effective-slot) (@ sod-class)} \end{describe} @@ -347,10 +347,11 @@ \end{describe} \begin{describe}{gf}{finalize-sod-class @ @> @} - \begin{describe}{meth}{finalize-sod-class (@ sod-class)} + \begin{describe}{meth}{sod-class} + {finalize-sod-class (@ sod-class)} \end{describe} - \begin{describe}{ar-meth}{finalize-sod-class (@ sod-class) - @> @} + \begin{describe}{ar-meth}{sod-class} + {finalize-sod-class (@ sod-class) @> @} \end{describe} \end{describe} diff --git a/doc/output.tex b/doc/output.tex index 4571b6a..37ab159 100644 --- a/doc/output.tex +++ b/doc/output.tex @@ -150,7 +150,7 @@ until the third. So the final processing order is \end{describe} \begin{describe}{gf}{hook-output progn @ @ @} - \begin{describe}{meth} + \begin{describe}{meth}{t,t} {hook-output progn (@ t) (@ t) @} \end{describe} \end{describe} diff --git a/doc/parsing.tex b/doc/parsing.tex index 4cb6ef1..8aeb26b 100644 --- a/doc/parsing.tex +++ b/doc/parsing.tex @@ -71,18 +71,21 @@ consumed any input items. \end{describe*} \begin{describe}{gf}{file-location @ @> @} - \begin{describe}{meth}{file-location (@ file-location) @> @} + \begin{describe}{meth}{file-location} + {file-location (@ file-location) @> @} \end{describe} - \begin{describe}{meth}{file-location (@ stream) @> @} + \begin{describe}{meth}{stream} + {file-location (@ stream) @> @} \end{describe} - \begin{describe}{meth}{file-location (@ t) @> @} + \begin{describe}{meth}{t} + {file-location (@ t) @> @} \end{describe} \end{describe} \begin{describe}{cls}{condition-with-location (condition) \&key :location} \end{describe} -\begin{describe}{meth} +\begin{describe}{meth}{condition-with-location} {file-location (@ condition-with-location) @> @} \end{describe} @@ -175,14 +178,19 @@ consumed any input items. \begin{describe}{gf}{classify-condition @ @> @} \begin{describe*} - {\dhead{meth}{classify-condition (@ error) @> @} - \dhead{meth}{classify-condition (@ warning) @> @} - \dhead{meth}{classify-condition (@ information) - @> @} - \dhead{meth}{classify-condition (@ base-lexer-error) - @> @} - \dhead{meth}{classify-condition (@ base-syntax-error) - @> @}} + {\dhead{meth}{error} + {classify-condition (@ error) @> @} + \dhead{meth}{warning} + {classify-condition (@ warning) @> @} + \dhead{meth}{information} + {classify-condition (@ information) + @> @} + \dhead{meth}{base-lexer-error} + {classify-condition (@ base-lexer-error) + @> @} + \dhead{meth}{base-syntax-error} + {classify-condition (@ base-syntax-error) + @> @}} \end{describe*} \end{describe} diff --git a/doc/sod.sty b/doc/sod.sty index 293411c..43b77cc 100644 --- a/doc/sod.sty +++ b/doc/sod.sty @@ -181,7 +181,9 @@ } %% Lisp documentation machinery. -\def\definedescribecategory#1#2{\@namedef{cat!#1}##1{#2}} +\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}} \def\describecategoryname{\@ifnextchar[\@descname@i{\@descname@i[]}} \def\@descname@i[#1]#2{% \expandafter\let\expandafter\@tempa\csname cat!#2\endcsname% @@ -196,10 +198,10 @@ \definedescribecategory{var}{variable} \definedescribecategory{modvar}{module variable} \definedescribecategory{const}{constant} -\definedescribecategory{meth}{primary #1{method}} -\definedescribecategory{ar-meth}{\code{:around} #1{method}} -\definedescribecategory{be-meth}{\code{:before} #1{method}} -\definedescribecategory{af-meth}{\code{:after} #1{method}} +\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} @@ -217,52 +219,90 @@ \@namedef{descmod/setf}#1{\code{setf}-#1} +\@namedef{descargs/plain}#1{#1{}} +\@namedef{desclabel/plain}#1#2#3{#1:\@maybe@modlabel{#2}{#3}} +\@namedef{descindex/plain}#1#2#3{% + #3@\noexpand\code{#3}!% + \protect\describecategoryname[#2]{#1}% +} + +\@namedef{descargs/method}#1#2{#1{{#2}}} +\@namedef{desclabel/method}#1#2#3#4{#1:\@maybe@modlabel{#2}{#3}(#4)} +\@namedef{descindex/method}#1#2#3#4{% + #3@\noexpand\code{#3}!% + \protect\describecategoryname[#2]{#1}% + \protect\fmtspecs{ specialized at }{#4}% +} + +\def\@desc@dispatch#1#2{% + \csname #1/% + \expandafter\ifx\csname catsw!#2\endcsname\relax plain% + \else \csname catsw!#2\endcsname \fi% + \endcsname% +} + \def\q@{\q@} \def\@setf{setf} -%% \parse@dhd{NEXT}{CAT}[NAME]{SYNOPSIS} -%% call NEXT{MOD}{CAT}{NAME}{SYNOPSIS} -%% #1 #2 #3 #4 +\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% +} + +%% \parse@dhd{NEXT}{CAT}{...}...[NAME]{SYNOPSIS} +%% call NEXT{MOD}{CAT}{{...}...}{NAME}{SYNOPSIS} +%% #1 #2 #3 #4 #5 \def\parse@dhd#1#2{% {NEXT}{CAT} - \@ifnextchar[{\parse@dhd@cc{#1}{#2}}{\parse@dhd@cd{#1}{#2}}} -\def\parse@dhd@cc#1#2[#3]#4{% {NEXT}{CAT}[NAME]{SYNOPSIS} - #1{}{#2}{#3}{#4}} -\def\parse@dhd@cd#1#2#3{% {NEXT}{CAT}{SYNOPSIS} - \parse@dhd@ce{#1}{#2}{#3}#3 \q@} -\def\parse@dhd@ce#1#2#3#4 #5\q@{% - % {NEXT}{CAT}{SYNOPSIS}NAME [ARGS...]\q@ - \def\temp@{#4}% - \ifx\temp@\@setf\def\next@{\parse@dhd@csetf{#1}{#2}{#3}#5 \q@}% - \else\def\next@{#1{}{#2}{#4}{#3}}\fi% + \@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{}{#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\next@{#1{}{#2}{#3}{#5}{#4}}\fi% \next@% } -\def\parse@dhd@csetf#1#2#3(#4 #5\q@{% - % {NEXT}{CAT}{SYNOPSIS}(NAME [ARGS...])\q@ - #1{setf}{#2}{#4}{#3}} +\def\parse@dhd@csetf#1#2#3#4(#5 #6\q@{% + % {NEXT}{CAT}{{...}...}{SYNOPSIS}(NAME [ARGS...])\q@ + #1{setf}{#2}{#3}{#5}{#4}} \newif\if@dheadfirst \def\dhead{\parse@dhd\dhead@} -\def\dhead@#1#2#3#4{% {}{CAT}{NAME}{SYNOPSIS} +\def\dhead@#1#2#3#4#5{% {MOD}{CAT}{{...}...}{NAME}{SYNOPSIS} \if@dheadfirst\global\@dheadfirstfalse\else\relax\\[\smallskipamount]\fi% {\let\protect\@empty\let\@uscore\relax% - \edef\temp@{#2:\@maybe@modlabel{#1}{#3}}% - \def\@uscore{_\@gobble}\message{\temp@}% - \def\@uscore{-\@gobble}\label{\temp@}}% + \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{% - #3@{\noexpand\code{#3}}!% - \protect\describecategoryname[#1]{#2}% - ##1% - }% - }% - \toks@\expandafter{\after@desc}% - \toks\tw@\expandafter{\@tempa{|)}}% - \xdef\after@desc{\the\toks@\the\toks\tw@}% + \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{|(}}% \rlap{\hb@xt@\linewidth{\hfil\normalfont\bfseries [\describecategoryname[#1]{#2}]}}% - #4% + #5% } \def\desc@begin#1{% @@ -284,7 +324,7 @@ \@namedef{describe*}#1{\desc@begin{#1}} \expandafter\let\csname enddescribe*\endcsname\desc@end \def\describe{\parse@dhd\desc@} -\def\desc@#1#2#3#4{\desc@begin{\dhead@{#1}{#2}{#3}{#4}}} +\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}{}}} -- 2.11.0