new package dtxgallery (6aug07)

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

9 files changed, 391 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/dtxgallery/README b/Master/texmf-dist/doc/latex/dtxgallery/README
new file mode 100644
index 00000000000..fe78ab4c2e2
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/dtxgallery/README
@@ -0,0 +1,62 @@
+============
+ DTXGALLERY 
+============
+
+This work is a collection of files that demonstrate 
+simple things that are possible with the flexible 
+and under-appreciated docstrip file format.
+
+It is intended as a companion to Scott Pakin's
+excellent and influential "dtxtut" example of producing
+LaTeX packages in this way.
+
+This work consists of the following files:
+
+--------------
+dtxgallery.dtx
+
+A `meta-example' showing how multiple .dtx files can be
+documented in a single file. Read the .pdf version of this
+file first. 
+--------------
+
+-----------------
+single-source.dtx
+
+This is an example of both the .sty and .ins
+files being extracted from the .dtx file. This
+allows maintenance of a single source file
+but still produces a "standard-behaviour" .dtx/.ins
+pair for upload to CTAN.
+-----------------
+
+--------------------
+conditional-code.dtx
+
+This example shows how code can be extracted in different
+contexts. For example, debug code in a package can be
+included in the source .dtx file but be automatically
+stripped out for the public release version of the package.
+--------------------
+
+-------------
+rearrange.dtx
+
+This example demonstrates how source code may
+be written and documented in a different logical 
+order than in which it is required to execute.
+
+This can be useful, for example, when default 
+values are provided at the very stage of the package 
+loading, but you wish to describe them first in the 
+main body of the (non-technical) documentation.
+-------------
+
+
+Maintained by Will Robertson, 2007.
+Please send comments and suggestions (entire examples very
+welcome!) to me at the typeset string of:
+  \zap@space wspr \number`\Q \char64 gmail \char46 com {}
+
+Distributed under the LaTeX Project Public License, version
+1.3c or higher (your choice).
diff --git a/Master/texmf-dist/doc/latex/dtxgallery/conditional-code.pdf b/Master/texmf-dist/doc/latex/dtxgallery/conditional-code.pdf
new file mode 100644
index 00000000000..a8bbef31f36
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/dtxgallery/conditional-code.pdf
diff --git a/Master/texmf-dist/doc/latex/dtxgallery/dtxgallery.pdf b/Master/texmf-dist/doc/latex/dtxgallery/dtxgallery.pdf
new file mode 100644
index 00000000000..b79836ce476
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/dtxgallery/dtxgallery.pdf
diff --git a/Master/texmf-dist/doc/latex/dtxgallery/rearrange.pdf b/Master/texmf-dist/doc/latex/dtxgallery/rearrange.pdf
new file mode 100644
index 00000000000..2c505c9123f
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/dtxgallery/rearrange.pdf
diff --git a/Master/texmf-dist/doc/latex/dtxgallery/single-source.pdf b/Master/texmf-dist/doc/latex/dtxgallery/single-source.pdf
new file mode 100644
index 00000000000..04055239a5d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/dtxgallery/single-source.pdf
diff --git a/Master/texmf-dist/source/latex/dtxgallery/conditional-code.dtx b/Master/texmf-dist/source/latex/dtxgallery/conditional-code.dtx
new file mode 100644
index 00000000000..658ff48ed18
--- /dev/null
+++ b/Master/texmf-dist/source/latex/dtxgallery/conditional-code.dtx
@@ -0,0 +1,48 @@
+% \iffalse meta-comment
+%
+% Part of Will Robertson's DTXGALLERY bundle, version 1.
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{fancyvrb}
+\begin{document}
+  \DocInput{conditional-code.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \section{Conditional inclusion of code}
+%
+% From previous examples the |%<*guard>|\dots|%</guard>| syntax should be a little familiar. This example demonstrates conditional extraction of such elements in the source document into multiple files. This technique makes it easy, say, to maintain a `debug' version of a package without polluting the public source with code for testing.
+%
+%    \begin{macrocode}
+%<A>  code in `A'
+%<B>  code in `B'
+%<!A>  code not in `A'
+%<!B>  code not in `B'
+%<A&B>  code in `A' and `B'
+%<A|B>  code in `A' or `B'
+%<(A|B)&!(A&B)>  code in `A' xor `B'
+%    \end{macrocode}
+% Note the change in the typeset source when guards are nested: \\
+% (this is equivalent to \verb|%<A&B>|)
+%    \begin{macrocode}
+%<*A>
+%<B>  `B' nested inside `A'
+%</A>
+%    \end{macrocode}
+% 
+% \section{Verbatim files that are produced}
+% \begin{minipage}{0.45\linewidth}
+% \subsection{Generated from `A'}
+% \VerbatimInput[frame=single]{A.txt}
+% \end{minipage}\hfill
+% \begin{minipage}{0.45\linewidth}
+% \subsection{Generated from `B'}
+% \VerbatimInput[frame=single]{B.txt}
+% \end{minipage}
+% \subsection{Generated from `A' and `B'}
+% \VerbatimInput[frame=single]{AB.txt}
+%
+% \Finale
+\endinput
diff --git a/Master/texmf-dist/source/latex/dtxgallery/dtxgallery.dtx b/Master/texmf-dist/source/latex/dtxgallery/dtxgallery.dtx
new file mode 100644
index 00000000000..adb5befd8e5
--- /dev/null
+++ b/Master/texmf-dist/source/latex/dtxgallery/dtxgallery.dtx
@@ -0,0 +1,168 @@
+%
+% Part of Will Robertson's DTXGALLERY bundle, version 1.
+%
+\documentclass{ltxdoc}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+%\OnlyDescription
+
+\usepackage{fancyvrb}
+\usepackage[T1]{fontenc}
+\usepackage[osf,sc]{mathpazo}
+\renewcommand\sfdefault{lmsf}
+\renewcommand\ttdefault{lmtt}
+\usepackage{microtype}
+\linespread{1.1}
+
+\usepackage{xcolor}
+\usepackage{textcomp}
+\usepackage{rearrange}
+\usepackage[small,it,center]{titlesec}
+\usepackage{enumitem}
+\setdescription{font=\itshape,style=nextline}
+
+\makeatletter
+\def\@part[#1]#2{%
+    \refstepcounter{part}%
+    \addcontentsline{toc}{part}{\thepart\hspace{1em}#1}%
+    {\parindent \z@ \raggedright
+     \interlinepenalty \@M
+     \centering\normalfont\scshape
+     \MakeLowercase{\large\partname\nobreakspace\thepart~---~#2}%
+     \markboth{}{}\par}%
+    \nobreak
+    \vskip 3ex
+    \@afterheading}
+\makeatother
+
+\def\dtx{\textsc{dtx}}
+\def\ins{\textsc{ins}}
+\def\pdf{\textsc{pdf}}
+\def\ctan{\textsc{ctan}}
+\def\pkg#1{\texttt{#1}}
+\def\LaTeX{\textsc{Latex}}
+
+\begin{document}
+
+\title{A gallery of \dtx\ files}
+\author{Will Robertson}
+\maketitle
+
+\section{Introduction}
+
+This work is a collection of files that demonstrate 
+simple things that are possible with the flexible 
+and under-appreciated docstrip file format.
+It is intended as a companion to Scott Pakin's
+excellent and influential `dtxtut' example of producing
+LaTeX packages in this way.
+
+\section{Files in the gallery}
+
+The \dtx\ examples in this gallery are listed below in 
+approximate order of both relevance and complexity.
+
+\begin{description}
+	\item[single-source.dtx]
+
+	This is an example of both the .sty and .ins
+	files being extracted from the .dtx file. This
+	allows maintenance of a single source file
+	but still produces a `standard-behaviour' \dtx/\ins\
+	pair for upload to \ctan.
+
+	\item[conditional-code.dtx]
+  This example shows conditional extraction of code into multiple files,
+  allowing the easy generation of `debug' versions of package, for example.
+	
+\item[rearrange.dtx]
+
+This example demonstrates how source code may
+be written and documented in a different logical 
+order than in which it is required to execute.
+
+This can be useful, for example, when default 
+values are provided at the last stage of the package 
+loading, but you wish to describe them first in the 
+main body of the (non-technical) documentation.
+
+\item[dtxgallery.dtx]
+
+This very document is an example of a \dtx\ file that is itself the compilation of multiple, external, \dtx\ files. It is useful for generating a single documentation file for a large software collection (e.g., the \LaTeX\ sources themselves).
+\end{description}
+
+\section{How to use this gallery}
+It will be clearest to now stop reading this document and take a look at the individual \dtx\ files (and their compiled \pdf\ files) mentioned above. The rest of this file contains a compilation of the \dtx\ files in the gallery, which is an example in itself. Read about it later on in File~\ref{part:gallery} on page~\pageref{part:gallery}.
+
+\section{Interlude: eliminating guards}
+While I'm in a position to comment on some things, I may as well put in a few tips that I use when writing \dtx\ files.
+
+`Guards' are what delimit code sections in \dtx\ files. Many packages will have no need for anything fancy in this regard, and it will be quite common to see things like:
+\begin{Verbatim}[commandchars=|\[\],frame=single]
+% [|color[blue]...]
+%   \begin{macrocode}
+%<*package>
+|meta[|color[blue]|rmfamily[]The entire, commented, package code]
+%</package>
+%   \end{macrocode}
+% [|color[blue]...]
+\end{Verbatim}
+with other guards used to section off things like the driver code in the beginning and possibly other bits and pieces. In such cases, it is not necessary to include the guards in the typeset documentation (if we're trying to make things as simple as possible for the reader), so I like to write instead:
+\begin{Verbatim}[commandchars=|\[\],frame=single]
+% [|color[blue]...]
+% \iffalse
+%<*package>
+% \fi
+%   \begin{macrocode}
+|meta[|color[blue]|rmfamily[]The entire, commented, package code]
+%   \end{macrocode}
+% \iffalse
+%</package>
+% \fi
+% [|color[blue]...]
+\end{Verbatim}
+This is also useful when logical part/section markup is used to separate the files in the \dtx\ anyway.
+
+\clearpage
+\part{Extracting the \ins\ file from the \dtx} 
+\DocInput{single-source.dtx}
+
+\clearpage
+\part{Conditionally extracting code} 
+\DocInput{conditional-code.dtx}
+
+\clearpage
+\part{Rearranging the code from logical to linear}
+\DocInput{rearrange.dtx}
+
+\clearpage
+\part{The \dtx\ gallery}
+\label{part:gallery}
+This very file, \pkg{dtxgallery.dtx}, is an example of a \dtx\ file that contains no code of its own but which loads \emph{other} \dtx\ files. 
+
+Note that code could be included in this file like any other \dtx\ file and typeset along with the following examples, but I've chosen to strip this particular \dtx\ file as far back as possible simply to demonstrate that I can. Therefore, it generates no files, and provides no code. It simply documents other \dtx\ files.
+
+Note that this file draws into relief the difference between the two locations that `documentation sources' can be placed in a \dtx\ file:
+\begin{Verbatim}[commandchars=|\[\],label=example.dtx,frame=single]
+% \iffalse
+% [|color[blue]...]
+%<*driver>
+\documentclass{ltxdoc}
+[|color[blue]...]
+\begin{document}
+  |meta[|color[blue]|rmfamily[]Documentation source |textemdash specific]
+  \DocInput{example.dtx}
+\end{document}
+%</driver>
+% \fi
+% |meta[|color[blue]|rmfamily[]Documentation source |textemdash general]
+% [|color[blue]...]
+\end{Verbatim}
+The `specific' documentation source is used when compiling only that \dtx\ file, whereas \emph{only} the `general' documentation source appears when input via \cmd\DocInclude. In the case of a compilation of \dtx\ files (which is what the document you're reading demonstrates), \cmd\DocInclude\ is referring to the hypothetical \pkg{example.dtx} in a completely different file, so the specific part of the code is invisible.
+
+Therefore, it is a good idea to define formatting and document metadata (such as \cmd\title\ and \cmd\maketitle) in the `specific' location, and include only the body of the documentation in the `general' area.
+
+This file is an example of how formatting code in the `specific' area here changes the fonts and layout used only in the \dtx\ gallery itself.
+
+\end{document}
\ No newline at end of file
diff --git a/Master/texmf-dist/source/latex/dtxgallery/rearrange.dtx b/Master/texmf-dist/source/latex/dtxgallery/rearrange.dtx
new file mode 100644
index 00000000000..6a43ad8fb0e
--- /dev/null
+++ b/Master/texmf-dist/source/latex/dtxgallery/rearrange.dtx
@@ -0,0 +1,46 @@
+% \iffalse meta-comment
+%
+% Part of Will Robertson's DTXGALLERY bundle, version 1.
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{rearrange,fancyvrb}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+%\OnlyDescription
+\begin{document}
+  \DocInput{\jobname.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \section{Example of re-arranging docstrip source}
+%
+% This is a test to show it's working: \string\test\ $\to$ \test
+% 
+% \section{Documented code}
+%
+% \noindent This is `defaults' code that the \emph{user} might want to see:
+%    \begin{macrocode}
+%<*defaults> 
+\mytest{1}
+%</defaults>
+%    \end{macrocode} 
+%
+% \noindent And this is the internal code that the user doesn't care so much about:
+%    \begin{macrocode}
+%<*package> 
+\ProvidesPackage{rearrange}[2005/07/15 v0.1 docstrip: rearranging]
+\def\mytest#1{\def\test{``#1''}}
+%</package>
+%    \end{macrocode} 
+%
+% \section{Verbatim files that are produced}
+% \subsection{rearrange.sty}
+% \VerbatimInput[frame=single]{rearrange.sty}
+% \subsection{rearrange.ins}
+% \VerbatimInput[frame=single]{rearrange.ins}
+%
+% \Finale
+\endinput
\ No newline at end of file
diff --git a/Master/texmf-dist/source/latex/dtxgallery/single-source.dtx b/Master/texmf-dist/source/latex/dtxgallery/single-source.dtx
new file mode 100644
index 00000000000..2b24ed47637
--- /dev/null
+++ b/Master/texmf-dist/source/latex/dtxgallery/single-source.dtx
@@ -0,0 +1,67 @@
+% \iffalse
+%
+% Part of Will Robertson's DTXGALLERY bundle, version 1.
+%
+%<*internal>
+\iffalse
+%</internal>
+%<*readme>
+-----------------
+single-source.dtx
+
+This is an example of everything 
+being extracted from the .dtx file.
+-----------------
+%</readme>
+%<*internal>
+\fi
+\begingroup
+%</internal>
+%<*batchfile>
+\input docstrip.tex
+\keepsilent\askforoverwritefalse
+\nopreamble\nopostamble
+\generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}}
+%</batchfile>
+%<batchfile>\endbatchfile
+%<*internal>
+\generate{\file{\jobname.ins}{\from{\jobname.dtx}{batchfile}}}
+\generate{\file{\jobname-readme.txt}{\from{\jobname.dtx}{readme}}}
+\endgroup
+%</internal>
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{single-source,fancyvrb}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+%\OnlyDescription
+\begin{document}
+\title{Example of `single source' docscript extraction}
+\DocInput{\jobname.dtx}
+\end{document}
+%</driver>
+%
+% \fi
+%
+% \section{The documented source code}
+%
+%    \begin{macrocode}
+%<*package> 
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{single-source}[2005/07/15 v0.1 dtx: single-source]
+\def\mymacro{hello :)}
+%</package>
+%    \end{macrocode} 
+%
+% \section{The contents of single-source.sty}
+% \VerbatimInput[frame=single]{single-source.sty}
+%
+% \section{The contents of single-source.ins}
+% \VerbatimInput[frame=single]{single-source.ins}
+%
+% \section{The contents of single-source-readme.txt}
+% \VerbatimInput[frame=single]{single-source-readme.txt}
+%
+% \Finale