doc/latex

git-svn-id: svn://tug.org/texlive/trunk@84 c570f23f-e606-0410-a88d-b1316a301751

5 files changed, 1712 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/makedtx/README b/Master/texmf-dist/doc/latex/makedtx/README
new file mode 100644
index 00000000000..3001cb26cec
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/makedtx/README
@@ -0,0 +1,32 @@
+makedtx v0.9b : a Perl script to help create .dtx and .ins files
+
+Last Modified : 13 Feb 2005
+
+Author        : Nicola Talbot
+
+Files         : makedtx.dtx - documented source file
+                makedtx.ins - installation script
+
+
+The makedtx bundle is provided to help LaTeX2e 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.
+
+To extract the code do:
+
+latex makedtx.ins
+
+To extract the documentation do:
+
+pdflatex makedtx.dtx
+pdflatex makedtx.dtx
+
+Read the documentation for installation instructions.
+
+This material is subject to the LaTeX Project Public License.
+See http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html for
+the details of that license.
+
+http://theoval.cmp.uea.ac.uk/~nlct/
+
diff --git a/Master/texmf-dist/doc/latex/makedtx/creatdtx.perl b/Master/texmf-dist/doc/latex/makedtx/creatdtx.perl
new file mode 100644
index 00000000000..add32266da4
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/makedtx/creatdtx.perl
@@ -0,0 +1,32 @@
+# creatdtx.perl LaTeX2HTML file corresponding to creatdtx.sty package
+# author : Nicola Talbot
+# date   : 8th Feb 2005
+
+package main;
+
+print " [creatdtx v0.9b (N.L.C. Talbot)]";
+
+sub do_cmd_meta
+{
+   &do_cmd_emph(@_);
+}
+
+&ignore_commands( <<_IGNORED_CMDS_);
+ifmakedtx # {}
+StopEventually # {}
+OnlyDescription
+RecordChanges
+PrintChanges
+EnableCrossRefs
+CodelineIndex
+GetFileInfo # {}
+CheckSum # {}
+DescribeMacro # {}
+DescribeEnvironment # {}
+MakeShortVerb # {}
+DeleteShortVerb # {}
+DoNotIndex # {}
+changes # {} # {} # {}
+_IGNORED_CMDS_
+
+1;
diff --git a/Master/texmf-dist/doc/latex/makedtx/makedtx.pdf b/Master/texmf-dist/doc/latex/makedtx/makedtx.pdf
new file mode 100644
index 00000000000..565321b9a17
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/makedtx/makedtx.pdf
diff --git a/Master/texmf-dist/doc/latex/makedtx/makedtx.pl b/Master/texmf-dist/doc/latex/makedtx/makedtx.pl
new file mode 100644
index 00000000000..7aba9c5454c
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/makedtx/makedtx.pl
@@ -0,0 +1,817 @@
+#!/usr/bin/perl
+
+# File          : makedtx
+# Author        : Dr Nicola Talbot
+# Date          : 29 Oct 2004
+# Last Modified : 11 Feb 2005
+# Version       : 0.9b
+
+# 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.
+# <basename> : create <basename>.dtx and <basename>.ins
+
+use Getopt::Long;
+
+$version = "0.9b";
+
+# 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();
+
+$srcdir          = ".";
+$patternop       = "=";
+$verbose         = 0;
+$noins           = 0;
+$askforoverwrite = 0;
+$preamble        = "";
+$postamble       = "";
+$author          = ($ENV{'USER'} || "Unknown");
+$stopeventually  = "";
+
+($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst) = localtime(time);
+
+$year = $year + 1900;
+
+foreach $setting (keys %optctl)
+{
+   if (($setting eq "h") || ($setting eq "help"))
+   {
+      help();
+   }
+   elsif ($setting eq "doc")
+   {
+      $docsrc   = $optctl{$setting};
+   }
+   elsif ($setting eq "src")
+   {
+      @source = @{ $optctl{$setting} };
+   }
+   elsif ($setting eq "dir")
+   {
+      $srcdir = $optctl{$setting};
+   }
+   elsif ($setting eq "op")
+   {
+      $patternop = $optctl{$setting};
+   }
+   elsif ($setting eq "v")
+   {
+      $verbose = 1;
+   }
+   elsif ($setting eq "ins")
+   {
+      $noins = 1-$optctl{$setting};
+   }
+   elsif ($setting eq "askforoverwrite")
+   {
+      $askforoverwrite = $optctl{$setting};
+   }
+   elsif ($setting eq "preamble")
+   {
+      $preamble = $optctl{$setting};
+   }
+   elsif ($setting eq "postamble")
+   {
+      $postamble = $optctl{$setting};
+   }
+   elsif ($setting eq "setambles")
+   {
+      @setambles = @{ $optctl{$setting} };
+   }
+   elsif ($setting eq "macrocode")
+   {
+      @macrocode = @{ $optctl{$setting} };
+   }
+   elsif ($setting eq "author")
+   {
+      $author = $optctl{$setting};
+   }
+   elsif ($setting eq "date")
+   {
+      $year = $optctl{$setting};
+   }
+   elsif ($setting eq "stopeventually")
+   {
+      $stopeventually = $optctl{$setting};
+   }
+}
+
+if ($preamble eq "")
+{
+   $preamble = "Copyright (C) $year $author, all rights reserved.\n";
+   $preamble = $preamble . "If you modify this file, you must change its name first.\n";
+   $preamble = $preamble . "You are NOT ALLOWED to distribute this file alone. You are NOT\n";
+   $preamble = $preamble . "ALLOWED to take money for the distribution or use of either this\n";
+   $preamble = $preamble . "file or a changed version, except for a nominal charge for copying\n";
+   $preamble = $preamble . "etc.";
+}
+
+if ($docsrc eq "")
+{
+   print "No document source specified (missing -doc)\n";
+   syntaxerror();
+}
+
+if ($#ARGV != 0)
+{
+   print "No basename specified\n";
+   syntaxerror();
+}
+
+if ($#source == -1)
+{
+   print "No source code specified (missing -src)\n";
+   syntaxerror();
+}
+
+$basename = $ARGV[0];
+
+open DTX, ">$basename.dtx" or die "Can't open '$basename.dtx'\n";
+
+if ($verbose)
+{
+   print "Documentation source : " . $docsrc . "\n";
+}
+
+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 "\% Command line args:\n";
+
+foreach $setting (keys %optctl)
+{
+   if ($setting eq "src")
+   {
+      foreach $source (@source)
+      {
+         print DTX "\%   -src \"$source\"\n";
+      }
+   }
+   elsif ($setting eq "setambles")
+   {
+      foreach $setamble (@setambles)
+      {
+         print DTX "\%   -setambles \"$setamble\"\n";
+      }
+   }
+   elsif ($setting eq "macrocode")
+   {
+      foreach $macrocode (@macrocode)
+      {
+         print DTX "\%   -macrocode \"$macrocode\"\n";
+      }
+   }
+   else
+   {
+      print DTX "\%   -", $setting, " \"",  $optctl{$setting}, "\"\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";
+print DTX "\%<*package>\n";
+print DTX "\%\% \\CharacterTable\n";
+print DTX "\%\%  {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\n";
+print DTX "\%\%   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\n";
+print DTX "\%\%   Digits        \\0\\1\\2\\3\\4\\5\\6\\7\\8\\9\n";
+print DTX "\%\%   Exclamation   \\!     Double quote  \\\"     Hash (number) \\#\n";
+print DTX "\%\%   Dollar        \\\$     Percent       \\\%     Ampersand     \\&\n";
+print DTX "\%\%   Acute accent  \\\'     Left paren    \\(     Right paren   \\)\n";
+print DTX "\%\%   Asterisk      \\*     Plus          \\+     Comma         \\,\n";
+print DTX "\%\%   Minus         \\-     Point         \\.     Solidus       \\/\n";
+print DTX "\%\%   Colon         \\:     Semicolon     \\;     Less than     \\<\n";
+print DTX "\%\%   Equals        \\=     Greater than  \\>     Question mark \\?\n";
+print DTX "\%\%   Commercial at \\\@     Left bracket  \\[     Backslash     \\\\\n";
+print DTX "\%\%   Right bracket \\]     Circumflex    \\^     Underscore    \\_\n";
+print DTX "\%\%   Grave accent  \\\`     Left brace    \\{     Vertical bar  \\|\n";
+print DTX "\%\%   Right brace   \\}     Tilde         \\~}\n";
+print DTX "\%</package>\n";
+print DTX "\%\\fi\n";
+
+print DTX "\% \\iffalse\n";
+print DTX "\% Doc-Source file to use with LaTeX2e\n";
+print DTX "\% Copyright (C) $year $author, all rights reserved.\n";
+print DTX "\% \\fi\n";
+
+# driver
+
+print DTX "\% \\iffalse\n";
+print DTX "\%<*driver>\n";
+
+$indoc=0;
+
+while (<DOC>)
+{
+   s/\\usepackage{creatdtx}//;
+
+   $restofline = $_;
+
+   $beginline = "";
+   $line = $restofline;
+
+   while ($restofline =~ /(.*)\\ifmakedtx(.*)/)
+   {
+      $beginline = $1;
+
+      ($group,$restofline,$done) = getnextgroup($2);
+
+      $startline = $.;
+
+      while (!$done)
+      {
+         if ($nextline = <DOC>)
+         {
+            $line = $line . $nextline;
+
+            $restofline = $restofline . $nextline;
+
+            ($group,$restofline,$done) = getnextgroup($restofline);
+         }
+         else
+         {
+            die "EOF found whilst scanning first argument to \\ifmakedtx on line $startline\n";
+         }
+      }
+
+      # print first arg, ignore second
+
+      $beginline = $beginline . $group;
+
+      ($group,$restofline,$done) = getnextgroup($restofline);
+
+      while (!$done)
+      {
+         if ($nextline = <DOC>)
+         {
+            $line = $line . $nextline;
+
+            $restofline = $restofline . $nextline;
+
+            ($group,$restofline,$done) = getnextgroup($restofline);
+         }
+         else
+         {
+            die "EOF found whilst scanning second argument to \\ifmakedtx on line $startline\n";
+         }
+      }
+
+      $line = $restofline;
+   }
+
+   $line = $beginline . $restofline;
+
+   print DTX $line;
+
+   if ($line=~/\\begin{document}/)
+   {
+      $indoc = 1;
+
+      last;
+   }
+}
+
+print DTX "\\DocInput{$basename.dtx}\n";
+print DTX "\\end{document}\n";
+print DTX "\%</driver>\n";
+print DTX "\%\\fi\n";
+
+$inverb=0;
+$stopfound=0;
+
+print DTX "\%";
+
+while (<DOC>)
+{
+   if (/\\begin{verbatim}/)
+   {
+      $inverb=1;
+   }
+
+   if (/\\end{verbatim}/)
+   {
+      $inverb=0;
+   }
+
+   if (/\\StopEventually/ && ($inverb==0))
+   {
+      $stopfound=1;
+   }
+
+   $restofline = $_;
+
+   $beginline = "";
+   $line = $restofline;
+
+   while ($restofline =~ /(.*)\\ifmakedtx(.*)/)
+   {
+      $beginline = $1;
+
+      ($group,$restofline,$done) = getnextgroup($2);
+
+      $startline = $.;
+
+      while (!$done)
+      {
+         if ($nextline = <DOC>)
+         {
+            $line = $line . $nextline;
+
+            $restofline = $restofline . $nextline;
+
+            ($group,$restofline,$done) = getnextgroup($restofline);
+         }
+         else
+         {
+            die "EOF found whilst scanning first argument to \\ifmakedtx on line $startline\n";
+         }
+      }
+
+      # print first arg, ignore second
+
+      $beginline = $beginline . $group;
+
+      ($group,$restofline,$done) = getnextgroup($restofline);
+
+      while (!$done)
+      {
+         if ($nextline = <DOC>)
+         {
+            $line = $line . $nextline;
+
+            $restofline = $restofline . $nextline;
+
+            ($group,$restofline,$done) = getnextgroup($restofline);
+         }
+         else
+         {
+            die "EOF found whilst scanning second argument to \\ifmakedtx on line $startline\n";
+         }
+      }
+
+      $line = $restofline;
+   }
+
+   $line = $beginline . $restofline;
+
+   if (($line=~/\\end{document}/) and not $inverb)
+   {
+      $indoc=0;
+
+      $line=~s/\\end{document}//;
+   }
+
+   $line=~s/\n/\n\%/mg;
+
+   print DTX "$line";
+}
+
+close DOC;
+
+print DTX "\n";
+
+if ($stopfound==0)
+{
+   print DTX "\%\\StopEventually{$stopeventually}\n";
+}
+
+print DTX "\%\\section{The Code}\n";
+
+@srcdirfile = glob("$srcdir/*");
+
+ %file = ();
+
+foreach $source (@source)
+{
+   ($infile, $outfile, $remainder) = split /=>/, $source;
+
+   if ($outfile eq "")
+   {
+      print "-src $source argument invalid (no output file specified)\n";
+
+      syntaxerror();
+   }
+
+   if (not ($remainder eq ""))
+   {
+      print "-src $source argument invalid (too many => specified)\n";
+
+      syntaxerror();
+   }
+
+   foreach $srcdirfile (@srcdirfile)
+   {
+      $fileexp = $srcdir . "/" . $infile;
+
+      $_ = $srcdirfile;
+
+      $expr = "s$patternop$fileexp$patternop$outfile$patternop";
+
+      if (eval($expr))
+      {
+         if ($verbose)
+         {
+            print "$srcdirfile -> $_ \n";
+         }
+
+         $thisoutfile = $_;
+
+         $thisinfile  = $srcdirfile;
+
+         open SRC, $thisinfile or die "Can't open $thisinfile\n";
+
+         print DTX "\%    \\begin{macrocode}\n";
+         print DTX "\%<*$thisoutfile>\n";
+         print DTX "\%    \\end{macrocode}\n";
+
+         $macrocode = 0;
+
+         foreach $expr (@macrocode)
+         {
+            if ($thisoutfile =~ m/$expr/)
+            {
+               print DTX "\%    \\begin{macrocode}\n";
+
+               $macrocode = 1;
+            }
+         }
+
+         while (<SRC>)
+         {
+            print DTX "$_";
+         }
+
+         if ($macrocode == 1)
+         {
+            print DTX "\%    \\end{macrocode}\n";
+         }
+
+         print DTX "\%    \\begin{macrocode}\n";
+         print DTX "\%</$thisoutfile>\n";
+         print DTX "\%    \\end{macrocode}\n";
+
+         close SRC;
+
+         $file{$thisinfile} = $thisoutfile;
+      }
+   }
+}
+
+print DTX "\%\\Finale\n";
+print DTX "\\endinput\n";
+
+close DTX;
+
+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 "\\input docstrip\n\n";
+   print INS "\\preamble\n";
+   print INS "$preamble\n";
+   print INS "\\endpreamble\n\n";
+
+   if ($postamble ne "")
+   {
+      print INS "\\postamble\n";
+      print INS "$postamble\n";
+      print INS "\\endpostamble\n\n";
+   }
+
+   if ($askforoverwrite)
+   {
+      print INS "\\askforoverwritetrue\n\n";
+   }
+   else
+   {
+      print INS "\\askforoverwritefalse\n\n";
+   }
+
+   print INS "\\generate{";
+
+   foreach $file (keys %file)
+   {
+      $outfile = $file{$file};
+
+      print INS "\\file{$outfile}{";
+
+      $ambleset = 0;
+      $noamble  = 0;
+
+      foreach $setamble (@setambles)
+      {
+         ($fileexp, $amble, $remainder) = split /=>/, $setamble;
+
+         if (not ($remainder eq ""))
+         {
+            die "-setambles $setamble argument invalid (too many => specified)\n";
+         }
+
+         if ($outfile =~ m/$fileexp/)
+         {
+            if ($verbose)
+            {
+               print "$fileexp matches $outfile -> setting \"$amble\"\n";
+            }
+
+            print INS $amble;
+
+            $ambleset = 1;
+
+            if ($amble =~ m/\\nopreamble/)
+            {
+               $noamble = 1;
+            }
+         }
+      }
+
+      if (!$ambleset)
+      {
+         print INS "\\usepreamble\\defaultpreamble\n\\usepostamble\\defaultpostamble";
+      }
+
+      print INS "\\from{$basename.dtx}{$outfile";
+
+      if ($noamble == 0)
+      {
+         # this will add the character table to all files except those that use \nopreamble
+
+         print INS ",package";
+      }
+
+      print INS "}}\n";
+   }
+
+   print INS "}\n\n";
+
+   print INS "\\endbatchfile\n";
+
+   close INS;
+}
+
+sub syntaxerror
+{
+   die "Syntax : $0 [options] <basename>\nUse -h for help\n";
+}
+
+sub help
+{
+   print "$0 Help\n\n";
+
+   print "Current Version : $version\n\n";
+
+   print "usage : $0 [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 "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";
+
+   print "-src \"<expr1>=><expr2>\"\n";
+   print "The command line switch -src identifies the original source code and the name\n";
+   print "of the file to which it will utimately be extracted on latexing the ins file\n";
+   print "<expr1> can be a Perl expression, such as (foo)src.(sty), and <expr2> can\n";
+   print "a Perl substitution style expression, such as $1.$2\n";
+   print "Note that double quotes must be used to prevent shell expansion\n";
+   print "Multiple invocations of -src are permitted\n";
+   print "See examples below.\n\n";
+
+   print "-doc <filename>\n";
+   print "The name of the documentation source code.  This should be a LaTeX2e document\n\n";
+
+   print "Optional Arguments:\n\n";
+
+   print "-dir <directory> : search for source files in <directory>\n";
+   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 "-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 "Examples:\n\n";
+
+   print "Example 1:\n";
+   print "Documenation is in foodoc.tex\n";
+   print "Source code is in foosrc.sty.  The final extracted version should be \n";
+   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 "Example 2:\n";
+   print "Documenation is in bardoc.tex\n";
+   print "Source code is in barsrc.sty.  The final extracted version should be\n";
+   print "called bar.sty.  Source code is also in barsrc.bst.  The final extracted\n";
+   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 "Or\n\n";
+
+   print "$0 -src \"barsrc\\.(bst|sty)=>bar.\$1\" -doc bardoc.tex bar\n\n";
+
+   die;
+}
+
+sub eatinitialspaces
+{
+   my ($STR) = @_;
+
+   while (substr($STR,0,1) eq "\s")
+   {
+      $STR = substr($STR,1);
+   }
+
+   return $STR;
+}
+
+sub getnextgroup
+{
+   my($curline) = @_;
+
+   $curline = eatinitialspaces($curline);
+
+   # check to see if current string is blank
+
+   if ($curline!~/[^\s]+/m)
+   {
+      return ("","",0);
+   }
+
+   if (($group = substr($curline,0,1)) ne "{")
+   {
+       # next group hasn't been delimited with braces
+       # return first non-whitespace character
+
+       $curline = substr($curline,1);
+
+       # unless it's a backslash, in which case get command name
+
+       if ($group eq "\\")
+       {
+          if ($curline=~/([a-zA-Z]+)(^[a-zA-Z].*)/m)
+          {
+             $group = $1;
+
+             $curline = $2;
+          }
+          else
+          {
+             # command is made up of backslash followed by symbol
+
+             $curline=~/([\W_0-9\s\\])(.*)/m;
+
+             $group = $1;
+
+             $curline = $2;
+          }
+       }
+
+       return ($group,$curline,1);
+   }
+
+   my $pos=index($curline, "{");
+   my $startpos=$pos;
+   my $posopen=0;
+   my $posclose=0;
+
+   my $bracelevel = 1;
+
+   my $done=0;
+
+   while (!$done)
+   {
+      $pos++;
+
+      $posopen = index($curline, "{", $pos);
+
+      # check to make sure it's not a \{
+
+      while ((substr($curline, $posopen-1,1) eq "\\") and ($posopen > 0))
+      {
+         # count how many backlashes come before it.
+
+         $i = $posopen-1;
+
+         $numbs = 1;
+
+         while ((substr($curline, $i-1,1) eq "\\") and ($i > 0))
+         {
+            $numbs++;
+            $i--;
+         }
+
+         # is $numbs is odd, we have a \{, otherwise we have \\{
+
+         if ($numbs%2 == 0)
+         {
+            last;
+         }
+         else
+         {
+            $posopen = index($curline, "{", $posopen+1);
+         }
+      }
+
+      $posclose= index($curline, "}", $pos);
+
+      # check to make sure it's not a \}
+
+      while ((substr($curline, $posclose-1,1) eq "\\") and ($posclose > 0))
+      {
+         # count how many backlashes come before it.
+
+         $i = $posclose-1;
+
+         $numbs = 1;
+
+         while ((substr($curline, $i-1,1) eq "\\") and ($i > 0))
+         {
+            $numbs++;
+            $i--;
+         }
+
+         # is $numbs is odd, we have a \}, otherwise we have \\}
+
+         if ($numbs%2 == 0)
+         {
+            last;
+         }
+         else
+         {
+            $posclose = index($curline, "}", $posclose+1);
+         }
+      }
+
+      if (($posopen==-1) and ($posclose==-1))
+      {
+         $done=1;
+      }
+      elsif ($posopen==-1)
+      {
+         $pos=$posclose;
+
+         $bracelevel--;
+
+         if ($bracelevel==0)
+         {
+            $group = substr($curline, $startpos+1, $pos-$startpos-1);
+
+            $curline = substr($curline, $pos+1);
+
+            return ($group,$curline,1);
+         }
+      }
+      elsif ($posclose==-1)
+      {
+         $pos=$posopen;
+
+         $bracelevel++;
+      }
+      elsif ($posopen<$posclose)
+      {
+         $pos=$posopen;
+
+         $bracelevel++;
+      }
+      elsif ($posclose<$posopen)
+      {
+         $pos=$posclose;
+
+         $bracelevel--;
+
+         if ($bracelevel==0)
+         {
+            $group = substr($curline, $startpos+1, $pos-$startpos-1);
+
+            $curline = substr($curline, $pos+1);
+
+            return ($group,$curline,1);
+         }
+      }
+   }
+
+   # closing brace must be on another line
+
+   return ("", $curline, 0);
+}
+1;
diff --git a/Master/texmf-dist/doc/latex/makedtx/manual.html b/Master/texmf-dist/doc/latex/makedtx/manual.html
new file mode 100644
index 00000000000..208bda39512
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/makedtx/manual.html
@@ -0,0 +1,831 @@
+<!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>