path: root/macros/latex/contrib/dox/dox.dtx

% \iffalse
%
% dox.dtx --- Doc file for DoX
%
% Copyright (C) 2009, 2010, 2017 Didier Verna
%
% Author: Didier Verna <didier@didierverna.net>
%
% This file is part of DoX.
%
% DoX may be distributed and/or modified under the conditions of the LaTeX
% Project Public License, either version 1.3 of this license or (at your
% option) any later version. The latest version of this license is in
% http://www.latex-project.org/lppl.txt and version 1.3 or later is part of
% all distributions of LaTeX version 2005/12/01 or later.
%
% DoX consists of the files listed in the file `README.md'.
%
%
% Commentary:
%
%
% Code:
%
%<*driver>
\documentclass[a4paper]{ltxdoc}
\usepackage[T1]{fontenc}
\usepackage{xspace}
\makeatletter
  \def\@currname{dox}
  \def\@currext{inc}
\makeatother
\input{header.inc}
% \OnlyDescription
\CodelineIndex
% \RecordChanges
\begin{document}
\DocInput{dox.dtx}
\end{document}
%</driver>
%
% \fi
%
% \CheckSum{390}
% \GetFileInfo{dox.inc}
%% \CharacterTable
%%  {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
%%   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
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%
% \MakeShortVerb{\|}
%
% \makeatletter
% \def\ps@mystyle{
%   \def\@oddfoot{\hfil\thepage\hfil}
%   \def\@evenfoot{\hfil\thepage\hfil}
%   \def\@evenhead{\hfil\slshape\leftmark}
%   \def\@oddhead{\slshape\rightmark\hfil}}
% \makeatother
%
% \newcommand\dox{\textsf{DoX}\xspace}
% \newcommand\packagecopyright{%
%   Copyright \copyright{} 2009, 2010, 2017 Didier Verna}
%
% \newcommand\emacs{\textsf{[X]Emacs}\xspace}
% \newcommand\auctex{AUC\TeX\xspace}
% \newcommand\api{\textsc{api}\xspace}
%
% \pagestyle{mystyle}
% \markright{\hskip-.5\marginparwidth \dox \fileversion{} (\filedate)}
%
% \date{\texttt{\fileversion{} (\filedate)}}
% \title{\dox{} -- \textsf{\textbf Doc}, \textbf only e\textbf
%   Xtended\footnote{\dox homepage:
%     \texttt{http://www.lrde.epita.fr/\~{}didier/software/latex.php\#dox}}}
% \author{Didier Verna\\
%   \texttt{mailto:didier@didierverna.net}\\
%   \texttt{http://www.lrde.epita.fr/\~{}didier/}}
% \maketitle
%
%
% \begin{abstract}
%   The \texttt{doc} package provides \LaTeX{} developers with means to
%   describe the usage and the definition of new commands and environments.
%   However, there is no simple way to extend this functionality to other
%   items (options or counters for instance). \dox is designed to circumvent
%   this limitation, and provides some improvements over the existing
%   functionality as well.
%
%   The \dox package is \packagecopyright{}, and distributed under the
%   terms of the LPPL license.
% \end{abstract}
%
% \tableofcontents
%
% \section{Installation}
% \subsection{Extraction}
% If you are building \dox from the tarball you need to execute the following
% steps in order to extract the necessary files:
% \begin{verbatim}
% [pdf]latex dox.ins
% [pdf]latex dox.dtx
% [pdf]latex dox.dtx
% \end{verbatim}
% After that, you need to install the generated documentation and style files
% to a location where \LaTeX{} can find them.
%
% \subsection{TDS-compliant layout}
% For a TDS-compliant layout, the following locations are suggested:
% \begin{verbatim}
% [TEXMF]/tex/latex/dox/dox.sty
% [TEXMF]/doc/latex/dox/dox.[pdf|dvi]
% \end{verbatim}
%
% \subsection{\auctex support}
% \auctex is a powerful major mode for editing \TeX{} documents in \emacs. In
% particular, it provides automatic completion of command names once they are
% known. \dox supports \auctex by providing a style file named \texttt{dox.el}
% which contains \auctex definitions for the relevant commands. This file
% should be installed in a place where \auctex can find it. Please refer to
% the \auctex documentation for more information on this. See also section
% \ref{sec:elisp}.
%
% \section{Usage}
% \subsection{Initialization}
% \subsubsection{Requirements}
% In order to work properly, \dox requires the presence of some \LaTeX{}
% packages. You don't have to load them explicitly though. As long as
% \LaTeX{} can locate them, they will be used automatically. \dox currently
% depends on \texttt{kvoptions}.
%
% \subsubsection{Loading the package}
% In order to load \dox, simply say |\usepackage[|\meta{options}|]{dox}|
% in the preamble of your document. The package options will be discussed when
% appropriate.
%
% \subsection{Creating new documentation items}
% \begin{quotation}
%   \emph{\textbf{Note}: we assume that you know about \texttt{doc}'s
%   \cs{DescribeMacro}, \cs{DescribeEnv} and all other associated commands and
%   environments}.
% \end{quotation}
% \DescribeMacro{\doxitem}
% \oarg{options}\marg{name}\marg{envname}\marg{idxcat}\\
% \dox provides a command named \cs{doxitem} to create new documentation items
% with functionalities equivalent to what \texttt{doc} provides for commands
% and environments. A whole \api is created for every new item.
%
% \subsubsection{Example}
% Perhaps the simplest way to describe what it does is to give an example.
% Suppose you would like to describe package options explicitely. Here is what
% you need to do:
% \begin{verbatim}
% \usepackage{dox}
% \doxitem{Option}{option}{options}
% \end{verbatim}
% \dox then creates the following \api for you:
% \begin{itemize}
% \item \cs{DescribeOption}
% \item the \texttt{option} environment
% \item \cs{PrintDescribeOption}
% \item \cs{PrintOptionName}
% \item \cs{SpecialMainOptionIndex}
% \item \cs{SpecialOptionIndex}
% \end{itemize}
% \begin{sloppypar}\noindent
%   In order to comply with \texttt{doc}'s original behavior, the commands
%   \cs{PrintDescribeOption} and \cs{PrintOptionName} will only be defined if
%   they do not already exist.
% \end{sloppypar}
%
% \subsubsection{Details}
% Here is a more precise description of the arguments to \cs{doxitem}.
% \begin{itemize}
% \item \meta{name} (\texttt{Option} in our example) is used to construct the
%   names of the commands in the new \api. It usually starts with an upcase
%   letter.
% \item \meta{envname} (\texttt{option} in our example) is the name of the
%   created environment. Be sure to avoid name clashes here! If you start
%   experimenting odd behavior, you've probably overridden an existing command
%   with your new environment.\footnote{It is a pity that \LaTeX{} use the
%   same namespace for commands and environments. The opening command for
%   environment \texttt{env} should be named \cs{beginenv} and not just
%   \cs{env}\ldots}
% \item \meta{idxcat} is the index category under which your items will
%   appear. In our example, all indexed options will be listed under the
%   ``options:'' index entry.
% \end{itemize}
%
% \subsubsection{Options to \cs{doxitem}}
% The first (optional) argument to \cs{doxitem} may contain a comma-separated
% list of options. The following ones are currently implemented.
% \begin{description}
% \item[\texttt{idxtype}]~\\
%   We saw earlier that individual items appear under the \texttt{idxcat}
%   index entry, but items also appear as standalone index entries,
%   alphabetically sorted with their type in parenthesis. For instance, the
%   \texttt{final} option would appear like this under the \texttt{F} index
%   entry: \mbox{``\texttt{final} (option)''}.
%
%   By default, the index type is the same as the environment's name (the
%   \meta{envname} argument). However, you can change this by providing a
%   value to the \texttt{idxtype} option.
%
%   For instance, you may find the word ``environment'' too long for an index
%   type. In that case, you may redefine the \texttt{environment} \api like
%   this:
% \begin{verbatim}
% \doxitem[idxtype=env.]{Env}{environment}{environments}
% \end{verbatim}
% \item[\texttt{macrolike}]~\\
%   At some point, you may find that the ``macro'' category is too gross, and
%   whish to further split it into different documentation items. A typical
%   example of this would be to provide a specific category for \LaTeX{}
%   lengths.
%
%   The difference with options or counters is that the names of your items
%   are actually control sequences, and so they need to be typeset and indexed
%   in a specific way.
%
%   As of version 2.2, \dox provides a \texttt{macrolike} boolean option which
%   instructs \cs{doxitem} to create new documentation items expecting control
%   sequences instead of plain text names. If you want to create explicit
%   documentation for lengths for instance, you can do this:
% \begin{verbatim}
% \doxitem[macrolike,idxtype=len.]{Length}{length}{lengths}
% \end{verbatim}
%   In turn this allows you do write things like that:
% \begin{verbatim}
% \DescribeLength{\partopsep}
% \begin{length}{\partopsep}
%   ...
% \end{length}
% \end{verbatim}
% \end{description}
%
% \subsection{Improvements over \texttt{doc}'s original \api}
% \begin{quotation}\itshape
%   Please note that the improvements described in this section are also
%   available in \texttt{doc}'s original command and environment \api's,
%   because \dox redefines them.
% \end{quotation}
%
% \subsubsection{Additional (optional) argument}
% Compared to \texttt{doc}, the \api's created by \cs{doxitem} are extended
% with a first optional argument containing a comma-separated list of options,
% such that, continuing with our initial example, the real prototypes are in
% fact the following:
% \begin{verbatim}
% \DescribeOption[opt,...]{name}
%
% \begin{option}[opt,...]{name}
% %% ...
% \end{option}
% \end{verbatim}
%
% \subsubsection{Available options}
% The options currently supported are:
% \begin{description}
% \item[noprint] Avoid printing \meta{name} in the margin
% \item[noindex] Avoid indexing \meta{name}
% \end{description}
% These options are useful if you don't want printing or indexing locally for
% one particular item. Without them, one would need to locally \cs{let} the
% relevant commands to \cs{@gobble} which is very inconvenient.
%
% There is also another advantage in using the \texttt{noprint} option: in
% \texttt{doc}'s original implementation, a margin paragraph will still be
% created just to be empty, hence wasting float resources. If you're
% referencing a lot of items close to each other, this may lead to a ``Too
% many unprocessed floats'' error. With \dox, the \cs{marginpar} is avoided
% altogether.
%
% \subsubsection{Global effect}
% The \texttt{macrolike}, \texttt{noprint} and \texttt{noindex} options are
% also available to \cs{usepackage}. Their effect then becomes global. Because
% these options are boolean, it is still possible to counteract their global
% effect locally. For instance, one could do:
% \begin{verbatim}
% \usepackage[noprint]{dox}
% \end{verbatim}
% and then later:
% \begin{verbatim}
% \DescribeOption[noprint=false]{french}
% \end{verbatim}
%
% \section{\auctex support for new documentation items\label{sec:elisp}}
% Recent versions of \auctex (in fact, \texttt{doc}\TeX{} mode) are aware of
% the \texttt{macro} and \texttt{environment} environments and give them a
% fixed indentation level of $0$, meaning no indentation at all even when they
% are nested. This is considered more convenient than the usual indentation
% for environments when editing \texttt{dtx} files. If you have created new
% documentation items for your package, you may want to let them behave the
% same way. For that, the \dox style file provides two Lisp functions to let
% \auctex know of your new environments: \texttt{doxitem} and
% \texttt{doxitems}. The first one registers a new environment by name with
% \auctex, and the second one takes an arbitrary number of environment names
% and does the same with them. The environment names can in fact be regular
% expressions, allowing you to combine several names together or build complex
% ones.
%
% Since these functions are located in the style file itself, a good place to
% use them is in \texttt{TeX-update-style-hook} which will be called after the
% file is parsed and the relevant style files applied. Note that the effect of
% calling these functions is always buffer-local.
%
% Here is an example to make all of this clearer. The following code sample is
% what I have at the end of \texttt{fixme.dxt} (another package of mine), in
% the local variables section:
% \begin{verbatim}
% (add-hook 'TeX-update-style-hook
%   (lambda () (doxitems "option" "counter" "lang" "face" "color")) nil t)
% (add-hook 'TeX-update-style-hook
%   (lambda () (doxitem "\\(env\\|target\\)?layout")) nil t)
% \end{verbatim}
%
% \section{Conclusion}
% If you want to see \dox in action, take a look at the documentation of the
% \textsf{FiXme} package (version 4.0 or later). In fact, I wrote \dox for it
% in the first place.
%
% \section{History}
% \begin{itemize}
% \item[v2.4] Improve \auctex support.\\
%   Fix spurious spaces in index entries, reported by Eric Domenjoud.
% \item[v2.3] Support \texttt{doc}'s \cs{saved@indexname} internal command,
%   thanks to Falk Hanisch.
% \item[v2.2] New \texttt{macrolike} option allowing to create control
%   sequence based documentation items.
% \item[v2.1] New lisp functions |doxitem[s]| to register new documentation
%   environments with \auctex.
% \item[v2.0] Optional argument to \cs{doxitem} (\texttt{idxtype} option to
%   change the item's index type).\\
%   Optional argument to \cs{Describe}\meta{Item} and the \meta{item}
%   environment (\texttt{noprint} to avoid marginal printing and
%   \texttt{noindex} to avoid indexing).\\
%   Extend \cs{DescribeMacro}, \cs{DescribeEnv} and their corresponding
%   environments with the same features.
% \item[v1.0] First public version.
% \end{itemize}
%
% \StopEventually{\vfill\hfill\small \packagecopyright{}}
%
% \section{Implementation}
% \subsection{Preamble}
%    \begin{macrocode}
%<dox>\NeedsTeXFormat{LaTeX2e}
%<*header>
\ProvidesPackage{dox}[2017/12/06 v2.4 Extensions to the doc package]

%</header>
%<*dox>
\RequirePackage{kvoptions}
\SetupKeyvalOptions{family=dox,prefix=dox@}

%    \end{macrocode}
%
% \subsection{\dox options}
% These two options are available for use in \cs{usepackage} or in the
% generated item \api's:
%    \begin{macrocode}
\DeclareBoolOption{noprint}
\DeclareBoolOption{noindex}
%    \end{macrocode}
% This one is for \cs{usepackage} and \cs{doxitem}:
%    \begin{macrocode}
\DeclareBoolOption{macrolike}
%    \end{macrocode}
% This one is for \cs{doxitem}:
%    \begin{macrocode}
\DeclareStringOption{idxtype}

%    \end{macrocode}
%
% \subsection{\dox environments}
% \begin{macro}{\@@doxenv}
%   \marg{item}\marg{name}\\
%   In \texttt{doc.sty}, the \texttt{macro} and \texttt{environment}
%   environments go through the \cs{m@cro@} macro which implements specific
%   parts by testing a boolean condition as its first argument. This mechanism
%   is not extensible, so I have to hack away a more generic version that
%   would work for any new \texttt{dox} item, only which looks pretty much
%   like the original one (with the addition of options management).
%    \begin{macrocode}
\long\def\@@doxenv#1#2{%
  \endgroup%
  \topsep\MacroTopsep%
  \trivlist%
    \edef\saved@macroname{\string#2}%
%    \end{macrocode}
% Since version 2.1g, \texttt{doc} creates a \cs{saved@indexname} command
% which in used by \cs{changes}. We now support that as well. The expansion of
% this command depends on whether the documented item is macrolike or not,
% which we don't know here (it's only know by \cs{doxitem}). That's why we
% need one specific command generating \cs{saved@indexname} the right way for
% every single item. These commands are named\cs{@Save\meta{item}IndexName};
% they are technically part of the generated API, only not meant for public
% use.
%    \begin{macrocode}
    \@nameuse{@Save#1IndexName}{\saved@macroname}%
    \def\makelabel##1{\llap{##1}}%
    \if@inlabel%
      \let\@tempa\@empty%
      \count@\macro@cnt%
      \loop\ifnum\count@>\z@%
        \edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne%
      \repeat%
      \edef\makelabel##1{\llap{\vtop to\baselineskip{\@tempa\hbox{##1}\vss}}}%
      \advance\macro@cnt\@ne%
    \else%
      \macro@cnt\@ne%
    \fi%
    \ifdox@noprint%
      \item%
    \else%
      \edef\@tempa{%
        \noexpand\item[%
%    \end{macrocode}
% The second notable modification to the original macro involves dynamically
% constructing the name of the print macro:
%    \begin{macrocode}
        \expandafter\noexpand\csname Print#1Name\endcsname{\saved@macroname}]}%
      \@tempa%
    \fi%
    \ifdox@noindex\else%
      \global\advance\c@CodelineNo\@ne%
%    \end{macrocode}
% and the third one involves dynamically constructing the name of the index
% macro:
%    \begin{macrocode}
      \@nameuse{SpecialMain#1Index}{#2}\nobreak%
      \global\advance\c@CodelineNo\m@ne%
    \fi%
    \ignorespaces}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\@doxenv}
%   \marg{item}\oarg{options}\\
%   Handle optional arguments and call \cs{@@doxenv}. Because environments can
%   be nested, we can't rely on grouping for getting options default values.
%   Hence, we need to reset the options at every call.
%    \begin{macrocode}
\def\@doxenv#1[#2]{%
  \@nameuse{dox@noprint\dox@noprintdefault}%
  \@nameuse{dox@noindex\dox@noindexdefault}%
  \setkeys{dox}{#2}%
  \begingroup%
    \catcode`\\12%
    \MakePrivateLetters%
    \@@doxenv{#1}}

%    \end{macrocode}
% \end{macro}
%
% \subsection{\dox descriptions}
% \begin{macro}{\@@doxdescribe}
%   \marg{item}\marg{name}\\
%   The first closed group was the one opened to parse the \meta{name}
%   argument. The second one was opened to handle local options.
%    \begin{macrocode}
\def\@@doxdescribe#1#2{%
    \endgroup%
    \ifdox@noprint\else%
      \marginpar{\raggedleft\@nameuse{PrintDescribe#1}{#2}}%
    \fi%
    \ifdox@noindex\else%
      \@nameuse{Special#1Index}{#2}%
    \fi%
    \endgroup%
  \@esphack\ignorespaces}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\@doxdescribe}
%   \marg{item}\oarg{options}\\
%   Handle optional arguments and call \cs{@@doxdescribe}.
%    \begin{macrocode}
\def\@doxdescribe#1[#2]{%
  \leavevmode\@bsphack%
  \begingroup%
    \setkeys{dox}{#2}%
    \begingroup%
      \MakePrivateLetters%
      \@@doxdescribe{#1}}

%    \end{macrocode}
% \end{macro}
%
% \subsection{API construction}
% First, the two index name generation macros (macrolike or not).
% \begin{macro}{\@doxsavemacrolikeindexname}
%   \marg{saved macro name}
%    \begin{macrocode}
\def\@doxsavemacrolikeindexname#1{%
  \edef\saved@indexname{\expandafter\@gobble#1}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\@doxsaveindexname}
%   \marg{saved macro name}
%    \begin{macrocode}
\def\@doxsaveindexname#1{\let\saved@indexname#1}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@doxcreatespecialmainindex}
%   \marg{item}\marg{idxtype}\marg{idxcat}
% \begin{macro}{\@doxcreatespecialmainmacrolikeindex}
%   \marg{item}\marg{idxtype}\marg{idxcat}\\
%   The ``macrolike'' version does something similar to |doc|'s
%   \cs{SpecialIndex@} macro, but simplified. Let's just hope nobody will ever
%   define \verb*|\ | or nonletter macros as macrolike \dox items\ldots
%    \begin{macrocode}
\def\@doxcreatespecialmainindex#1#2#3{%
  \expandafter\def\csname SpecialMain#1Index\endcsname##1{%
    \@bsphack%
    \special@index{##1\actualchar{\string\ttfamily\space##1} (#2)%
      \encapchar main}%
    \special@index{#3:\levelchar##1\actualchar{\string\ttfamily\space##1}%
      \encapchar main}%
    \@esphack}}
\def\@doxcreatespecialmainmacrolikeindex#1#2#3{%
  \expandafter\def\csname SpecialMain#1Index\endcsname##1{%
    \@SpecialIndexHelper@##1\@nil
    \@bsphack%
    \special@index{\@gtempa\actualchar
      \string\verb\quotechar*\verbatimchar\bslash\@gtempa\verbatimchar
      \space(#2)\encapchar main}%
    \special@index{#3:\levelchar\@gtempa\actualchar%
      \string\verb\quotechar*\verbatimchar\bslash\@gtempa\verbatimchar%
      \encapchar main}%
    \@esphack}}

%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\@doxcreatespecialindex}
%   \marg{item}\marg{idxtype}\marg{idxcat}
% \begin{macro}{\@doxcreatespecialmacrolikeindex}
%   \marg{item}\marg{idxtype}\marg{idxcat}\\
%   Same comment as above.
%    \begin{macrocode}
\def\@doxcreatespecialindex#1#2#3{%
  \expandafter\def\csname Special#1Index\endcsname##1{%
    \@bsphack%
    \index{##1\actualchar{\protect\ttfamily##1} (#2)\encapchar usage}%
    \index{#3:\levelchar##1\actualchar{\protect\ttfamily##1}%
      \encapchar usage}%
    \@esphack}}
\def\@doxcreatespecialmacrolikeindex#1#2#3{%
  \expandafter\def\csname Special#1Index\endcsname##1{%
    \@SpecialIndexHelper@##1\@nil
    \@bsphack%
    \index{\@gtempa\actualchar
      \string\verb\quotechar*\verbatimchar\bslash\@gtempa\verbatimchar
      \space(#2)\encapchar usage}%
    \index{#3:\levelchar\@gtempa\actualchar
      \string\verb\quotechar*\verbatimchar\bslash\@gtempa\verbatimchar%
      \encapchar usage}%
    \@esphack}}

%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@doxcreatedescribe}
%   \marg{item}
%    \begin{macrocode}
\def\@doxcreatedescribe#1{%
  \expandafter\def\csname Describe#1\endcsname{%
    \@ifnextchar[%]
    {\@doxdescribe{#1}}{\@doxdescribe{#1}[]}}}

%    \end{macrocode}
% \end{macro}
% \begin{macro}{\@doxcreateenv}
%   \marg{item}\marg{envname}
%    \begin{macrocode}
\def\@doxcreateenv#1#2{%
  \expandafter\def\csname #2\endcsname{%
    \@ifnextchar[%]
    {\@doxenv{#1}}{\@doxenv{#1}[]}}
  \expandafter\let\csname end#2\endcsname\endtrivlist}

%    \end{macrocode}
% \end{macro}
%
% \subsection{\texttt{Doc} overrides}
% \subsubsection{Macro facilities}
% Making \cs{DescribeMacro} work the \dox way is straightforward. The only
% precaution we need is to provide an alias to \cs{SpecialUsageIndex} because
% it should really be named \cs{SpecialMacroIndex}.
%    \begin{macrocode}
\let\SpecialMacroIndex\SpecialUsageIndex
\@doxcreatedescribe{Macro}

%    \end{macrocode}
% Making the \texttt{macro} environment work the \dox way is straightforward.
% The only precaution we need is to to provide a \cs{SpecialMainMacroIndex}
% macro that does the job originally done in \texttt{doc}'s \cs{m@cro@}.
%    \begin{macrocode}
\def\SpecialMainMacroIndex#1{%
  \SpecialMainIndex{#1}\nobreak%
  \DoNotIndex{#1}}
\let\@SaveMacroIndexName\@doxsavemacrolikeindexname
\@doxcreateenv{Macro}{macro}

%    \end{macrocode}
%
% \subsubsection{Environment facilities}
% Making \cs{DescribeEnv} and the \texttt{environment} environment work the
% \dox way is even more straightforward.
%    \begin{macrocode}
\@doxcreatedescribe{Env}
\@doxcreateenv{Env}{environment}
\let\@SaveEnvIndexName\@doxsaveindexname

%    \end{macrocode}
%
% \subsection{API creation}
% The whole user interface is created in one macro call.
% \begin{macro}{\doxitem}
%   \oarg{options}\marg{name}\marg{envname}\marg{idxcat}
%    \begin{macrocode}
\newcommand\doxitem[4][]{%
  \@nameuse{dox@macrolike\dox@macrolikedefault}%
  \def\dox@idxtype{#3}%
  \setkeys{dox}{#1}
%    \end{macrocode}
%   \begin{macro}{\Print...Name}
%     \marg{name}
%    \begin{macrocode}
  \@ifundefined{Print#2Name}{%
    \ifdox@macrolike
      \expandafter\def\csname Print#2Name\endcsname##1{%
        \strut\MacroFont\string ##1\ }
    \else
      \expandafter\def\csname Print#2Name\endcsname##1{%
        \strut\MacroFont ##1\ }
    \fi}{}
%    \end{macrocode}
%   \end{macro}
%   \begin{macro}{\SpecialMain...Index}
%     \marg{name}
%    \begin{macrocode}
  \ifdox@macrolike
    \def\@doxexpr{\@doxcreatespecialmainmacrolikeindex{#2}}%
  \else
    \def\@doxexpr{\@doxcreatespecialmainindex{#2}}%
  \fi
  \expandafter\@doxexpr\expandafter{\dox@idxtype}{#4}%
%    \end{macrocode}
%   \end{macro}
%   \begin{macro}{\PrintDescribe...}
%     \marg{name}
%    \begin{macrocode}
  \@ifundefined{PrintDescribe#2}{%
    \ifdox@macrolike
      \expandafter\def\csname PrintDescribe#2\endcsname##1{%
        \strut\MacroFont\string ##1\ }
    \else
      \expandafter\def\csname PrintDescribe#2\endcsname##1{%
        \strut\MacroFont ##1\ }
    \fi}{}
%    \end{macrocode}
%   \end{macro}
%   \begin{macro}{\Special...Index}
%     \marg{name}
%    \begin{macrocode}
  \ifdox@macrolike
    \def\@doxexpr{\@doxcreatespecialmacrolikeindex{#2}}%
  \else
    \def\@doxexpr{\@doxcreatespecialindex{#2}}%
  \fi
  \expandafter\@doxexpr\expandafter{\dox@idxtype}{#4}%
%    \end{macrocode}
%   \end{macro}
%   \begin{macro}{\Describe...}
%     \oarg{options}\marg{name}
%    \begin{macrocode}
  \@doxcreatedescribe{#2}
%    \end{macrocode}
%   \end{macro}
%   \begin{environment}{item}
%     \oarg{options}\marg{name}
%    \begin{macrocode}
  \@doxcreateenv{#2}{#3}
%    \end{macrocode}
%   \end{environment}
% \begin{macro}{\@Ssave...IndexName}
%    \begin{macrocode}
  \ifdox@macrolike
    \expandafter\let\csname @Save#2IndexName\endcsname%
      \@doxsavemacrolikeindexname%
  \else
    \expandafter\let\csname @Save#2IndexName\endcsname\@doxsaveindexname%
  \fi}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Finale}
% We need to save the default value for every option because \dox environments
% need to reset them at every call.
%    \begin{macrocode}
\ProcessKeyvalOptions*
\ifdox@noprint
  \def\dox@noprintdefault{true}
\else
  \def\dox@noprintdefault{false}
\fi
\ifdox@noindex
  \def\dox@noindexdefault{true}
\else
  \def\dox@noindexdefault{false}
\fi
\ifdox@macrolike
  \def\dox@macrolikedefault{true}
\else
  \def\dox@macrolikedefault{false}
\fi

%</dox>
%    \end{macrocode}
% ^^A \PrintChanges
% ^^A Nobody messes up with the marks in this document, but \index@prologue.
% ^^A That sucks.
% ^^A \makeatletter{\let\markboth\@gobbletwo\PrintIndex}\makeatother
% \Finale
%
% ^^A dox.dtx ends here