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'.

diff --git a/doc/lispintro.tex b/doc/lispintro.tex
index c628a2c..9497164 100644 (file)
--- 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 @<required>
+\begin{describe*}{\dhead*{fun}{example-function @<required>}
     \&optional @<optional>
     \&rest @<rest>
     \&key :keyword
@@ -179,14 +179,15 @@ category (function, class, macro, etc.) on the right.
     some-generic-function ((@<specialized> list) @<unspecialized>)
       @> @<result>
   \end{quote}
-\end{describe}
-
-\begin{describe}{mac}
-    {example-macro
-        (@{ @<symbol> @! (@<symbol> @<form>) @}^*)              \\ \ind
-      @[[ @<declaration>^* @! @<doc-string> @]]                 \\
-      @<form>^*
-     \nlret @<value>^*}
+\end{describe*}
+
+\begin{describe*}
+    {\dhead*{mac}
+      {example-macro
+          (@{ @<symbol> @! (@<symbol> @<form>) @}^*)            \\ \ind
+        @[[ @<declaration>^* @! @<doc-string> @]]               \\
+        @<form>^*
+       \nlret @<value>^*}}
   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 (file)
--- 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}}