doc/misc.tex: Document some more miscellaneous utilities.

[sod] / doc / sod.sty

diff --git a/doc/sod.sty b/doc/sod.sty
index 03d62f6..0452348 100644 (file)
--- a/doc/sod.sty
+++ b/doc/sod.sty
@@ -28,6 +28,8 @@
 %% More reference types.
 \defxref{p}{part}
 
+\def\instead#1#2{#1}
+
 %% Other languages with special typesetting.
 \def\Cplusplus{C\kern-\p@++}
 \def\Csharp{C\#}
@@ -187,9 +189,15 @@
 \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 descmod/#1\endcsname%
+  \expandafter\let\expandafter\@tempb\csname modcat/#1\endcsname%
   \ifx\@tempa\relax\@tempb{#2}\else\@tempa\@tempb\fi}
-\def\@maybe@modlabel#1#2{\if!#1!\else#1/\fi#2}
+\def\@mod@dispatch#1#2{\csname #1/#2\endcsname}
+\def\@desc@dispatch#1#2{%
+  \csname #1/%
+  \expandafter\ifx\csname catsw!#2\endcsname\relax plain%
+  \else \csname catsw!#2\endcsname \fi%
+  \endcsname%
+}
 
 \definedescribecategory{sym}{symbol}
 \definedescribecategory{fun}{#1{function}}
@@ -215,32 +223,38 @@
 \definedescribecategory{plug}{pluggable parser}
 \def\nlret{\\\hspace{4em}\returns}
 
-\@namedef{descmod/}#1{#1}
+\@namedef{modcat/}#1{#1}
+\@namedef{modlabel/}#1{#1}
+\@namedef{modindex/}#1{#1@\noexpand\code{#1}}
+
+\@namedef{modcat/setf}#1{\code{setf}-#1}
+\@namedef{modlabel/setf}#1{setf/#1}
+\@namedef{modindex/setf}#1{#1@\noexpand\code{#1}}
 
-\@namedef{descmod/setf}#1{\code{setf}-#1}
+\@namedef{modcat/muffs}#1{#1}
+\@namedef{modlabel/muffs}#1{*#1*}
+\@namedef{modindex/muffs}#1{#1@\noexpand\code{*#1*}}
+
+\@namedef{modcat/kwd}#1{#1}
+\@namedef{modlabel/kwd}#1{:#1}
+\@namedef{modindex/kwd}#1{#1@\noexpand\code{:#1}}
 
 \@namedef{descargs/plain}#1{#1{}}
-\@namedef{desclabel/plain}#1#2#3{#1:\@maybe@modlabel{#2}{#3}}
+\@namedef{desclabel/plain}#1#2#3{#1:\@mod@dispatch{modlabel}{#2}{#3}}
 \@namedef{descindex/plain}#1#2#3{%
-  #3@\noexpand\code{#3}!%
+  \@mod@dispatch{modindex}{#2}{#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{desclabel/method}#1#2#3#4%
+  {#1:\@mod@dispatch{modlabel}{#2}{#3}(#4)}
 \@namedef{descindex/method}#1#2#3#4{%
-  #3@\noexpand\code{#3}!%
+  \@mod@dispatch{modindex}{#2}{#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}
 
@@ -267,6 +281,7 @@
 %% call NEXT{MOD}{CAT}{{...}...}{NAME}{SYNOPSIS}
 %%            #1   #2      #3     #4      #5
 \def\@setf{setf}
+\def\@starstar{**}
 \def\parse@dhd#1{%  {NEXT}
   \@ifnextchar[{\parse@dhd@a{#1}}{\parse@dhd@c{#1}}}
 \def\parse@dhd@a#1[#2]#3{%  {NEXT}[MOD]{CAT}
@@ -293,12 +308,22 @@
   % {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%
+  \else\def\temp@##1##2*##3\q@{\def\temp@{##1##3}}\temp@#5*\q@%
+    \ifx\temp@\@starstar\def\next@{\parse@dhd@cmuffs{#1}{#2}{#3}{#4}#5}%
+    \else\def\temp@##1##2\q@{\def\temp@{##1}}\temp@#5\q@%
+      \if:\temp@\def\next@{\parse@dhd@ckwd{#1}{#2}{#3}{#4}#5\q@}%
+      \else\def\next@{#1{}{#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}}
+\def\parse@dhd@cmuffs#1#2#3#4*#5*{%
+  % {NEXT}{CAT}{{...}...}{SYNOPSIS}*NAME*
+  #1{muffs}{#2}{#3}{#5}{#4}}
+\def\parse@dhd@ckwd#1#2#3#4:#5\q@{%
+  % {NEXT}{CAT}{{...}...}{SYNOPSIS}:NAME\q@
+  #1{kwd}{#2}{#3}{#5}{#4}}
 
 \newif\if@dheadfirst
 \def\dhead{\parse@dhd\dhead@}
@@ -337,19 +362,37 @@
 }
 \def\desc@end{\endlist\after@desc\global\let\after@desc\saved@after@desc}
 
+\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}
+
 \@namedef{describe*}#1{\desc@begin{#1}}
 \expandafter\let\csname enddescribe*\endcsname\desc@end
 \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{%
-  \code{#1}#2 (page~%
-  {\let\protect\@empty%
-   \def\@uscore{-\@gobble}\edef\@tempa{\noexpand\pageref{#3:#1}}\@tempa}%
-  )%
+\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[#4:#5]%
+      ##1%
+      #2{#4:#5}%
+    }%
+  \@tempa{{\code{#5}}#6#1}#3%
 }
 
 %%%----- That's all, folks --------------------------------------------------