1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
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}
|
