summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/dox/dox.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-09-12 18:05:51 +0000
committerKarl Berry <karl@freefriends.org>2009-09-12 18:05:51 +0000
commit873a6f9281ea219d530a5f1113c54a48a6951703 (patch)
treef3c715ad9e164cd56d4d0db40b83e986c35d39d1 /Master/texmf-dist/source/latex/dox/dox.dtx
parent5e4989d7312e4e11eda708529fa09746de41a31e (diff)
new latex package dox 1.0 (11sep09)
git-svn-id: svn://tug.org/texlive/trunk@15235 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.dtx250
1 files changed, 250 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