summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/dox
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/dox
Initial commit
Diffstat (limited to 'macros/latex/contrib/dox')
-rw-r--r--macros/latex/contrib/dox/NEWS53
-rw-r--r--macros/latex/contrib/dox/README.md56
-rw-r--r--macros/latex/contrib/dox/THANKS31
-rw-r--r--macros/latex/contrib/dox/dox.dtx741
-rw-r--r--macros/latex/contrib/dox/dox.el64
-rw-r--r--macros/latex/contrib/dox/dox.ins47
-rw-r--r--macros/latex/contrib/dox/dox.pdfbin0 -> 157525 bytes
7 files changed, 992 insertions, 0 deletions
diff --git a/macros/latex/contrib/dox/NEWS b/macros/latex/contrib/dox/NEWS
new file mode 100644
index 0000000000..044d924154
--- /dev/null
+++ b/macros/latex/contrib/dox/NEWS
@@ -0,0 +1,53 @@
+ WHAT'S NEW IN 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'.
+
+
+*Version 2.4
+** Improve AUCTeX support
+** Fix spurious spaces in index entries
+reported by Eric Domenjoud.
+
+* Version 2.3
+** Support Doc's internal \saved@indexname command
+thanks to Falk Hanisch.
+
+* Version 2.2
+** New option 'macrolike' to \doxitem
+allowing to create control sequence based documentation items.
+
+* Version 2.1
+** New lisp functions doxitem[s]
+to register new documentation environments with AUCTeX.
+
+* 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
+
+
+
+
+Local Variables:
+mode: outline
+End:
diff --git a/macros/latex/contrib/dox/README.md b/macros/latex/contrib/dox/README.md
new file mode 100644
index 0000000000..9c0fe8e123
--- /dev/null
+++ b/macros/latex/contrib/dox/README.md
@@ -0,0 +1,56 @@
+ABOUT 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 following files:
+
+- README.md (this file)
+- NEWS
+- dox.ins
+- dox.dtx
+- dox.el
+- THANKS
+
+
+Description
+-----------
+
+The 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. Dox also comes with
+support for [AUCTeX](https://www.gnu.org/software/auctex/).
+
+DoX homepage: http://www.lrde.epita.fr/~didier/software/latex.php#dox
+
+
+Installation
+------------
+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]
+
+If you're an AUCTeX user, you may also install the file `dox.el` in a
+suitable AUCTeX style directory.
diff --git a/macros/latex/contrib/dox/THANKS b/macros/latex/contrib/dox/THANKS
new file mode 100644
index 0000000000..cb7f9d1d00
--- /dev/null
+++ b/macros/latex/contrib/dox/THANKS
@@ -0,0 +1,31 @@
+ THANK YOU!
+
+
+Copyright (C) 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'.
+
+
+* Contributors
+
+** The following persons have contributed code, bug reports, localization,
+** suggestions etc.:
+
+Eric Domenjoud, Falk Hanisch.
+
+
+
+
+Local Variables:
+mode: outline
+End:
diff --git a/macros/latex/contrib/dox/dox.dtx b/macros/latex/contrib/dox/dox.dtx
new file mode 100644
index 0000000000..212b343189
--- /dev/null
+++ b/macros/latex/contrib/dox/dox.dtx
@@ -0,0 +1,741 @@
+% \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
diff --git a/macros/latex/contrib/dox/dox.el b/macros/latex/contrib/dox/dox.el
new file mode 100644
index 0000000000..2de037d5ed
--- /dev/null
+++ b/macros/latex/contrib/dox/dox.el
@@ -0,0 +1,64 @@
+;;; dox.el --- AUCTeX style file for DoX
+
+;; Copyright (C) 2009, 2010, 2017 Didier Verna
+
+;; Author: Didier Verna <didier@didierverna.net>
+;; Keywords: tex abbrev data
+
+;; 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 all files listed in the file `README.md'.
+
+
+;;; Commentary:
+
+
+;;; Code:
+
+(TeX-add-style-hook "dox"
+ (lambda ()
+ (TeX-add-symbols
+ '("doxitem" [ TeX-arg-key-val (("idxtype") ("macrolike")) ]
+ "Function name" "Environment name" "Index category name"))
+ (when (and (featurep 'font-latex)
+ (eq TeX-install-font-lock 'font-latex-setup))
+ (font-latex-add-keywords '(("doxitem" "[{{{")) 'function)))
+ LaTeX-dialect)
+
+(defun doxitem (envname)
+ "Register a new environment ENVNAME with AUCTeX.
+The effect is to make docTeX mode treat this new environment just
+like the macro and environment ones. Currently, this means
+avoiding inner indentation.
+
+ENVNAME is actually a regexp appearing in a logical group. This
+means that you can register several environments simultaneously
+by means or regexp combination."
+ (make-local-variable 'docTeX-indent-inner-fixed)
+ (push (list
+ (concat (regexp-quote TeX-esc)
+ "\\(begin\\|end\\)[ \t]*{\\("
+ envname
+ "\\)\\*?}")
+ 0 nil)
+ docTeX-indent-inner-fixed))
+
+(defun doxitems (&rest envnames)
+ "Register environments ENVNAMES with AUCTeX.
+See the function `doxitem' for more information."
+ (mapc #'doxitem envnames))
+
+
+
+
+;;; Local variables:
+;;; eval: (put 'TeX-add-style-hook 'lisp-indent-function 1)
+;;; End:
+
+;;; dox.el ends here
diff --git a/macros/latex/contrib/dox/dox.ins b/macros/latex/contrib/dox/dox.ins
new file mode 100644
index 0000000000..2a692d5878
--- /dev/null
+++ b/macros/latex/contrib/dox/dox.ins
@@ -0,0 +1,47 @@
+%%% dox.ins --- Installation 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:
+
+\NeedsTeXFormat{LaTeX2e}
+\input docstrip.tex
+\InputIfFileExists{ltxpkg.tex}{}{}
+\askforoverwritefalse
+\keepsilent
+
+\preamble
+^^J^^J
+Copyright (C) 2009, 2010, 2017 Didier Verna^^J
+This file is part of DoX.^^J
+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.^^J
+DoX consists of the files listed in the file `README.md'.^^J
+\endpreamble
+
+\generate{
+ \file{header.inc}{\from{dox.dtx}{header}}
+ \file{dox.sty}{\from{dox.dtx}{header,dox}}}
+
+\endbatchfile
+
+%%% dox.ins ends here
diff --git a/macros/latex/contrib/dox/dox.pdf b/macros/latex/contrib/dox/dox.pdf
new file mode 100644
index 0000000000..924eee0579
--- /dev/null
+++ b/macros/latex/contrib/dox/dox.pdf
Binary files differ