dox 2.0 (21sep09)

git-svn-id: svn://tug.org/texlive/trunk@15409 c570f23f-e606-0410-a88d-b1316a301751

8 files changed, 596 insertions, 157 deletions

diff --git a/Master/texmf-dist/doc/latex/dox/NEWS b/Master/texmf-dist/doc/latex/dox/NEWS
index b7f27cb159b..bdd77517df2 100644
--- a/Master/texmf-dist/doc/latex/dox/NEWS
+++ b/Master/texmf-dist/doc/latex/dox/NEWS
@@ -17,6 +17,19 @@ version 1999/06/01 or later.
 DoX consists of the files listed in the file `README'.
 
 
+* Version 2.0
+=============
+** Optional argument to \doxitem
+idxtype option to change the item's index type
+
+** Optional argument to \Describe<Item> and the <Item> environment
+noprint option to avoid marginal printing
+noindex option to avoid item indexing
+
+** Extend \DescribeMacro, \DescribeEnv and their corresponding environments
+with the same features
+
+
 * Version 1.0
 =============
 ** First public version
diff --git a/Master/texmf-dist/doc/latex/dox/README b/Master/texmf-dist/doc/latex/dox/README
index 5356e7a7b6d..a856f77065d 100644
--- a/Master/texmf-dist/doc/latex/dox/README
+++ b/Master/texmf-dist/doc/latex/dox/README
@@ -18,7 +18,6 @@ DoX consists of the following files:
 
 - README (this file)
 - NEWS
-- THANKS
 - dox.ins
 - dox.dtx
 - dox.el
@@ -28,31 +27,42 @@ DoX consists of the following files:
 =============
 
 The doc package provides LaTeX developers with means to describe the usage and
-the definition of new macros and environments. However, there is no simple way
-to extend this functionality to other items (options or counters for
-instance). The DoX package is designed to circumvent this limitation. DoX also
-comes with support for AUC-TeX.
+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.
+
+DoX homepage: http://www.lrde.epita.fr/~didier/software/latex.php#dox
 
 
 * Installation
 ==============
 
-	To install the package, please follow these steps:
+If you are building DoX from the tarball you need to execute the following
+steps in order to extract the necessary files: 
+
+[pdf]latex dox.ins 
+[pdf]latex dox.dtx 
+[pdf]latex dox.dtx 
+
+After that, you need to install the generated documentation and style file to
+a location where LaTeX can find them. For a TDS-compliant layout, the
+following locations are suggested:
+
+[TEXMF]/tex/latex/dox/dox.sty 
+[TEXMF]/doc/latex/dox/dox.[pdf|dvi] 
 
-- Run LaTeX on the file `dox.ins' to create the style file `dox.sty'.
-- Run LaTeX on the file `dox.dtx' to create the documentation.
-- Install these files anywhere you see fit.
+If you're an AUC-TeX user, you may also install the file 'dox.el' in a
+suitable AUC-TeX style directory.
 
-	If you're an AUC-TeX user, you can also install the file `dox.el' in
-a suitable AUC-TeX style directory.
 
 	Have fun!
 
 --
-Didier Verna, didier@lrde.epita.fr, http://www.lrde.epita.fr/~didier
+Didier Verna <didier@lrde.epita.fr>
 
-EPITA / LRDE, 14-16 rue Voltaire   Tel.+33 (0)1 44 08 01 85
-94276 Le Kremlin-Bicêtre, France   Fax.+33 (0)1 53 14 59 22
+Sientific site:    http://www.lrde.epita.fr/~didier
+Music (Jazz) site: http://www.didierverna.com
 
 
 
diff --git a/Master/texmf-dist/doc/latex/dox/THANKS b/Master/texmf-dist/doc/latex/dox/THANKS
deleted file mode 100644
index e69de29bb2d..00000000000
--- a/Master/texmf-dist/doc/latex/dox/THANKS
+++ /dev/null
diff --git a/Master/texmf-dist/doc/latex/dox/dox.el b/Master/texmf-dist/doc/latex/dox/dox.el
index b233a1e47a9..ca6496fb870 100644
--- a/Master/texmf-dist/doc/latex/dox/dox.el
+++ b/Master/texmf-dist/doc/latex/dox/dox.el
@@ -5,7 +5,7 @@
 ;; Author:        Didier Verna <didier@lrde.epita.fr>
 ;; Maintainer:    Didier Verna <didier@lrde.epita.fr>
 ;; Created:       Fri Sep 11 11:24:16 2009
-;; Last Revision: Fri Sep 11 11:26:28 2009
+;; Last Revision: Sat Sep 19 09:54:43 2009
 ;; Keywords:      tex abbrev data
 
 
@@ -33,7 +33,9 @@
 (TeX-add-style-hook "dox"
   (function
    (lambda ()
-     (TeX-add-symbols '("doxitem" "Functions name" "singular" "plural")))))
+     (TeX-add-symbols
+      '("doxitem" [ "Options" ]
+	"Function name" "Environment name" "Index category name")))))
 
 
 
diff --git a/Master/texmf-dist/doc/latex/dox/dox.pdf b/Master/texmf-dist/doc/latex/dox/dox.pdf
index 47907177c4b..ecc1d727932 100644
--- a/Master/texmf-dist/doc/latex/dox/dox.pdf
+++ b/Master/texmf-dist/doc/latex/dox/dox.pdf
diff --git a/Master/texmf-dist/doc/latex/dox/header.inc b/Master/texmf-dist/doc/latex/dox/header.inc
index 155b3aa1de6..163ed9c6f68 100644
--- a/Master/texmf-dist/doc/latex/dox/header.inc
+++ b/Master/texmf-dist/doc/latex/dox/header.inc
@@ -37,7 +37,7 @@
 %%   Right bracket \]     Circumflex    \^     Underscore    \_
 %%   Grave accent  \`     Left brace    \{     Vertical bar  \|
 %%   Right brace   \}     Tilde         \~}
-\ProvidesPackage{dox}[2009/09/11 v1.0 Extensions to the doc package]
+\ProvidesPackage{dox}[2009/09/21 v2.0 Extensions to the doc package]
 
 \endinput
 %%
diff --git a/Master/texmf-dist/source/latex/dox/dox.dtx b/Master/texmf-dist/source/latex/dox/dox.dtx
index 7e2557820e1..f7eabfa4fef 100644
--- a/Master/texmf-dist/source/latex/dox/dox.dtx
+++ b/Master/texmf-dist/source/latex/dox/dox.dtx
@@ -1,4 +1,4 @@
-% \iffalse                                                 -*- mode: LaTeX -*-
+% \iffalse
 %
 % dox.dtx --- Doc file for the DoX package (code and documentation)
 %
@@ -7,7 +7,7 @@
 % Author:        Didier Verna <didier@lrde.epita.fr>
 % Maintainer:    Didier Verna <didier@lrde.epita.fr>
 % Created:       Thu Sep 10 21:11:32 2009
-% Last Revision: Fri Sep 11 11:20:13 2009
+% Last Revision: Sat Sep 19 09:55:31 2009
 %
 % This file is part of DoX.
 %
@@ -48,7 +48,7 @@
 % \fi
 %
 % \catcode`\¡=14
-% \CheckSum{157}
+% \CheckSum{247}
 % \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
@@ -80,11 +80,17 @@
 % \newcommand\packagecopyright{%
 %   Copyright \copyright{} 2009 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}
+% \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@lrde.epita.fr}\\
 %   \texttt{http://www.lrde.epita.fr/\~{}didier/}}
@@ -93,30 +99,80 @@
 %
 % \begin{abstract}
 %   The \texttt{doc} package provides \LaTeX{} developers with means to
-%   describe the usage and the definition of new macros and environments.
+%   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). The \texttt{dox} package is
-%   designed to circumvent this limitation.
+%   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}
 %
-% ^^A \tableofcontents
+% \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.
+%
 %
 % \section{Usage}
-% \emph{Note: we assume that you know about \texttt{doc}'s \cs{DescribeMacro},
-%   \cs{DescribeEnv} and all other associated commands and environments}.
-%
-% \medskip\noindent
-% \DescribeMacro{\doxitem}\marg{funcsname}\marg{singular}\marg{plural}\\
-% The \dox style provides a single user-level command to create new items with
-% functionalities equivalent to what \texttt{doc} provides for macros and
-% environments. Perhaps the simplest way to describe how it works is to give
-% an example. Suppose you would like to describe package options. Here is what
-% you need to do:
+% \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. 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:
+% \dox then creates the following \api for you:
 % \begin{itemize}
 % \item \cs{DescribeOption}
 % \item the \texttt{option} environment
@@ -125,8 +181,119 @@
 % \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}}
+% \item \meta{idxcat} (\texttt{options} in our example) is the index category
+%   under which your items will appear. For example, all indexed options will
+%   be listed in 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. Currently, there is only one supported option:
+% \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}
+%
+% \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}
+% All options described in the previous section 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{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.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}
 %
-% That's about it.
 % \StopEventually{\vfill\hfill\small \packagecopyright{}.}
 %
 % \section{Implementation}
@@ -134,68 +301,135 @@
 %    \begin{macrocode}
 %<dox>\NeedsTeXFormat{LaTeX2e}
 %<*header>
-\ProvidesPackage{dox}[2009/09/11 v1.0 Extensions to the doc package]
+\ProvidesPackage{dox}[2009/09/21 v2.0 Extensions to the doc package]
 
 %</header>
+%<*dox>
+\RequirePackage{kvoptions}
+\SetupKeyvalOptions{family=dox,prefix=dox@}
+
 %    \end{macrocode}
-% \subsection{Real job execution}
-% \begin{macro}{\doxm@cro@}
-%   \marg{item}\marg{contents}\\
-%   In \texttt{doc.sty}, the macro and environment environments go through the
-%   \cs{m@cro@} command 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:
+%
+% \subsection{\dox options}
+% These two options are available for use in \cs{usepackage} or in the
+% generated item \api's:
 %    \begin{macrocode}
-%<*dox>
-\long\def\doxm@cro@#1#2{%
+\DeclareBoolOption{noprint}
+\DeclareBoolOption{noindex}
+%    \end{macrocode}
+% This one is for \cs{doxitem} only:
+%    \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.
+%    \begin{macrocode}
+\long\def\@@doxenv#1#2{%
   \endgroup%
-  \topsep\MacroTopsep\trivlist
-  \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
-  \edef\@tempa{%
-    \noexpand\item[%
-%    \end{macrocode}
-% That's the first modification:
-%    \begin{macrocode}
-      \expandafter\noexpand\csname Print#1Name\endcsname{\string#2}]}%
-  \@tempa
-  \global\advance\c@CodelineNo\@ne
-%    \end{macrocode}
-% And that's the second one:
-%    \begin{macrocode}
-  \@nameuse{SpecialMain#1Index}{#2}\nobreak
-  \global\advance\c@CodelineNo\m@ne
-  \ignorespaces}
+  \topsep\MacroTopsep%
+  \trivlist%
+    \edef\saved@macroname{\string#2}%
+    \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}
+% Apart from dependency on options, the first 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 second 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{API creation}
-% \begin{macro}{\doxitem}
-%   \marg{funcsname}\marg{singular}\marg{plural}
+%
+% \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}
-\newcommand\doxitem[3]{%
+\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}
-% The \cs{Print}\meta{item}\texttt{Name} macro:
+% \end{macro}
+% \begin{macro}{\@doxdescribe}
+%   \marg{item}\oarg{options}\\
+%   Handle optional arguments and call \cs{@@doxdescribe}.
 %    \begin{macrocode}
-  \@ifundefined{Print#1Name}{%
-    \expandafter\def\csname Print#1Name\endcsname##1{%
-      \strut\MacroFont\string##1\ }}{}
+\def\@doxdescribe#1[#2]{%
+  \leavevmode\@bsphack%
+  \begingroup%
+    \setkeys{dox}{#2}%
+    \begingroup%
+      \MakePrivateLetters%
+      \@@doxdescribe{#1}}
+
 %    \end{macrocode}
-% The \cs{SpecialMain}\meta{item}\texttt{Index} macro:
+% \end{macro}
+%
+% \subsection{API construction}
+% \begin{macro}{\@doxcreatespecialmainindex}
+%   \marg{item}\marg{idxtype}\marg{idxcat}
 %    \begin{macrocode}
+\def\@doxcreatespecialmainindex#1#2#3{%
   \expandafter\def\csname SpecialMain#1Index\endcsname##1{%
     \@bsphack%
     \special@index{%
@@ -203,48 +437,153 @@
     \special@index{%
       #3:\levelchar##1\actualchar%
       {\string\ttfamily\space##1}\encapchar main}%
-    \@esphack}
-%    \end{macrocode}
-% The \cs{PrintDescribe}\meta{item} macro:
-%    \begin{macrocode}
-  \@ifundefined{PrintDescribe#1}{%
-    \expandafter\def\csname PrintDescribe#1\endcsname##1{%
-      \strut\MacroFont##1\ }}{}
+    \@esphack}}
+
 %    \end{macrocode}
-% The \cs{Special}\meta{item}\texttt{Index} macro:
+% \end{macro}
+% \begin{macro}{\@doxcreatespecialindex}
+%   \marg{item}\marg{idxtype}\marg{idxcat}
 %    \begin{macrocode}
-  \expandafter\def\csname Special#1Index\endcsname##1{\@bsphack
+\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}
-%    \end{macrocode}
-% The \cs{Describe@}\meta{item} macro:
-%    \begin{macrocode}
-  \expandafter\def\csname Describe@#1\endcsname##1{%
-    \endgroup
-    \marginpar{\raggedleft\@nameuse{PrintDescribe#1}{##1}}%
-    \@nameuse{Special#1Index}{##1}\@esphack\ignorespaces}
+      usage}%
+    \@esphack}}
+
 %    \end{macrocode}
-% The \cs{Describe}\meta{item} macro:
+% \end{macro}
+%
+% \begin{macro}{\@doxcreatedescribe}
+%   \marg{item}
 %    \begin{macrocode}
+\def\@doxcreatedescribe#1{%
   \expandafter\def\csname Describe#1\endcsname{%
-    \leavevmode\@bsphack\begingroup\MakePrivateLetters
-    \@nameuse{Describe@#1}}
+    \@ifnextchar[%]
+    {\@doxdescribe{#1}}{\@doxdescribe{#1}[]}}}
+
 %    \end{macrocode}
-% The \meta{item} environment:
+% \end{macro}
+% \begin{macro}{\@doxcreateenv}
+%   \marg{item}\marg{envname}
 %    \begin{macrocode}
+\def\@doxcreateenv#1#2{%
   \expandafter\def\csname #2\endcsname{%
-    \begingroup
-      \catcode`\\12
-      \MakePrivateLetters\doxm@cro@{#1}}
+    \@ifnextchar[%]
+    {\@doxenv{#1}}{\@doxenv{#1}[]}}
   \expandafter\let\csname end#2\endcsname\endtrivlist}
 
-%</dox>
 %    \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 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}}
+\@doxcreateenv{Macro}{macro}
+
+%    \end{macrocode}
+%
+% \subsubsection{Environment facilities}
+% Making \cs{DescribeEnv} and the \texttt{environment} environment work the
+% \dox way is straightforward.
+%    \begin{macrocode}
+\@doxcreatedescribe{Env}
+\@doxcreateenv{Env}{environment}
+
+%    \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][]{%
+  \def\dox@idxtype{#3}%
+  \setkeys{dox}{#1}
+%    \end{macrocode}
+%   \begin{macro}{\Print...Name}
+%     \marg{name}
+%    \begin{macrocode}
+  \@ifundefined{Print#2Name}{%
+    \expandafter\def\csname Print#2Name\endcsname##1{%
+      \strut\MacroFont##1\ }}{}
+%    \end{macrocode}
+%   \end{macro}
+%   \begin{macro}{\SpecialMain...Index}
+%     \marg{name}
+%    \begin{macrocode}
+  \def\@doxexpr{\@doxcreatespecialmainindex{#2}}%
+  \expandafter\@doxexpr\expandafter{\dox@idxtype}{#4}%
+%    \end{macrocode}
+%   \end{macro}
+%   \begin{macro}{\PrintDescribe...}
+%     \marg{name}
+%    \begin{macrocode}
+  \@ifundefined{PrintDescribe#2}{%
+    \expandafter\def\csname PrintDescribe#2\endcsname##1{%
+      \strut\MacroFont##1\ }}{}
+%    \end{macrocode}
+%   \end{macro}
+%   \begin{macro}{\Special...Index}
+%     \marg{name}
+%    \begin{macrocode}
+  \def\@doxexpr{\@doxcreatespecialindex{#2}}%
+  \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}
+% \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
+
+%</dox>
+%    \end{macrocode}
 % ^^A \PrintChanges
-% ^^A \PrintIndex
+% ^^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
diff --git a/Master/texmf-dist/tex/latex/dox/dox.sty b/Master/texmf-dist/tex/latex/dox/dox.sty
index 592dfa7a290..c493fb6b8b1 100644
--- a/Master/texmf-dist/tex/latex/dox/dox.sty
+++ b/Master/texmf-dist/tex/latex/dox/dox.sty
@@ -38,38 +38,74 @@
 %%   Grave accent  \`     Left brace    \{     Vertical bar  \|
 %%   Right brace   \}     Tilde         \~}
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{dox}[2009/09/11 v1.0 Extensions to the doc package]
+\ProvidesPackage{dox}[2009/09/21 v2.0 Extensions to the doc package]
 
-\long\def\doxm@cro@#1#2{%
+\RequirePackage{kvoptions}
+\SetupKeyvalOptions{family=dox,prefix=dox@}
+
+\DeclareBoolOption{noprint}
+\DeclareBoolOption{noindex}
+\DeclareStringOption{idxtype}
+
+\long\def\@@doxenv#1#2{%
   \endgroup%
-  \topsep\MacroTopsep\trivlist
-  \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
-  \edef\@tempa{%
-    \noexpand\item[%
-      \expandafter\noexpand\csname Print#1Name\endcsname{\string#2}]}%
-  \@tempa
-  \global\advance\c@CodelineNo\@ne
-  \@nameuse{SpecialMain#1Index}{#2}\nobreak
-  \global\advance\c@CodelineNo\m@ne
-  \ignorespaces}
-
-\newcommand\doxitem[3]{%
-  \@ifundefined{Print#1Name}{%
-    \expandafter\def\csname Print#1Name\endcsname##1{%
-      \strut\MacroFont\string##1\ }}{}
+  \topsep\MacroTopsep%
+  \trivlist%
+    \edef\saved@macroname{\string#2}%
+    \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[%
+        \expandafter\noexpand\csname Print#1Name\endcsname{\saved@macroname}]}%
+      \@tempa%
+    \fi%
+    \ifdox@noindex\else%
+      \global\advance\c@CodelineNo\@ne%
+      \@nameuse{SpecialMain#1Index}{#2}\nobreak%
+      \global\advance\c@CodelineNo\m@ne%
+    \fi%
+    \ignorespaces}
+\def\@doxenv#1[#2]{%
+  \@nameuse{dox@noprint\dox@noprintdefault}%
+  \@nameuse{dox@noindex\dox@noindexdefault}%
+  \setkeys{dox}{#2}%
+  \begingroup%
+    \catcode`\\12%
+    \MakePrivateLetters%
+    \@@doxenv{#1}}
+
+\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}
+\def\@doxdescribe#1[#2]{%
+  \leavevmode\@bsphack%
+  \begingroup%
+    \setkeys{dox}{#2}%
+    \begingroup%
+      \MakePrivateLetters%
+      \@@doxdescribe{#1}}
+
+\def\@doxcreatespecialmainindex#1#2#3{%
   \expandafter\def\csname SpecialMain#1Index\endcsname##1{%
     \@bsphack%
     \special@index{%
@@ -77,28 +113,67 @@
     \special@index{%
       #3:\levelchar##1\actualchar%
       {\string\ttfamily\space##1}\encapchar main}%
-    \@esphack}
-  \@ifundefined{PrintDescribe#1}{%
-    \expandafter\def\csname PrintDescribe#1\endcsname##1{%
-      \strut\MacroFont##1\ }}{}
-  \expandafter\def\csname Special#1Index\endcsname##1{\@bsphack
+    \@esphack}}
+
+\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}
-  \expandafter\def\csname Describe@#1\endcsname##1{%
-    \endgroup
-    \marginpar{\raggedleft\@nameuse{PrintDescribe#1}{##1}}%
-    \@nameuse{Special#1Index}{##1}\@esphack\ignorespaces}
+      usage}%
+    \@esphack}}
+
+\def\@doxcreatedescribe#1{%
   \expandafter\def\csname Describe#1\endcsname{%
-    \leavevmode\@bsphack\begingroup\MakePrivateLetters
-    \@nameuse{Describe@#1}}
+    \@ifnextchar[%]
+    {\@doxdescribe{#1}}{\@doxdescribe{#1}[]}}}
+
+\def\@doxcreateenv#1#2{%
   \expandafter\def\csname #2\endcsname{%
-    \begingroup
-      \catcode`\\12
-      \MakePrivateLetters\doxm@cro@{#1}}
+    \@ifnextchar[%]
+    {\@doxenv{#1}}{\@doxenv{#1}[]}}
   \expandafter\let\csname end#2\endcsname\endtrivlist}
 
+\let\SpecialMacroIndex\SpecialUsageIndex
+\@doxcreatedescribe{Macro}
+
+\def\SpecialMainMacroIndex#1{%
+  \SpecialMainIndex{#1}\nobreak%
+  \DoNotIndex{#1}}
+\@doxcreateenv{Macro}{macro}
+
+\@doxcreatedescribe{Env}
+\@doxcreateenv{Env}{environment}
+
+\newcommand\doxitem[4][]{%
+  \def\dox@idxtype{#3}%
+  \setkeys{dox}{#1}
+  \@ifundefined{Print#2Name}{%
+    \expandafter\def\csname Print#2Name\endcsname##1{%
+      \strut\MacroFont##1\ }}{}
+  \def\@doxexpr{\@doxcreatespecialmainindex{#2}}%
+  \expandafter\@doxexpr\expandafter{\dox@idxtype}{#4}%
+  \@ifundefined{PrintDescribe#2}{%
+    \expandafter\def\csname PrintDescribe#2\endcsname##1{%
+      \strut\MacroFont##1\ }}{}
+  \def\@doxexpr{\@doxcreatespecialindex{#2}}%
+  \expandafter\@doxexpr\expandafter{\dox@idxtype}{#4}%
+  \@doxcreatedescribe{#2}
+  \@doxcreateenv{#2}{#3}}
+
+\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
+
 \endinput
 %%
 %% End of file `dox.sty'.