Debian Codegraph @

texmf-dist/source/latex/dox/dox.dtx

raw
1 % \iffalse
2 %
3 % dox.dtx --- Doc file for DoX
4 %
5 % Copyright (C) 2009, 2010, 2017 Didier Verna
6 %
7 % Author: Didier Verna <[email protected]>
8 %
9 % This file is part of DoX.
10 %
11 % DoX may be distributed and/or modified under the conditions of the LaTeX
12 % Project Public License, either version 1.3 of this license or (at your
13 % option) any later version. The latest version of this license is in
14 % http://www.latex-project.org/lppl.txt and version 1.3 or later is part of
15 % all distributions of LaTeX version 2005/12/01 or later.
16 %
17 % DoX consists of the files listed in the file `README.md'.
18 %
19 %
20 % Commentary:
21 %
22 %
23 % Code:
24 %
25 %<*driver>
26 \documentclass[a4paper]{ltxdoc}
27 \usepackage[T1]{fontenc}
28 \usepackage{xspace}
29 \makeatletter
30 \def\@currname{dox}
31 \def\@currext{inc}
32 \makeatother
33 \input{header.inc}
34 % \OnlyDescription
35 \CodelineIndex
36 % \RecordChanges
37 \begin{document}
38 \DocInput{dox.dtx}
39 \end{document}
40 %</driver>
41 %
42 % \fi
43 %
44 % \CheckSum{390}
45 % \GetFileInfo{dox.inc}
46 %% \CharacterTable
47 %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
48 %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
49 %% Digits \0\1\2\3\4\5\6\7\8\9
50 %% Exclamation \! Double quote \" Hash (number) \#
51 %% Dollar \$ Percent \% Ampersand \&
52 %% Acute accent \' Left paren \( Right paren \)
53 %% Asterisk \* Plus \+ Comma \,
54 %% Minus \- Point \. Solidus \/
55 %% Colon \: Semicolon \; Less than \<
56 %% Equals \= Greater than \> Question mark \?
57 %% Commercial at \@ Left bracket \[ Backslash \\
58 %% Right bracket \] Circumflex \^ Underscore \_
59 %% Grave accent \` Left brace \{ Vertical bar \|
60 %% Right brace \} Tilde \~}
61 %
62 % \MakeShortVerb{\|}
63 %
64 % \makeatletter
65 % \def\ps@mystyle{
66 % \def\@oddfoot{\hfil\thepage\hfil}
67 % \def\@evenfoot{\hfil\thepage\hfil}
68 % \def\@evenhead{\hfil\slshape\leftmark}
69 % \def\@oddhead{\slshape\rightmark\hfil}}
70 % \makeatother
71 %
72 % \newcommand\dox{\textsf{DoX}\xspace}
73 % \newcommand\packagecopyright{%
74 % Copyright \copyright{} 2009, 2010, 2017 Didier Verna}
75 %
76 % \newcommand\emacs{\textsf{[X]Emacs}\xspace}
77 % \newcommand\auctex{AUC\TeX\xspace}
78 % \newcommand\api{\textsc{api}\xspace}
79 %
80 % \pagestyle{mystyle}
81 % \markright{\hskip-.5\marginparwidth \dox \fileversion{} (\filedate)}
82 %
83 % \date{\texttt{\fileversion{} (\filedate)}}
84 % \title{\dox{} -- \textsf{\textbf Doc}, \textbf only e\textbf
85 % Xtended\footnote{\dox homepage:
86 % \texttt{http://www.lrde.epita.fr/\~{}didier/software/latex.php\#dox}}}
87 % \author{Didier Verna\\
88 % \texttt{mailto:[email protected]}\\
89 % \texttt{http://www.lrde.epita.fr/\~{}didier/}}
90 % \maketitle
91 %
92 %
93 % \begin{abstract}
94 % The \texttt{doc} package provides \LaTeX{} developers with means to
95 % describe the usage and the definition of new commands and environments.
96 % However, there is no simple way to extend this functionality to other
97 % items (options or counters for instance). \dox is designed to circumvent
98 % this limitation, and provides some improvements over the existing
99 % functionality as well.
100 %
101 % The \dox package is \packagecopyright{}, and distributed under the
102 % terms of the LPPL license.
103 % \end{abstract}
104 %
105 % \tableofcontents
106 %
107 % \section{Installation}
108 % \subsection{Extraction}
109 % If you are building \dox from the tarball you need to execute the following
110 % steps in order to extract the necessary files:
111 % \begin{verbatim}
112 % [pdf]latex dox.ins
113 % [pdf]latex dox.dtx
114 % [pdf]latex dox.dtx
115 % \end{verbatim}
116 % After that, you need to install the generated documentation and style files
117 % to a location where \LaTeX{} can find them.
118 %
119 % \subsection{TDS-compliant layout}
120 % For a TDS-compliant layout, the following locations are suggested:
121 % \begin{verbatim}
122 % [TEXMF]/tex/latex/dox/dox.sty
123 % [TEXMF]/doc/latex/dox/dox.[pdf|dvi]
124 % \end{verbatim}
125 %
126 % \subsection{\auctex support}
127 % \auctex is a powerful major mode for editing \TeX{} documents in \emacs. In
128 % particular, it provides automatic completion of command names once they are
129 % known. \dox supports \auctex by providing a style file named \texttt{dox.el}
130 % which contains \auctex definitions for the relevant commands. This file
131 % should be installed in a place where \auctex can find it. Please refer to
132 % the \auctex documentation for more information on this. See also section
133 % \ref{sec:elisp}.
134 %
135 % \section{Usage}
136 % \subsection{Initialization}
137 % \subsubsection{Requirements}
138 % In order to work properly, \dox requires the presence of some \LaTeX{}
139 % packages. You don't have to load them explicitly though. As long as
140 % \LaTeX{} can locate them, they will be used automatically. \dox currently
141 % depends on \texttt{kvoptions}.
142 %
143 % \subsubsection{Loading the package}
144 % In order to load \dox, simply say |\usepackage[|\meta{options}|]{dox}|
145 % in the preamble of your document. The package options will be discussed when
146 % appropriate.
147 %
148 % \subsection{Creating new documentation items}
149 % \begin{quotation}
150 % \emph{\textbf{Note}: we assume that you know about \texttt{doc}'s
151 % \cs{DescribeMacro}, \cs{DescribeEnv} and all other associated commands and
152 % environments}.
153 % \end{quotation}
154 % \DescribeMacro{\doxitem}
155 % \oarg{options}\marg{name}\marg{envname}\marg{idxcat}\\
156 % \dox provides a command named \cs{doxitem} to create new documentation items
157 % with functionalities equivalent to what \texttt{doc} provides for commands
158 % and environments. A whole \api is created for every new item.
159 %
160 % \subsubsection{Example}
161 % Perhaps the simplest way to describe what it does is to give an example.
162 % Suppose you would like to describe package options explicitely. Here is what
163 % you need to do:
164 % \begin{verbatim}
165 % \usepackage{dox}
166 % \doxitem{Option}{option}{options}
167 % \end{verbatim}
168 % \dox then creates the following \api for you:
169 % \begin{itemize}
170 % \item \cs{DescribeOption}
171 % \item the \texttt{option} environment
172 % \item \cs{PrintDescribeOption}
173 % \item \cs{PrintOptionName}
174 % \item \cs{SpecialMainOptionIndex}
175 % \item \cs{SpecialOptionIndex}
176 % \end{itemize}
177 % \begin{sloppypar}\noindent
178 % In order to comply with \texttt{doc}'s original behavior, the commands
179 % \cs{PrintDescribeOption} and \cs{PrintOptionName} will only be defined if
180 % they do not already exist.
181 % \end{sloppypar}
182 %
183 % \subsubsection{Details}
184 % Here is a more precise description of the arguments to \cs{doxitem}.
185 % \begin{itemize}
186 % \item \meta{name} (\texttt{Option} in our example) is used to construct the
187 % names of the commands in the new \api. It usually starts with an upcase
188 % letter.
189 % \item \meta{envname} (\texttt{option} in our example) is the name of the
190 % created environment. Be sure to avoid name clashes here! If you start
191 % experimenting odd behavior, you've probably overridden an existing command
192 % with your new environment.\footnote{It is a pity that \LaTeX{} use the
193 % same namespace for commands and environments. The opening command for
194 % environment \texttt{env} should be named \cs{beginenv} and not just
195 % \cs{env}\ldots}
196 % \item \meta{idxcat} is the index category under which your items will
197 % appear. In our example, all indexed options will be listed under the
198 % ``options:'' index entry.
199 % \end{itemize}
200 %
201 % \subsubsection{Options to \cs{doxitem}}
202 % The first (optional) argument to \cs{doxitem} may contain a comma-separated
203 % list of options. The following ones are currently implemented.
204 % \begin{description}
205 % \item[\texttt{idxtype}]~\\
206 % We saw earlier that individual items appear under the \texttt{idxcat}
207 % index entry, but items also appear as standalone index entries,
208 % alphabetically sorted with their type in parenthesis. For instance, the
209 % \texttt{final} option would appear like this under the \texttt{F} index
210 % entry: \mbox{``\texttt{final} (option)''}.
211 %
212 % By default, the index type is the same as the environment's name (the
213 % \meta{envname} argument). However, you can change this by providing a
214 % value to the \texttt{idxtype} option.
215 %
216 % For instance, you may find the word ``environment'' too long for an index
217 % type. In that case, you may redefine the \texttt{environment} \api like
218 % this:
219 % \begin{verbatim}
220 % \doxitem[idxtype=env.]{Env}{environment}{environments}
221 % \end{verbatim}
222 % \item[\texttt{macrolike}]~\\
223 % At some point, you may find that the ``macro'' category is too gross, and
224 % whish to further split it into different documentation items. A typical
225 % example of this would be to provide a specific category for \LaTeX{}
226 % lengths.
227 %
228 % The difference with options or counters is that the names of your items
229 % are actually control sequences, and so they need to be typeset and indexed
230 % in a specific way.
231 %
232 % As of version 2.2, \dox provides a \texttt{macrolike} boolean option which
233 % instructs \cs{doxitem} to create new documentation items expecting control
234 % sequences instead of plain text names. If you want to create explicit
235 % documentation for lengths for instance, you can do this:
236 % \begin{verbatim}
237 % \doxitem[macrolike,idxtype=len.]{Length}{length}{lengths}
238 % \end{verbatim}
239 % In turn this allows you do write things like that:
240 % \begin{verbatim}
241 % \DescribeLength{\partopsep}
242 % \begin{length}{\partopsep}
243 % ...
244 % \end{length}
245 % \end{verbatim}
246 % \end{description}
247 %
248 % \subsection{Improvements over \texttt{doc}'s original \api}
249 % \begin{quotation}\itshape
250 % Please note that the improvements described in this section are also
251 % available in \texttt{doc}'s original command and environment \api's,
252 % because \dox redefines them.
253 % \end{quotation}
254 %
255 % \subsubsection{Additional (optional) argument}
256 % Compared to \texttt{doc}, the \api's created by \cs{doxitem} are extended
257 % with a first optional argument containing a comma-separated list of options,
258 % such that, continuing with our initial example, the real prototypes are in
259 % fact the following:
260 % \begin{verbatim}
261 % \DescribeOption[opt,...]{name}
262 %
263 % \begin{option}[opt,...]{name}
264 % %% ...
265 % \end{option}
266 % \end{verbatim}
267 %
268 % \subsubsection{Available options}
269 % The options currently supported are:
270 % \begin{description}
271 % \item[noprint] Avoid printing \meta{name} in the margin
272 % \item[noindex] Avoid indexing \meta{name}
273 % \end{description}
274 % These options are useful if you don't want printing or indexing locally for
275 % one particular item. Without them, one would need to locally \cs{let} the
276 % relevant commands to \cs{@gobble} which is very inconvenient.
277 %
278 % There is also another advantage in using the \texttt{noprint} option: in
279 % \texttt{doc}'s original implementation, a margin paragraph will still be
280 % created just to be empty, hence wasting float resources. If you're
281 % referencing a lot of items close to each other, this may lead to a ``Too
282 % many unprocessed floats'' error. With \dox, the \cs{marginpar} is avoided
283 % altogether.
284 %
285 % \subsubsection{Global effect}
286 % The \texttt{macrolike}, \texttt{noprint} and \texttt{noindex} options are
287 % also available to \cs{usepackage}. Their effect then becomes global. Because
288 % these options are boolean, it is still possible to counteract their global
289 % effect locally. For instance, one could do:
290 % \begin{verbatim}
291 % \usepackage[noprint]{dox}
292 % \end{verbatim}
293 % and then later:
294 % \begin{verbatim}
295 % \DescribeOption[noprint=false]{french}
296 % \end{verbatim}
297 %
298 % \section{\auctex support for new documentation items\label{sec:elisp}}
299 % Recent versions of \auctex (in fact, \texttt{doc}\TeX{} mode) are aware of
300 % the \texttt{macro} and \texttt{environment} environments and give them a
301 % fixed indentation level of $0$, meaning no indentation at all even when they
302 % are nested. This is considered more convenient than the usual indentation
303 % for environments when editing \texttt{dtx} files. If you have created new
304 % documentation items for your package, you may want to let them behave the
305 % same way. For that, the \dox style file provides two Lisp functions to let
306 % \auctex know of your new environments: \texttt{doxitem} and
307 % \texttt{doxitems}. The first one registers a new environment by name with
308 % \auctex, and the second one takes an arbitrary number of environment names
309 % and does the same with them. The environment names can in fact be regular
310 % expressions, allowing you to combine several names together or build complex
311 % ones.
312 %
313 % Since these functions are located in the style file itself, a good place to
314 % use them is in \texttt{TeX-update-style-hook} which will be called after the
315 % file is parsed and the relevant style files applied. Note that the effect of
316 % calling these functions is always buffer-local.
317 %
318 % Here is an example to make all of this clearer. The following code sample is
319 % what I have at the end of \texttt{fixme.dxt} (another package of mine), in
320 % the local variables section:
321 % \begin{verbatim}
322 % (add-hook 'TeX-update-style-hook
323 % (lambda () (doxitems "option" "counter" "lang" "face" "color")) nil t)
324 % (add-hook 'TeX-update-style-hook
325 % (lambda () (doxitem "\\(env\\|target\\)?layout")) nil t)
326 % \end{verbatim}
327 %
328 % \section{Conclusion}
329 % If you want to see \dox in action, take a look at the documentation of the
330 % \textsf{FiXme} package (version 4.0 or later). In fact, I wrote \dox for it
331 % in the first place.
332 %
333 % \section{History}
334 % \begin{itemize}
335 % \item[v2.4] Improve \auctex support.\\
336 % Fix spurious spaces in index entries, reported by Eric Domenjoud.
337 % \item[v2.3] Support \texttt{doc}'s \cs{saved@indexname} internal command,
338 % thanks to Falk Hanisch.
339 % \item[v2.2] New \texttt{macrolike} option allowing to create control
340 % sequence based documentation items.
341 % \item[v2.1] New lisp functions |doxitem[s]| to register new documentation
342 % environments with \auctex.
343 % \item[v2.0] Optional argument to \cs{doxitem} (\texttt{idxtype} option to
344 % change the item's index type).\\
345 % Optional argument to \cs{Describe}\meta{Item} and the \meta{item}
346 % environment (\texttt{noprint} to avoid marginal printing and
347 % \texttt{noindex} to avoid indexing).\\
348 % Extend \cs{DescribeMacro}, \cs{DescribeEnv} and their corresponding
349 % environments with the same features.
350 % \item[v1.0] First public version.
351 % \end{itemize}
352 %
353 % \StopEventually{\vfill\hfill\small \packagecopyright{}}
354 %
355 % \section{Implementation}
356 % \subsection{Preamble}
357 % \begin{macrocode}
358 %<dox>\NeedsTeXFormat{LaTeX2e}
359 %<*header>
360 \ProvidesPackage{dox}[2017/12/06 v2.4 Extensions to the doc package]
361
362 %</header>
363 %<*dox>
364 \RequirePackage{kvoptions}
365 \SetupKeyvalOptions{family=dox,prefix=dox@}
366
367 % \end{macrocode}
368 %
369 % \subsection{\dox options}
370 % These two options are available for use in \cs{usepackage} or in the
371 % generated item \api's:
372 % \begin{macrocode}
373 \DeclareBoolOption{noprint}
374 \DeclareBoolOption{noindex}
375 % \end{macrocode}
376 % This one is for \cs{usepackage} and \cs{doxitem}:
377 % \begin{macrocode}
378 \DeclareBoolOption{macrolike}
379 % \end{macrocode}
380 % This one is for \cs{doxitem}:
381 % \begin{macrocode}
382 \DeclareStringOption{idxtype}
383
384 % \end{macrocode}
385 %
386 % \subsection{\dox environments}
387 % \begin{macro}{\@@doxenv}
388 % \marg{item}\marg{name}\\
389 % In \texttt{doc.sty}, the \texttt{macro} and \texttt{environment}
390 % environments go through the \cs{m@cro@} macro which implements specific
391 % parts by testing a boolean condition as its first argument. This mechanism
392 % is not extensible, so I have to hack away a more generic version that
393 % would work for any new \texttt{dox} item, only which looks pretty much
394 % like the original one (with the addition of options management).
395 % \begin{macrocode}
396 \long\def\@@doxenv#1#2{%
397 \endgroup%
398 \topsep\MacroTopsep%
399 \trivlist%
400 \edef\saved@macroname{\string#2}%
401 % \end{macrocode}
402 % Since version 2.1g, \texttt{doc} creates a \cs{saved@indexname} command
403 % which in used by \cs{changes}. We now support that as well. The expansion of
404 % this command depends on whether the documented item is macrolike or not,
405 % which we don't know here (it's only know by \cs{doxitem}). That's why we
406 % need one specific command generating \cs{saved@indexname} the right way for
407 % every single item. These commands are named\cs{@Save\meta{item}IndexName};
408 % they are technically part of the generated API, only not meant for public
409 % use.
410 % \begin{macrocode}
411 \@nameuse{@Save#1IndexName}{\saved@macroname}%
412 \def\makelabel##1{\llap{##1}}%
413 \if@inlabel%
414 \let\@tempa\@empty%
415 \count@\macro@cnt%
416 \loop\ifnum\count@>\z@%
417 \edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne%
418 \repeat%
419 \edef\makelabel##1{\llap{\vtop to\baselineskip{\@tempa\hbox{##1}\vss}}}%
420 \advance\macro@cnt\@ne%
421 \else%
422 \macro@cnt\@ne%
423 \fi%
424 \ifdox@noprint%
425 \item%
426 \else%
427 \edef\@tempa{%
428 \noexpand\item[%
429 % \end{macrocode}
430 % The second notable modification to the original macro involves dynamically
431 % constructing the name of the print macro:
432 % \begin{macrocode}
433 \expandafter\noexpand\csname Print#1Name\endcsname{\saved@macroname}]}%
434 \@tempa%
435 \fi%
436 \ifdox@noindex\else%
437 \global\advance\c@CodelineNo\@ne%
438 % \end{macrocode}
439 % and the third one involves dynamically constructing the name of the index
440 % macro:
441 % \begin{macrocode}
442 \@nameuse{SpecialMain#1Index}{#2}\nobreak%
443 \global\advance\c@CodelineNo\m@ne%
444 \fi%
445 \ignorespaces}
446 % \end{macrocode}
447 % \end{macro}
448 % \begin{macro}{\@doxenv}
449 % \marg{item}\oarg{options}\\
450 % Handle optional arguments and call \cs{@@doxenv}. Because environments can
451 % be nested, we can't rely on grouping for getting options default values.
452 % Hence, we need to reset the options at every call.
453 % \begin{macrocode}
454 \def\@doxenv#1[#2]{%
455 \@nameuse{dox@noprint\dox@noprintdefault}%
456 \@nameuse{dox@noindex\dox@noindexdefault}%
457 \setkeys{dox}{#2}%
458 \begingroup%
459 \catcode`\\12%
460 \MakePrivateLetters%
461 \@@doxenv{#1}}
462
463 % \end{macrocode}
464 % \end{macro}
465 %
466 % \subsection{\dox descriptions}
467 % \begin{macro}{\@@doxdescribe}
468 % \marg{item}\marg{name}\\
469 % The first closed group was the one opened to parse the \meta{name}
470 % argument. The second one was opened to handle local options.
471 % \begin{macrocode}
472 \def\@@doxdescribe#1#2{%
473 \endgroup%
474 \ifdox@noprint\else%
475 \marginpar{\raggedleft\@nameuse{PrintDescribe#1}{#2}}%
476 \fi%
477 \ifdox@noindex\else%
478 \@nameuse{Special#1Index}{#2}%
479 \fi%
480 \endgroup%
481 \@esphack\ignorespaces}
482 % \end{macrocode}
483 % \end{macro}
484 % \begin{macro}{\@doxdescribe}
485 % \marg{item}\oarg{options}\\
486 % Handle optional arguments and call \cs{@@doxdescribe}.
487 % \begin{macrocode}
488 \def\@doxdescribe#1[#2]{%
489 \leavevmode\@bsphack%
490 \begingroup%
491 \setkeys{dox}{#2}%
492 \begingroup%
493 \MakePrivateLetters%
494 \@@doxdescribe{#1}}
495
496 % \end{macrocode}
497 % \end{macro}
498 %
499 % \subsection{API construction}
500 % First, the two index name generation macros (macrolike or not).
501 % \begin{macro}{\@doxsavemacrolikeindexname}
502 % \marg{saved macro name}
503 % \begin{macrocode}
504 \def\@doxsavemacrolikeindexname#1{%
505 \edef\saved@indexname{\expandafter\@gobble#1}}
506 % \end{macrocode}
507 % \end{macro}
508 % \begin{macro}{\@doxsaveindexname}
509 % \marg{saved macro name}
510 % \begin{macrocode}
511 \def\@doxsaveindexname#1{\let\saved@indexname#1}
512
513 % \end{macrocode}
514 % \end{macro}
515 %
516 % \begin{macro}{\@doxcreatespecialmainindex}
517 % \marg{item}\marg{idxtype}\marg{idxcat}
518 % \begin{macro}{\@doxcreatespecialmainmacrolikeindex}
519 % \marg{item}\marg{idxtype}\marg{idxcat}\\
520 % The ``macrolike'' version does something similar to |doc|'s
521 % \cs{SpecialIndex@} macro, but simplified. Let's just hope nobody will ever
522 % define \verb*|\ | or nonletter macros as macrolike \dox items\ldots
523 % \begin{macrocode}
524 \def\@doxcreatespecialmainindex#1#2#3{%
525 \expandafter\def\csname SpecialMain#1Index\endcsname##1{%
526 \@bsphack%
527 \special@index{##1\actualchar{\string\ttfamily\space##1} (#2)%
528 \encapchar main}%
529 \special@index{#3:\levelchar##1\actualchar{\string\ttfamily\space##1}%
530 \encapchar main}%
531 \@esphack}}
532 \def\@doxcreatespecialmainmacrolikeindex#1#2#3{%
533 \expandafter\def\csname SpecialMain#1Index\endcsname##1{%
534 \@SpecialIndexHelper@##1\@nil
535 \@bsphack%
536 \special@index{\@gtempa\actualchar
537 \string\verb\quotechar*\verbatimchar\bslash\@gtempa\verbatimchar
538 \space(#2)\encapchar main}%
539 \special@index{#3:\levelchar\@gtempa\actualchar%
540 \string\verb\quotechar*\verbatimchar\bslash\@gtempa\verbatimchar%
541 \encapchar main}%
542 \@esphack}}
543
544 % \end{macrocode}
545 % \end{macro}
546 % \end{macro}
547 % \begin{macro}{\@doxcreatespecialindex}
548 % \marg{item}\marg{idxtype}\marg{idxcat}
549 % \begin{macro}{\@doxcreatespecialmacrolikeindex}
550 % \marg{item}\marg{idxtype}\marg{idxcat}\\
551 % Same comment as above.
552 % \begin{macrocode}
553 \def\@doxcreatespecialindex#1#2#3{%
554 \expandafter\def\csname Special#1Index\endcsname##1{%
555 \@bsphack%
556 \index{##1\actualchar{\protect\ttfamily##1} (#2)\encapchar usage}%
557 \index{#3:\levelchar##1\actualchar{\protect\ttfamily##1}%
558 \encapchar usage}%
559 \@esphack}}
560 \def\@doxcreatespecialmacrolikeindex#1#2#3{%
561 \expandafter\def\csname Special#1Index\endcsname##1{%
562 \@SpecialIndexHelper@##1\@nil
563 \@bsphack%
564 \index{\@gtempa\actualchar
565 \string\verb\quotechar*\verbatimchar\bslash\@gtempa\verbatimchar
566 \space(#2)\encapchar usage}%
567 \index{#3:\levelchar\@gtempa\actualchar
568 \string\verb\quotechar*\verbatimchar\bslash\@gtempa\verbatimchar%
569 \encapchar usage}%
570 \@esphack}}
571
572 % \end{macrocode}
573 % \end{macro}
574 % \end{macro}
575 %
576 % \begin{macro}{\@doxcreatedescribe}
577 % \marg{item}
578 % \begin{macrocode}
579 \def\@doxcreatedescribe#1{%
580 \expandafter\def\csname Describe#1\endcsname{%
581 \@ifnextchar[%]
582 {\@doxdescribe{#1}}{\@doxdescribe{#1}[]}}}
583
584 % \end{macrocode}
585 % \end{macro}
586 % \begin{macro}{\@doxcreateenv}
587 % \marg{item}\marg{envname}
588 % \begin{macrocode}
589 \def\@doxcreateenv#1#2{%
590 \expandafter\def\csname #2\endcsname{%
591 \@ifnextchar[%]
592 {\@doxenv{#1}}{\@doxenv{#1}[]}}
593 \expandafter\let\csname end#2\endcsname\endtrivlist}
594
595 % \end{macrocode}
596 % \end{macro}
597 %
598 % \subsection{\texttt{Doc} overrides}
599 % \subsubsection{Macro facilities}
600 % Making \cs{DescribeMacro} work the \dox way is straightforward. The only
601 % precaution we need is to provide an alias to \cs{SpecialUsageIndex} because
602 % it should really be named \cs{SpecialMacroIndex}.
603 % \begin{macrocode}
604 \let\SpecialMacroIndex\SpecialUsageIndex
605 \@doxcreatedescribe{Macro}
606
607 % \end{macrocode}
608 % Making the \texttt{macro} environment work the \dox way is straightforward.
609 % The only precaution we need is to to provide a \cs{SpecialMainMacroIndex}
610 % macro that does the job originally done in \texttt{doc}'s \cs{m@cro@}.
611 % \begin{macrocode}
612 \def\SpecialMainMacroIndex#1{%
613 \SpecialMainIndex{#1}\nobreak%
614 \DoNotIndex{#1}}
615 \let\@SaveMacroIndexName\@doxsavemacrolikeindexname
616 \@doxcreateenv{Macro}{macro}
617
618 % \end{macrocode}
619 %
620 % \subsubsection{Environment facilities}
621 % Making \cs{DescribeEnv} and the \texttt{environment} environment work the
622 % \dox way is even more straightforward.
623 % \begin{macrocode}
624 \@doxcreatedescribe{Env}
625 \@doxcreateenv{Env}{environment}
626 \let\@SaveEnvIndexName\@doxsaveindexname
627
628 % \end{macrocode}
629 %
630 % \subsection{API creation}
631 % The whole user interface is created in one macro call.
632 % \begin{macro}{\doxitem}
633 % \oarg{options}\marg{name}\marg{envname}\marg{idxcat}
634 % \begin{macrocode}
635 \newcommand\doxitem[4][]{%
636 \@nameuse{dox@macrolike\dox@macrolikedefault}%
637 \def\dox@idxtype{#3}%
638 \setkeys{dox}{#1}
639 % \end{macrocode}
640 % \begin{macro}{\Print...Name}
641 % \marg{name}
642 % \begin{macrocode}
643 \@ifundefined{Print#2Name}{%
644 \ifdox@macrolike
645 \expandafter\def\csname Print#2Name\endcsname##1{%
646 \strut\MacroFont\string ##1\ }
647 \else
648 \expandafter\def\csname Print#2Name\endcsname##1{%
649 \strut\MacroFont ##1\ }
650 \fi}{}
651 % \end{macrocode}
652 % \end{macro}
653 % \begin{macro}{\SpecialMain...Index}
654 % \marg{name}
655 % \begin{macrocode}
656 \ifdox@macrolike
657 \def\@doxexpr{\@doxcreatespecialmainmacrolikeindex{#2}}%
658 \else
659 \def\@doxexpr{\@doxcreatespecialmainindex{#2}}%
660 \fi
661 \expandafter\@doxexpr\expandafter{\dox@idxtype}{#4}%
662 % \end{macrocode}
663 % \end{macro}
664 % \begin{macro}{\PrintDescribe...}
665 % \marg{name}
666 % \begin{macrocode}
667 \@ifundefined{PrintDescribe#2}{%
668 \ifdox@macrolike
669 \expandafter\def\csname PrintDescribe#2\endcsname##1{%
670 \strut\MacroFont\string ##1\ }
671 \else
672 \expandafter\def\csname PrintDescribe#2\endcsname##1{%
673 \strut\MacroFont ##1\ }
674 \fi}{}
675 % \end{macrocode}
676 % \end{macro}
677 % \begin{macro}{\Special...Index}
678 % \marg{name}
679 % \begin{macrocode}
680 \ifdox@macrolike
681 \def\@doxexpr{\@doxcreatespecialmacrolikeindex{#2}}%
682 \else
683 \def\@doxexpr{\@doxcreatespecialindex{#2}}%
684 \fi
685 \expandafter\@doxexpr\expandafter{\dox@idxtype}{#4}%
686 % \end{macrocode}
687 % \end{macro}
688 % \begin{macro}{\Describe...}
689 % \oarg{options}\marg{name}
690 % \begin{macrocode}
691 \@doxcreatedescribe{#2}
692 % \end{macrocode}
693 % \end{macro}
694 % \begin{environment}{item}
695 % \oarg{options}\marg{name}
696 % \begin{macrocode}
697 \@doxcreateenv{#2}{#3}
698 % \end{macrocode}
699 % \end{environment}
700 % \begin{macro}{\@Ssave...IndexName}
701 % \begin{macrocode}
702 \ifdox@macrolike
703 \expandafter\let\csname @Save#2IndexName\endcsname%
704 \@doxsavemacrolikeindexname%
705 \else
706 \expandafter\let\csname @Save#2IndexName\endcsname\@doxsaveindexname%
707 \fi}
708 % \end{macrocode}
709 % \end{macro}
710 % \end{macro}
711 %
712 % \subsection{Finale}
713 % We need to save the default value for every option because \dox environments
714 % need to reset them at every call.
715 % \begin{macrocode}
716 \ProcessKeyvalOptions*
717 \ifdox@noprint
718 \def\dox@noprintdefault{true}
719 \else
720 \def\dox@noprintdefault{false}
721 \fi
722 \ifdox@noindex
723 \def\dox@noindexdefault{true}
724 \else
725 \def\dox@noindexdefault{false}
726 \fi
727 \ifdox@macrolike
728 \def\dox@macrolikedefault{true}
729 \else
730 \def\dox@macrolikedefault{false}
731 \fi
732
733 %</dox>
734 % \end{macrocode}
735 % ^^A \PrintChanges
736 % ^^A Nobody messes up with the marks in this document, but \index@prologue.
737 % ^^A That sucks.
738 % ^^A \makeatletter{\let\markboth\@gobbletwo\PrintIndex}\makeatother
739 % \Finale
740 %
741 % ^^A dox.dtx ends here