Commit | Line | Data |
---|---|---|
1f7d590d MW |
1 | %%% -*-latex-*- |
2 | %%% | |
3 | %%% Styles and other hacking for the Sod manual | |
4 | %%% | |
5 | %%% (c) 2015 Straylight/Edgeware | |
6 | %%% | |
7 | ||
8 | %%%----- Licensing notice --------------------------------------------------- | |
9 | %%% | |
e0808c47 | 10 | %%% This file is part of the Sensible Object Design, an object system for C. |
1f7d590d MW |
11 | %%% |
12 | %%% SOD is free software; you can redistribute it and/or modify | |
13 | %%% it under the terms of the GNU General Public License as published by | |
14 | %%% the Free Software Foundation; either version 2 of the License, or | |
15 | %%% (at your option) any later version. | |
16 | %%% | |
17 | %%% SOD is distributed in the hope that it will be useful, | |
18 | %%% but WITHOUT ANY WARRANTY; without even the implied warranty of | |
19 | %%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
20 | %%% GNU General Public License for more details. | |
21 | %%% | |
22 | %%% You should have received a copy of the GNU General Public License | |
23 | %%% along with SOD; if not, write to the Free Software Foundation, | |
24 | %%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. | |
25 | ||
26 | \ProvidesPackage{sod} | |
27 | ||
82567ea9 MW |
28 | %%%-------------------------------------------------------------------------- |
29 | %%% Basic style things. | |
30 | ||
1f7d590d MW |
31 | %% More reference types. |
32 | \defxref{p}{part} | |
33 | ||
82567ea9 MW |
34 | %% A gadget to include in `\xref': call as |
35 | %% | |
36 | %% \xref[\instead{THING}]{LABEL} | |
37 | %% | |
38 | %% to replace the usual `section' or whatever with THING. | |
ca2023b8 MW |
39 | \def\instead#1#2{#1} |
40 | ||
1f7d590d MW |
41 | %% Other languages with special typesetting. |
42 | \def\Cplusplus{C\kern-\p@++} | |
43 | \def\Csharp{C\#} | |
44 | ||
45 | %% Special maths notation. | |
46 | \def\chain#1#2{\mathsf{ch}_{#1}(#2)} | |
47 | \def\chainhead#1#2{\mathsf{hd}_{#1}(#2)} | |
48 | \def\chaintail#1#2{\mathsf{tl}_{#1}(#2)} | |
49 | ||
50 | %% Other mathematical tweaks. | |
51 | \let\implies\Rightarrow | |
52 | \let\epsilon\varepsilon | |
53 | ||
2ba6e0bd MW |
54 | %% A table heading cell. Clone and hack \multicolumn. |
55 | \def\thd{\omit\@ifnextchar[\thd@{\thd@[l]}} | |
56 | \def\thd@[#1]#2{% | |
57 | \begingroup | |
58 | \tab@multicol \tab@initread \let\tab@looped\tab@err@multi | |
59 | \tab@preamble{}\def\tab@midtext{\bfseries#2}\tab@readpreamble{#1}% | |
60 | \the\tab@preamble | |
61 | \endgroup \ignorespaces | |
62 | } | |
63 | ||
1f7d590d MW |
64 | %% Unix manpage references. |
65 | \def\man#1#2{\textbf{#1}(#2)} | |
66 | ||
67 | %% Listings don't need to be small. | |
68 | \let\listingsize\relax | |
69 | ||
fea590fe | 70 | %% Notes for later. |
228b271d | 71 | \def\fixme#1{\leavevmode\marginpar{FIXME}\index{FIXME}[FIXME: #1]} |
fea590fe | 72 | |
a4094071 | 73 | %% Diagram settings. |
7be31112 MW |
74 | \tikzset{ |
75 | every picture/.style={>=stealth, thick}, | |
1f6f6dc8 MW |
76 | lit/.style={font=\sffamily}, |
77 | dashed/.style={dash pattern=on 2.19pt off 2.19pt} | |
7be31112 | 78 | } |
a4094071 | 79 | |
1f7d590d MW |
80 | %% Metavariables are italics without decoration. |
81 | \def\syntleft{\normalfont\itshape} | |
82 | \let\syntright\empty | |
83 | ||
84 | %% Literal code is in sans face. | |
5f1bbd61 | 85 | \def\codeface{\upshape\sffamily} |
ddfe4265 MW |
86 | \DeclareRobustCommand\code[1]{% |
87 | \ifmmode\hbox\else\leavevmode\fi% | |
88 | {\normalfont\codeface\/#1\/}% | |
89 | } | |
1f7d590d MW |
90 | \def\ulitleft{\normalfont\codeface} |
91 | \let\ulitright\empty | |
48ab1447 | 92 | \def\lit@i#1#2#3{\ifmmode\leavevmode\hbox\fi{#1{#3\/}#2}} |
1f7d590d MW |
93 | |
94 | %% Conditionally enter maths mode. Can't use \ensuremath here because we | |
95 | %% aren't necessarily sure where the maths will actually end. | |
96 | \let\m@maybe@end\relax | |
97 | \def\m@maybe{\ifmmode\else$\let\m@maybe@end$\fi} | |
98 | ||
99 | %% Standard syntax shortcuts. | |
100 | \atdef <#1>{\synt{#1}\@scripts} | |
101 | \atdef "#1"{\lit*{#1}\@scripts} | |
102 | \atdef `#1'{\lit{#1}\@scripts} | |
5f1bbd61 | 103 | \atdef |#1|{\lit*{#1}\@scripts} |
1f7d590d MW |
104 | |
105 | %% A handy abbreviation; `\\' itself is too good to steal. | |
106 | \atdef \\{\textbackslash} | |
107 | ||
108 | %% Intercept grammar typesetting and replace the vertical bar with the | |
109 | %% maths-font version. | |
b04739d0 MW |
110 | \let\@@syn@shorts\syn@shorts |
111 | \def\syn@shorts{\def\textbar{\hbox{$|$}}\@@syn@shorts} | |
1f7d590d MW |
112 | |
113 | %% Collect super- and subscripts. (Note that underscores are active for the | |
114 | %% most part.) When we're done, end maths mode if we entered it | |
115 | %% conditionally. | |
116 | \def\@scripts{\futurelet\@ch\@scripts@i} | |
117 | \begingroup\lccode`\~=`\_\lowercase{\endgroup | |
d80aee35 | 118 | \def\@scripts@i{\if1\ifx\@ch~1\else\ifx\@ch_1\else\ifx\@ch^1\else0\fi\fi\fi% |
1f7d590d MW |
119 | \expandafter\@scripts@ii\else\expandafter\m@maybe@end\fi}} |
120 | \def\@scripts@ii#1#2{\m@maybe#1{#2}\@scripts} | |
121 | ||
122 | %% Doubling characters, maybe. Either way, chain onto \@scripts. | |
123 | \def\dbl@maybe#1{\let\@tempa#1\futurelet\@ch\dbl@maybe@i} | |
124 | \def\dbl@maybe@i{\m@maybe\ifx\@ch\@tempa\@tempa\!\@tempa% | |
125 | \expandafter\@firstoftwo\expandafter\@scripts% | |
126 | \else\@tempa\expandafter\@scripts\fi} | |
127 | ||
b13a8764 MW |
128 | %% Lookahead without eating spaces. |
129 | \def\@ifnextchar@preserve#1#2#3{% | |
130 | \let\want@= #1\def\@tempa{#2}\def\@tempb{#3}% | |
131 | \futurelet\nch@\@ifnch@p% | |
132 | } | |
133 | \def\@ifnch@p{% | |
134 | \ifx\want@\nch@\expandafter\@tempa\else\expandafter\@tempb\fi} | |
135 | ||
1f7d590d MW |
136 | %% Extra syntax for Lisp templates. These produce the maths-font versions of |
137 | %% characters, which should contrast well against the sans face used for | |
138 | %% literals. | |
139 | \atdef [{\dbl@maybe[} | |
140 | \atdef ]{\dbl@maybe]} | |
141 | \atdef {{\m@maybe\{\@scripts} | |
142 | \atdef }{\m@maybe\}\@scripts} | |
143 | \atdef ({\m@maybe(\@scripts} | |
144 | \atdef ){\m@maybe)\@scripts} | |
145 | \atdef !{\m@maybe|\@scripts} | |
82567ea9 | 146 | |
1f7d590d | 147 | \def\returns{\m@maybe\longrightarrow\m@maybe@end\hspace{0.5em}\ignorespaces} |
82567ea9 | 148 | \def\nlret{\\\hspace{4em}\returns} |
1f7d590d | 149 | \atdef >{\leavevmode\unskip\hspace{0.5em}\returns} |
82567ea9 MW |
150 | |
151 | %% Extra syntax for common tokens. | |
152 | \atdef ~{\textasciitilde} | |
92608d0d MW |
153 | \atdef -{\leavevmode\hbox\bgroup\futurelet\ch@\@dash} |
154 | \def\@dash{% | |
155 | \ifx\ch@>% | |
156 | --\raisebox{.4pt}{>}% | |
157 | \def\next@{\@firstoftwo{\egroup\penalty200\relax}}% | |
a8596377 MW |
158 | \else\ifx\ch@-% |
159 | --\,% | |
160 | \def\next@{\@firstoftwo{\futurelet\ch@\@dash}}% | |
92608d0d MW |
161 | \else% |
162 | --% | |
163 | \let\next@\egroup% | |
164 | \fi\fi | |
165 | \next@% | |
166 | } | |
1f7d590d MW |
167 | |
168 | %% Comment setting. | |
888d5e58 MW |
169 | \def\comment#1{\mbox{\normalfont\itshape\/#1\/}} |
170 | \atdef /*#1*/{/*\comment{#1}*/} | |
7dd104a3 | 171 | \def\@semis;{\@ifnextchar@preserve;{;\@semis}\@semicomment} |
888d5e58 | 172 | \def\@semicomment#1\\{\comment{#1}\\} |
7dd104a3 | 173 | \atdef ;{;\@semis;} |
1f7d590d | 174 | |
82567ea9 MW |
175 | %% Put a chunk of text in a box. |
176 | \newenvironment{boxy}[1][\q@]{% | |
177 | \savenotes% | |
178 | \dimen@\linewidth\advance\dimen@-1.2pt\advance\dimen@-2ex% | |
179 | \medskip% | |
180 | \vbox\bgroup\hrule\hbox\bgroup\vrule% | |
181 | \vbox\bgroup\vskip1ex\hbox\bgroup\hskip1ex\minipage\dimen@% | |
182 | \def\@temp{#1}\ifx\@temp\q@\else\leavevmode{\headfam\bfseries#1\quad}\fi% | |
183 | }{% | |
184 | \endminipage\hskip1ex\egroup\vskip1ex\egroup% | |
185 | \vrule\egroup\hrule\egroup% | |
186 | \medskip% | |
187 | \spewnotes% | |
188 | } | |
189 | ||
190 | %%%-------------------------------------------------------------------------- | |
191 | %%% Environment for setting programs. | |
192 | ||
12a6d10d MW |
193 | %% Save `\kill' so that `longtable' won't clobber it. |
194 | \let\prog@@kill\kill | |
195 | ||
82567ea9 | 196 | %% Main guts of `prog' and `nprog'. |
276be7d7 MW |
197 | \def\@prog{% |
198 | \let\prog@@cr\@tabcr% | |
199 | \let\@tabcr\@progcr% | |
12a6d10d | 200 | \let\kill\prog@@kill% |
276be7d7 MW |
201 | \codeface% |
202 | \tabbing% | |
203 | } | |
82567ea9 MW |
204 | |
205 | %% Newlines: called by `\\' within a `prog'. | |
206 | %% | |
207 | %% \\ newline without following break | |
208 | %% \\[SKIP] newline /with/ break and vertical glue | |
209 | %% \\*[SKIP] newline without break, with optional glue | |
210 | %% \\+ newline with break and a vertical gap | |
211 | %% \\- newline without break, with a tiny gap | |
ebf5ae2e | 212 | \def\@progcr{\futurelet\@tempa\@progcr@i} |
ebf5ae2e MW |
213 | \def\@progcr@i{% |
214 | \ifx\@tempa\@sptoken\let\next@\@progcr@sp\else | |
215 | \if1\ifx\@tempa[1\else | |
216 | \ifx\@tempa*1\else | |
217 | 0\fi\fi | |
218 | \let\next@\prog@@cr\else | |
219 | \if1\ifx\@tempa+1\else | |
220 | \ifx\@tempa-1\else | |
221 | 0\fi\fi | |
222 | \let\next@\@progcr@ii\else | |
223 | \let\next@\@progcr@a\fi\fi\fi | |
224 | \next@} | |
225 | \def\@progcr@a{\prog@@cr*{}\ignorespaces} | |
226 | \def\@progcr@ii#1{\csname @progcr@#1\endcsname\ignorespaces} | |
227 | \@namedef{@progcr@+}{\prog@@cr[\medskipamount]} | |
228 | \@namedef{@progcr@-}{\prog@@cr*[\jot]} | |
82567ea9 | 229 | {\def\:{\gdef\@progcr@sp}\: {\@progcr}} % \@progcr@sp eats space and recurses |
1f7d590d | 230 | |
82567ea9 MW |
231 | %% Set a program in `codeface', with implicit tabbing and other toys. |
232 | %% Newlines are explicit, because otherwise I need comments in weird places | |
233 | %% to make the vertical spacing come out properly. You can write | |
234 | %% `\obeylines' if you really want to. | |
235 | \def\prog{\quote\@prog} | |
236 | \def\endprog{\endtabbing\endquote} | |
237 | ||
238 | %% Like `prog', but without indenting the code. Use this within environments | |
239 | %% which already set their contents out from the body text in some | |
240 | %% distinctive way. | |
241 | \let\nprog\@prog | |
242 | \let\endnprog\endtabbing | |
243 | ||
244 | %% Indent the following material. Cancel using `\-'. | |
245 | \def\ind{\quad\=\+\kill} | |
246 | ||
247 | %% Show a backslash by the right-hand margin; for multiline macros etc. | |
248 | \def\macsl{\`\textbackslash\hskip\leftmargin} | |
1f7d590d | 249 | |
0a8f78ec MW |
250 | %% \maplist{THING}{{ITEM}...}: Invoke THING{ITEM} for each ITEM in turn. |
251 | \def\maplist#1#2{\map@i{#1}#2\q@} | |
252 | \def\map@i#1{\def\next@{\map@ii{#1}}\futurelet\ch@\next@} | |
253 | \def\map@ii#1{\ifx\ch@\q@\expandafter\@gobble% | |
254 | \else\def\next@{\map@iii{#1}}\expandafter\next@\fi} | |
255 | \def\map@iii#1#2{#1{#2}\map@i{#1}} | |
256 | ||
257 | %% \crossproduct{THING}{{LIST}...} where each LIST is {ITEM}... | |
258 | %% For each possible way of selecting one ITEM from each LIST, in order, | |
259 | %% invoke THING{{ITEM}...} | |
260 | \toksdef\cprod@new=0 | |
261 | \toksdef\cprod@old=2 | |
262 | \toksdef\cprod@head=4 | |
263 | \toksdef\cprod@tail=6 | |
264 | \def\crossproduct#1#2{% | |
265 | \cprod@new{{}}% | |
266 | \maplist{\cprod@f{#1}}{#2}% | |
267 | \cprod@head{#1}% | |
268 | \edef\next@{\noexpand\maplist{\the\cprod@head}{\the\cprod@new}} | |
269 | \next@% | |
270 | } | |
271 | \def\cprod@f#1#2{% | |
272 | \cprod@old\cprod@new\cprod@new{}% | |
273 | \maplist\cprod@g{#2}% | |
274 | } | |
275 | \def\cprod@g#1{% | |
276 | \cprod@head{#1}% | |
277 | \expandafter\maplist\expandafter\cprod@h\expandafter{\the\cprod@old}% | |
278 | } | |
279 | \def\cprod@h#1{% | |
280 | \cprod@tail{#1}% | |
281 | \cprod@new\expandafter{\the\expandafter\cprod@new\expandafter{% | |
282 | \the\expandafter\cprod@tail\the\cprod@head}}% | |
283 | } | |
284 | ||
82567ea9 MW |
285 | %%%-------------------------------------------------------------------------- |
286 | %%% Machinery for describing functions, etc. | |
287 | ||
288 | %% \definedescribecategory{CAT}[KIND]{NAME} | |
289 | %% | |
290 | %% Define a category of things to document. CAT is a short label identifying | |
291 | %% the category to `\describe', `\descref', and friends. The NAME is the | |
292 | %% text to show in the description headline; it is a macro body which is | |
293 | %% passed an argument `#1' that applies a modifier to some portion of the | |
294 | %% text. | |
295 | %% | |
296 | %% The KIND allows additional arguments to be collected, included in label | |
297 | %% strings, and mentioned in the index. The default is `plain'. | |
87883222 MW |
298 | \def\definedescribecategory#1{% |
299 | \@ifnextchar[{\def@desc{#1}}{\def@desc{#1}[plain]}} | |
300 | \def\def@desc#1[#2]#3{\@namedef{cat!#1}##1{#3}\@namedef{catsw!#1}{#2}} | |
82567ea9 MW |
301 | |
302 | %% \describecategoryname[MOD]{CAT} | |
303 | %% | |
304 | %% Typeset the category name for CAT, modified by MOD. | |
072f666e MW |
305 | \def\describecategoryname{\@ifnextchar[\@descname@i{\@descname@i[]}} |
306 | \def\@descname@i[#1]#2{% | |
307 | \expandafter\let\expandafter\@tempa\csname cat!#2\endcsname% | |
19a89075 | 308 | \expandafter\let\expandafter\@tempb\csname modcat/#1\endcsname% |
83f56c86 MW |
309 | \ifx\@tempa\relax\PackageError{sod}{unknown description category `#2'}% |
310 | {I don't know what `#2' means as a thing you might try to\MessageBreak | |
311 | document. Maybe you mistyped it, or forgot to say\MessageBreak | |
312 | `\protect\definedescribecategory' for it. For now I'm going\MessageBreak | |
313 | just use the literal string `#2' and hope that doesn't look\MessageBreak | |
314 | too terrible.}% | |
315 | \@tempb{#2}% | |
316 | \else\@tempa\@tempb\fi} | |
82567ea9 MW |
317 | |
318 | %% Call a modifier method. | |
22549a08 | 319 | \def\@mod@dispatch#1#2{\csname #1/#2\endcsname} |
82567ea9 MW |
320 | |
321 | %% Call a description method given the category. | |
894e3dc9 MW |
322 | \def\@desc@dispatch#1#2{% |
323 | \csname #1/% | |
82567ea9 MW |
324 | \expandafter\ifx\csname catsw!#2\endcsname\relax plain% |
325 | \else \csname catsw!#2\endcsname \fi% | |
894e3dc9 MW |
326 | \endcsname% |
327 | } | |
072f666e | 328 | |
e3e83b8a MW |
329 | %% Modifier methods for the default `plain' modifier. |
330 | \@namedef{modcat/plain}#1{#1} | |
331 | \@namedef{modlabel/plain}#1{#1} | |
332 | \@namedef{modindex/plain}#1{#1@\noexpand\code{#1}} | |
b35ac53a | 333 | |
82567ea9 MW |
334 | %% Modifier methods for `setf'. The name text prefixes the relevant word |
335 | %% with `setf-'. | |
19a89075 | 336 | \@namedef{modcat/setf}#1{\code{setf}-#1} |
22549a08 MW |
337 | \@namedef{modlabel/setf}#1{setf/#1} |
338 | \@namedef{modindex/setf}#1{#1@\noexpand\code{#1}} | |
b35ac53a | 339 | |
82567ea9 MW |
340 | %% Modifier methods for words with *earmuffs*. Sort into the index without |
341 | %% the earmuffs. | |
63288801 | 342 | \@namedef{modcat/muffs}#1{#1} |
6f38c318 MW |
343 | \@namedef{modlabel/muffs}#1{#1} |
344 | \@namedef{modindex/muffs}#1{\@unmuff#1@\noexpand\code{#1}} | |
345 | \def\@unmuff*#1*{#1} | |
63288801 | 346 | |
82567ea9 | 347 | %% Modifier methods for :keywords. Sort into the index without the `:'. |
63288801 | 348 | \@namedef{modcat/kwd}#1{#1} |
6f38c318 MW |
349 | \@namedef{modlabel/kwd}#1{#1} |
350 | \@namedef{modindex/kwd}#1{\@gobble#1@\noexpand\code{#1}} | |
63288801 | 351 | |
82567ea9 | 352 | %% Category-kind methods for plain categories. |
87883222 | 353 | \@namedef{descargs/plain}#1{#1{}} |
aadea863 | 354 | \@namedef{desclabel/plain}#1#2#3{#2:\@mod@dispatch{modlabel}{#1}{#3}} |
87883222 | 355 | \@namedef{descindex/plain}#1#2#3{% |
aadea863 MW |
356 | \@mod@dispatch{modindex}{#1}{#3}!% |
357 | \protect\describecategoryname[#1]{#2}% | |
87883222 MW |
358 | } |
359 | ||
82567ea9 MW |
360 | %% Category-kind methods for `method' categories. Collect an extra argument |
361 | %% listing the specializers: include them in the label, and typeset them in | |
362 | %% the index. | |
e812c742 MW |
363 | \def\fmtspecs#1#2{% |
364 | \if!#2!\else\count@\z@\toks@{}#1\fmtspecs@i#2,\q@,\fi} | |
365 | \def\fmtspecs@i#1,{% | |
87883222 MW |
366 | \def\@tempa{#1}% |
367 | \ifx\@tempa\q@% | |
368 | \ifcase\count@(no args?!)% | |
369 | \or% nothin' doin | |
370 | \or \space and % | |
371 | \else, and % | |
372 | \fi% | |
373 | \the\toks@% | |
374 | \else% | |
375 | \ifnum\count@>\@ne, \fi% | |
376 | \the\toks@% | |
377 | \toks@{\code{#1}}\advance\count@\@ne% | |
e812c742 | 378 | \expandafter\fmtspecs@i% |
87883222 MW |
379 | \fi% |
380 | } | |
82567ea9 MW |
381 | \@namedef{descargs/method}#1#2{#1{{#2}}} |
382 | \@namedef{desclabel/method}#1#2#3#4% | |
aadea863 | 383 | {#2:\@mod@dispatch{modlabel}{#1}{#4}(#3)} |
82567ea9 | 384 | \@namedef{descindex/method}#1#2#3#4{% |
aadea863 MW |
385 | \@mod@dispatch{modindex}{#1}{#4}!% |
386 | \protect\describecategoryname[#1]{#2}% | |
387 | \protect\fmtspecs{ specialized at }{#3}% | |
82567ea9 | 388 | } |
87883222 | 389 | |
82567ea9 MW |
390 | %% Some magic strings. |
391 | \def\q@{\q@} | |
be18b63c | 392 | \def\@setf{setf} |
63288801 | 393 | \def\@starstar{**} |
82567ea9 MW |
394 | |
395 | %% \parse@dhd{NEXT}[MOD]{CAT}{...}...[NAME]{SYNOPSIS} | |
396 | %% | |
397 | %% Parse the arguments for a description header, and call | |
398 | %% | |
399 | %% NEXT{MOD}{CAT}{{...}...}{NAME}{SYNOPSIS} | |
400 | %% | |
401 | %% Here, {...}... represents the additional category-kind arguments. See | |
402 | %% `describe' for what all of this means. | |
be18b63c MW |
403 | \def\parse@dhd#1{% {NEXT} |
404 | \@ifnextchar[{\parse@dhd@a{#1}}{\parse@dhd@c{#1}}} | |
405 | \def\parse@dhd@a#1[#2]#3{% {NEXT}[MOD]{CAT} | |
406 | \@desc@dispatch{descargs}{#3}{\parse@dhd@ab{#1}{#2}{#3}}} | |
407 | \def\parse@dhd@ab#1#2#3#4{% {NEXT}{MOD}{CAT}{{...}...} | |
408 | \@ifnextchar[{\parse@dhd@ac{#1}{#2}{#3}{#4}}{\parse@dhd@ad{#1}{#2}{#3}{#4}}} | |
409 | \def\parse@dhd@ac#1#2#3#4[#5]#6{% {NEXT}{MOD}{CAT}{{...}...}[NAME]{SYNOPSIS} | |
410 | #1{#2}{#3}{#4}{#5}{#6}} | |
411 | \def\parse@dhd@ad#1#2#3#4#5{% {NEXT}{MOD}{CAT}{{...}...}{NAME [ARGS...]} | |
412 | \parse@dhd@ae{#1}{#2}{#3}{#4}{#5}#5 \q@} | |
413 | \def\parse@dhd@ae#1#2#3#4#5#6 #7\q@{% | |
414 | % {NEXT}{MOD}{CAT}{{...}...}{SYNSOPSIS}NAME [ARGS...]\q@ | |
415 | #1{#2}{#3}{#4}{#6}{#5}} | |
416 | ||
417 | \def\parse@dhd@c#1#2{% {NEXT}{CAT} | |
87883222 MW |
418 | \@desc@dispatch{descargs}{#2}{\parse@dhd@cb{#1}{#2}}} |
419 | \def\parse@dhd@cb#1#2#3{% {NEXT}{CAT}{{...}...} | |
420 | \@ifnextchar[{\parse@dhd@cc{#1}{#2}{#3}}{\parse@dhd@cd{#1}{#2}{#3}}} | |
421 | \def\parse@dhd@cc#1#2#3[#4]#5{% {NEXT}{CAT}{{...}...}[NAME]{SYNOPSIS} | |
e3e83b8a | 422 | #1{plain}{#2}{#3}{#4}{#5}} |
87883222 MW |
423 | \def\parse@dhd@cd#1#2#3#4{% {NEXT}{CAT}{{...}...}{SYNOPSIS} |
424 | \parse@dhd@ce{#1}{#2}{#3}{#4}#4 \q@} | |
425 | \def\parse@dhd@ce#1#2#3#4#5 #6\q@{% | |
426 | % {NEXT}{CAT}{{...}...}{SYNOPSIS}NAME [ARGS...]\q@ | |
427 | \def\temp@{#5}% | |
428 | \ifx\@setf\temp@\def\next@{\parse@dhd@csetf{#1}{#2}{#3}{#4}#6 \q@}% | |
63288801 | 429 | \else\def\temp@##1##2*##3\q@{\def\temp@{##1##3}}\temp@#5*\q@% |
6f38c318 | 430 | \ifx\temp@\@starstar\def\next@{#1{muffs}{#2}{#3}{#5}{#4}}% |
63288801 | 431 | \else\def\temp@##1##2\q@{\def\temp@{##1}}\temp@#5\q@% |
6f38c318 | 432 | \if:\temp@\def\next@{#1{kwd}{#2}{#3}{#5}{#4}}% |
e3e83b8a | 433 | \else\def\next@{#1{plain}{#2}{#3}{#5}{#4}}\fi\fi\fi% |
072f666e MW |
434 | \next@% |
435 | } | |
87883222 MW |
436 | \def\parse@dhd@csetf#1#2#3#4(#5 #6\q@{% |
437 | % {NEXT}{CAT}{{...}...}{SYNOPSIS}(NAME [ARGS...])\q@ | |
438 | #1{setf}{#2}{#3}{#5}{#4}} | |
7e94c5fe | 439 | |
82567ea9 | 440 | %% \dhead[MOD]{CAT}{...}...[NAME]{SYNOPSIS} |
a6ec8b3f | 441 | %% \dhead*[MOD]{CAT}{...}...[NAME]{SYNOPSIS} |
82567ea9 MW |
442 | %% |
443 | %% Typeset a description head. Use this within the first argument of | |
444 | %% `describe*'; see `describe' for the details. | |
a6ec8b3f MW |
445 | %% |
446 | %% With `*', don't set labels or add items to the index. | |
7e94c5fe | 447 | \newif\if@dheadfirst |
a6ec8b3f MW |
448 | \newif\if@dheadindex |
449 | \def\dhead{\@ifstar% | |
450 | {\parse@dhd{\global\@dheadindexfalse\dhead@}}% | |
451 | {\parse@dhd{\global\@dheadindextrue\dhead@}}} | |
87883222 | 452 | \def\dhead@#1#2#3#4#5{% {MOD}{CAT}{{...}...}{NAME}{SYNOPSIS} |
79766c36 | 453 | \if@dheadfirst\global\@dheadfirstfalse\else\relax\\*[\smallskipamount]\fi% |
a6ec8b3f MW |
454 | \if@dheadindex% |
455 | \phantomsection% | |
456 | {\let\protect\@empty\let\@uscore\relax% | |
457 | \edef\temp@{\@desc@dispatch{desclabel}{#2}{#1}{#2}#3{#4}}% | |
458 | \def\@uscore{_\@gobble}\expandafter\message\expandafter{\temp@}% | |
459 | \def\@uscore{-\@gobble}\expandafter\label\expandafter{\temp@}}% | |
460 | {\begingroup\lccode`\~=`\_\lowercase{\endgroup\def~{_}}% | |
461 | \protected@edef\@tempa##1{% | |
462 | \noexpand\index{\@desc@dispatch{descindex}{#2}{#1}{#2}#3{#4}##1}}% | |
463 | \toks@\expandafter{\@tempa{|)}}% | |
464 | \toks\tw@\expandafter{\after@desc}% | |
465 | \xdef\after@desc{\the\toks\tw@\the\toks@}% | |
466 | \@tempa{|(}}% | |
467 | \fi% | |
ac6e7a4e | 468 | \rlap{\hb@xt@\linewidth{\hfil\normalfont\bfseries |
072f666e | 469 | [\describecategoryname[#1]{#2}]}}% |
87883222 | 470 | #5% |
7e94c5fe MW |
471 | } |
472 | ||
82567ea9 MW |
473 | %% Main guts of a description environment. The argument here typesets the |
474 | %% header line(s). | |
7e94c5fe | 475 | \def\desc@begin#1{% |
ddfe4265 MW |
476 | \let\saved@after@desc\after@desc% |
477 | \gdef\after@desc{}% | |
1f7d590d | 478 | \normalfont% |
7e94c5fe MW |
479 | \if@nobreak\else\par\goodbreak\fi% |
480 | \global\@dheadfirsttrue% | |
481 | \begingroup% | |
7e94c5fe MW |
482 | \let\@endparenv\relax% |
483 | \clubpenalty\@M \widowpenalty\@M \interlinepenalty50% | |
ebf5ae2e | 484 | \@prog#1\endtabbing% |
7e94c5fe MW |
485 | \endgroup% |
486 | \penalty\@M\@afterheading% | |
487 | \list{}{\rightmargin\z@\topsep\z@}\item% | |
1f7d590d | 488 | } |
ddfe4265 | 489 | \def\desc@end{\endlist\after@desc\global\let\after@desc\saved@after@desc} |
7e94c5fe | 490 | |
82567ea9 MW |
491 | %% \begin{describe}[MOD]{CAT}{...}...[NAME]{SYNOPSIS} |
492 | %% ... | |
493 | %% \end{describe} | |
494 | %% | |
495 | %% Describe some kind of program object. The CAT names the category of thing | |
496 | %% being described -- this will be shown in the header, and index. The | |
497 | %% SYNOPSIS is an implicit `prog' environment in which invoking the thing can | |
498 | %% be summarized. | |
499 | %% | |
500 | %% The {...}... are any additional arguments required by the category's kind | |
501 | %% (e.g., method specializers). | |
502 | %% | |
503 | %% The NAME is the name of the thing, which ends up in the index and | |
504 | %% cross-reference label. If omitted, it defaults to the first word of the | |
505 | %% SYNOPSIS, except that there are some special cases. | |
506 | %% | |
507 | %% The MOD is the modifier to apply. If omitted, it will usually default to | |
508 | %% `plain', but in the absence of a NAME, some kinds of synopses are | |
509 | %% recognized specially: | |
510 | %% | |
511 | %% * `setf (NAME ...) ...': selects NAME, and defaults MOD to `setf'. | |
512 | %% | |
6f38c318 | 513 | %% * `*NAME*': defaults MOD to `muffs'. |
82567ea9 | 514 | %% |
6f38c318 | 515 | %% * `:NAME': defaults MOD to `kwd'. |
7e94c5fe | 516 | \def\describe{\parse@dhd\desc@} |
a6ec8b3f MW |
517 | \def\desc@#1#2#3#4#5{% |
518 | \global\@dheadindextrue% | |
519 | \desc@begin{\dhead@{#1}{#2}{#3}{#4}{#5}}% | |
520 | } | |
7e94c5fe | 521 | \let\enddescribe\desc@end |
1f7d590d | 522 | |
82567ea9 MW |
523 | %% \begin{describe*} |
524 | %% {\dhead[MOD]{CAT}{...}...[NAME]{SYNOPSIS} | |
525 | %% ...} | |
526 | %% ... | |
527 | %% \end{describe*} | |
528 | %% | |
529 | %% This is the fancy form of `describe' for describing several different | |
530 | %% things at once. | |
531 | \@namedef{describe*}#1{\desc@begin{#1}} | |
532 | \expandafter\let\csname enddescribe*\endcsname\desc@end | |
533 | ||
89092cc1 MW |
534 | %% \parse@dlbl{NEXT}[MOD]{CAT}{...}...{LABEL} |
535 | %% | |
536 | %% Parse a description label, and call | |
537 | %% | |
538 | %% NEXT{MOD}{CAT}{{...}...}{LABEL} | |
539 | %% | |
540 | %% This handles defaulting the MOD correctly, based on the LABEL text. See | |
541 | %% `\descref' for the details. | |
542 | \def\parse@dlbl#1{\@ifnextchar[{\parse@dlbl@a{#1}}{\parse@dlbl@c{#1}}} | |
543 | \def\parse@dlbl@a#1[#2]#3{\@desc@dispatch{descargs}{#3}{#1{#2}{#3}}} | |
544 | \def\parse@dlbl@c#1#2% | |
545 | {\@desc@dispatch{descargs}{#2}{\parse@dlbl@cb{#1}{#2}}} | |
546 | \def\parse@dlbl@cb#1#2#3#4{% | |
547 | \def\temp@##1##2*##3\q@{\def\temp@{##1##3}}\temp@#4*\q@% | |
548 | \ifx\temp@\@starstar\def\next@{#1{muffs}{#2}{#3}{#4}}% | |
549 | \else\def\temp@##1##2\q@{\def\temp@{##1}}\temp@#4\q@% | |
550 | \if:\temp@\def\next@{#1{kwd}{#2}{#3}{#4}} | |
551 | \else\def\next@{#1{plain}{#2}{#3}{#4}}\fi\fi% | |
552 | \next@% | |
553 | } | |
554 | ||
555 | %% \descref[MOD]{CAT}{...}...{LABEL}[TEXT] | |
556 | %% \descref*[MOD]{CAT}{...}...{LABEL} | |
82567ea9 MW |
557 | %% |
558 | %% Typesets a cross-reference to a described thing. The CAT names the | |
559 | %% category of thing being described, and the LABEL names the specific thing. | |
560 | %% | |
561 | %% The {...}... are any additional arguments required by the category's kind | |
562 | %% (e.g., method specializers). | |
563 | %% | |
89092cc1 MW |
564 | %% The MOD is the modifier to apply, similar (but subtly different from) to |
565 | %% the `describe' environment. If omitted, it will usually default to | |
566 | %% `plain', but in the absence of a NAME, some kinds of synopses are | |
567 | %% recognized specially: | |
568 | %% | |
569 | %% * `*NAME*': defaults MOD to `muffs'. | |
82567ea9 | 570 | %% |
89092cc1 MW |
571 | %% * `:NAME': defaults MOD to `kwd'. |
572 | %% | |
573 | %% (`setf' is /not/ specially detected here. Write an explicit `setf' | |
574 | %% modifier if necessary, because it's no more typing.) | |
82567ea9 MW |
575 | %% |
576 | %% Usually a page-number cross-reference is included, so as to help readers | |
577 | %% of a dead-tree copy; this is suppressed by the `*' version. | |
ea214e5e | 578 | \def\descref{\@ifstar% |
89092cc1 MW |
579 | {\parse@dlbl{\descref@i\relax\@gobble\relax}}% |
580 | {\parse@dlbl{\descref@i{ (}\autopageref)}}} | |
581 | \def\descref@i#1#2#3#4#5#6#7{\@ifnextchar@preserve[% | |
582 | % {PGA}{PGB}{PGC}{MOD}{CAT}{{...}...}{LABEL} | |
583 | {\descref@ii{#1}{#2}{#3}{#4}{#5}{#6}{#7}}% | |
584 | {\descref@iii{#1}{#2}{#3}{#4}{#5}{#6}{#7}{}}} | |
585 | \def\descref@ii#1#2#3#4#5#6#7[#8]% | |
586 | % {PGA}{PGB}{PGC}{MOD}{CAT}{{...}...}{LABEL}[AFTER] | |
587 | {\descref@iii{#1}{#2}{#3}{#4}{#5}{#6}{#7}{ #8}} | |
588 | \def\descref@iii#1#2#3#4#5#6#7#8{% | |
589 | % {PGA}{PGB}{PGC}{MOD}{CAT}{{...}...}{LABEL}{AFTER} | |
5cf27cf1 | 590 | \begingroup% |
89092cc1 MW |
591 | \let\protect\@empty\def\@uscore{-\@gobble}% |
592 | \edef\temp@{\@desc@dispatch{desclabel}{#5}{#4}{#5}#6{#7}}% | |
3934b7ee MW |
593 | \edef\next@##1##2##3{\endgroup% |
594 | \noexpand\hyperref[\temp@]{##1}##2{\temp@}##3}% | |
595 | \next@{\code{#7}}{#8#1#2}{#3}% | |
58f9b400 MW |
596 | } |
597 | ||
a6ec8b3f MW |
598 | %% \descindex[MOD]{CAT}{...}...{LABEL}[SUFFIX] |
599 | %% | |
600 | %% Set a label and index entry here, as if for a description. The CAT names | |
601 | %% the category of thing being described, and the LABEL names the specific | |
602 | %% thing, as for `\descref'. The {...}... are any additional arguments | |
603 | %% required by the category's kind (e.g., method specializers). The MOD is | |
604 | %% the modifier to apply; see `\descref' for the details. | |
605 | %% | |
606 | %% The SUFFIX is appended to the index-entry text; by default it is empty. | |
607 | %% Useful values are `|(' and `|)' to set ranges. | |
608 | \def\descindex{\parse@dlbl\descindex@i} | |
609 | \def\descindex@i#1#2#3#4{\@ifnextchar[% | |
610 | {\descindex@ii{#1}{#2}{#3}{#4}}% | |
611 | {\descindex@ii{#1}{#2}{#3}{#4}[]}} | |
612 | \def\descindex@ii#1#2#3#4[#5]{% | |
613 | {\begingroup\lccode`\~=`\_\lowercase{\endgroup\def~{_}}% | |
614 | \protected@edef\@tempa{% | |
615 | \noexpand\index{\@desc@dispatch{descindex}{#2}{#1}{#2}#3{#4}#5}}% | |
616 | \@tempa}% | |
617 | } | |
618 | ||
619 | %% \desclabel[MOD]{CAT}{...}...{LABEL}[INDEX-SUFFIX] | |
620 | %% | |
621 | %% Set a label and index entry here, as if for a description. The CAT names | |
622 | %% the category of thing being described, and the LABEL names the specific | |
623 | %% thing, as for `\descref'. The {...}... are any additional arguments | |
624 | %% required by the category's kind (e.g., method specializers). The MOD is | |
625 | %% the modifier to apply; see `\descref' for the details. | |
626 | %% | |
627 | %% This will also add an index entry, as for `\descindex'; the INDEX-SUFFIX | |
628 | %% argument has the same effect as its SUFFIX argument. | |
629 | \def\desclabel{\parse@dlbl\desclabel@i} | |
630 | \def\desclabel@i#1#2#3#4{% | |
631 | \begingroup% | |
632 | \let\protect\@empty\def\@uscore{-\@gobble}% | |
633 | \edef\@tempa{\@desc@dispatch{desclabel}{#2}{#1}{#2}#3{#4}}% | |
634 | \phantomsection\label{\@tempa}% | |
635 | \endgroup% | |
636 | \descindex@i{#1}{#2}{#3}{#4}% | |
637 | } | |
638 | ||
82567ea9 MW |
639 | %% Description categories. |
640 | \definedescribecategory{sym}{symbol} | |
641 | \definedescribecategory{fun}{#1{function}} | |
642 | \definedescribecategory{gf}{generic #1{function}} | |
643 | \definedescribecategory{msg}{message} | |
644 | \definedescribecategory{var}{variable} | |
645 | \definedescribecategory{modvar}{module variable} | |
646 | \definedescribecategory{const}{constant} | |
647 | \definedescribecategory{meth}[method]{primary #1{method}} | |
648 | \definedescribecategory{ar-meth}[method]{\code{:around} #1{method}} | |
649 | \definedescribecategory{be-meth}[method]{\code{:before} #1{method}} | |
650 | \definedescribecategory{af-meth}[method]{\code{:after} #1{method}} | |
651 | \definedescribecategory{cls}{class} | |
652 | \definedescribecategory{rst}{restart} | |
653 | \definedescribecategory{ty}{type} | |
654 | \definedescribecategory{mac}{#1{macro}} | |
655 | \definedescribecategory{feat}{feature macro} | |
656 | \definedescribecategory{lmac}{local #1{macro}} | |
657 | \definedescribecategory{parse}{parser spec} | |
658 | \definedescribecategory{parseform}{parser form} | |
659 | \definedescribecategory{opt}{option handler} | |
660 | \definedescribecategory{optmac}{option macro} | |
661 | \definedescribecategory{plug}{pluggable parser} | |
662 | ||
f1f17867 MW |
663 | %%%----- That's all, folks -------------------------------------------------- |
664 | \endinput |