Nicola Talbot
http://theoval.cmp.uea.ac.uk/~nlct/
19th August 2007
Authors of LATEX2e class files or packages are encouraged to bundle their source and documentation together into a single DTX file. This makes distribution much easier, as users need only download the DTX file and possibly a corresponding installation script (INS file) instead of a multitude of .sty, .cls, .def etc files. However, having the documentation and code bundled together can cause problems if a developer wants to, say, use ispell to spell check the documentation, or convert the documentation to a format other than DVI, PostScript or PDF (such as HTML).
Why should I want to convert my documentation to HTML when I can just use PDFLaTeX? The more general purpose packages that I write (such as datetime and glossary) I upload to CTAN, however most of the packages I write are specific to the School of Computing Sciences at the University of East Anglia, so these I keep on my web site, and as some of the faculty either don't have a PDF plug in or prefer to view HTML rather than PDF documents, I have taken to writing both PDF and HTML versions of my package documentation. However, doesn't work on a .dtx file so I used to convert them manually which is fine for one or two small documents, but becomes rather cumbersome as soon as I have large documents or a lot of packages. Therefore I decided to write the documentation separately, and use a Perl script to bundle everything together. It also has the added convenience in that I don't have to keep copying and pasting the character table every time I write a new package, and it saves the laborious task of writing the installation script1.
This document is structured as follows: Section 2 describes how to install the makedtx bundle, Section 3 gives an overview of the makedtx.pl Perl script, Section 4 describes the creatdtx package, Section 5 illustrates the use of the makedtx bundle with examples and Section 6 gives a list of possible errors and their solutions.
You need to download both makedtx.dtx and makedtx.ins, and run the installation script through LaTeX:
latex makedtx.ins
The following files will be created:
If you are using UNIX/Linux etc you will need to make makedtx.pl executable using chmod:
chmod a+x
makedtx.pl
and place it somewhere on your
path. If perl is located somewhere other than
/usr/bin/ you will need to edit the first line of
makedtx.pl. (If you don't know where perl is
located, you can use the command: which perl.) The package
creatdtx.sty needs to be placed somewhere on the LaTeX path
and creatdtx.perl should be placed in a directory searched by
. (See the documentation for details.)
The Perl script makedtx.pl has the following syntax:
makedtx.pl [options] -src
"expr1=>expr2"
-doc filename basename
The very last argument basename is the basename of the
.dtx and .ins files you want to create. The
-doc filename switch indicates the file containing the
documentation and -src
"expr1=>expr2" indicates the
original source file(s), given by expr1, and the corresponding
file name when it has been extracted from the .dtx file,
given by expr2. This switch is a little complicated, so it's
best described using examples.
Suppose you have your documentation in the file foodoc.tex, and the original source code is in the file foosrc.sty. You want to create the files foo.dtx and foo.ins. When you LaTeX foo.dtx you want the documentation as specified in foodoc.tex and when you LaTeX foo.ins you want the file foo.sty to be created, using the code specified in foosrc.sty. You will need to do:
makedtx.pl -src "foosrc\.sty=>foo.sty" -doc foodoc.tex foo
You may have multiple invocations of the -src switch. For example, suppose you also have the file barsrc.sty which you want to be extracted from the .dtx file as bar.sty, you can do:
makedtx.pl -src "foosrc\.sty=>foo.sty" -src "barsrc\.sty=>bar.sty" -doc foodoc.tex fooAlternatively, you can use Perl-type regular expressions:
makedtx.pl -src "(.*)src\.sty=>\1.sty" -doc foodoc.tex foo(Note the use of double quotes to prevent shell expansion.) Appendix A gives a brief overview of Perl regular expressions for the uninitiated.
makedtx.pl -dir sourcefiles -src "(.*)\.sty=>\1.sty" -doc foodoc.tex foo
basename.dtx Copyright date author
This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3 of this license of (at your option) any later version. The latest version of this license is in http://www.latex-project.org/lppl.txt and version 1.3 or later is part of all distributions of LaTeX version 2005/12/01 or later.
This work has the LPPL maintenance status `maintained'.
The Current Maintainer of this work is author.
This work consists of the files basename.dtx and basename.ins and the derived files file list.
where date is the copyright date, and author is the author's name (see below).
Note that this has been changed as of makedtx v0.94. Older versions of makedtx do not conform to any of the free licenses.
-stopeventually "\\PrintIndex" will result in the line:
\StopEventually{\PrintIndex}. If makedtx.pl
encounters a \StopEventually command within the document,
this will be used instead. If there is no \StopEventually
command in the document and the -stopeventually switch is
absent \StopEventually{} will be inserted in the DTX
file.
makedtx.pl -dir sourcefiles -src "(.*)\.sty=>\1.sty" -src "foobar.pl=>foobar.pl" -setambles "foobar\.pl=>\\nopreamble\\nopostamble" -doc foodoc.tex foo(Note that the line is only broken to fit it onto the page, and there should be no line break when entering at the command prompt.)
If the argument to -setambles contains the string
\\nopreamble, the character table will be excluded from the
corresponding files. So, in the above example, when you do:
latex foo.ins the resulting files foo.sty and
bar.sty will contain the character table, but
foobar.pl won't. (If for some reason you don't want a
preamble but you do want the character table included use
\\usepreamble\\empty instead of \\nopreamble.
Conversely, if you want a preamble but don't want the character table
do something like \\nopreamble\\usepreamble\\defaultpreamble.
Note that the =>text part is optional. If it is
omitted, text is assumed to be empty.
The documentation source code, as specified using the -doc switch will typically be a standard LaTeX document using the ltxdoc class file. Unlike the DTX file, there is no \DocInput command, and the lines do not begin with a percent symbol, which means that the document can be, say, passed to the converter, or some other application that would otherwise be confused by a DTX file. The creatdtx package can be used in this document using
\usepackage{creatdtx}
although this package will be not be included in the DTX file by
makedtx.pl. There is only one command defined in this
package:\ifmakedtx{dtx text}{non dtx text}. The first
argument dtx text will be copied to the DTX file by
makedtx.pl, but the second argument non dtx text
won't. However, if you LaTeX the document, the first argument will
be ignored, and the second argument will be used.
For example, if your code (in foodoc.tex) contains the line:
\ifmakedtx{}{\usepackage{html}}
the html package will only be
loaded if you LaTeX foodoc.tex, but not when you LaTeX foo.dtx.
The Perl script creatdtx.perl ignores the following commands (and any associated arguments): \OnlyDescription, \RecordChanges, \MakeShortVerb, \DeleteShortVerb, \DoNotIndex, \EnableCrossrefs, \CodelineIndex, \GetFileInfo, \PrintChanges, \changes, \CheckSum, \DescribeMacro and \DescribeEnvironment. So even if you don't use the \ifmakedtx command, using the creatdtx package will help ensure that extraneous text does not appear in the HTML document when using .
As from version 0.93b, creatdtx.perl also defines the commands \cs, \marg, \oarg and \parg, since there is no implementation of the ltxdoc class file.
Let's first consider a very simple example. Suppose you want to create a package that redefines \today so that the date is displayed in the form: yyyy-m-d. Let's call this package dashdate. The file dashdate.sty should look something like:
% First define package:
% \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{dashdate}
% \end{macrocode}
% Redefine |\today| command:
% \begin{macrocode}
\renewcommand{\today}{\the\year-\the\month-\the\day}
% \end{macrocode}
Now let's make some (very brief) documentation. Let's call the file,
say manual.tex2:
\documentclass{ltxdoc}
\usepackage{creatdtx}
\begin{document}
\title{A Sample Package}
\author{AN Other}
\maketitle
The \texttt{dashdate} package redefines |\today|
to produce the current date in the form: yyyy-m-d.
\end{document}
Suppose you have saved dashdate.sty and manual.tex
in the subdirectory source. You can now create the
.dtx and .ins file using the command:
makedtx.pl -author "AN Other" -dir source -src "dashdate\.sty=>dashdate.sty" -doc source/manual.tex dashdateThe file dashdate.dtx is created, and contains the following code:
%\iffalse
% dashdate.dtx generated using makedtx.pl version 0.9b (c) Nicola Talbot
% Command line args:
% -dir "source"
% -src "dashdate\.sty=>dashdate.sty"
% -author "AN Other"
% -doc "source/manual.tex"
% dashdate
% Created on 2005/2/10 22:22
%\fi
%\iffalse
%<*package>
%% \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 \~}
%</package>
%\fi
% \iffalse
% Doc-Source file to use with LaTeX2e
% Copyright (C) 2005 AN Other, all rights reserved.
% \fi
% \iffalse
%<*driver>
\documentclass{ltxdoc}
\begin{document}
\DocInput{dashdate.dtx}
\end{document}
%</driver>
%\fi
%\title{A Sample Package}
%\author{AN Other}
%\maketitle
%
%The \texttt{dashdate} package redefines "\today"
%to produce the current date in the form: yyyy-m-d.
%\end{document}
%
%\StopEventually{}
%\section{The Code}
%\iffalse
% \begin{macrocode}
%<*dashdate.sty>
% \end{macrocode}
%\fi
% First define package:
% \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{dashdate}
% \end{macrocode}
% Redefine |\today| command:
% \begin{macrocode}
\renewcommand{\today}{\the\year-\the\month-\the\day}
% \end{macrocode}
%\iffalse
% \begin{macrocode}
%</dashdate.sty>
% \end{macrocode}
%\fi
%\Finale
\endinput
The installation file dashdate.ins looks like:
% dashdate.ins generated using makedtx.pl version 0.94b 2007/8/19 22:22
\input docstrip
\preamble
dashdate.dtx
Copyright 2007 AN Other
This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.3
of this license of (at your option) any later version.
The latest version of this license is in
http://www.latex-project.org/lppl.txt
and version 1.3 or later is part of all distributions of LaTeX
version 2005/12/01 or later.
This work has the LPPL maintenance status `maintained'.
The Current Maintainer of this work is AN Other.
This work consists of the files dashdate.dtx and
dashdate.ins and the derived file dashdate.sty.
\endpreamble
\askforoverwritefalse
\generate{\file{dashdate.sty}{\usepreamble\defaultpreamble
\usepostamble\defaultpostamble\from{dashdate.dtx}{dashdate.sty,package}}
}
\endbatchfile
Note that the command \usepackage{creatdtx} has not been
transcribed to dashdate.dtx (although in this simple example
it's not really needed).
Now let's extend the example: suppose you want to create an analogous Perl script for use with . This will need to be called dashdate.perl and will look something like:
package main;
sub do_cmd_today{
local($_) = @_;
local($today) = &get_date();
$today =~ s|(\d+)/(\d+)/(\d+)|$3-$1-$2|;
"$today$_";
}
1;
You will now need to call makedtx.pl as follows:
makedtx.pl -author "AN Other" -dir source -src "dashdate\.sty=>dashdate.sty" -src "dashdate\.perl=>dashdate.perl" -setambles "dashdate\.perl=>\\nopreamble\\nopostamble" -macrocode "dashdate\.perl" -doc source/manual.tex dashdate(Note that the line is only broken to allow it to fit onto the page, there should be no line break when you enter it on the command line.) Alternatively, you could save typing and do:
makedtx.pl -author "AN Other" -dir source -src "dashdate\.(.*)=>dashdate.\1" -setambles "dashdate\.perl=>\\nopreamble\\nopostamble" -macrocode "dashdate\.perl" -doc source/manual.tex dashdateNote the use of the -setambles switch which suppresses the insertion of text at the start and end of the Perl script which would only confuse Perl. Note also the use of the -macrocode switch. This is not needed for dashdate.sty since it has already been included in the source code, but since % is not a comment character in Perl, the macrocode environment is not included in the source code, and needs to be added. (If you are unfamiliar with DocStrip and the use of the macrocode environment, I suggest you read either A guide to LaTeX [2, Appendix D] or The LaTeX companion [1, Chapter 14].)
It's likely that you may not want the Perl code to appear in the document, but you still want it included in the DTX file. In addition to the -macrocode switch, you would then also need to use the -comment switch:
makedtx.pl -author "AN Other" -dir source -src "dashdate\.(.*)=>dashdate.\1" -setambles "dashdate\.perl=>\\nopreamble\\nopostamble" -macrocode "dashdate\.perl" -comment "dashdate\.perl" -doc source/manual.tex dashdate
As another example, consider the datetime package. Version 2.42 of this package has 2 .sty files and 42 .def files. The documentation is written in the file manual.tex, and the .sty and .def files are saved in a subdirectory called source. Since these are the only files in this directory, they can easily be merged into one .dtx file using:
makedtx.pl -author "Nicola Talbot" -dir source -src "(.+)\.(.+)=>\1.\2" -doc manual.tex datetimeThis creates the files datetime.dtx and datetime.ins which can then be distributed. The PDF version of the documentation is obtained by doing:
pdflatex datetime.dtxand the HTML version (manual.html) is obtained by doing:
latex2html -split 0 -nonavigation -nofootnode -numbered_footnotes -noinfo manualAny minor differences between the HTML and PDF versions are dealt by using \ifmakedtx in the original file manual.tex.
The makedtx bundle has only been tested under Linux using Perl v5.6.0. There are no guarantees whether or not it will work on other operating systems or on different versions (in fact, there are no guarantees or warranties at all).
It's possible to confuse makedtx.pl by placing either the
command \end{document} or the command \ifmakedtx in a
\verb command, or by having the \ifmakedtx command on the same
line as \begin{document}. You will also need to take care
about lines beginning with a percent symbol (%) in the documentation,
as this will get converted into a line beginning with %% in the
.dtx file, which has a special meaning. Either place a space
immediately prior the percent symbol, or do \relax% if you
really don't want the extra space (or place your comment in an
\iffalse ... \fi conditional).
Note: be careful to use double quotes around arguments that contain
characters that the shell might try interpreting, e.g. * or
>.
Syntax error messages:
You must use the -doc switch.
You must specify at least one -src switch.
You must specify the basename of the .dtx and .ins files. This should be the last argument passed to makedtx.pl.
You have omitted the => separator in the argument of the
-src switch.
You have used too many => separators in the argument of the
-src switch. (Similarly for the -setambles switch.)
This section gives a very brief overview of Perl regular expressions. For more detail, look at the Perl
documentation (use man perlre for the man page.)
\ |
Quote the next character |
. |
Match any character |
| |
Alternation |
() |
Grouping |
[] |
Character class |
* |
Match 0 or more times |
+ |
Match 1 or more times |
? |
Match 1 or 0 times |
{n} |
Match exactly n times |
{n,} |
Match at least n times |
{n,m} |
Match at least n but no more than m times. |
In the replacement text, a backslash followed by a number n indicates the text from the nth group.
For example, suppose you have the following files:
abcsrc.sty abcsrc.bst abcsrc.perl foosrc.sty foobarsrc.stythen if you pass the following switch to makedtx.pl:
-src "abcsrc\.([styb]+)=>abc.\1"
will be equivalent to:
-src "abcsrc.sty=>abc.sty" -src "abcsrc.bst=>abc.bst"since
[styb]+ will match one or more of the letters styb (so it will match sty and bst).
\1 indicates the text found in the first group, which in this example will either be sty or bst.
-src "abcsrc\.(.+)=>abc.\1"
will be equivalent to:
-src "abcsrc.sty=>abc.sty" -src "abcsrc.bst=>abc.bst" -src "abcsrc.perl=>abc.perl"Note that a full stop represents any character so .+ means any string of length 1 or more, whereas
\. means an actual full stop character.
-src "foo(.*)src\.sty=>foo\1.sty"
will be equivalent to:
-src "foosrc.sty=>foo.sty" -src "foobarsrc.sty=>foobar.sty"
-src "(.+)src\.(.+)=>\1.\2"
will be equivalent to
-src "abcsrc.sty=>abc.sty" -src "abcsrc.bst=>abc.bst" -src "abcsrc.perl=>abc.perl" -src "foosrc.sty=>foo.sty" -src "foobarsrc.sty=>foobar.sty"