/ [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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 72 - (hide annotations)
Mon Feb 19 21:54:52 2018 UTC (3 years, 11 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 vincentb1 72 \documentclass[a4paper,english]{ltxdoc}
2 Vincent 63
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 Vincent 67 \usepackage{createdtx}
10 vincentb1 72 \usepackage{datetime2}
11     \DTMsetstyle{english}
12 Vincent 63
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 vincentb1 72 \DTMsavedate{makedtx-date}{2018-02-19}
30 Vincent 63
31 Vincent 67 \input{makedtx-version}
32 Vincent 63 \begin{document}
33 Vincent 67
34     \title{makedtx \version : a Perl script to help create a DTX
35 Vincent 63 file from source code}
36     \author{Nicola Talbot\\
37     \url{http://theoval.cmp.uea.ac.uk/~nlct/}}
38 vincentb1 72 \date{\DTMusedate{makedtx-date}}
39 Vincent 63 \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 Vincent 71 DTX file.
296 Vincent 63
297 Vincent 71 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 Vincent 63 \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