summaryrefslogtreecommitdiff
path: root/Master
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-09-21 22:39:03 +0000
committerKarl Berry <karl@freefriends.org>2009-09-21 22:39:03 +0000
commit97748b815092e16107c3fbfbe08795cff718a5fa (patch)
tree832f306d645e13209f2450c05ee9e1c5ea42ab7e /Master
parent88d26d8a8079d7b343841bb875a83f89cb27e050 (diff)
dox 2.0 (21sep09)
git-svn-id: svn://tug.org/texlive/trunk@15409 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master')
-rw-r--r--Master/texmf-dist/doc/latex/dox/NEWS13
-rw-r--r--Master/texmf-dist/doc/latex/dox/README38
-rw-r--r--Master/texmf-dist/doc/latex/dox/THANKS0
-rw-r--r--Master/texmf-dist/doc/latex/dox/dox.el6
-rw-r--r--Master/texmf-dist/doc/latex/dox/dox.pdfbin112661 -> 114170 bytes
-rw-r--r--Master/texmf-dist/doc/latex/dox/header.inc2
-rw-r--r--Master/texmf-dist/source/latex/dox/dox.dtx529
-rw-r--r--Master/texmf-dist/tex/latex/dox/dox.sty165
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
Binary files differ
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'.