summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/dox/dox.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-12-16 23:57:53 +0000
committerKarl Berry <karl@freefriends.org>2010-12-16 23:57:53 +0000
commitf565a84e02adcdb964437eb46e1f5c3a6554ddc2 (patch)
treebe5f5f3d469a34a8a8e6f0a7a60b33328ca92327 /Master/texmf-dist/source/latex/dox/dox.dtx
parent3d7921d8c3592f86548fb1c0dda79e234a63c223 (diff)
dox 2.2 (17dec10)
git-svn-id: svn://tug.org/texlive/trunk@20768 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/dox/dox.dtx')
-rw-r--r--Master/texmf-dist/source/latex/dox/dox.dtx184
1 files changed, 135 insertions, 49 deletions
diff --git a/Master/texmf-dist/source/latex/dox/dox.dtx b/Master/texmf-dist/source/latex/dox/dox.dtx
index 92c15714f47..d9036de1f8e 100644
--- a/Master/texmf-dist/source/latex/dox/dox.dtx
+++ b/Master/texmf-dist/source/latex/dox/dox.dtx
@@ -2,7 +2,7 @@
%
% dox.dtx --- Doc file for the DoX package (code and documentation)
%
-% Copyright (C) 2009 Didier Verna.
+% Copyright (C) 2009, 2010 Didier Verna
%
% Author: Didier Verna <didier@lrde.epita.fr>
% Maintainer: Didier Verna <didier@lrde.epita.fr>
@@ -31,6 +31,7 @@
%
%<*driver>
\documentclass[a4paper]{ltxdoc}
+\usepackage[T1]{fontenc}
\usepackage{xspace}
\makeatletter
\def\@currname{dox}
@@ -48,7 +49,7 @@
% \fi
%
% \catcode`\¡=14
-% \CheckSum{247}
+% \CheckSum{359}
% \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
@@ -78,7 +79,7 @@
%
% \newcommand\dox{\textsf{DoX}\xspace}
% \newcommand\packagecopyright{%
-% Copyright \copyright{} 2009 Didier Verna}
+% Copyright \copyright{} 2009, 2010 Didier Verna}
%
% \newcommand\emacs{\textsf{[X]Emacs}\xspace}
% \newcommand\auctex{AUC-\TeX\xspace}
@@ -166,8 +167,8 @@
%
% \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:
+% Suppose you would like to describe package options explicitely. Here is what
+% you need to do:
% \begin{verbatim}
% \usepackage{dox}
% \doxitem{Option}{option}{options}
@@ -207,25 +208,50 @@
%
% \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:
+% 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
@@ -265,10 +291,10 @@
% 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:
+% 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}
@@ -288,8 +314,8 @@
% \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 a regular
-% expression, allowing you to combine several names together or build complex
+% 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
@@ -312,10 +338,12 @@
% \textsf{FiXme} package (version 4.0 or later). In fact, I wrote \dox for it
% in the first place.
%
-% \section{History}
+% \section{Changes}
% \begin{itemize}
-% \item[v2.1] New lisp functions |doxitem[s]| to register new documentation
-% environments with \auctex.
+% \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}
@@ -326,14 +354,14 @@
% \item[v1.0] First public version
% \end{itemize}
%
-% \StopEventually{\vfill\hfill\small \packagecopyright{}.}
+% \StopEventually{\vfill\hfill\small \packagecopyright{}}
%
% \section{Implementation}
% \subsection{Preamble}
% \begin{macrocode}
%<dox>\NeedsTeXFormat{LaTeX2e}
%<*header>
-\ProvidesPackage{dox}[2009/09/28 v2.1 Extensions to the doc package]
+\ProvidesPackage{dox}[2010/12/16 v2.2 Extensions to the doc package]
%</header>
%<*dox>
@@ -349,7 +377,11 @@
\DeclareBoolOption{noprint}
\DeclareBoolOption{noindex}
% \end{macrocode}
-% This one is for \cs{doxitem} only:
+% 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}
@@ -460,33 +492,63 @@
% \subsection{API construction}
% \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}%
+ \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}%
+ \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}
@@ -533,7 +595,7 @@
%
% \subsubsection{Environment facilities}
% Making \cs{DescribeEnv} and the \texttt{environment} environment work the
-% \dox way is straightforward.
+% \dox way is even more straightforward.
% \begin{macrocode}
\@doxcreatedescribe{Env}
\@doxcreateenv{Env}{environment}
@@ -546,6 +608,7 @@
% \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}
@@ -553,14 +616,23 @@
% \marg{name}
% \begin{macrocode}
\@ifundefined{Print#2Name}{%
- \expandafter\def\csname Print#2Name\endcsname##1{%
- \strut\MacroFont##1\ }}{}
+ \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}
- \def\@doxexpr{\@doxcreatespecialmainindex{#2}}%
+ \ifdox@macrolike
+ \def\@doxexpr{\@doxcreatespecialmainmacrolikeindex{#2}}%
+ \else
+ \def\@doxexpr{\@doxcreatespecialmainindex{#2}}%
+ \fi
\expandafter\@doxexpr\expandafter{\dox@idxtype}{#4}%
% \end{macrocode}
% \end{macro}
@@ -568,14 +640,23 @@
% \marg{name}
% \begin{macrocode}
\@ifundefined{PrintDescribe#2}{%
- \expandafter\def\csname PrintDescribe#2\endcsname##1{%
- \strut\MacroFont##1\ }}{}
+ \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}
- \def\@doxexpr{\@doxcreatespecialindex{#2}}%
+ \ifdox@macrolike
+ \def\@doxexpr{\@doxcreatespecialmacrolikeindex{#2}}%
+ \else
+ \def\@doxexpr{\@doxcreatespecialindex{#2}}%
+ \fi
\expandafter\@doxexpr\expandafter{\dox@idxtype}{#4}%
% \end{macrocode}
% \end{macro}
@@ -609,6 +690,11 @@
\else
\def\dox@noindexdefault{false}
\fi
+\ifdox@macrolike
+ \def\dox@macrolikedefault{true}
+\else
+ \def\dox@macrolikedefault{false}
+\fi
%</dox>
% \end{macrocode}