summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/makedtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2007-08-16 00:36:22 +0000
committerKarl Berry <karl@freefriends.org>2007-08-16 00:36:22 +0000
commite8a50aed5d15bb07b077c572f74b697de13dd259 (patch)
tree655e386dc7e1a3c56c933fa1dcb570a45c2d8290 /Master/texmf-dist/doc/latex/makedtx
parent633e589696b3070094a313c5cddd484571a3ea7b (diff)
makedtx 0.93b (15aug07)
git-svn-id: svn://tug.org/texlive/trunk@4739 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/makedtx')
-rw-r--r--Master/texmf-dist/doc/latex/makedtx/README4
-rw-r--r--Master/texmf-dist/doc/latex/makedtx/creatdtx.perl48
-rw-r--r--Master/texmf-dist/doc/latex/makedtx/makedtx-manual.html930
-rw-r--r--Master/texmf-dist/doc/latex/makedtx/makedtx.pdfbin218544 -> 198173 bytes
-rw-r--r--Master/texmf-dist/doc/latex/makedtx/makedtx.pl132
-rw-r--r--Master/texmf-dist/doc/latex/makedtx/manual.html831
6 files changed, 1067 insertions, 878 deletions
diff --git a/Master/texmf-dist/doc/latex/makedtx/README b/Master/texmf-dist/doc/latex/makedtx/README
index 3001cb26cec..5e65973a0e7 100644
--- a/Master/texmf-dist/doc/latex/makedtx/README
+++ b/Master/texmf-dist/doc/latex/makedtx/README
@@ -1,6 +1,6 @@
-makedtx v0.9b : a Perl script to help create .dtx and .ins files
+makedtx v0.93b : a Perl script to help create .dtx and .ins files
-Last Modified : 13 Feb 2005
+Last Modified : 2 August 2007
Author : Nicola Talbot
diff --git a/Master/texmf-dist/doc/latex/makedtx/creatdtx.perl b/Master/texmf-dist/doc/latex/makedtx/creatdtx.perl
index add32266da4..9149cba164b 100644
--- a/Master/texmf-dist/doc/latex/makedtx/creatdtx.perl
+++ b/Master/texmf-dist/doc/latex/makedtx/creatdtx.perl
@@ -1,16 +1,56 @@
# creatdtx.perl LaTeX2HTML file corresponding to creatdtx.sty package
# author : Nicola Talbot
-# date : 8th Feb 2005
+# date : 2nd August 2007
package main;
-print " [creatdtx v0.9b (N.L.C. Talbot)]";
+print " [creatdtx v0.93b (N.L.C. Talbot)]";
sub do_cmd_meta
{
&do_cmd_emph(@_);
}
+sub do_cmd_cs{
+ local($_) = @_;
+ local($name);
+
+ $name = &missing_braces unless
+ (s/$next_pair_pr_rx/$name=$2;''/eo);
+
+ "<TT>&#092;$name</TT>$_";
+}
+
+sub do_cmd_marg{
+ local($_) = @_;
+ local($arg);
+
+ $arg = &missing_braces unless
+ (s/$next_pair_pr_rx/$arg=$2;''/eo);
+
+ "<TT>{</TT><EM>$arg</EM><TT>}</TT>$_";
+}
+
+sub do_cmd_oarg{
+ local($_) = @_;
+ local($arg);
+
+ $arg = &missing_braces unless
+ (s/$next_pair_pr_rx/$arg=$2;''/eo);
+
+ "<TT>[</TT><EM>$arg</EM><TT>]</TT>$_";
+}
+
+sub do_cmd_parg{
+ local($_) = @_;
+ local($arg);
+
+ $arg = &missing_braces unless
+ (s/$next_pair_pr_rx/$arg=$2;''/eo);
+
+ "<TT>(</TT><EM>$arg</EM><TT>)</TT>$_";
+}
+
&ignore_commands( <<_IGNORED_CMDS_);
ifmakedtx # {}
StopEventually # {}
@@ -23,10 +63,10 @@ GetFileInfo # {}
CheckSum # {}
DescribeMacro # {}
DescribeEnvironment # {}
-MakeShortVerb # {}
-DeleteShortVerb # {}
DoNotIndex # {}
changes # {} # {} # {}
+DeleteShortVerb # {}
+MakeShortVerb # {}
_IGNORED_CMDS_
1;
diff --git a/Master/texmf-dist/doc/latex/makedtx/makedtx-manual.html b/Master/texmf-dist/doc/latex/makedtx/makedtx-manual.html
new file mode 100644
index 00000000000..d99beb071cc
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/makedtx/makedtx-manual.html
@@ -0,0 +1,930 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+
+<!--Converted with LaTeX2HTML 2002 (1.67)
+original version by: Nikos Drakos, CBLU, University of Leeds
+* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
+* with significant contributions from:
+ Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
+<HTML>
+<HEAD>
+<TITLE>makedtx v0.93b : a Perl script to help create a DTX file from source code</TITLE>
+<META NAME="description" CONTENT="makedtx v0.93b : a Perl script to help create a DTX file from source code">
+<META NAME="keywords" CONTENT="manual">
+<META NAME="resource-type" CONTENT="document">
+<META NAME="distribution" CONTENT="global">
+
+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
+<META NAME="Generator" CONTENT="LaTeX2HTML v2002">
+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+
+
+</HEAD>
+
+<BODY >
+
+<H1 ALIGN="CENTER">makedtx v0.93b : a Perl script to help create a DTX
+file from source code</H1>
+<P ALIGN="CENTER"><STRONG>Nicola Talbot
+<BR><TT><A NAME="tex2html1"
+ HREF="http://theoval.cmp.uea.ac.uk/~nlct/">http://theoval.cmp.uea.ac.uk/~nlct/</A></TT></STRONG></P>
+<P ALIGN="CENTER"><STRONG>2nd August 2007</STRONG></P>
+
+<P>
+<BR>
+
+<H2><A NAME="SECTION00010000000000000000">
+Contents</A>
+</H2>
+<!--Table of Contents-->
+
+<UL>
+<LI><A NAME="tex2html17"
+ HREF="manual.html#SECTION00020000000000000000">Introduction</A>
+<LI><A NAME="tex2html18"
+ HREF="manual.html#SECTION00030000000000000000">Installation</A>
+<LI><A NAME="tex2html19"
+ HREF="manual.html#SECTION00040000000000000000">makedtx.pl</A>
+<UL>
+<LI><A NAME="tex2html20"
+ HREF="manual.html#SECTION00041000000000000000">Compulsory Arguments</A>
+<LI><A NAME="tex2html21"
+ HREF="manual.html#SECTION00042000000000000000">Options</A>
+</UL><BR>
+<LI><A NAME="tex2html22"
+ HREF="manual.html#SECTION00050000000000000000">The creatdtx Package</A>
+<LI><A NAME="tex2html23"
+ HREF="manual.html#SECTION00060000000000000000">Examples</A>
+<LI><A NAME="tex2html24"
+ HREF="manual.html#SECTION00070000000000000000">Troubleshooting</A>
+<UL>
+<LI><A NAME="tex2html25"
+ HREF="manual.html#SECTION00071000000000000000">Known Bugs</A>
+<LI><A NAME="tex2html26"
+ HREF="manual.html#SECTION00072000000000000000">Possible errors encountered using makedtx.pl</A>
+</UL><BR>
+<LI><A NAME="tex2html27"
+ HREF="manual.html#SECTION00080000000000000000">Perl Regular Expressions</A>
+<LI><A NAME="tex2html28"
+ HREF="manual.html#SECTION00090000000000000000">Bibliography</A>
+</UL>
+<!--End of Table of Contents-->
+<P>
+
+<H3>Abstract:</H3>
+<DIV>
+The <TT>makedtx</TT> bundle is provided to help developers to write
+the code and documentation in separate files, and then combine them
+into a single DTX file for distribution. It automatically generates
+the character table, and also writes the associated installation
+(.ins) script.
+</DIV>
+<P>
+
+<P>
+
+<H1><A NAME="SECTION00020000000000000000">
+Introduction</A>
+</H1>
+
+<P>
+Authors of L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X2<SUB>e</SUB> 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 <TT>.sty</TT>, <TT>.cls</TT>, <TT>.def</TT>
+etc files. However, having the documentation and code bundled
+together can cause problems if a developer wants to, say, use
+<TT>ispell</TT> to spell check the documentation, or convert the
+documentation to a format other than DVI, PostScript or PDF (such as
+HTML).
+
+<P>
+Why should I want to convert my documentation to HTML when I can just
+use PDFL<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X? The more general purpose packages that I write (such
+as <TT>datetime</TT> and <TT>glossary</TT>) 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 <TT>.dtx</TT> 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
+script<A NAME="tex2html2"
+ HREF="#foot47"><SUP>1</SUP></A>.
+
+<P>
+This document is structured as follows: Section&nbsp;<A HREF="manual.html#sec:install">2</A>
+describes how to install the <TT>makedtx</TT> bundle,
+Section&nbsp;<A HREF="manual.html#sec:makedtx">3</A> gives an overview of the <TT>makedtx.pl</TT>
+Perl script, Section&nbsp;<A HREF="manual.html#sec:creatdtx">4</A> describes the
+<TT>creatdtx</TT> package, Section&nbsp;<A HREF="manual.html#sec:examples">5</A> illustrates the
+use of the <TT>makedtx</TT> bundle with examples and
+Section&nbsp;<A HREF="manual.html#sec:problems">6</A> gives a list of possible errors and their
+solutions.
+
+<P>
+
+<H1><A NAME="SECTION00030000000000000000"></A><A NAME="sec:install"></A><BR>
+Installation
+</H1>
+
+<P>
+You need to download both <TT>makedtx.dtx</TT> and
+<TT>makedtx.ins</TT>, and run the installation script through
+L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X:
+<P>
+<TT>latex makedtx.ins</TT>
+
+<P>
+The following files will be created:
+<DL>
+<DT><STRONG><TT>makedtx.pl</TT></STRONG></DT>
+<DD>Perl script
+</DD>
+<DT><STRONG><TT>creatdtx.sty</TT></STRONG></DT>
+<DD>L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X package for use with <TT>makedtx.pl</TT>
+</DD>
+<DT><STRONG><TT>creatdtx.perl</TT></STRONG></DT>
+<DD>Corresponding Perl script for use with LaTeX2HTML
+</DD>
+</DL>
+
+<P>
+If you are using UNIX/Linux etc you will need to make
+<TT>makedtx.pl</TT> executable using
+<TT>chmod</TT>:
+<P>
+<BR>
+<BR><TT>chmod a+x
+makedtx.pl</TT>
+<P>
+<BR>
+<BR>and place it somewhere on your
+path. If <TT>perl</TT> is located somewhere other than
+<TT>/usr/bin/</TT> you will need to edit the first line of
+<TT>makedtx.pl</TT>. (If you don't know where <TT>perl</TT> is
+located, you can use the command: <TT>which perl</TT>.) The package
+<TT>creatdtx.sty</TT> needs to be placed somewhere on the L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X path
+and <TT>creatdtx.perl</TT> should be placed in a directory searched by
+. (See the documentation for details.)
+
+<P>
+
+<H1><A NAME="SECTION00040000000000000000"></A><A NAME="sec:makedtx"></A><BR>
+makedtx.pl
+</H1>
+
+<P>
+The Perl script <TT>makedtx.pl</TT> has the following syntax:
+<P>
+<TT>makedtx.pl</TT> <TT>[</TT><EM>options</EM><TT>]</TT> <TT>-src</TT>
+<TT>"</TT><I>expr1</I><code>=&gt;</code><I>expr2</I><TT>"</TT>
+<TT>-doc</TT> <I>filename</I> <I>basename</I>
+
+<P>
+
+<H2><A NAME="SECTION00041000000000000000">
+Compulsory Arguments</A>
+</H2>
+
+<P>
+The very last argument <I>basename</I> is the basename of the
+<TT>.dtx</TT> and <TT>.ins</TT> files you want to create. The
+<TT>-doc</TT> <I>filename</I> switch indicates the file containing the
+documentation and <TT>-src</TT>
+<code>"</code><I>expr1</I><code>=&gt;</code><I>expr2</I><code>"</code> indicates the
+original source file(s), given by <I>expr1</I>, and the corresponding
+file name when it has been extracted from the <TT>.dtx</TT> file,
+given by <I>expr2</I>. This switch is a little complicated, so it's
+best described using examples.
+
+<P>
+Suppose you have your documentation in the file <TT>foodoc.tex</TT>,
+and the original source code is in the file <TT>foosrc.sty</TT>. You
+want to create the files <TT>foo.dtx</TT> and <TT>foo.ins</TT>. When
+you L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X <TT>foo.dtx</TT> you want the documentation as specified
+in <TT>foodoc.tex</TT> and when you L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X <TT>foo.ins</TT> you want
+the file <TT>foo.sty</TT> to be created, using the code specified in
+<TT>foosrc.sty</TT>. You will need to do:
+<PRE>
+makedtx.pl -src "foosrc\.sty=&gt;foo.sty" -doc foodoc.tex foo
+</PRE>
+
+<P>
+You may have multiple invocations of the <TT>-src</TT> switch. For
+example, suppose you also have the file <TT>barsrc.sty</TT> which you
+want to be extracted from the <TT>.dtx</TT> file as <TT>bar.sty</TT>,
+you can do:
+<PRE>
+makedtx.pl -src "foosrc\.sty=&gt;foo.sty" -src "barsrc\.sty=&gt;bar.sty" -doc foodoc.tex foo
+</PRE>
+Alternatively, you can use Perl-type regular expressions:
+<PRE>
+makedtx.pl -src "(.*)src\.sty=&gt;\1.sty" -doc foodoc.tex foo
+</PRE>
+(Note the use of double quotes to prevent shell expansion.)
+Appendix&nbsp;<A HREF="manual.html#sec:prex">A</A> gives a brief overview of Perl regular
+expressions for the uninitiated.
+
+<P>
+
+<H2><A NAME="SECTION00042000000000000000">
+Options</A>
+</H2>
+
+<P>
+<DL>
+<DT><STRONG><TT>-h</TT> or <TT>-help</TT></STRONG></DT>
+<DD>Prints on-line help, and exits.
+
+<P>
+</DD>
+<DT><STRONG><TT>-version</TT></STRONG></DT>
+<DD>Prints version number, and exits.
+
+<P>
+</DD>
+<DT><STRONG><TT>-v</TT></STRONG></DT>
+<DD>Uses verbose mode.
+
+<P>
+</DD>
+<DT><STRONG><TT>-dir</TT> <I>name</I></STRONG></DT>
+<DD>Specifies directory containing source
+files, as specified by the <TT>-src</TT> switch. For example, suppose
+you have source files <TT>foo.sty</TT>, <TT>bar.sty</TT> in the
+subdirectory <TT>sourcefiles</TT> you can do:
+<PRE>
+makedtx.pl -dir sourcefiles -src "(.*)\.sty=&gt;\1.sty" -doc foodoc.tex foo
+</PRE>
+
+<P>
+</DD>
+<DT><STRONG><TT>-op</TT> <I>character</I></STRONG></DT>
+<DD>sets the Perl pattern matching
+operator (the default is set to <TT>=</TT> symbol since the <TT>/</TT>
+character is used as the directory divider).
+
+<P>
+</DD>
+<DT><STRONG><TT>-askforoverwrite</TT></STRONG></DT>
+<DD>uses <TT>&#092;askforoverwritetrue</TT> in
+the installation script.
+
+<P>
+</DD>
+<DT><STRONG><TT>-noaskforoverwrite</TT></STRONG></DT>
+<DD>uses <TT>&#092;askforoverwritefalse</TT>
+in the installation script (default).
+
+<P>
+</DD>
+<DT><STRONG><TT>-noins</TT></STRONG></DT>
+<DD>Don't create the installation script
+(<TT>.ins</TT> file). This is useful if you want to tweak the file
+manually and you don't want your modifications overwritten.
+
+<P>
+</DD>
+<DT><STRONG><TT>-preamble</TT> <I>text</I></STRONG></DT>
+<DD>Set the preamble to
+<TT>text</TT>. The default preamble is:
+<P>
+<TT>Copyright (C) <I>date</I> <I>author</I>, all rights reserved.
+If you modify this file, you must change its name first.
+You are NOT ALLOWED to distribute this file alone. You are NOT
+ALLOWED to take money for the distribution or use of either this
+file or a changed version, except for a nominal charge for copying
+etc.
+</TT>
+
+<P>
+where <I>date</I> is the copyright date, and <I>author</I> is the
+author's name (see below).
+
+<P>
+</DD>
+<DT><STRONG><TT>-postamble</TT> <I>text</I></STRONG></DT>
+<DD>Set the postamble to
+<TT>text</TT>. If this is omitted the <TT>&#092;postamble</TT> command is
+omitted from the installation script.
+
+<P>
+</DD>
+<DT><STRONG><TT>-author</TT> <I>name</I></STRONG></DT>
+<DD>The author's name (as used in the
+default preamble). If omitted the user's name is used.
+
+<P>
+</DD>
+<DT><STRONG><TT>-date</TT> <I>text</I></STRONG></DT>
+<DD>The copyright date (as used in the
+default preamble). If omitted the current year is used.
+
+<P>
+</DD>
+<DT><STRONG><TT>-stopeventually</TT> <I>text</I></STRONG></DT>
+<DD>Insert <I>text</I> into the
+argument of <TT>&#092;StopEventually</TT>. For example:
+<code>-stopeventually "\\PrintIndex"</code> will result in the line:
+<TT>&#092;StopEventually</TT><code>{\PrintIndex}</code>. If <TT>makedtx.pl</TT>
+encounters a <TT>&#092;StopEventually</TT> command within the document,
+this will be used instead. If there is no <TT>&#092;StopEventually</TT>
+command in the document and the <TT>-stopeventually</TT> switch is
+absent <TT>&#092;StopEventually{}</TT> will be inserted in the DTX
+file.
+
+<P>
+</DD>
+<DT><STRONG><TT>-prefinale</TT> <I>text</I></STRONG></DT>
+<DD>Inset <I>text</I> immediately prior to <TT>&#092;Finale</TT>
+in the dtx file.
+
+<P>
+</DD>
+<DT><STRONG><TT>-setambles</TT> <TT>"</TT><I>expr</I><TT>=&#62;</TT><I>text</I><TT>"</TT></STRONG></DT>
+<DD>Sets the pre- and postambles for files matching <I>expr</I> within the
+<TT>&#092;file</TT> command in the installation script. To illustrate this,
+let's suppose you have source files <TT>foo.sty</TT>, <TT>bar.sty</TT>
+and <TT>foobar.pl</TT> in the subdirectory <TT>sourcefiles</TT>.
+Since <TT>foo.sty</TT> and <TT>bar.sty</TT> are L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X files, they
+should have pre- and postambles, but <TT>foobar.pl</TT> is a Perl
+file, and since the percent symbol (%) is not a comment character in
+Perl, there should be no pre- and postambles for this file. Therefore
+you would need to do something like:
+<PRE>
+makedtx.pl -dir sourcefiles -src "(.*)\.sty=&gt;\1.sty" -src "foobar.pl=&gt;foobar.pl"
+-setambles "foobar\.pl=&gt;\\nopreamble\\nopostamble" -doc foodoc.tex foo
+</PRE>
+(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.)
+
+<P>
+If the argument to <TT>-setambles</TT> contains the string
+<code>\\nopreamble</code>, the character table will be excluded from the
+corresponding files. So, in the above example, when you do:
+<code>latex foo.ins</code> the resulting files <TT>foo.sty</TT> and
+<TT>bar.sty</TT> will contain the character table, but
+<TT>foobar.pl</TT> won't. (If for some reason you don't want a
+preamble but you do want the character table included use
+<code>\\usepreamble\\empty</code> instead of <code>\\nopreamble</code>.
+Conversely, if you want a preamble but don't want the character table
+do something like <code>\\nopreamble\\usepreamble\\defaultpreamble</code>,
+although I can't think of a good reason for wanting either of these
+situations.)
+
+<P>
+Note that the <code>=&gt;</code><I>text</I> part is optional. If it is
+omitted, <I>text</I> is assumed to be empty.
+
+<P>
+</DD>
+<DT><STRONG><TT>-macrocode</TT> <TT>"</TT><I>expr</I><TT>"</TT></STRONG></DT>
+<DD>If source
+file matches the Perl regular expression given by <I>expr</I>, the
+source code is inserted into a <TT>macrocode</TT> environment in the
+DTX file.
+
+<P>
+</DD>
+<DT><STRONG><TT>-comment</TT> <TT>"</TT><I>expr</I><TT>"</TT></STRONG></DT>
+<DD>If the source file matches the Perl regular expression given by
+<I>expr</I>, the source code will be inserted between <TT>&#092;iffalse</TT>
+<TT>&#092;fi</TT> commands. The contents of this file will be included in the
+DTX file, but will be excluded from the documentation. Since this
+is provided mainly for non-TeX files (such as Perl scripts) the
+<TT>-comment</TT> switch will typically need to be used in conjunction
+with <TT>-macrocode</TT>.
+
+<P>
+</DD>
+<DT><STRONG><TT>-codetitle</TT> <TT>"</TT><I>title</I><TT>"</TT></STRONG></DT>
+<DD>This sets the title for the code section. The default is
+<TT>The Code</TT>.
+</DD>
+</DL>
+
+<P>
+
+<H1><A NAME="SECTION00050000000000000000"></A>
+<A NAME="sec:creatdtx"></A><BR>
+The creatdtx Package
+</H1>
+
+<P>
+The documentation source code, as specified using the <TT>-doc</TT>
+switch will typically be a standard L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X document using the
+<TT>ltxdoc</TT> class file. Unlike the DTX file, there is no
+<TT>&#092;DocInput</TT> 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 <TT>creatdtx</TT> package
+can be used in this document using
+<PRE>
+\usepackage{creatdtx}
+</PRE>
+although this package will be not be included in the DTX file by
+<TT>makedtx.pl</TT>. There is only one command defined in this
+package:<TT>&#092;ifmakedtx{</TT><EM>dtx text</EM><TT>}{</TT><EM>non dtx text</EM><TT>}</TT>. The first
+argument <I>dtx text</I> will be copied to the DTX file by
+<TT>makedtx.pl</TT>, but the second argument <I>non dtx text</I>
+won't. However, if you L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X the document, the first argument will
+be ignored, and the second argument will be used.
+
+<P>
+For example, if your code (in <TT>foodoc.tex</TT>) contains the
+line:
+<P>
+<BR>
+<BR><TT><TT>&#092;ifmakedtx</TT>{}{<TT>&#092;usepackage</TT>{html}}</TT>
+
+<P>
+<BR>
+<BR>the <TT>html</TT> package will only be
+loaded if you L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X <TT>foodoc.tex</TT>, but not when you L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X <TT>foo.dtx</TT>.
+
+<P>
+The Perl script <TT>creatdtx.perl</TT> ignores the following commands
+(and any associated arguments): <TT>&#092;OnlyDescription</TT>,
+<TT>&#092;RecordChanges</TT>, <TT>&#092;MakeShortVerb</TT>, <TT>&#092;DeleteShortVerb</TT>,
+<TT>&#092;DoNotIndex</TT>, <TT>&#092;EnableCrossrefs</TT>, <TT>&#092;CodelineIndex</TT>,
+<TT>&#092;GetFileInfo</TT>, <TT>&#092;PrintChanges</TT>, <TT>&#092;changes</TT>, <TT>&#092;CheckSum</TT>,
+<TT>&#092;DescribeMacro</TT> and <TT>&#092;DescribeEnvironment</TT>. So even if you don't
+use the <TT>&#092;ifmakedtx</TT> command, using the <TT>creatdtx</TT> package
+will help ensure that extraneous text does not appear in the HTML
+document when using .
+
+<P>
+As from version 0.93b, <TT>creatdtx.perl</TT> also defines the
+commands <TT>&#092;cs</TT>, <TT>&#092;marg</TT>, <TT>&#092;oarg</TT> and <TT>&#092;parg</TT>, since there
+is no implementation of the <TT>ltxdoc</TT> class file.
+
+<P>
+
+<H1><A NAME="SECTION00060000000000000000"></A>
+<A NAME="sec:examples"></A><BR>
+Examples
+</H1>
+
+<P>
+Let's first consider a very simple example. Suppose you want to
+create a package that redefines <TT>&#092;today</TT> so that the date is
+displayed in the form: yyyy-m-d. Let's call this package
+<TT>dashdate</TT>. The file <TT>dashdate.sty</TT> should look
+something like:
+<PRE>
+ % 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}
+</PRE>
+Now let's make some (very brief) documentation. Let's call the file,
+say <TT>manual.tex</TT><A NAME="tex2html3"
+ HREF="#foot450"><SUP>2</SUP></A>:
+<PRE>
+\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}
+</PRE>
+Suppose you have saved <TT>dashdate.sty</TT> and <TT>manual.tex</TT>
+in the subdirectory <TT>source</TT>. You can now create the
+<TT>.dtx</TT> and <TT>.ins</TT> file using the command:
+<PRE>
+makedtx.pl -author "AN Other" -dir source -src "dashdate\.sty=&gt;dashdate.sty"
+-doc source/manual.tex dashdate
+</PRE>
+The file <TT>dashdate.dtx</TT> is created, and contains the following
+code:
+<PRE>
+ %\iffalse
+ % dashdate.dtx generated using makedtx.pl version 0.9b (c) Nicola Talbot
+ % Command line args:
+ % -dir "source"
+ % -src "dashdate\.sty=&gt;dashdate.sty"
+ % -author "AN Other"
+ % -doc "source/manual.tex"
+ % dashdate
+ % Created on 2005/2/10 22:22
+ %\fi
+ %\iffalse
+ %&lt;*package&gt;
+ %% \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 \&amp;
+ %% Acute accent \' Left paren \( Right paren \)
+ %% Asterisk \* Plus \+ Comma \,
+ %% Minus \- Point \. Solidus \/
+ %% Colon \: Semicolon \; Less than \&lt;
+ %% Equals \= Greater than \&gt; Question mark \?
+ %% Commercial at \@ Left bracket \[ Backslash \\
+ %% Right bracket \] Circumflex \^ Underscore \_
+ %% Grave accent \` Left brace \{ Vertical bar \|
+ %% Right brace \} Tilde \~}
+ %&lt;/package&gt;
+ %\fi
+ % \iffalse
+ % Doc-Source file to use with LaTeX2e
+ % Copyright (C) 2005 AN Other, all rights reserved.
+ % \fi
+ % \iffalse
+ %&lt;*driver&gt;
+ \documentclass{ltxdoc}
+
+ \begin{document}
+ \DocInput{dashdate.dtx}
+ \end{document}
+ %&lt;/driver&gt;
+ %\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}
+ %&lt;*dashdate.sty&gt;
+ % \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}
+ %&lt;/dashdate.sty&gt;
+ % \end{macrocode}
+ %\fi
+ %\Finale
+ \endinput
+</PRE>
+The installation file <TT>dashdate.ins</TT> looks like:
+<PRE>
+ % dashdate.ins generated using makedtx.pl version 0.9b 2005/2/10 22:22
+ \input docstrip
+
+ \preamble
+ Copyright (C) 2005 AN Other, all rights reserved.
+ If you modify this file, you must change its name first.
+ You are NOT ALLOWED to distribute this file alone. You are NOT
+ ALLOWED to take money for the distribution or use of either this
+ file or a changed version, except for a nominal charge for copying
+ etc.
+ \endpreamble
+
+ \askforoverwritefalse
+
+ \generate{\file{dashdate.sty}{\usepreamble\defaultpreamble
+ \usepostamble\defaultpostamble\from{dashdate.dtx}{dashdate.sty,package}}
+ }
+
+ \endbatchfile
+</PRE>
+Note that the command <code>\usepackage{creatdtx}</code> has not been
+transcribed to <TT>dashdate.dtx</TT> (although in this simple example
+it's not really needed).
+
+<P>
+Now let's extend the example: suppose you want to create an analogous
+Perl script for use with . This will need to be called
+<TT>dashdate.perl</TT> and will look something like:
+<PRE>
+package main;
+
+sub do_cmd_today{
+ local($_) = @_;
+ local($today) = &amp;get_date();
+ $today =~ s|(\d+)/(\d+)/(\d+)|$3-$1-$2|;
+ "$today$_";
+}
+
+1;
+</PRE>
+You will now need to call <TT>makedtx.pl</TT> as follows:
+<PRE>
+makedtx.pl -author "AN Other" -dir source -src "dashdate\.sty=&gt;dashdate.sty"
+-src "dashdate\.perl=&gt;dashdate.perl"
+-setambles "dashdate\.perl=&gt;\\nopreamble\\nopostamble"
+-macrocode "dashdate\.perl" -doc source/manual.tex dashdate
+</PRE>
+(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:
+<PRE>
+makedtx.pl -author "AN Other" -dir source -src "dashdate\.(.*)=&gt;dashdate.\1"
+-setambles "dashdate\.perl=&gt;\\nopreamble\\nopostamble" -macrocode "dashdate\.perl"
+-doc source/manual.tex dashdate
+</PRE>
+Note the use of the <TT>-setambles</TT> 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 <TT>-macrocode</TT>
+switch. This is not needed for <TT>dashdate.sty</TT> since it has
+already been included in the source code, but since % is not a
+comment character in Perl, the <TT>macrocode</TT> environment is not
+included in the source code, and needs to be added. (If you are
+unfamiliar with DocStrip and the use of the <TT>macrocode</TT>
+environment, I suggest you read either <I>A guide to
+L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X</I>&nbsp;[<A
+ HREF="manual.html#Kopka98">2</A>, Appendix&nbsp;D] or <I>The L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X companion</I>&nbsp;[<A
+ HREF="manual.html#Goossens93">1</A>, Chapter&nbsp;14].)
+
+<P>
+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 <TT>-macrocode</TT> switch, you would then also need to use
+the <TT>-comment</TT> switch:
+<PRE>
+makedtx.pl -author "AN Other" -dir source -src "dashdate\.(.*)=&gt;dashdate.\1"
+-setambles "dashdate\.perl=&gt;\\nopreamble\\nopostamble" -macrocode "dashdate\.perl"
+-comment "dashdate\.perl" -doc source/manual.tex dashdate
+</PRE>
+
+<P>
+As another example, consider the <TT>datetime</TT> package. Version
+2.42 of this package has 2 <TT>.sty</TT> files and 42 <TT>.def</TT>
+files. The documentation is written in the file <TT>manual.tex</TT>,
+and the <TT>.sty</TT> and <TT>.def</TT> files are saved in a
+subdirectory called <TT>source</TT>. Since these are the only files
+in this directory, they can easily be merged into one <TT>.dtx</TT>
+file using:
+<PRE>
+makedtx.pl -author "Nicola Talbot" -dir source -src "(.+)\.(.+)=&gt;\1.\2"
+-doc manual.tex datetime
+</PRE>
+This creates the files <TT>datetime.dtx</TT> and <TT>datetime.ins</TT> which can then be distributed. The PDF version
+of the documentation is obtained by doing:
+<PRE>
+pdflatex datetime.dtx
+</PRE>
+and the HTML version (<TT>manual.html</TT>) is obtained by doing:
+<PRE>
+latex2html -split 0 -nonavigation -nofootnode -numbered_footnotes -noinfo manual
+</PRE>
+Any minor differences between the HTML and PDF versions are dealt by
+using <TT>&#092;ifmakedtx</TT> in the original file <TT>manual.tex</TT>.
+
+<P>
+
+<H1><A NAME="SECTION00070000000000000000"></A>
+<A NAME="sec:problems"></A><BR>
+Troubleshooting
+</H1>
+
+<P>
+The <TT>makedtx</TT> 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).
+
+<P>
+
+<H2><A NAME="SECTION00071000000000000000">
+Known Bugs</A>
+</H2>
+
+<P>
+It's possible to confuse <TT>makedtx.pl</TT> by placing either the
+command <TT>&#092;end{</TT><EM>document</EM><TT>}</TT> or the command <TT>&#092;ifmakedtx</TT> in a
+<TT>&#092;verb</TT> command, or by having the <TT>&#092;ifmakedtx</TT> command on the same
+line as <TT>&#092;begin{</TT><EM>document</EM><TT>}</TT>. 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 <code>%%</code> in the
+<TT>.dtx</TT> file, which has a special meaning. Either place a space
+immediately prior the percent symbol, or do <code>\relax%</code> if you
+really don't want the extra space (or place your comment in an
+<TT>&#092;iffalse</TT> ... <TT>&#092;fi</TT> conditional).
+
+<P>
+
+<H2><A NAME="SECTION00072000000000000000">
+Possible errors encountered using <TT>makedtx.pl</TT></A>
+</H2>
+
+<P>
+Note: be careful to use double quotes around arguments that contain
+characters that the shell might try interpreting, e.g. <code>*</code> or
+<code>&gt;</code>.
+
+<P>
+Syntax error messages:
+
+<OL>
+<LI><TT>No document source specified (missing -doc)</TT>
+
+<P>
+You must use the <TT>-doc</TT> switch.
+
+<P>
+</LI>
+<LI><TT>No source code specified (missing -src)</TT>
+
+<P>
+You must specify at least one <TT>-src</TT> switch.
+
+<P>
+</LI>
+<LI><TT>No basename specified</TT>
+
+<P>
+You must specify the basename of the <TT>.dtx</TT> and <TT>.ins</TT> files. This should
+be the last argument passed to <TT>makedtx.pl</TT>.
+
+<P>
+</LI>
+<LI><TT>-src ... argument invalid (no output file specified)</TT>
+
+<P>
+You have omitted the <code>=&gt;</code> separator in the argument of the
+<TT>-src</TT> switch.
+
+<P>
+</LI>
+<LI><TT>-src argument ... invalid (too many =&gt; specified)</TT>
+
+<P>
+You have used too many <code>=&gt;</code> separators in the argument of the
+<TT>-src</TT> switch. (Similarly for the <TT>-setambles</TT> switch.)
+</LI>
+</OL>
+
+<P>
+
+<P>
+
+<H1><A NAME="SECTION00080000000000000000"></A>
+<A NAME="sec:prex"></A><BR>
+Perl Regular Expressions
+</H1>
+
+<P>
+This section gives a very brief overview of Perl regular expressions. For more detail, look at the Perl
+documentation (use <code>man perlre</code> for the man page.)
+
+<P>
+<TABLE CELLPADDING=3>
+<TR><TD ALIGN="LEFT"><code>\</code></TD>
+<TD ALIGN="LEFT">Quote the next character</TD>
+</TR>
+<TR><TD ALIGN="LEFT"><code>.</code></TD>
+<TD ALIGN="LEFT">Match any character</TD>
+</TR>
+<TR><TD ALIGN="LEFT"><code>|</code></TD>
+<TD ALIGN="LEFT">Alternation</TD>
+</TR>
+<TR><TD ALIGN="LEFT"><code>()</code></TD>
+<TD ALIGN="LEFT">Grouping</TD>
+</TR>
+<TR><TD ALIGN="LEFT"><code>[]</code></TD>
+<TD ALIGN="LEFT">Character class</TD>
+</TR>
+<TR><TD ALIGN="LEFT"><code>*</code></TD>
+<TD ALIGN="LEFT">Match 0 or more times</TD>
+</TR>
+<TR><TD ALIGN="LEFT"><code>+</code></TD>
+<TD ALIGN="LEFT">Match 1 or more times</TD>
+</TR>
+<TR><TD ALIGN="LEFT"><code>?</code></TD>
+<TD ALIGN="LEFT">Match 1 or 0 times</TD>
+</TR>
+<TR><TD ALIGN="LEFT"><code>{n}</code></TD>
+<TD ALIGN="LEFT">Match exactly <TT>n</TT> times</TD>
+</TR>
+<TR><TD ALIGN="LEFT"><code>{n,}</code></TD>
+<TD ALIGN="LEFT">Match at least <TT>n</TT> times</TD>
+</TR>
+<TR><TD ALIGN="LEFT"><code>{n,m}</code></TD>
+<TD ALIGN="LEFT">Match at least <TT>n</TT> but no more than <TT>m</TT> times.</TD>
+</TR>
+</TABLE>
+
+<P>
+In the replacement text, a backslash followed by a number <I>n</I> indicates the text from the <I>n</I>th group.
+
+<P>
+For example, suppose you have the following files:
+<PRE>
+abcsrc.sty
+abcsrc.bst
+abcsrc.perl
+foosrc.sty
+foobarsrc.sty
+</PRE>
+then if you pass the following switch to <TT>makedtx.pl</TT>:
+
+<UL>
+<LI><code>-src "abcsrc\.([styb]+)=&gt;abc.\1"</code>
+will be equivalent to:
+<PRE>
+-src "abcsrc.sty=&gt;abc.sty" -src "abcsrc.bst=&gt;abc.bst"
+</PRE>
+since <code>[styb]+</code> will match one or more of the letters <TT>styb</TT> (so it will match <TT>sty</TT> and <TT>bst</TT>).
+<code>\1</code> indicates the text found in the first group, which in this example will either be <TT>sty</TT> or <TT>bst</TT>.
+
+<P>
+</LI>
+<LI><code>-src "abcsrc\.(.+)=&gt;abc.\1"</code>
+will be equivalent to:
+<PRE>
+-src "abcsrc.sty=&gt;abc.sty" -src "abcsrc.bst=&gt;abc.bst" -src "abcsrc.perl=&gt;abc.perl"
+</PRE>
+Note that a full stop represents any character so <TT>.+</TT> means any string of length 1 or more, whereas
+<code>\.</code> means an actual full stop character.
+
+<P>
+</LI>
+<LI><code>-src "foo(.*)src\.sty=&gt;foo\1.sty"</code>
+will be equivalent to:
+<PRE>
+-src "foosrc.sty=&gt;foo.sty" -src "foobarsrc.sty=&gt;foobar.sty"
+</PRE>
+
+<P>
+</LI>
+<LI><code>-src "(.+)src\.(.+)=&gt;\1.\2"</code>
+will be equivalent to
+<PRE>
+-src "abcsrc.sty=&gt;abc.sty"
+-src "abcsrc.bst=&gt;abc.bst"
+-src "abcsrc.perl=&gt;abc.perl"
+-src "foosrc.sty=&gt;foo.sty"
+-src "foobarsrc.sty=&gt;foobar.sty"
+</PRE>
+
+<P>
+</LI>
+</UL>
+
+<P>
+
+<P>
+
+
+<H2><A NAME="SECTION00090000000000000000">
+Bibliography</A>
+</H2><DL COMPACT><DD><P></P><DT><A NAME="Goossens93">1</A>
+<DD> The L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X companion. Michel&nbsp;Goossens, Frank&nbsp;Mittelbach and Alexander&nbsp;Samarin.
+Addison-Wesley 1993.
+
+<P>
+<P></P><DT><A NAME="Kopka98">2</A>
+<DD> A guide to L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X. Helmut&nbsp;Kopka and Patrick&nbsp;W.&nbsp;Daly. Addison-Wesley 1998.
+</DL>
+
+<BR><HR><H4>Footnotes</H4>
+<DL>
+<DT><A NAME="foot47">...
+script</A><A
+ HREF="manual.html#tex2html2"><SUP>1</SUP></A></DT>
+<DD>or at least, it's laborious if there are rather a lot
+of files associated with a package
+
+</DD>
+<DT><A NAME="foot450">...manual.tex</A><A
+ HREF="manual.html#tex2html3"><SUP>2</SUP></A></DT>
+<DD>Note: if you want to use
+ on this document, you will need to use, e.g.,
+<TT>&#092;verb!<TT>&#092;today</TT>!</TT> instead of
+<TT>&#124;<TT>&#092;today</TT>&#124;</TT> since it doesn't recognise
+<TT>&#092;MakeShortVerb</TT>.
+
+</DD>
+</DL><BR><HR>
+<ADDRESS>
+<A href=http://theoval.cmp.uea.ac.uk/~nlct/>Nicola L. C. Talbot</A>.
+<A HREF=http://www.cmp.uea.ac.uk/>School of Computing Sciences</A>.
+<A HREF=http://www.uea.ac.uk/>University of East Anglia.</A>
+Last Modified: 2007-08-02
+</ADDRESS>
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/latex/makedtx/makedtx.pdf b/Master/texmf-dist/doc/latex/makedtx/makedtx.pdf
index 565321b9a17..69afe1db94d 100644
--- a/Master/texmf-dist/doc/latex/makedtx/makedtx.pdf
+++ b/Master/texmf-dist/doc/latex/makedtx/makedtx.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/makedtx/makedtx.pl b/Master/texmf-dist/doc/latex/makedtx/makedtx.pl
index 7aba9c5454c..ea0825c6409 100644
--- a/Master/texmf-dist/doc/latex/makedtx/makedtx.pl
+++ b/Master/texmf-dist/doc/latex/makedtx/makedtx.pl
@@ -3,27 +3,31 @@
# File : makedtx
# Author : Dr Nicola Talbot
# Date : 29 Oct 2004
-# Last Modified : 11 Feb 2005
-# Version : 0.9b
+# Last Modified : 2 Aug 2007
+# Version : 0.93b
# usage : makedtx [options] -src <expr>=><expr> -doc <filename> <basename>
#
# -h : help message
# -src <expr>=><expr> : e.g. -src "(foo)src\.(bar)=>$1.$2" will add foosrc.bar to <basename>.dtx to be extracted to foo.bar
# -doc <filename> : file containing documentation.
+# -prefinale <string> : text to add to dtx file just before \Finale (added to version 0.91b)
# <basename> : create <basename>.dtx and <basename>.ins
use Getopt::Long;
-$version = "0.9b";
+$version = "0.93b";
# process command line options
%optctl = ();
-&GetOptions(\%optctl, "h", "help", "v", "src=s@", "doc=s", "dir=s", "op=s", "askforoverwrite!", "ins!",
- "preamble=s", "postamble=s", "setambles=s@", "macrocode=s@",
- "author=s", "date=s", "stopeventually=s") or syntaxerror();
+&GetOptions(\%optctl, "h", "help", "v", "src=s@", "doc=s",
+"dir=s", "op=s", "askforoverwrite!", "ins!",
+"preamble=s", "postamble=s", "setambles=s@", "macrocode=s@",
+"author=s", "date=s", "stopeventually=s",
+"prefinale=s", "codetitle=s", "comment=s@",
+"version") or &syntaxerror();
$srcdir = ".";
$patternop = "=";
@@ -32,8 +36,10 @@ $noins = 0;
$askforoverwrite = 0;
$preamble = "";
$postamble = "";
-$author = ($ENV{'USER'} || "Unknown");
+$author = (getpwuid($<))[6] || 'Unknown';
$stopeventually = "";
+$prefinale = "";
+$codetitle = "The Code";
($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst) = localtime(time);
@@ -43,7 +49,11 @@ foreach $setting (keys %optctl)
{
if (($setting eq "h") || ($setting eq "help"))
{
- help();
+ &help();
+ }
+ elsif ($setting eq "version")
+ {
+ die "makedtx version $version\n";
}
elsif ($setting eq "doc")
{
@@ -101,6 +111,18 @@ foreach $setting (keys %optctl)
{
$stopeventually = $optctl{$setting};
}
+ elsif ($setting eq "prefinale")
+ {
+ $prefinale = $optctl{$setting};
+ }
+ elsif ($setting eq "codetitle")
+ {
+ $codetitle = $optctl{$setting};
+ }
+ elsif ($setting eq "comment")
+ {
+ @comment = @{ $optctl{$setting} };
+ }
}
if ($preamble eq "")
@@ -116,19 +138,19 @@ if ($preamble eq "")
if ($docsrc eq "")
{
print "No document source specified (missing -doc)\n";
- syntaxerror();
+ &syntaxerror();
}
if ($#ARGV != 0)
{
print "No basename specified\n";
- syntaxerror();
+ &syntaxerror();
}
if ($#source == -1)
{
print "No source code specified (missing -src)\n";
- syntaxerror();
+ &syntaxerror();
}
$basename = $ARGV[0];
@@ -143,7 +165,7 @@ if ($verbose)
open DOC, $docsrc or die "Can't open '$docsrc'\n";
print DTX "\%\\iffalse\n";
-print DTX "\% $basename.dtx generated using $0 version $version (c) Nicola Talbot\n";
+print DTX "\% $basename.dtx generated using makedtx version $version (c) Nicola Talbot\n";
print DTX "\% Command line args:\n";
foreach $setting (keys %optctl)
@@ -171,11 +193,14 @@ foreach $setting (keys %optctl)
}
else
{
- print DTX "\% -", $setting, " \"", $optctl{$setting}, "\"\n";
+ $val = $optctl{$setting};
+ $val=~s/\\/\\\\/g;
+ print DTX "\% -", $setting, " \"", $val, "\"\n";
}
}
print DTX "\% $basename\n";
+
print DTX "\% Created on $year/", $mon+1, "/$mday $hour:", $min<10?"0$min" : $min,"\n";
print DTX "\%\\fi\n";
print DTX "\%\\iffalse\n";
@@ -223,7 +248,7 @@ while (<DOC>)
{
$beginline = $1;
- ($group,$restofline,$done) = getnextgroup($2);
+ ($group,$restofline,$done) = &getnextgroup($2);
$startline = $.;
@@ -235,7 +260,7 @@ while (<DOC>)
$restofline = $restofline . $nextline;
- ($group,$restofline,$done) = getnextgroup($restofline);
+ ($group,$restofline,$done) = &getnextgroup($restofline);
}
else
{
@@ -247,7 +272,7 @@ while (<DOC>)
$beginline = $beginline . $group;
- ($group,$restofline,$done) = getnextgroup($restofline);
+ ($group,$restofline,$done) = &getnextgroup($restofline);
while (!$done)
{
@@ -257,7 +282,7 @@ while (<DOC>)
$restofline = $restofline . $nextline;
- ($group,$restofline,$done) = getnextgroup($restofline);
+ ($group,$restofline,$done) = &getnextgroup($restofline);
}
else
{
@@ -316,7 +341,7 @@ while (<DOC>)
{
$beginline = $1;
- ($group,$restofline,$done) = getnextgroup($2);
+ ($group,$restofline,$done) = &getnextgroup($2);
$startline = $.;
@@ -328,7 +353,7 @@ while (<DOC>)
$restofline = $restofline . $nextline;
- ($group,$restofline,$done) = getnextgroup($restofline);
+ ($group,$restofline,$done) = &getnextgroup($restofline);
}
else
{
@@ -340,7 +365,7 @@ while (<DOC>)
$beginline = $beginline . $group;
- ($group,$restofline,$done) = getnextgroup($restofline);
+ ($group,$restofline,$done) = &getnextgroup($restofline);
while (!$done)
{
@@ -350,7 +375,7 @@ while (<DOC>)
$restofline = $restofline . $nextline;
- ($group,$restofline,$done) = getnextgroup($restofline);
+ ($group,$restofline,$done) = &getnextgroup($restofline);
}
else
{
@@ -384,7 +409,7 @@ if ($stopfound==0)
print DTX "\%\\StopEventually{$stopeventually}\n";
}
-print DTX "\%\\section{The Code}\n";
+print DTX "\%\\section{$codetitle}\n";
@srcdirfile = glob("$srcdir/*");
@@ -398,14 +423,14 @@ foreach $source (@source)
{
print "-src $source argument invalid (no output file specified)\n";
- syntaxerror();
+ &syntaxerror();
}
if (not ($remainder eq ""))
{
print "-src $source argument invalid (too many => specified)\n";
- syntaxerror();
+ &syntaxerror();
}
foreach $srcdirfile (@srcdirfile)
@@ -429,11 +454,24 @@ foreach $source (@source)
open SRC, $thisinfile or die "Can't open $thisinfile\n";
+ print DTX "\%\\iffalse\n";
print DTX "\% \\begin{macrocode}\n";
print DTX "\%<*$thisoutfile>\n";
print DTX "\% \\end{macrocode}\n";
+ print DTX "\%\\fi\n";
$macrocode = 0;
+ $comment = 0;
+
+ foreach $expr (@comment)
+ {
+ if ($thisoutfile =~ m/$expr/)
+ {
+ print DTX "\%\\iffalse\n";
+
+ $comment = 1;
+ }
+ }
foreach $expr (@macrocode)
{
@@ -455,9 +493,16 @@ foreach $source (@source)
print DTX "\% \\end{macrocode}\n";
}
+ if ($comment == 1)
+ {
+ print DTX "\%\\fi\n";
+ }
+
+ print DTX "\%\\iffalse\n";
print DTX "\% \\begin{macrocode}\n";
print DTX "\%</$thisoutfile>\n";
print DTX "\% \\end{macrocode}\n";
+ print DTX "\%\\fi\n";
close SRC;
@@ -466,6 +511,7 @@ foreach $source (@source)
}
}
+print DTX "\%$prefinale\n" if ($prefinale);
print DTX "\%\\Finale\n";
print DTX "\\endinput\n";
@@ -475,7 +521,7 @@ if (!$noins)
{
open INS, ">$basename.ins" or die "Can't open '$basename.ins'\n";
- print INS "\% $basename.ins generated using $0 version $version $year/",$mon+1,"/$mday $hour:", $min<10?"0$min":$min,"\n";
+ print INS "\% $basename.ins generated using makedtx version $version $year/",$mon+1,"/$mday $hour:", $min<10?"0$min":$min,"\n";
print INS "\\input docstrip\n\n";
print INS "\\preamble\n";
@@ -562,18 +608,18 @@ if (!$noins)
sub syntaxerror
{
- die "Syntax : $0 [options] <basename>\nUse -h for help\n";
+ die "Syntax : makedtx [options] <basename>\nUse -h for help\n";
}
sub help
{
- print "$0 Help\n\n";
+ print "makedtx Help\n\n";
print "Current Version : $version\n\n";
- print "usage : $0 [options] -src \"<expr>=><expr>\" -doc <filename> <basename>\n\n";
+ print "usage : makedtx [options] -src \"<expr>=><expr>\" -doc <filename> <basename>\n\n";
- print "$0 can be used to construct a LaTeX2e dtx and ins file from\n";
+ print "makedtx can be used to construct a LaTeX2e dtx and ins file from\n";
print "the specified source code. The final command line argument\n";
print "<basename> should be used to specify the basename of the dtx\n";
print "and ins files.\n\n";
@@ -596,15 +642,19 @@ sub help
print "-op <character> : set the pattern matching operator (default '$patternop')\n";
print "-askforoverwrite : set askforoverwrite switch in INS file to true\n";
print "-noaskforoverwrite : set askforoverwrite switch in INS file to false (default)\n";
- print "-preamble <text> : set the preamble. Standard one inserted if omitted\n";
- print "-postamble <text> : set the postamble.\n";
+ print "-preamble <text> : set the preamble. Standard one inserted if omitted\n";
+ print "-postamble <text> : set the postamble.\n";
print "-setambles \"<pattern>=><text>\" : set pre- and postambles to <text> if file matches pattern\n";
- print "-author <text> : name of author (inserted into standard preamble. User name inserted if omitted)\n";
- print "-date <text> : copyright date\n";
- print "-ins : create the ins file (default)\n";
- print "-noins : don't create the ins file\n";
- print "-h : help message\n";
- print "-v : verbose\n\n";
+ print "-author <text> : name of author (inserted into standard preamble. User name inserted if omitted)\n";
+ print "-date <text> : copyright date\n";
+ print "-ins : create the ins file (default)\n";
+ print "-noins : don't create the ins file\n";
+ print "-prefinale <text> : add <text> immediately prior to \\Finale\n";
+ print "-macrocode <expr> : surround any file which matches <expr> in a macrocode environment\n";
+ print "-comment <expr> : surround any file which matches <expr> with \\iffalse \\fi pair\n";
+ print "-codetitle <text> : The title for the documented code section (default: The Code)\n";
+ print "-h : help message\n";
+ print "-v : verbose\n\n";
print "Examples:\n\n";
@@ -614,7 +664,7 @@ sub help
print "called foo.sty. The dtx file should be called foo.dtx and the ins file\n";
print " should be called foo.ins\n\n";
- print "$0 -src \"foosrc\\.sty=>foo.sty\" -doc foodoc.tex foo\n\n";
+ print "makedtx -src \"foosrc\\.sty=>foo.sty\" -doc foodoc.tex foo\n\n";
print "Example 2:\n";
print "Documenation is in bardoc.tex\n";
@@ -623,11 +673,11 @@ sub help
print "version should be called bar.bst. The dtx file should be called bar.dtx and\n";
print "the ins file should be called bar.ins\n\n";
- print "$0 -src \"barsrc\\.sty=>bar.sty\" -src \"barsrc\\.bst=>bar.bst\" -doc bardoc.tex bar\n\n";
+ print "makedtx -src \"barsrc\\.sty=>bar.sty\" -src \"barsrc\\.bst=>bar.bst\" -doc bardoc.tex bar\n\n";
print "Or\n\n";
- print "$0 -src \"barsrc\\.(bst|sty)=>bar.\$1\" -doc bardoc.tex bar\n\n";
+ print "makedtx -src \"barsrc\\.(bst|sty)=>bar.\$1\" -doc bardoc.tex bar\n\n";
die;
}
@@ -648,7 +698,7 @@ sub getnextgroup
{
my($curline) = @_;
- $curline = eatinitialspaces($curline);
+ $curline = &eatinitialspaces($curline);
# check to see if current string is blank
diff --git a/Master/texmf-dist/doc/latex/makedtx/manual.html b/Master/texmf-dist/doc/latex/makedtx/manual.html
deleted file mode 100644
index 208bda39512..00000000000
--- a/Master/texmf-dist/doc/latex/makedtx/manual.html
+++ /dev/null
@@ -1,831 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-
-<!--Converted with LaTeX2HTML 2K.1beta (1.47)
-original version by: Nikos Drakos, CBLU, University of Leeds
-* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
-* with significant contributions from:
- Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
-<HTML>
-<HEAD>
-<TITLE>makedtx : a Perl script to help create a DTX file from source code</TITLE>
-<META NAME="description" CONTENT="makedtx : a Perl script to help create a DTX file from source code">
-<META NAME="keywords" CONTENT="manual">
-<META NAME="resource-type" CONTENT="document">
-<META NAME="distribution" CONTENT="global">
-
-<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
-<META NAME="Generator" CONTENT="LaTeX2HTML v2K.1beta">
-<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
-
-
-
-</HEAD>
-
-<BODY >
-<A NAME="tex2html1"
- HREF="http://theoval.cmp.uea.ac.uk/~nlct/">Dr Nicola Talbot</A>
-|
-<A NAME="tex2html2"
- HREF="http://www.cmp.uea.ac.uk/">School of Computing Sciences</A>
-|
-<A NAME="tex2html3"
- HREF="http://www.uea.ac.uk/">University of East Anglia</A>
-
-<P>
-
-<H1 ALIGN="CENTER">makedtx : a Perl script to help create a DTX file from source code</H1>
-<P ALIGN="CENTER"><STRONG>Nicola Talbot</STRONG></P>
-<P ALIGN="CENTER"><STRONG>11th February 2005</STRONG></P>
-
-<P>
-<BR>
-
-<H2><A NAME="SECTION00010000000000000000">
-Contents</A>
-</H2>
-<!--Table of Contents-->
-
-<UL>
-<LI><A NAME="tex2html21"
- HREF="#SECTION00020000000000000000">1 Introduction</A>
-<LI><A NAME="tex2html22"
- HREF="#SECTION00030000000000000000">2 Installation</A>
-<LI><A NAME="tex2html23"
- HREF="#SECTION00040000000000000000">3 makedtx.pl</A>
-<UL>
-<LI><A NAME="tex2html24"
- HREF="#SECTION00041000000000000000">3.1 Compulsory Arguments</A>
-<LI><A NAME="tex2html25"
- HREF="#SECTION00042000000000000000">3.2 Options</A>
-</UL><BR>
-<LI><A NAME="tex2html26"
- HREF="#SECTION00050000000000000000">4 The creatdtx Package</A>
-<LI><A NAME="tex2html27"
- HREF="#SECTION00060000000000000000">5 Examples</A>
-<LI><A NAME="tex2html28"
- HREF="#SECTION00070000000000000000">6 Troubleshooting</A>
-<UL>
-<LI><A NAME="tex2html29"
- HREF="#SECTION00071000000000000000">6.1 Known Bugs</A>
-<LI><A NAME="tex2html30"
- HREF="#SECTION00072000000000000000">6.2 Possible errors encountered using <TT>makedtx.pl</TT></A>
-</UL><BR>
-<LI><A NAME="tex2html31"
- HREF="#SECTION00080000000000000000">A. Perl Regular Expressions</A>
-<LI><A NAME="tex2html32"
- HREF="#SECTION00090000000000000000">Bibliography</A>
-<LI><A NAME="tex2html33"
- HREF="#SECTION000100000000000000000">Contact Details</A>
-</UL>
-<!--End of Table of Contents-->
-<P>
-
-<H3>Abstract:</H3>
-<DIV>
-The <TT>makedtx</TT> bundle is provided to help developers to write the code and
-documentation in separate files, and then combine them into a single DTX
-file for distribution. It automatically generates the character table, and also
-writes the associated installation (.ins) script.
-</DIV>
-<P>
-
-<P>
-
-<H1><A NAME="SECTION00020000000000000000">
-1 Introduction</A>
-</H1>
-
-<P>
-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 <TT>.sty</TT>, <TT>.cls</TT>, <TT>.def</TT> etc files.
-However, having the documentation and code bundled together can cause
-problems if a developer wants to, say, use <TT>ispell</TT> to spell check
-the documentation, or convert the documentation to a format other than DVI,
-PostScript or PDF (such as HTML).
-
-<P>
-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 <TT>datetime</TT> and <TT>glossary</TT>)
-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
-the PDF documents, I have taken to writing both PDF and HTML versions of my package documentation.
-However, LaTeX2HTML doesn't work on a <TT>.dtx</TT> 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 script<A NAME="tex2html4"
- HREF="#foot48"><SUP>1</SUP></A>.
-
-<P>
-This document is structured as follows: Section&nbsp;<A HREF="manual.html#sec:install">2</A> describes how to install the
-<TT>makedtx</TT> bundle, Section&nbsp;<A HREF="manual.html#sec:makedtx">3</A> gives an overview of the <TT>makedtx.pl</TT>
-Perl script, Section&nbsp;<A HREF="manual.html#sec:creatdtx">4</A> describes the <TT>creatdtx</TT> package, Section&nbsp;<A HREF="manual.html#sec:examples">5</A>
-illustrates the use of the <TT>makedtx</TT> bundle with examples and Section&nbsp;<A HREF="manual.html#sec:problems">6</A>
-gives a list of possible errors and their solutions.
-
-<P>
-
-<H1><A NAME="SECTION00030000000000000000"></A><A NAME="sec:install"></A><BR>
-2 Installation
-</H1>
-
-<P>
-You need to download both <TT>makedtx.dtx</TT> and <TT>makedtx.ins</TT>, and
-run the installation script through LaTeX:
-<P>
-<TT>latex makedtx.ins</TT>
-
-<P>
-The following files will be created:
-<DL>
-<DT><STRONG><TT>makedtx.pl</TT></STRONG></DT>
-<DD>Perl script
-</DD>
-<DT><STRONG><TT>creatdtx.sty</TT></STRONG></DT>
-<DD>LaTeX package for use with <TT>makedtx.pl</TT>
-</DD>
-<DT><STRONG><TT>creatdtx.perl</TT></STRONG></DT>
-<DD>Corresponding Perl script for use with LaTeX2HTML
-</DD>
-</DL>
-
-<P>
-If you are using UNIX/Linux etc you will need to make <TT>makedtx.pl</TT> executable using
-<TT>chmod</TT>:
-<P>
-
-<TT>chmod a+x makedtx.pl</TT>
-<P>
-
-and place it somewhere on your path. If <TT>perl</TT> is located somewhere other than <TT>/usr/bin/</TT>
-you will need to edit the first line of <TT>makedtx.pl</TT>. (If you don't know where <TT>perl</TT> is
-located, you can use the command: <TT>which perl</TT>.) The package <TT>creatdtx.sty</TT> needs to be placed somewhere
-on the LaTeX path and <TT>creatdtx.perl</TT> should be placed in a directory searched by LaTeX2HTML.
-(See the LaTeX2HTML documentation for details.)
-
-<P>
-
-<H1><A NAME="SECTION00040000000000000000"></A><A NAME="sec:makedtx"></A><BR>
-3 makedtx.pl
-</H1>
-
-<P>
-The Perl script <TT>makedtx.pl</TT> has the following syntax:
-<P>
-<TT>makedtx.pl [<I>options</I>] -src "<I>expr1</I>=&gt;<I>expr2</I>" -doc <I>filename</I> <I>basename</I></TT>
-
-<P>
-
-<H2><A NAME="SECTION00041000000000000000">
-3.1 Compulsory Arguments</A>
-</H2>
-
-<P>
-The very last argument <I>basename</I> is the basename of the <TT>.dtx</TT> and <TT>.ins</TT> files you want
-to create. The <TT>-doc</TT> <I>filename</I> switch indicates the file containing the documentation and
-<TT>-src</TT> <code>"</code><I>expr1</I><code>=&gt;</code><I>expr2</I><code>"</code> indicates the original source file(s),
-given by <I>expr1</I>, and the corresponding file name when it has been extracted from the <TT>.dtx</TT> file,
-given by <I>expr2</I>. This switch is a little complicated, so
-it's best described using examples.
-
-<P>
-Suppose you have your documentation in the file <TT>foodoc.tex</TT>, and the original source code is in the
-file <TT>foosrc.sty</TT>. You want to create the files <TT>foo.dtx</TT> and <TT>foo.ins</TT>. When you
-LaTeX <TT>foo.dtx</TT> you want the documentation as specified in <TT>foodoc.tex</TT> and when
-you LaTeX <TT>foo.ins</TT> you want the file <TT>foo.sty</TT> to be created, using the code specified
-in <TT>foosrc.sty</TT>. You will need to do:
-<PRE>
-makedtx.pl -src "foosrc\.sty=&gt;foo.sty" -doc foodoc.tex foo
-</PRE>
-
-<P>
-You may have multiple invocations of the <TT>-src</TT> switch. For example, suppose you also have the
-file <TT>barsrc.sty</TT> which you want to be extracted from the <TT>.dtx</TT> file as <TT>bar.sty</TT>,
-you can do:
-<PRE>
-makedtx.pl -src "foosrc\.sty=&gt;foo.sty" -src "barsrc\.sty=&gt;bar.sty" -doc foodoc.tex foo
-</PRE>
-Alternatively, you can use Perl-type regular expressions:
-<PRE>
-makedtx.pl -src "(.*)src\.sty=&gt;\1.sty" -doc foodoc.tex foo
-</PRE>
-(Note the use of double quotes to prevent shell expansion.) Appendix&nbsp;<A HREF="manual.html#sec:prex">A</A> gives a brief
-overview of Perl regular expressions for the uninitiated.
-
-<P>
-
-<H2><A NAME="SECTION00042000000000000000">
-3.2 Options</A>
-</H2>
-
-<P>
-<DL>
-<DT><STRONG><TT>-h</TT> or <TT>-help</TT></STRONG></DT>
-<DD>Prints on-line help, and exits.
-
-<P>
-</DD>
-<DT><STRONG><TT>-v</TT></STRONG></DT>
-<DD>Uses verbose mode.
-
-<P>
-</DD>
-<DT><STRONG><TT>-dir</TT> <I>name</I></STRONG></DT>
-<DD>Specifies directory containing source files, as specified by the <TT>-src</TT> switch.
-For example, suppose you have source files
-<TT>foo.sty</TT>, <TT>bar.sty</TT> in the subdirectory <TT>sourcefiles</TT>
-you can do:
-<PRE>
-makedtx.pl -dir sourcefiles -src "(.*)\.sty=&gt;\1.sty" -doc foodoc.tex foo
-</PRE>
-
-<P>
-</DD>
-<DT><STRONG><TT>-op</TT> <I>character</I></STRONG></DT>
-<DD>sets the Perl pattern matching operator (the default is set to <TT>=</TT> symbol since the
-<TT>/</TT> character is used as the directory divider).
-
-<P>
-</DD>
-<DT><STRONG><TT>-askforoverwrite</TT></STRONG></DT>
-<DD>uses <TT>&#92;askforoverwritetrue</TT> in the installation script.
-
-<P>
-</DD>
-<DT><STRONG><TT>-noaskforoverwrite</TT></STRONG></DT>
-<DD>uses <TT>&#92;askforoverwritefalse</TT> in the installation script (default).
-
-<P>
-</DD>
-<DT><STRONG><TT>-noins</TT></STRONG></DT>
-<DD>Don't create the installation script (<TT>.ins</TT> file). This is useful if you want to tweak the
-file manually and you don't want your modifications overwritten.
-
-<P>
-</DD>
-<DT><STRONG><TT>-preamble</TT> <I>text</I></STRONG></DT>
-<DD>Set the preamble to <TT>text</TT>. The default preamble is:
-<P>
-<TT>Copyright (C) <I>date</I> <I>author</I>, all rights reserved.
-If you modify this file, you must change its name first.
-You are NOT ALLOWED to distribute this file alone. You are NOT
-ALLOWED to take money for the distribution or use of either this
-file or a changed version, except for a nominal charge for copying
-etc.
-</TT>
-
-<P>
-where <I>date</I> is the copyright date, and <I>author</I> is the author's name (see below).
-
-<P>
-</DD>
-<DT><STRONG><TT>-postamble</TT> <I>text</I></STRONG></DT>
-<DD>Set the postamble to <TT>text</TT>. If this is omitted the <TT>&#92;postamble</TT>
-command is omitted from the installation script.
-
-<P>
-</DD>
-<DT><STRONG><TT>-author</TT> <I>name</I></STRONG></DT>
-<DD>The author's name (as used in the default preamble). If omitted the user's name is used.
-
-<P>
-</DD>
-<DT><STRONG><TT>-date</TT> <I>text</I></STRONG></DT>
-<DD>The copyright date (as used in the default preamble). If omitted the current
-year is used.
-
-<P>
-</DD>
-<DT><STRONG><TT>-stopeventually</TT> <I>text</I></STRONG></DT>
-<DD>Insert <I>text</I> into the argument of <TT>&#92;StopEventually</TT>.
-For example: <code>-stopeventually "\\PrintIndex"</code> will result in the
-line: <TT>&#92;StopEventually</TT><code>{\PrintIndex}</code>.
-If <TT>makedtx.pl</TT> encounters a <TT>&#92;StopEventually</TT> command within the document, this will be used instead.
-If there is no <TT>&#92;StopEventually</TT> command in the document and the <TT>-stopeventually</TT> switch is absent
-<TT>&#92;StopEventually</TT><code>{}</code> will be inserted in the DTX file.
-
-<P>
-</DD>
-<DT><STRONG><TT>-setambles</TT> <TT>"</TT><I>expr</I><TT>=&#62;</TT><I>text</I><TT>"</TT></STRONG></DT>
-<DD>Sets the pre- and postambles for files matching <I>expr</I> within
-the <TT>&#92;file</TT> command in the installation script. To illustrate this, let's suppose you have source files
-<TT>foo.sty</TT>, <TT>bar.sty</TT> and <TT>foobar.pl</TT> in the subdirectory <TT>sourcefiles</TT>. Since
-<TT>foo.sty</TT> and <TT>bar.sty</TT> are LaTeX files, they should have pre- and postambles, but <TT>foobar.pl</TT>
-is a Perl file, and since the percent symbol (%) is not a comment character in Perl, there should be no pre- and
-postambles for this file. Therefore you would need to do something like:
-<PRE>
-makedtx.pl -dir sourcefiles -src "(.*)\.sty=&gt;\1.sty" -src "foobar.pl=&gt;foobar.pl"
--setambles "foobar\.pl=&gt;\\nopreamble\\nopostamble" -doc foodoc.tex foo
-</PRE>
-(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.)
-
-<P>
-If the argument to <TT>-setambles</TT> contains the string <code>\\nopreamble</code>, the character table will be
-excluded from the corresponding files. So, in the above example, when you do: <code>latex foo.ins</code> the
-resulting files <TT>foo.sty</TT> and <TT>bar.sty</TT> will contain the character table, but <TT>foobar.pl</TT>
-won't. (If for some reason you don't want a preamble but you do want the character table included
-use <code>\\usepreamble\\empty</code> instead of <code>\\nopreamble</code>. Conversely, if you want a preamble but don't
-want the character table do something like <code>\\nopreamble\\usepreamble\\defaultpreamble</code>, although I can't think
-of a good reason for wanting either of these situations.)
-
-<P>
-Note that the <code>=&gt;</code><I>text</I> part is optional. If it is omitted, <I>text</I> is assumed to be empty.
-
-<P>
-</DD>
-<DT><STRONG><TT>-macrocode</TT> <TT>"</TT><I>expr</I><TT>"</TT></STRONG></DT>
-<DD>If source file matches the Perl regular expression given by <I>expr</I>,
-the source code is inserted into a <TT>macrocode</TT> environment in the DTX file.
-</DD>
-</DL>
-
-<P>
-
-<H1><A NAME="SECTION00050000000000000000"></A>
-<A NAME="sec:creatdtx"></A><BR>
-4 The creatdtx Package
-</H1>
-
-<P>
-The documentation source code, as specified using the <TT>-doc</TT> switch will typically be a standard
-LaTeX document using the <TT>ltxdoc</TT> class file. Unlike the DTX file, there is no <TT>&#92;DocInput</TT> command,
-and the lines do not begin with a percent symbol, which means that the document can be, say, passed to the
-LaTeX2HTML converter, or some other application that would otherwise be confused by a DTX file. The <TT>creatdtx</TT>
-package can be used in this document using
-<PRE>
-\usepackage{creatdtx}
-</PRE>
-although this package will be not be included in the DTX file by <TT>makedtx.pl</TT>.
-There is only one command defined in this package:
-<TT>&#92;ifmakedtx{<I>dtx text</I>}{<I>non dtx text</I>}</TT>.
-The first argument <I>dtx text</I> will be copied to the DTX file by <TT>makedtx.pl</TT>, but the second argument
-<I>non dtx text</I> won't.
-However, if you LaTeX the document, the first argument will be ignored, and the second argument will be used.
-
-<P>
-For example, if your code (in <TT>foodoc.tex</TT>) contains the line:
-<P>
-
-<TT><TT>&#92;ifmakedtx</TT>{}{<TT>&#92;usepackage</TT>{html}}</TT>
-
-<P>
-
-the <TT>html</TT> package will only be loaded if you LaTeX <TT>foodoc.tex</TT>, but not when you LaTeX
-<TT>foo.dtx</TT>.
-
-<P>
-The Perl script <TT>creatdtx.perl</TT> ignores the following commands (and any associated arguments):
-<TT>&#92;OnlyDescription</TT>, <TT>&#92;RecordChanges</TT>, <TT>&#92;MakeShortVerb</TT>, <TT>&#92;DeleteShortVerb</TT>, <TT>&#92;DoNotIndex</TT>,
-<TT>&#92;EnableCrossrefs</TT>, <TT>&#92;CodelineIndex</TT>, <TT>&#92;GetFileInfo</TT>,
-<TT>&#92;PrintChanges</TT>, <TT>&#92;changes</TT>, <TT>&#92;CheckSum</TT>, <TT>&#92;DescribeMacro</TT> and <TT>&#92;DescribeEnvironment</TT>.
-So even if you don't use the <TT>&#92;ifmakedtx</TT> command, using the <TT>creatdtx</TT> package will help ensure that
-extraneous text does not appear in the HTML document when using LaTeX2HTML.
-
-<P>
-
-<H1><A NAME="SECTION00060000000000000000"></A>
-<A NAME="sec:examples"></A><BR>
-5 Examples
-</H1>
-
-<P>
-Let's first consider a very simple example. Suppose you want to create a package that redefines <TT>&#92;today</TT>
-so that the date is displayed in the form: yyyy-m-d. Let's call this package <TT>dashdate</TT>. The file
-<TT>dashdate.sty</TT> should look something like:
-<PRE>
- % 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}
-</PRE>
-Now let's make some (very brief) documentation. Let's call the file, say <TT>manual.tex</TT><A NAME="tex2html5"
- HREF="#foot401"><SUP>2</SUP></A>:
-<PRE>
-\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}
-</PRE>
-Suppose you have saved <TT>dashdate.sty</TT> and <TT>manual.tex</TT> in the subdirectory <TT>source</TT>. You
-can now create the <TT>.dtx</TT> and <TT>.ins</TT> file using the command:
-<PRE>
-makedtx.pl -author "AN Other" -dir source -src "dashdate\.sty=&gt;dashdate.sty"
--doc source/manual.tex dashdate
-</PRE>
-The file <TT>dashdate.dtx</TT> is created, and contains the following code:
-<PRE>
- %\iffalse
- % dashdate.dtx generated using makedtx.pl version 0.9b (c) Nicola Talbot
- % Command line args:
- % -dir "source"
- % -src "dashdate\.sty=&gt;dashdate.sty"
- % -author "AN Other"
- % -doc "source/manual.tex"
- % dashdate
- % Created on 2005/2/10 22:22
- %\fi
- %\iffalse
- %&lt;*package&gt;
- %% \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 \~}
- %&lt;/package&gt;
- %\fi
- % \iffalse
- % Doc-Source file to use with LaTeX2e
- % Copyright (C) 2005 AN Other, all rights reserved.
- % \fi
- % \iffalse
- %&lt;*driver&gt;
- \documentclass{ltxdoc}
-
- \begin{document}
- \DocInput{dashdate.dtx}
- \end{document}
- %&lt;/driver&gt;
- %\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}
- % \begin{macrocode}
- %&lt;*dashdate.sty&gt;
- % \end{macrocode}
- % 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}
- % \begin{macrocode}
- %&lt;/dashdate.sty&gt;
- % \end{macrocode}
- %\Finale
- \endinput
-</PRE>
-The installation file <TT>dashdate.ins</TT> looks like:
-<PRE>
- % dashdate.ins generated using makedtx.pl version 0.9b 2005/2/10 22:22
- \input docstrip
-
- \preamble
- Copyright (C) 2005 AN Other, all rights reserved.
- If you modify this file, you must change its name first.
- You are NOT ALLOWED to distribute this file alone. You are NOT
- ALLOWED to take money for the distribution or use of either this
- file or a changed version, except for a nominal charge for copying
- etc.
- \endpreamble
-
- \askforoverwritefalse
-
- \generate{\file{dashdate.sty}{\usepreamble\defaultpreamble
- \usepostamble\defaultpostamble\from{dashdate.dtx}{dashdate.sty,package}}
- }
-
- \endbatchfile
-</PRE>
-Note that the command <code>\usepackage{creatdtx}</code> has not been transcribed to <TT>dashdate.dtx</TT>
-(although in this simple example it's not really needed).
-
-<P>
-Now let's extend the example:
-suppose you want to create an analogous Perl script for use with LaTeX2HTML.
-This will need to be called <TT>dashdate.perl</TT> and will look something like:
-<PRE>
-package main;
-
-sub do_cmd_today{
- local($today) = &amp;get_date();
- $today =~ s|(\d+)/(\d+)/(\d+)|$3-$1-$2|;
- $_ = $today;
-}
-
-1;
-</PRE>
-You will now need to call <TT>makedtx.pl</TT> as follows:
-<PRE>
-makedtx.pl -author "AN Other" -dir source -src "dashdate\.sty=&gt;dashdate.sty"
--src "dashdate\.perl=&gt;dashdate.perl"
--setambles "dashdate\.perl=&gt;\\nopreamble\\nopostamble"
--macrocode "dashdate\.perl" -doc source/manual.tex dashdate
-</PRE>
-(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:
-<PRE>
-makedtx.pl -author "AN Other" -dir source -src "dashdate\.(.*)=&gt;dashdate.\1"
--setambles "dashdate\.perl=&gt;\\nopreamble\\nopostamble" -macrocode "dashdate\.perl"
--doc source/manual.tex dashdate
-</PRE>
-Note the use of the <TT>-setambles</TT> 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 <TT>-macrocode</TT>
-switch. This is not needed for <TT>dashdate.sty</TT> since it has already been included in the source
-code, but since % is not a comment character in Perl, the <TT>macrocode</TT> environment
-is not included in the source code, and needs to be added.
-(If you are unfamiliar with DocStrip and the use of the <TT>macrocode</TT> environment,
-I suggest you read either <I>A guide to LaTeX</I>&nbsp;[<A
- HREF="manual.html#Kopka98">2</A>, Appendix&nbsp;D]
-or <I>The LaTeX companion</I>&nbsp;[<A
- HREF="manual.html#Goossens93">1</A>, Chapter&nbsp;14])
-
-<P>
-As another example, consider the <TT>datetime</TT> package. Version 2.42 of this package has 2 <TT>.sty</TT> files
-and 42 <TT>.def</TT> files. The documentation is written in the file <TT>manual.tex</TT>, and the <TT>.sty</TT>
-and <TT>.def</TT> files are saved in a subdirectory called <TT>source</TT>. Since these are the only files in this
-directory, they can easily be merged into one <TT>.dtx</TT> file using:
-<PRE>
-makedtx.pl -author "Nicola Talbot" -dir source -src "(.+)\.(.+)=&gt;\1.\2"
--doc manual.tex datetime
-</PRE>
-This creates the files <TT>datetime.dtx</TT> and <TT>datetime.ins</TT> which can then be distributed. The PDF version
-of the documentation is obtained by doing:
-<PRE>
-pdflatex datetime.dtx
-</PRE>
-and the HTML version (<TT>manual.html</TT>) is obtained by doing:
-<PRE>
-latex2html -split 0 -nonavigation -nofootnode -numbered_footnotes -noinfo manual
-</PRE>
-Any minor differences between the HTML and PDF versions are dealt by using <TT>&#92;ifmakedtx</TT> in
-the original file <TT>manual.tex</TT>.
-
-<P>
-
-<H1><A NAME="SECTION00070000000000000000"></A>
-<A NAME="sec:problems"></A><BR>
-6 Troubleshooting
-</H1>
-
-<P>
-The <TT>makedtx</TT> 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).
-
-<P>
-
-<H2><A NAME="SECTION00071000000000000000">
-6.1 Known Bugs</A>
-</H2>
-
-<P>
-It's possible to confuse <TT>makedtx.pl</TT> by placing either the command <TT>&#92;end</TT><code>{document}</code>
-or the command <TT>&#92;ifmakedtx</TT> in a <TT>&#92;verb</TT> command, or by having the <TT>&#92;ifmakedtx</TT> command
-on the same line as <TT>&#92;begin</TT><code>{document}</code>. 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 <code>%%</code>
-in the <TT>.dtx</TT> file, which has a special meaning. Either place a space immediately prior the percent symbol,
-or do <code>\relax%</code> if you really don't want the extra space (or place your comment in an <TT>&#92;iffalse</TT> ... <TT>&#92;fi</TT>
-conditional).
-
-<P>
-
-<H2><A NAME="SECTION00072000000000000000">
-6.2 Possible errors encountered using <TT>makedtx.pl</TT></A>
-</H2>
-
-<P>
-Note: be careful to use double quotes around arguments that contain characters that the shell might
-try interpreting, e.g. <code>*</code> or <code>&gt;</code>.
-
-<P>
-Syntax error messages:
-
-<OL>
-<LI><TT>No document source specified (missing -doc)</TT>
-
-<P>
-You must use the <TT>-doc</TT> switch.
-
-<P>
-</LI>
-<LI><TT>No source code specified (missing -src)</TT>
-
-<P>
-You must specify at least one <TT>-src</TT> switch.
-
-<P>
-</LI>
-<LI><TT>No basename specified</TT>
-
-<P>
-You must specify the basename of the <TT>.dtx</TT> and <TT>.ins</TT> files. This should
-be the last argument passed to <TT>makedtx.pl</TT>.
-
-<P>
-</LI>
-<LI><TT>-src ... argument invalid (no output file specified)</TT>
-
-<P>
-You have omitted the <code>=&gt;</code> separator in the argument of the <TT>-src</TT> switch.
-
-<P>
-</LI>
-<LI><TT>-src argument ... invalid (too many =&gt; specified)</TT>
-
-<P>
-You have used too many <code>=&gt;</code> separators in the argument of the <TT>-src</TT> switch.
-(Similarly for the <TT>-setambles</TT> switch.)
-</LI>
-</OL>
-
-<P>
-
-<P>
-
-<H1><A NAME="SECTION00080000000000000000"></A>
-<A NAME="sec:prex"></A><BR>
-A. Perl Regular Expressions
-</H1>
-
-<P>
-This section gives a very brief overview of Perl regular expressions. For more detail, look at the Perl
-documentation (use <code>man perlre</code> for the man page.)
-
-<P>
-<TABLE CELLPADDING=3>
-<TR><TD ALIGN="LEFT"><code>\</code></TD>
-<TD ALIGN="LEFT">Quote the next character</TD>
-</TR>
-<TR><TD ALIGN="LEFT"><code>.</code></TD>
-<TD ALIGN="LEFT">Match any character</TD>
-</TR>
-<TR><TD ALIGN="LEFT"><code>|</code></TD>
-<TD ALIGN="LEFT">Alternation</TD>
-</TR>
-<TR><TD ALIGN="LEFT"><code>()</code></TD>
-<TD ALIGN="LEFT">Grouping</TD>
-</TR>
-<TR><TD ALIGN="LEFT"><code>[]</code></TD>
-<TD ALIGN="LEFT">Character class</TD>
-</TR>
-<TR><TD ALIGN="LEFT"><code>*</code></TD>
-<TD ALIGN="LEFT">Match 0 or more times</TD>
-</TR>
-<TR><TD ALIGN="LEFT"><code>+</code></TD>
-<TD ALIGN="LEFT">Match 1 or more times</TD>
-</TR>
-<TR><TD ALIGN="LEFT"><code>?</code></TD>
-<TD ALIGN="LEFT">Match 1 or 0 times</TD>
-</TR>
-<TR><TD ALIGN="LEFT"><code>{n}</code></TD>
-<TD ALIGN="LEFT">Match exactly <TT>n</TT> times</TD>
-</TR>
-<TR><TD ALIGN="LEFT"><code>{n,}</code></TD>
-<TD ALIGN="LEFT">Match at least <TT>n</TT> times</TD>
-</TR>
-<TR><TD ALIGN="LEFT"><code>{n,m}</code></TD>
-<TD ALIGN="LEFT">Match at least <TT>n</TT> but no more than <TT>m</TT> times.</TD>
-</TR>
-</TABLE>
-
-<P>
-In the replacement text, a backslash followed by a number <I>n</I> indicates the text from the <I>n</I>th group.
-
-<P>
-For example, suppose you have the following files:
-<PRE>
-abcsrc.sty
-abcsrc.bst
-abcsrc.perl
-foosrc.sty
-foobarsrc.sty
-</PRE>
-then if you pass the following switch to <TT>makedtx.pl</TT>:
-
-<UL>
-<LI><code>-src "abcsrc\.([styb]+)=&gt;abc.\1"</code>
-will be equivalent to:
-<PRE>
--src "abcsrc.sty=&gt;abc.sty" -src "abcsrc.bst=&gt;abc.bst"
-</PRE>
-since <code>[styb]+</code> will match one or more of the letters <TT>styb</TT> (so it will match <TT>sty</TT> and <TT>bst</TT>).
-<code>\1</code> indicates the text found in the first group, which in this example will either be <TT>sty</TT> or <TT>bst</TT>.
-
-<P>
-</LI>
-<LI><code>-src "abcsrc\.(.+)=&gt;abc.\1"</code>
-will be equivalent to:
-<PRE>
--src "abcsrc.sty=&gt;abc.sty" -src "abcsrc.bst=&gt;abc.bst" -src "abcsrc.perl=&gt;abc.perl"
-</PRE>
-Note that a full stop represents any character so <TT>.+</TT> means any string of length 1 or more, whereas
-<code>\.</code> means an actual full stop character.
-
-<P>
-</LI>
-<LI><code>-src "foo(.*)src\.sty=&gt;foo\1.sty"</code>
-will be equivalent to:
-<PRE>
--src "foosrc.sty=&gt;foo.sty" -src "foobarsrc.sty=&gt;foobar.sty"
-</PRE>
-
-<P>
-</LI>
-<LI><code>-src "(.+)src\.(.+)=&gt;\1.\2"</code>
-will be equivalent to
-<PRE>
--src "abcsrc.sty=&gt;abc.sty"
--src "abcsrc.bst=&gt;abc.bst"
--src "abcsrc.perl=&gt;abc.perl"
--src "foosrc.sty=&gt;foo.sty"
--src "foobarsrc.sty=&gt;foobar.sty"
-</PRE>
-
-<P>
-</LI>
-</UL>
-
-<P>
-
-<H2><A NAME="SECTION00090000000000000000">
-Bibliography</A>
-</H2><DL COMPACT><DD><P></P><DT><A NAME="Goossens93">1</A>
-<DD> The LaTeX companion. Michel&nbsp;Goossens, Frank&nbsp;Mittelbach and Alexander&nbsp;Samarin.
-Addison-Wesley 1993.
-
-<P>
-<P></P><DT><A NAME="Kopka98">2</A>
-<DD> A guide to LaTeX. Helmut&nbsp;Kopka and Patrick&nbsp;W.&nbsp;Daly. Addison-Wesley 1998.
-</DL>
-
-<P>
-
-<H1><A NAME="SECTION000100000000000000000">
-Contact Details</A>
-</H1>
-
-<P>
-<TABLE CELLPADDING=3>
-<TR><TD ALIGN="LEFT">Dr Nicola Talbot</TD>
-</TR>
-<TR><TD ALIGN="LEFT">School of Computing Sciences</TD>
-</TR>
-<TR><TD ALIGN="LEFT">University of East Anglia</TD>
-</TR>
-<TR><TD ALIGN="LEFT">Norwich. NR4 7TJ</TD>
-</TR>
-<TR><TD ALIGN="LEFT">United Kingdom</TD>
-</TR>
-<TR><TD ALIGN="LEFT"><TT><A NAME="tex2html6"
- HREF="http://theoval.cmp.uea.ac.uk/~nlct/">http://theoval.cmp.uea.ac.uk/~nlct/</A></TT></TD>
-</TR>
-</TABLE>
-
-<P>
-<BR><HR><H4>Footnotes</H4>
-<DL>
-<DT><A NAME="foot48">... script</A><A NAME="foot48"
- HREF="manual.html#tex2html4"><SUP>1</SUP></A>
-<DD>or at least, it's laborious if there
-are rather a lot of files associated with a package
-
-<DT><A NAME="foot401">...manual.tex</A><A NAME="foot401"
- HREF="manual.html#tex2html5"><SUP>2</SUP></A>
-<DD>Note: if you
-want to use LaTeX2HTML on this document, you will need to use, e.g., <TT>&#92;verb!<TT>&#92;today</TT>!</TT> instead of
-<TT>&#124;<TT>&#92;today</TT>&#124;</TT> since it doesn't recognise <TT>&#92;MakeShortVerb</TT>.
-
-</DL><BR><HR>
-<ADDRESS>
-<h5>N.L.C. Talbot. School of Computing Sciences. University of East Anglia. Last Modified: 2005-02-13</h5>
-</ADDRESS>
-</BODY>
-</HTML>