From f565a84e02adcdb964437eb46e1f5c3a6554ddc2 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 16 Dec 2010 23:57:53 +0000 Subject: dox 2.2 (17dec10) git-svn-id: svn://tug.org/texlive/trunk@20768 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/source/latex/dox/dox.dtx | 184 +++++++++++++++++++++-------- Master/texmf-dist/source/latex/dox/dox.ins | 4 +- 2 files changed, 137 insertions(+), 51 deletions(-) (limited to 'Master/texmf-dist/source') 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 % Maintainer: Didier Verna @@ -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} %\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] % %<*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 % % \end{macrocode} diff --git a/Master/texmf-dist/source/latex/dox/dox.ins b/Master/texmf-dist/source/latex/dox/dox.ins index a6084db6a3c..0f2fde84c64 100644 --- a/Master/texmf-dist/source/latex/dox/dox.ins +++ b/Master/texmf-dist/source/latex/dox/dox.ins @@ -1,6 +1,6 @@ %%% dox.ins --- Installation file for DoX -*- mode: LaTeX -*- -%% Copyright (C) 2009 Didier Verna. +%% Copyright (C) 2009, 2010 Didier Verna %% Author: Didier Verna %% Maintainer: Didier Verna @@ -35,7 +35,7 @@ \preamble ^^J^^J -Copyright (C) 2009 Didier Verna^^J +Copyright (C) 2009, 2010 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.1 -- cgit v1.2.3