From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/dox/NEWS | 53 +++ macros/latex/contrib/dox/README.md | 56 +++ macros/latex/contrib/dox/THANKS | 31 ++ macros/latex/contrib/dox/dox.dtx | 741 +++++++++++++++++++++++++++++++++++++ macros/latex/contrib/dox/dox.el | 64 ++++ macros/latex/contrib/dox/dox.ins | 47 +++ macros/latex/contrib/dox/dox.pdf | Bin 0 -> 157525 bytes 7 files changed, 992 insertions(+) create mode 100644 macros/latex/contrib/dox/NEWS create mode 100644 macros/latex/contrib/dox/README.md create mode 100644 macros/latex/contrib/dox/THANKS create mode 100644 macros/latex/contrib/dox/dox.dtx create mode 100644 macros/latex/contrib/dox/dox.el create mode 100644 macros/latex/contrib/dox/dox.ins create mode 100644 macros/latex/contrib/dox/dox.pdf (limited to 'macros/latex/contrib/dox') 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 + +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 and the 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 + +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 + +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 +% +% 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} +% +% +% \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} +%\NeedsTeXFormat{LaTeX2e} +%<*header> +\ProvidesPackage{dox}[2017/12/06 v2.4 Extensions to the doc package] + +% +%<*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 + +% +% \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 +;; 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 + +%% 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 Binary files /dev/null and b/macros/latex/contrib/dox/dox.pdf differ -- cgit v1.2.3