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