diff options
Diffstat (limited to 'Master/texmf-dist/source')
| -rw-r--r-- | Master/texmf-dist/source/latex/dox/dox.dtx | 529 |
1 files changed, 434 insertions, 95 deletions
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 |