/ [latex-makedtx] / trunk / doc / support / makedtx / makedtx.tex
To checkout: svn checkout http://svn.gnu.org.ua/sources/latex-makedtx/trunk/doc/support/makedtx/makedtx.tex
Puszcza

Contents of /trunk/doc/support/makedtx/makedtx.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 72 - (show annotations)
Mon Feb 19 21:54:52 2018 UTC (3 years, 9 months ago) by vincentb1
File MIME type: application/x-tex
File size: 29589 byte(s)
Prepare delivery 1.2 to CTAN

* Makefile (ctan): Add check_vc dependency.
(check_vc): new target.
(test): new target --- convenience to launch test.
(ctantag): new target.

* doc/support/makedtx/CHANGES.org: Prepare delivery 1.2 to CTAN.

* doc/support/makedtx/makedtx.bib: Import --- forgotten in the initial import.

* doc/support/makedtx/makedtx.tex: Change date and format it with datetime2.

1 \documentclass[a4paper,english]{ltxdoc}
2
3 \usepackage[colorlinks,
4 bookmarks,
5 hyperindex=false,
6 bookmarksopen,
7 pdfauthor={Nicola Talbot},
8 pdftitle={makedtx : a Perl script to help create a DTX file from source code}]{hyperref}
9 \usepackage{createdtx}
10 \usepackage{datetime2}
11 \DTMsetstyle{english}
12
13
14 \renewcommand{\usage}[1]{\textit{\hyperpage{#1}}}
15 \renewcommand{\main}[1]{\hyperpage{#1}}
16 \newcommand{\see}[2]{\emph{see} #1}
17 \makeatletter
18 \def\index@prologue{\section*{Index}}
19 \makeatother
20 \RecordChanges
21 \PageIndex
22 \CodelineNumbered
23 \newcommand{\latextohtml}{\LaTeX2HTML}
24 \newcommand{\switch}[1]{\texttt{-#1}\index{makedtx switches=\texttt{makedtx} switches>#1=\texttt{-#1}}}
25 \newcommand{\ics}[1]{\cs{#1}\SpecialMainIndex{#1}}
26 \CheckSum{8}
27
28 \newcommand{\PDFLaTeX}{PDF\LaTeX}
29 \DTMsavedate{makedtx-date}{2018-02-19}
30
31 \input{makedtx-version}
32 \begin{document}
33
34 \title{makedtx \version : a Perl script to help create a DTX
35 file from source code}
36 \author{Nicola Talbot\\
37 \url{http://theoval.cmp.uea.ac.uk/~nlct/}}
38 \date{\DTMusedate{makedtx-date}}
39 \maketitle
40
41 \tableofcontents
42
43 \begin{abstract}
44 The \texttt{makedtx} bundle is provided to help developers to write
45 the code and documentation in separate files, and then combine them
46 into a single DTX file for distribution. It automatically generates
47 the character table, and also writes the associated installation
48 (.ins) script.
49 \end{abstract}
50
51 \section{Introduction}
52
53 \changes{0.9}{2005/02/11}{Initial beta release}%
54 Authors of \LaTeXe\ class files or packages are encouraged to bundle
55 their source and documentation together into a single DTX file. This
56 makes distribution much easier, as users need only download the DTX
57 file and possibly a corresponding installation script (INS file)
58 instead of a multitude of \texttt{.sty}, \texttt{.cls}, \texttt{.def}
59 etc files. However, having the documentation and code bundled
60 together can cause problems if a developer wants to, say, use
61 \texttt{ispell} to spell check the documentation, or convert the
62 documentation to a format other than DVI, PostScript or PDF (such as
63 HTML).
64
65 Why should I want to convert my documentation to HTML when I can just
66 use \PDFLaTeX? The more general purpose packages that I write (such
67 as \texttt{datetime} and \texttt{glossary}) I upload to CTAN, however
68 most of the packages I write are specific to the School of Computing
69 Sciences at the University of East Anglia, so these I keep on my web
70 site, and as some of the faculty either don't have a PDF plug in or
71 prefer to view HTML rather than PDF documents, I have taken to writing
72 both PDF and HTML versions of my package documentation. However,
73 \latextohtml\ doesn't work on a \texttt{.dtx} file so I used to
74 convert them manually which is fine for one or two small documents,
75 but becomes rather cumbersome as soon as I have large documents or a
76 lot of packages. Therefore I decided to write the documentation
77 separately, and use a Perl script to bundle everything together. It
78 also has the added convenience in that I don't have to keep copying
79 and pasting the character table every time I write a new package, and
80 it saves the laborious task of writing the installation
81 script\footnote{or at least, it's laborious if there are rather a lot
82 of files associated with a package}.
83
84 This document is structured as follows: Section~\ref{sec:install}
85 describes how to install the \texttt{makedtx} bundle,
86 Section~\ref{sec:makedtx} gives an overview of the \texttt{makedtx.pl}
87 Perl script, Section~\ref{sec:creatdtx} describes the
88 \texttt{creatdtx} package, Section~\ref{sec:examples} illustrates the
89 use of the \texttt{makedtx} bundle with examples and
90 Section~\ref{sec:problems} gives a list of possible errors and their
91 solutions.
92
93 \section{Installation}\label{sec:install}
94
95 You need to download both \texttt{makedtx.dtx} and
96 \texttt{makedtx.ins}, and run the installation script through
97 \LaTeX:\par \texttt{latex makedtx.ins}
98
99 The following files will be created:
100 \begin{description}
101 \item[\texttt{makedtx.pl}] Perl script
102 \item[\texttt{creatdtx.sty}] \LaTeX\ package for use with \texttt{makedtx.pl}
103 \item[\texttt{creatdtx.perl}] Corresponding Perl script for use with LaTeX2HTML
104 \end{description}
105
106 If you are using UNIX/Linux etc you will need to make
107 \texttt{makedtx.pl} executable using
108 \texttt{chmod}:\par\vspace{6pt}\noindent\texttt{chmod a+x
109 makedtx.pl}\par\vspace{6pt}\noindent and place it somewhere on your
110 path. If \texttt{perl} is located somewhere other than
111 \texttt{/usr/bin/} you will need to edit the first line of
112 \texttt{makedtx.pl}. (If you don't know where \texttt{perl} is
113 located, you can use the command: \texttt{which perl}.) The package
114 \texttt{creatdtx.sty} needs to be placed somewhere on the \LaTeX\ path
115 and \texttt{creatdtx.perl} should be placed in a directory searched by
116 \latextohtml. (See the \latextohtml\ documentation for details.)
117
118 \section{makedtx.pl}\label{sec:makedtx}
119
120 The Perl script \texttt{makedtx.pl} has the following syntax:\par
121 \texttt{makedtx.pl} \oarg{options} \switch{src}
122 \texttt{"}\meta{expr1}\verb|=>|\meta{expr2}\texttt{"}
123 \switch{doc} \meta{filename} \meta{basename}
124
125 \subsection{Compulsory Arguments}
126
127 The very last argument \meta{basename} is the basename of the
128 \texttt{.dtx} and \texttt{.ins} files you want to create. The
129 \switch{doc} \meta{filename} switch indicates the file containing the
130 documentation and \switch{src}
131 \verb!"!\meta{expr1}\verb+=>+\meta{expr2}\verb'"' indicates the
132 original source file(s), given by \meta{expr1}, and the corresponding
133 file name when it has been extracted from the \texttt{.dtx} file,
134 given by \meta{expr2}. This switch is a little complicated, so it's
135 best described using examples.
136
137 Suppose you have your documentation in the file \texttt{foodoc.tex},
138 and the original source code is in the file \texttt{foosrc.sty}. You
139 want to create the files \texttt{foo.dtx} and \texttt{foo.ins}. When
140 you \LaTeX\ \texttt{foo.dtx} you want the documentation as specified
141 in \texttt{foodoc.tex} and when you \LaTeX\ \texttt{foo.ins} you want
142 the file \texttt{foo.sty} to be created, using the code specified in
143 \texttt{foosrc.sty}. You will need to do:
144 \begin{verbatim}
145 makedtx.pl -src "foosrc\.sty=>foo.sty" -doc foodoc.tex foo
146 \end{verbatim}
147
148 You may have multiple invocations of the \switch{src} switch. For
149 example, suppose you also have the file \texttt{barsrc.sty} which you
150 want to be extracted from the \texttt{.dtx} file as \texttt{bar.sty},
151 you can do:
152 \begin{verbatim}
153 makedtx.pl -src "foosrc\.sty=>foo.sty" -src "barsrc\.sty=>bar.sty" -doc foodoc.tex foo
154 \end{verbatim}
155 Alternatively, you can use Perl-type regular expressions:
156 \begin{verbatim}
157 makedtx.pl -src "(.*)src\.sty=>\1.sty" -doc foodoc.tex foo
158 \end{verbatim}
159 (Note the use of double quotes to prevent shell expansion.)
160 Appendix~\ref{sec:prex} gives a brief overview of Perl regular
161 expressions for the uninitiated.
162
163 \subsection{Options}
164
165 \begin{description}
166 \item[\switch{h} or \switch{help}] Prints on-line help, and exits.
167
168 \item[\switch{version}] Prints version number, and exits.
169 \changes{0.93}{2007/08/02}{version switch added}%
170
171 \item[\switch{v}] Uses verbose mode.
172
173 \item[\switch{dir} \meta{name}] Specifies directory containing source
174 files, as specified by the \switch{src} switch. For example, suppose
175 you have source files \texttt{foo.sty}, \texttt{bar.sty} in the
176 subdirectory \texttt{sourcefiles} you can do:
177 \begin{verbatim}
178 makedtx.pl -dir sourcefiles -src "(.*)\.sty=>\1.sty" -doc foodoc.tex foo
179 \end{verbatim}
180
181 \item[\switch{op} \meta{character}] sets the Perl pattern matching
182 operator (the default is set to \texttt{=} symbol since the \texttt{/}
183 character is used as the directory divider).
184
185 \item[\switch{askforoverwrite}] uses \ics{askforoverwritetrue} in
186 the installation script.
187
188 \item[\switch{noaskforoverwrite}] uses \ics{askforoverwritefalse}
189 in the installation script (default).
190
191 \item[\switch{noins}] Don't create the installation script
192 (\texttt{.ins} file). This is useful if you want to tweak the file
193 manually and you don't want your modifications overwritten.
194
195 \item[\switch{preamble} \meta{text}] Set the preamble to
196 \texttt{text}. The default preamble is:\par
197 \changes{0.94}{2007/08/19}{default preamble changed to one
198 conforming with the LPPL}%
199 \begin{ttfamily}\obeylines
200 \meta{basename}.dtx
201 Copyright \meta{date} \meta{author}
202
203 This work may be distributed and/or modified under the
204 conditions of the LaTeX Project Public License, either version 1.3
205 of this license of (at your option) any later version.
206 The latest version of this license is in
207 http://www.latex-project.org/lppl.txt
208 and version 1.3 or later is part of all distributions of LaTeX
209 version 2005/12/01 or later.
210
211 This work has the LPPL maintenance status `maintained'.
212
213 The Current Maintainer of this work is \meta{author}.
214
215 This work consists of the files \meta{basename}.dtx and
216 \meta{basename}.ins and the derived files \meta{file list}.
217 \end{ttfamily}
218
219 where \meta{date} is the copyright date, and \meta{author} is the
220 author's name (see below).
221
222 \textbf{Note that this has been changed as of makedtx v0.94.
223 Older versions of makedtx do not conform to any of the free
224 licenses.}
225
226 \item[\switch{license} \meta{name}]
227 \changes{0.94}{2007/08/19}{license switch added}%
228 This sets the preamble to
229 the license text for the license \meta{name}. Currently \meta{name}
230 may be either \texttt{lppl} (the default, which produces the
231 default preamble detailed above), \texttt{bsd} or \texttt{gpl}.
232 You may use either \switch{license} or \switch{preamble},
233 but not both. (If you have used the \switch{preamble} switch, the
234 \switch{license} switch will be ignored.)
235
236 \item[\switch{postamble} \meta{text}] Set the postamble to
237 \texttt{text}. If this is omitted the \ics{postamble} command is
238 omitted from the installation script.
239
240 \item[\switch{author} \meta{name}] The author's name (as used in the
241 default preamble). If omitted the user's name is used.
242
243 \item[\switch{date} \meta{text}] The copyright date (as used in the
244 default preamble). If omitted the current year is used.
245
246 \item[\switch{stopeventually} \meta{text}] Insert \meta{text} into the
247 argument of \ics{StopEventually}. For example:
248 \verb+-stopeventually "\\PrintIndex"+ will result in the line:
249 \cs{StopEventually}\verb"{\PrintIndex}". If \texttt{makedtx.pl}
250 encounters a \cs{StopEventually} command within the document,
251 this will be used instead. If there is no \cs{StopEventually}
252 command in the document and the \switch{stopeventually} switch is
253 absent \cs{StopEventually}\marg{} will be inserted in the DTX
254 file.
255
256 \item[\switch{prefinale} \meta{text}]
257 \changes{0.91}{2006/07/21}{prefinale switch added}%
258 Inset \meta{text} immediately prior to \cs{Finale}
259 in the dtx file.
260
261 \item[\switch{setambles} \texttt{"}\meta{expr}\texttt{=\symbol{62}}\meta{text}\texttt{"}]
262 Sets the pre- and postambles for files matching \meta{expr} within the
263 \cs{file} command in the installation script. To illustrate this,
264 let's suppose you have source files \texttt{foo.sty}, \texttt{bar.sty}
265 and \texttt{foobar.pl} in the subdirectory \texttt{sourcefiles}.
266 Since \texttt{foo.sty} and \texttt{bar.sty} are \LaTeX\ files, they
267 should have pre- and postambles, but \texttt{foobar.pl} is a Perl
268 file, and since the percent symbol (\%) is not a comment character in
269 Perl, there should be no pre- and postambles for this file. Therefore
270 you would need to do something like:
271 \begin{verbatim}
272 makedtx.pl -dir sourcefiles -src "(.*)\.sty=>\1.sty" -src "foobar.pl=>foobar.pl"
273 -setambles "foobar\.pl=>\\nopreamble\\nopostamble" -doc foodoc.tex foo
274 \end{verbatim}
275 (Note that the line is only broken to fit it onto the page, and there
276 should be no line break when entering at the command prompt.)
277
278 If the argument to \switch{setambles} contains the string
279 \verb"\\nopreamble", the character table will be excluded from the
280 corresponding files. So, in the above example, when you do:
281 \verb"latex foo.ins" the resulting files \texttt{foo.sty} and
282 \texttt{bar.sty} will contain the character table, but
283 \texttt{foobar.pl} won't. (If for some reason you don't want a
284 preamble but you do want the character table included use
285 \verb"\\usepreamble\\empty" instead of \verb'\\nopreamble'.
286 Conversely, if you want a preamble but don't want the character table
287 do something like \verb"\\nopreamble\\usepreamble\\defaultpreamble".
288
289 Note that the \verb"=>"\meta{text} part is optional. If it is
290 omitted, \meta{text} is assumed to be empty.
291
292 \item[\switch{macrocode} \texttt{"}\meta{expr}\texttt{"}] If source
293 file matches the Perl regular expression given by \meta{expr}, the
294 source code is inserted into a \texttt{macrocode} environment in the
295 DTX file.
296
297 Please note that the source code is supposed to be text insensitive to end of line format, as a matter of fact
298 \texttt{makedtx.pl} will convert all end of lines of this source code to LF's.
299
300 Please note also that only the source files given by the \switch{src} switch are considered, the
301 \switch{macrocode} switch by itself does not cause the source file to be insterted into the DTX file, it only
302 affects \emph{how} it is inserted.
303
304 \item[\switch{comment} \texttt{"}\meta{expr}\texttt{"}]
305 \changes{0.93}{2007/08/02}{comment switch added}%
306 If the source file matches the Perl regular expression given by
307 \meta{expr}, the source code will be inserted between \cs{iffalse}
308 \cs{fi} commands. The contents of this file will be included in the
309 DTX file, but will be excluded from the documentation. Since this
310 is provided mainly for non-TeX files (such as Perl scripts) the
311 \switch{comment} switch will typically need to be used in conjunction
312 with \switch{macrocode}.
313
314 \item[\switch{codetitle} \texttt{"}\meta{title}\texttt{"}]
315 \changes{0.93}{2007/08/02}{Added codetitle switch}%
316 This sets the title for the code section. The default is
317 \texttt{The Code}.
318 \end{description}
319
320 \section{The creatdtx Package}
321 \label{sec:creatdtx}
322
323 The documentation source code, as specified using the \switch{doc}
324 switch will typically be a standard \LaTeX\ document using the
325 \texttt{ltxdoc} class file. Unlike the DTX file, there is no
326 \ics{DocInput} command, and the lines do not begin with a percent
327 symbol, which means that the document can be, say, passed to the
328 \latextohtml\ converter, or some other application that would
329 otherwise be confused by a DTX file. The \texttt{creatdtx} package
330 can be used in this document using
331 \begin{verbatim}
332 \usepackage{creatdtx}
333 \end{verbatim}
334 although this package will be not be included in the DTX file by
335 \texttt{makedtx.pl}. There is only one command defined in this
336 package:\ics{ifmakedtx}\marg{dtx text}\marg{non dtx text}. The first
337 argument \meta{dtx text} will be copied to the DTX file by
338 \texttt{makedtx.pl}, but the second argument \meta{non dtx text}
339 won't. However, if you \LaTeX\ the document, the first argument will
340 be ignored, and the second argument will be used.
341
342 For example, if your code (in \texttt{foodoc.tex}) contains the
343 line:\par\vspace{6pt}\noindent\texttt{\cs{ifmakedtx}\{\}\{\cs{usepackage}\{html\}\}}
344 \par\vspace{6pt}\noindent the \texttt{html} package will only be
345 loaded if you \LaTeX\ \texttt{foodoc.tex}, but not when you \LaTeX\
346 \texttt{foo.dtx}.
347
348 The Perl script \texttt{creatdtx.perl} ignores the following commands
349 (and any associated arguments): \ics{OnlyDescription},
350 \ics{RecordChanges}, \ics{MakeShortVerb}, \ics{DeleteShortVerb},
351 \ics{DoNotIndex}, \ics{EnableCrossrefs}, \ics{CodelineIndex},
352 \ics{GetFileInfo}, \ics{PrintChanges}, \ics{changes}, \ics{CheckSum},
353 \ics{DescribeMacro} and \ics{DescribeEnvironment}. So even if you don't
354 use the \cs{ifmakedtx} command, using the \texttt{creatdtx} package
355 will help ensure that extraneous text does not appear in the HTML
356 document when using \latextohtml.
357
358 As from version 0.93b, \texttt{creatdtx.perl} also defines the
359 commands \ics{cs}, \ics{marg}, \ics{oarg} and \ics{parg}, since there
360 is no \latextohtml\ implementation of the \texttt{ltxdoc} class file.
361
362 \section{Examples}
363 \label{sec:examples}
364
365 Let's first consider a very simple example. Suppose you want to
366 create a package that redefines \cs{today} so that the date is
367 displayed in the form: yyyy-m-d. Let's call this package
368 \texttt{dashdate}. The file \texttt{dashdate.sty} should look
369 something like:
370 \begin{verbatim}
371 % First define package:
372 % \begin{macrocode}
373 \NeedsTeXFormat{LaTeX2e}
374 \ProvidesPackage{dashdate}
375 % \end{macrocode}
376 % Redefine |\today| command:
377 % \begin{macrocode}
378 \renewcommand{\today}{\the\year-\the\month-\the\day}
379 % \end{macrocode}
380 \end{verbatim}
381 Now let's make some (very brief) documentation. Let's call the file,
382 say \texttt{manual.tex}\footnote{Note: if you want to use
383 \latextohtml\ on this document, you will need to use, e.g.,
384 \cs{verb}\texttt{!\cs{today}!} instead of
385 \texttt{\symbol{124}\cs{today}\symbol{124}} since it doesn't recognise
386 \ics{MakeShortVerb}.}:
387 \begin{verbatim}
388 \documentclass{ltxdoc}
389 \usepackage{creatdtx}
390
391 \begin{document}
392 \title{A Sample Package}
393 \author{AN Other}
394 \maketitle
395
396 The \texttt{dashdate} package redefines |\today|
397 to produce the current date in the form: yyyy-m-d.
398 \end{document}
399 \end{verbatim}
400 Suppose you have saved \texttt{dashdate.sty} and \texttt{manual.tex}
401 in the subdirectory \texttt{source}. You can now create the
402 \texttt{.dtx} and \texttt{.ins} file using the command:
403 \begin{verbatim}
404 makedtx.pl -author "AN Other" -dir source -src "dashdate\.sty=>dashdate.sty"
405 -doc source/manual.tex dashdate
406 \end{verbatim}
407 The file \texttt{dashdate.dtx} is created, and contains the following
408 code:
409 \begin{verbatim}
410 %\iffalse
411 % dashdate.dtx generated using makedtx.pl version 0.9b (c) Nicola Talbot
412 % Command line args:
413 % -dir "source"
414 % -src "dashdate\.sty=>dashdate.sty"
415 % -author "AN Other"
416 % -doc "source/manual.tex"
417 % dashdate
418 % Created on 2005/2/10 22:22
419 %\fi
420 %\iffalse
421 %<*package>
422 %% \CharacterTable
423 %% {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
424 %% 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
425 %% Digits \0\1\2\3\4\5\6\7\8\9
426 %% Exclamation \! Double quote \" Hash (number) \#
427 %% Dollar \$ Percent \% Ampersand \&
428 %% Acute accent \' Left paren \( Right paren \)
429 %% Asterisk \* Plus \+ Comma \,
430 %% Minus \- Point \. Solidus \/
431 %% Colon \: Semicolon \; Less than \<
432 %% Equals \= Greater than \> Question mark \?
433 %% Commercial at \@ Left bracket \[ Backslash \\
434 %% Right bracket \] Circumflex \^ Underscore \_
435 %% Grave accent \` Left brace \{ Vertical bar \|
436 %% Right brace \} Tilde \~}
437 %</package>
438 %\fi
439 % \iffalse
440 % Doc-Source file to use with LaTeX2e
441 % Copyright (C) 2005 AN Other, all rights reserved.
442 % \fi
443 % \iffalse
444 %<*driver>
445 \documentclass{ltxdoc}
446
447 \begin{document}
448 \DocInput{dashdate.dtx}
449 \end{document}
450 %</driver>
451 %\fi
452 %\title{A Sample Package}
453 %\author{AN Other}
454 %\maketitle
455 %
456 %The \texttt{dashdate} package redefines "\today"
457 %to produce the current date in the form: yyyy-m-d.
458 %\end{document}
459 %
460 %\StopEventually{}
461 %\section{The Code}
462 %\iffalse
463 % \begin{macrocode}
464 %<*dashdate.sty>
465 % \end{macrocode}
466 %\fi
467 % First define package:
468 % \begin{macrocode}
469 \NeedsTeXFormat{LaTeX2e}
470 \ProvidesPackage{dashdate}
471 % \end{macrocode}
472 % Redefine |\today| command:
473 % \begin{macrocode}
474 \renewcommand{\today}{\the\year-\the\month-\the\day}
475 % \end{macrocode}
476 %\iffalse
477 % \begin{macrocode}
478 %</dashdate.sty>
479 % \end{macrocode}
480 %\fi
481 %\Finale
482 \endinput
483 \end{verbatim}
484 The installation file \texttt{dashdate.ins} looks like:
485 \begin{verbatim}
486 % dashdate.ins generated using makedtx.pl version 0.94b 2007/8/19 22:22
487 \input docstrip
488
489 \preamble
490 dashdate.dtx
491 Copyright 2007 AN Other
492
493 This work may be distributed and/or modified under the
494 conditions of the LaTeX Project Public License, either version 1.3
495 of this license of (at your option) any later version.
496 The latest version of this license is in
497 http://www.latex-project.org/lppl.txt
498 and version 1.3 or later is part of all distributions of LaTeX
499 version 2005/12/01 or later.
500
501 This work has the LPPL maintenance status `maintained'.
502
503 The Current Maintainer of this work is AN Other.
504
505 This work consists of the files dashdate.dtx and
506 dashdate.ins and the derived file dashdate.sty.
507 \endpreamble
508
509 \askforoverwritefalse
510
511 \generate{\file{dashdate.sty}{\usepreamble\defaultpreamble
512 \usepostamble\defaultpostamble\from{dashdate.dtx}{dashdate.sty,package}}
513 }
514
515 \endbatchfile
516 \end{verbatim}
517 Note that the command \verb"\usepackage{creatdtx}" has not been
518 transcribed to \texttt{dashdate.dtx} (although in this simple example
519 it's not really needed).
520
521 Now let's extend the example: suppose you want to create an analogous
522 Perl script for use with \latextohtml. This will need to be called
523 \texttt{dashdate.perl} and will look something like:
524 \begin{verbatim}
525 package main;
526
527 sub do_cmd_today{
528 local($_) = @_;
529 local($today) = &get_date();
530 $today =~ s|(\d+)/(\d+)/(\d+)|$3-$1-$2|;
531 "$today$_";
532 }
533
534 1;
535 \end{verbatim}
536 You will now need to call \texttt{makedtx.pl} as follows:
537 \begin{verbatim}
538 makedtx.pl -author "AN Other" -dir source -src "dashdate\.sty=>dashdate.sty"
539 -src "dashdate\.perl=>dashdate.perl"
540 -setambles "dashdate\.perl=>\\nopreamble\\nopostamble"
541 -macrocode "dashdate\.perl" -doc source/manual.tex dashdate
542 \end{verbatim}
543 (Note that the line is only broken to allow it to fit onto the page,
544 there should be no line break when you enter it on the command line.)
545 Alternatively, you could save typing and do:
546 \begin{verbatim}
547 makedtx.pl -author "AN Other" -dir source -src "dashdate\.(.*)=>dashdate.\1"
548 -setambles "dashdate\.perl=>\\nopreamble\\nopostamble" -macrocode "dashdate\.perl"
549 -doc source/manual.tex dashdate
550 \end{verbatim}
551 Note the use of the \switch{setambles} switch which suppresses the
552 insertion of text at the start and end of the Perl script which would
553 only confuse Perl. Note also the use of the \switch{macrocode}
554 switch. This is not needed for \texttt{dashdate.sty} since it has
555 already been included in the source code, but since \% is not a
556 comment character in Perl, the \texttt{macrocode} environment is not
557 included in the source code, and needs to be added. (If you are
558 unfamiliar with DocStrip and the use of the \texttt{macrocode}
559 environment, I suggest you read either \emph{A guide to
560 \LaTeX}~\cite[Appendix~D]{Kopka98} or \emph{The \LaTeX\
561 companion}~\cite[Chapter~14]{Goossens93}.)
562
563 It's likely that you may not want the Perl code to appear in the
564 document, but you still want it included in the DTX file. In addition
565 to the \switch{macrocode} switch, you would then also need to use
566 the \switch{comment} switch:
567 \begin{verbatim}
568 makedtx.pl -author "AN Other" -dir source -src "dashdate\.(.*)=>dashdate.\1"
569 -setambles "dashdate\.perl=>\\nopreamble\\nopostamble" -macrocode "dashdate\.perl"
570 -comment "dashdate\.perl" -doc source/manual.tex dashdate
571 \end{verbatim}
572
573 As another example, consider the \texttt{datetime} package. Version
574 2.42 of this package has 2 \texttt{.sty} files and 42 \texttt{.def}
575 files. The documentation is written in the file \texttt{manual.tex},
576 and the \texttt{.sty} and \texttt{.def} files are saved in a
577 subdirectory called \texttt{source}. Since these are the only files
578 in this directory, they can easily be merged into one \texttt{.dtx}
579 file using:
580 \begin{verbatim}
581 makedtx.pl -author "Nicola Talbot" -dir source -src "(.+)\.(.+)=>\1.\2"
582 -doc manual.tex datetime
583 \end{verbatim}
584 This creates the files \texttt{datetime.dtx} and \texttt{datetime.ins} which can then be distributed. The PDF version
585 of the documentation is obtained by doing:
586 \begin{verbatim}
587 pdflatex datetime.dtx
588 \end{verbatim}
589 and the HTML version (\texttt{manual.html}) is obtained by doing:
590 \begin{verbatim}
591 latex2html -split 0 -nonavigation -nofootnode -numbered_footnotes -noinfo manual
592 \end{verbatim}
593 Any minor differences between the HTML and PDF versions are dealt by
594 using \cs{ifmakedtx} in the original file \texttt{manual.tex}.
595
596 \section{Troubleshooting}
597 \label{sec:problems}
598
599 The \texttt{makedtx} bundle has only been tested under Linux using
600 Perl v5.6.0. There are no guarantees whether or not it will work on
601 other operating systems or on different versions (in fact, there are
602 no guarantees or warranties at all).
603
604 \subsection{Known Bugs}
605
606 It's possible to confuse \texttt{makedtx.pl} by placing either the
607 command \cs{end}\marg{document} or the command \ics{ifmakedtx} in a
608 \cs{verb} command, or by having the \ics{ifmakedtx} command on the same
609 line as \cs{begin}\marg{document}. You will also need to take care
610 about lines beginning with a percent symbol (\%) in the documentation,
611 as this will get converted into a line beginning with \verb"%%" in the
612 \texttt{.dtx} file, which has a special meaning. Either place a space
613 immediately prior the percent symbol, or do \verb"\relax%" if you
614 really don't want the extra space (or place your comment in an
615 \cs{iffalse} \ldots\ \cs{fi} conditional).
616
617 \subsection{Possible errors encountered using \texttt{makedtx.pl}}
618
619 Note: be careful to use double quotes around arguments that contain
620 characters that the shell might try interpreting, e.g.\ \verb"*" or
621 \verb'>'.
622
623 Syntax error messages:
624 \begin{enumerate}
625 \item \texttt{No document source specified (missing -doc)}
626
627 You must use the \switch{doc} switch.
628
629 \item \texttt{No source code specified (missing -src)}
630
631 You must specify at least one \switch{src} switch.
632
633 \item \texttt{No basename specified}
634
635 You must specify the basename of the \texttt{.dtx} and \texttt{.ins} files. This should
636 be the last argument passed to \texttt{makedtx.pl}.
637
638 \item \texttt{-src \ldots\ argument invalid (no output file specified)}
639
640 You have omitted the \verb"=>" separator in the argument of the
641 \switch{src} switch.
642
643 \item \texttt{-src argument \ldots\ invalid (too many => specified)}
644
645 You have used too many \verb"=>" separators in the argument of the
646 \switch{src} switch. (Similarly for the \switch{setambles} switch.)
647 \end{enumerate}
648
649 \appendix
650
651 \section{Perl Regular Expressions}
652 \label{sec:prex}
653
654 This section gives a very brief overview of Perl regular expressions. For more detail, look at the Perl
655 documentation (use \verb"man perlre" for the man page.)
656
657 \begin{tabular}{ll}
658 \verb'\' & Quote the next character\\
659 \verb"." & Match any character\\
660 \verb"|" & Alternation\\
661 \verb"()" & Grouping\\
662 \verb"[]" & Character class\\
663 \verb"*" & Match 0 or more times\\
664 \verb"+" & Match 1 or more times\\
665 \verb"?" & Match 1 or 0 times\\
666 \verb"{n}" & Match exactly \texttt{n} times\\
667 \verb"{n,}" & Match at least \texttt{n} times\\
668 \verb"{n,m}" & Match at least \texttt{n} but no more than \texttt{m} times.
669 \end{tabular}
670
671 In the replacement text, a backslash followed by a number \meta{n} indicates the text from the \meta{n}th group.
672
673 For example, suppose you have the following files:
674 \begin{verbatim}
675 abcsrc.sty
676 abcsrc.bst
677 abcsrc.perl
678 foosrc.sty
679 foobarsrc.sty
680 \end{verbatim}
681 then if you pass the following switch to \texttt{makedtx.pl}:
682 \begin{itemize}
683 \item \verb'-src "abcsrc\.([styb]+)=>abc.\1"'
684 will be equivalent to:
685 \begin{verbatim}
686 -src "abcsrc.sty=>abc.sty" -src "abcsrc.bst=>abc.bst"
687 \end{verbatim}
688 since \verb'[styb]+' will match one or more of the letters \texttt{styb} (so it will match \texttt{sty} and \texttt{bst}).
689 \verb'\1' indicates the text found in the first group, which in this example will either be \texttt{sty} or \texttt{bst}.
690
691 \item \verb'-src "abcsrc\.(.+)=>abc.\1"'
692 will be equivalent to:
693 \begin{verbatim}
694 -src "abcsrc.sty=>abc.sty" -src "abcsrc.bst=>abc.bst" -src "abcsrc.perl=>abc.perl"
695 \end{verbatim}
696 Note that a full stop represents any character so \texttt{.+} means any string of length 1 or more, whereas
697 \verb"\." means an actual full stop character.
698
699 \item \verb'-src "foo(.*)src\.sty=>foo\1.sty"'
700 will be equivalent to:
701 \begin{verbatim}
702 -src "foosrc.sty=>foo.sty" -src "foobarsrc.sty=>foobar.sty"
703 \end{verbatim}
704
705 \item \verb'-src "(.+)src\.(.+)=>\1.\2"'
706 will be equivalent to
707 \begin{verbatim}
708 -src "abcsrc.sty=>abc.sty"
709 -src "abcsrc.bst=>abc.bst"
710 -src "abcsrc.perl=>abc.perl"
711 -src "foosrc.sty=>foo.sty"
712 -src "foobarsrc.sty=>foobar.sty"
713 \end{verbatim}
714
715 \end{itemize}
716
717 \StopEventually{\phantomsection\addcontentsline{toc}{section}{\refname}
718 \csname begin\endcsname{thebibliography}{1}
719 \bibitem{Goossens93} The \LaTeX\ companion. Michel~Goossens, Frank~Mittelbach and Alexander~Samarin.
720 Addison-Wesley 1993.
721
722 \bibitem{Kopka98} A guide to \LaTeX. Helmut~Kopka and Patrick~W.~Daly. Addison-Wesley 1998.
723 \csname end\endcsname{thebibliography}
724 \PrintChanges
725 \phantomsection\addcontentsline{toc}{section}{Index}
726 \PrintIndex}
727 \end{document}

Send suggestions and bug reports to Sergey Poznyakoff
ViewVC Help
Powered by ViewVC 1.1.20