new latex package dox 1.0 (11sep09)

git-svn-id: svn://tug.org/texlive/trunk@15235 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 306 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/dox/dox.dtx b/Master/texmf-dist/source/latex/dox/dox.dtx
new file mode 100644
index 00000000000..7e2557820e1
--- /dev/null
+++ b/Master/texmf-dist/source/latex/dox/dox.dtx
@@ -0,0 +1,250 @@
+% \iffalse                                                 -*- mode: LaTeX -*-
+%
+% dox.dtx --- Doc file for the DoX package (code and documentation)
+%
+% Copyright (C) 2009 Didier Verna.
+%
+% 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
+%
+% 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.1
+% 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.1 or later is part of all distributions of LaTeX
+% version 1999/06/01 or later.
+%
+% DoX consists of the files listed in the file `README'.
+%
+%
+% Commentary:
+%
+% Contents management by FCM version 0.1.
+%
+%
+% Code:
+%
+%<*driver>
+\documentclass[a4paper]{ltxdoc}
+\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
+%
+% \catcode`\¡=14
+% \CheckSum{157}
+% \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 Didier Verna}
+%
+% \pagestyle{mystyle}
+% \markright{\hskip-.5\marginparwidth \dox \fileversion{} (\filedate)}
+%
+% \date{\texttt{\fileversion{} (\filedate)}}
+% \title{\dox{} -- \textsf{\textbf Doc}, \textbf only e\textbf Xtended}
+% \author{Didier Verna\\
+%   \texttt{mailto:didier@lrde.epita.fr}\\
+%   \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 macros 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.
+% \end{abstract}
+%
+% ^^A \tableofcontents
+%
+% \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:
+% \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}
+%
+% That's about it.
+% \StopEventually{\vfill\hfill\small \packagecopyright{}.}
+%
+% \section{Implementation}
+% \subsection{Preamble}
+%    \begin{macrocode}
+%<dox>\NeedsTeXFormat{LaTeX2e}
+%<*header>
+\ProvidesPackage{dox}[2009/09/11 v1.0 Extensions to the doc package]
+
+%</header>
+%    \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:
+%    \begin{macrocode}
+%<*dox>
+\long\def\doxm@cro@#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}
+
+%    \end{macrocode}
+% \end{macro}
+% \subsection{API creation}
+% \begin{macro}{\doxitem}
+%   \marg{funcsname}\marg{singular}\marg{plural}
+%    \begin{macrocode}
+\newcommand\doxitem[3]{%
+%    \end{macrocode}
+% The \cs{Print}\meta{item}\texttt{Name} macro:
+%    \begin{macrocode}
+  \@ifundefined{Print#1Name}{%
+    \expandafter\def\csname Print#1Name\endcsname##1{%
+      \strut\MacroFont\string##1\ }}{}
+%    \end{macrocode}
+% The \cs{SpecialMain}\meta{item}\texttt{Index} macro:
+%    \begin{macrocode}
+  \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}
+%    \end{macrocode}
+% The \cs{PrintDescribe}\meta{item} macro:
+%    \begin{macrocode}
+  \@ifundefined{PrintDescribe#1}{%
+    \expandafter\def\csname PrintDescribe#1\endcsname##1{%
+      \strut\MacroFont##1\ }}{}
+%    \end{macrocode}
+% The \cs{Special}\meta{item}\texttt{Index} macro:
+%    \begin{macrocode}
+  \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}
+%    \end{macrocode}
+% The \cs{Describe}\meta{item} macro:
+%    \begin{macrocode}
+  \expandafter\def\csname Describe#1\endcsname{%
+    \leavevmode\@bsphack\begingroup\MakePrivateLetters
+    \@nameuse{Describe@#1}}
+%    \end{macrocode}
+% The \meta{item} environment:
+%    \begin{macrocode}
+  \expandafter\def\csname #2\endcsname{%
+    \begingroup
+      \catcode`\\12
+      \MakePrivateLetters\doxm@cro@{#1}}
+  \expandafter\let\csname end#2\endcsname\endtrivlist}
+
+%</dox>
+%    \end{macrocode}
+% \end{macro}
+% ^^A \PrintChanges
+% ^^A \PrintIndex
+% \Finale
+%
+% ^^A dox.dtx ends here
diff --git a/Master/texmf-dist/source/latex/dox/dox.ins b/Master/texmf-dist/source/latex/dox/dox.ins
new file mode 100644
index 00000000000..c98430c1396
--- /dev/null
+++ b/Master/texmf-dist/source/latex/dox/dox.ins
@@ -0,0 +1,56 @@
+%%% dox.ins --- Installation file for DoX              -*- mode: LaTeX -*-
+
+%% Copyright (C) 2009 Didier Verna.
+
+%% Author:        Didier Verna <didier@lrde.epita.fr>
+%% Maintainer:    Didier Verna <didier@lrde.epita.fr>
+%% Created:       Thu Sep 10 21:25:41 2009
+%% Last Revision: Thu Sep 10 21:26:35 2009
+
+%% 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.1
+%% 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.1 or later is part of all distributions of LaTeX
+%% version 1999/06/01 or later.
+
+%% DoX consists of the files listed in the file `README'.
+
+
+%%% Commentary:
+
+%% Contents management by FCM version 0.1.
+
+
+%%% Code:
+
+\NeedsTeXFormat{LaTeX2e}
+\input docstrip.tex
+\askforoverwritefalse
+\keepsilent
+
+\preamble
+^^J^^J
+Copyright (C) 2009 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
+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.1 or later is part of all distributions of LaTeX
+version 1999/06/01 or later.^^J
+DoX consists of the files listed in the file `README'.^^J
+\endpreamble
+
+\catcode`\¡=14
+\generate{
+  \file{header.inc}{\from{dox.dtx}{header}}
+  \file{dox.sty}{\from{dox.dtx}{header,dox}}}
+
+\endbatchfile
+
+%%% dox.ins ends here