doc/sod.sty: Add commentary to help following `\parse@dhd' and friends.

Mostly just comments and newlines, but two code changes:

  * the internal steps of `\parse@dhd' have been renamed to anticipate
    future developments; and

  * `\parse@dhd@cc' has been uncurried.

diff --git a/doc/sod.sty b/doc/sod.sty
index 467d74b..d3e7740 100644 (file)
--- a/doc/sod.sty
+++ b/doc/sod.sty
@@ -210,14 +210,23 @@
 \def\nlret{\\\hspace{4em}\returns}
 
 \def\q@{\q@}
-\def\parse@dhd#1{\@ifnextchar[{\parse@dhd@a{#1}}{\parse@dhd@c{#1}}}
-\def\parse@dhd@a#1[#2]{#1{#2}}
-\def\parse@dhd@c#1#2#3{\parse@dhd@cc{#1}{#2}{#3}#3 \q@}
-\def\parse@dhd@cc#1#2#3#4 #5\q@{#1{#4}{#2}{#3}}
+
+%% \parse@dhd{NEXT}[NAME]{CAT}{SYNOPSIS}
+%% call NEXT{NAME}{CAT}{SYNOPSIS}
+%%            #1    #2     #3
+\def\parse@dhd#1{%  {NEXT}
+  \@ifnextchar[{\parse@dhd@cc{#1}}{\parse@dhd@cd{#1}}}
+\def\parse@dhd@cc#1[#2]#3#4{%  {NEXT}[NAME]{CAT}{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@
+  #1{#4}{#2}{#3}}
 
 \newif\if@dheadfirst
 \def\dhead{\parse@dhd\dhead@}
-\def\dhead@#1#2#3{%
+\def\dhead@#1#2#3{%  {NAME}{CAT}{SYNOPSIS}
   \if@dheadfirst\global\@dheadfirstfalse\else\relax\\[\smallskipamount]\fi%
   {\let\protect\@empty\def\@uscore{_\@gobble}\message{#2:#1}%
    \def\@uscore{-\@gobble}\edef\@tempa{\noexpand\label{#2:#1}}\@tempa}%