From a6ec8b3f5bd19ad4a2a6fc950639cdff196eea2c Mon Sep 17 00:00:00 2001 From: Mark Wooding Date: Wed, 7 Aug 2019 16:26:34 +0100 Subject: [PATCH] doc/sod.sty: Provide explicit description labelling and indexing commands. And a `\dhead*' which suppresses the usual labelling and indexing, for the sake of special effects. Use this new machinery to inhibit the (possibly confusing) indexing on the example entries in `lispintro.tex'. --- doc/lispintro.tex | 28 ++++++++++--------- doc/sod.sty | 80 +++++++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 81 insertions(+), 27 deletions(-) diff --git a/doc/lispintro.tex b/doc/lispintro.tex index c628a2c..9497164 100644 --- a/doc/lispintro.tex +++ b/doc/lispintro.tex @@ -153,7 +153,7 @@ Most symbols defined by the protocol have their own entries. An entry begins with a header line, showing a synopsis of the symbol on the left, and the category (function, class, macro, etc.) on the right. -\begin{describe}{fun}{example-function @ +\begin{describe*}{\dhead*{fun}{example-function @} \&optional @ \&rest @ \&key :keyword @@ -179,14 +179,15 @@ category (function, class, macro, etc.) on the right. some-generic-function ((@ list) @) @> @ \end{quote} -\end{describe} - -\begin{describe}{mac} - {example-macro - (@{ @ @! (@ @
) @}^*) \\ \ind - @[[ @^* @! @ @]] \\ - @^* - \nlret @^*} +\end{describe*} + +\begin{describe*} + {\dhead*{mac} + {example-macro + (@{ @ @! (@ @) @}^*) \\ \ind + @[[ @^* @! @ @]] \\ + @^* + \nlret @^*}} The synopsis for a macro describes the acceptable syntax using the following notation. \begin{itemize} @@ -209,10 +210,11 @@ category (function, class, macro, etc.) on the right. \end{itemize} For example, the notation at the head of this example describes syntax for @|let|. -\end{describe} +\end{describe*} -\begin{describe}{cls}{example-class (direct-super other-direct-super) \&key - :initarg} +\begin{describe*} + {\dhead*{cls}{example-class (direct-super other-direct-super) + \&key :initarg}} The synopsis for a class lists the class's direct superclasses, and the acceptable initargs in the form of a lambda-list. The initargs may be passed to @|make-instance| when constructing an instance of the class or a @@ -221,7 +223,7 @@ category (function, class, macro, etc.) on the right. may also be passed to @|reinitialize-instance| and/or @|change-class| as applicable; the class description will state explicitly when these operations are allowed. -\end{describe} +\end{describe*} %%%----- That's all, folks -------------------------------------------------- diff --git a/doc/sod.sty b/doc/sod.sty index 4d50de9..4d2f407 100644 --- a/doc/sod.sty +++ b/doc/sod.sty @@ -386,25 +386,33 @@ #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@} +\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}{#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{|(}}% + \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% @@ -454,7 +462,10 @@ %% %% * `:NAME': defaults MOD to `kwd'. \def\describe{\parse@dhd\desc@} -\def\desc@#1#2#3#4#5{\desc@begin{\dhead@{#1}{#2}{#3}{#4}{#5}}} +\def\desc@#1#2#3#4#5{% + \global\@dheadindextrue% + \desc@begin{\dhead@{#1}{#2}{#3}{#4}{#5}}% +} \let\enddescribe\desc@end %% \begin{describe*} @@ -532,6 +543,47 @@ \endgroup% } +%% \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}} -- 2.11.0