diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex')
-rw-r--r-- | Master/texmf-dist/doc/latex/makedtx/README | 4 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/makedtx/creatdtx.perl | 48 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/makedtx/makedtx-manual.html | 930 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/makedtx/makedtx.pdf | bin | 218544 -> 198173 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/makedtx/makedtx.pl | 132 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/makedtx/manual.html | 831 |
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>\$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 <A HREF="manual.html#sec:install">2</A> +describes how to install the <TT>makedtx</TT> bundle, +Section <A HREF="manual.html#sec:makedtx">3</A> gives an overview of the <TT>makedtx.pl</TT> +Perl script, Section <A HREF="manual.html#sec:creatdtx">4</A> describes the +<TT>creatdtx</TT> package, Section <A HREF="manual.html#sec:examples">5</A> illustrates the +use of the <TT>makedtx</TT> bundle with examples and +Section <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>=></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>=></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=>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=>foo.sty" -src "barsrc\.sty=>bar.sty" -doc foodoc.tex foo +</PRE> +Alternatively, you can use Perl-type regular expressions: +<PRE> +makedtx.pl -src "(.*)src\.sty=>\1.sty" -doc foodoc.tex foo +</PRE> +(Note the use of double quotes to prevent shell expansion.) +Appendix <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=>\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>\askforoverwritetrue</TT> in +the installation script. + +<P> +</DD> +<DT><STRONG><TT>-noaskforoverwrite</TT></STRONG></DT> +<DD>uses <TT>\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>\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>\StopEventually</TT>. For example: +<code>-stopeventually "\\PrintIndex"</code> will result in the line: +<TT>\StopEventually</TT><code>{\PrintIndex}</code>. If <TT>makedtx.pl</TT> +encounters a <TT>\StopEventually</TT> command within the document, +this will be used instead. If there is no <TT>\StopEventually</TT> +command in the document and the <TT>-stopeventually</TT> switch is +absent <TT>\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>\Finale</TT> +in the dtx file. + +<P> +</DD> +<DT><STRONG><TT>-setambles</TT> <TT>"</TT><I>expr</I><TT>=></TT><I>text</I><TT>"</TT></STRONG></DT> +<DD>Sets the pre- and postambles for files matching <I>expr</I> within the +<TT>\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=>\1.sty" -src "foobar.pl=>foobar.pl" +-setambles "foobar\.pl=>\\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>=></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>\iffalse</TT> +<TT>\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>\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>\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>\ifmakedtx</TT>{}{<TT>\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>\OnlyDescription</TT>, +<TT>\RecordChanges</TT>, <TT>\MakeShortVerb</TT>, <TT>\DeleteShortVerb</TT>, +<TT>\DoNotIndex</TT>, <TT>\EnableCrossrefs</TT>, <TT>\CodelineIndex</TT>, +<TT>\GetFileInfo</TT>, <TT>\PrintChanges</TT>, <TT>\changes</TT>, <TT>\CheckSum</TT>, +<TT>\DescribeMacro</TT> and <TT>\DescribeEnvironment</TT>. So even if you don't +use the <TT>\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>\cs</TT>, <TT>\marg</TT>, <TT>\oarg</TT> and <TT>\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>\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=>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=>dashdate.sty" + % -author "AN Other" + % -doc "source/manual.tex" + % dashdate + % Created on 2005/2/10 22:22 + %\fi + %\iffalse + %<*package> + %% \CharacterTable + %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z + %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z + %% Digits \0\1\2\3\4\5\6\7\8\9 + %% Exclamation \! Double quote \" Hash (number) \# + %% Dollar \$ Percent \% Ampersand \& + %% Acute accent \' Left paren \( Right paren \) + %% Asterisk \* Plus \+ Comma \, + %% Minus \- Point \. Solidus \/ + %% Colon \: Semicolon \; Less than \< + %% Equals \= Greater than \> Question mark \? + %% Commercial at \@ Left bracket \[ Backslash \\ + %% Right bracket \] Circumflex \^ Underscore \_ + %% Grave accent \` Left brace \{ Vertical bar \| + %% Right brace \} Tilde \~} + %</package> + %\fi + % \iffalse + % Doc-Source file to use with LaTeX2e + % Copyright (C) 2005 AN Other, all rights reserved. + % \fi + % \iffalse + %<*driver> + \documentclass{ltxdoc} + + \begin{document} + \DocInput{dashdate.dtx} + \end{document} + %</driver> + %\fi + %\title{A Sample Package} + %\author{AN Other} + %\maketitle + % + %The \texttt{dashdate} package redefines "\today" + %to produce the current date in the form: yyyy-m-d. + %\end{document} + % + %\StopEventually{} + %\section{The Code} + %\iffalse + % \begin{macrocode} + %<*dashdate.sty> + % \end{macrocode} + %\fi + % First define package: + % \begin{macrocode} + \NeedsTeXFormat{LaTeX2e} + \ProvidesPackage{dashdate} + % \end{macrocode} + % Redefine |\today| command: + % \begin{macrocode} + \renewcommand{\today}{\the\year-\the\month-\the\day} + % \end{macrocode} + %\iffalse + % \begin{macrocode} + %</dashdate.sty> + % \end{macrocode} + %\fi + %\Finale + \endinput +</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) = &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=>dashdate.sty" +-src "dashdate\.perl=>dashdate.perl" +-setambles "dashdate\.perl=>\\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\.(.*)=>dashdate.\1" +-setambles "dashdate\.perl=>\\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> [<A + HREF="manual.html#Kopka98">2</A>, Appendix D] or <I>The L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X companion</I> [<A + HREF="manual.html#Goossens93">1</A>, Chapter 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\.(.*)=>dashdate.\1" +-setambles "dashdate\.perl=>\\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 "(.+)\.(.+)=>\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>\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>\end{</TT><EM>document</EM><TT>}</TT> or the command <TT>\ifmakedtx</TT> in a +<TT>\verb</TT> command, or by having the <TT>\ifmakedtx</TT> command on the same +line as <TT>\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>\iffalse</TT> ... <TT>\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>></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>=></code> separator in the argument of the +<TT>-src</TT> switch. + +<P> +</LI> +<LI><TT>-src argument ... invalid (too many => specified)</TT> + +<P> +You have used too many <code>=></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]+)=>abc.\1"</code> +will be equivalent to: +<PRE> +-src "abcsrc.sty=>abc.sty" -src "abcsrc.bst=>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\.(.+)=>abc.\1"</code> +will be equivalent to: +<PRE> +-src "abcsrc.sty=>abc.sty" -src "abcsrc.bst=>abc.bst" -src "abcsrc.perl=>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=>foo\1.sty"</code> +will be equivalent to: +<PRE> +-src "foosrc.sty=>foo.sty" -src "foobarsrc.sty=>foobar.sty" +</PRE> + +<P> +</LI> +<LI><code>-src "(.+)src\.(.+)=>\1.\2"</code> +will be equivalent to +<PRE> +-src "abcsrc.sty=>abc.sty" +-src "abcsrc.bst=>abc.bst" +-src "abcsrc.perl=>abc.perl" +-src "foosrc.sty=>foo.sty" +-src "foobarsrc.sty=>foobar.sty" +</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 Goossens, Frank Mittelbach and Alexander 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 Kopka and Patrick W. 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>\verb!<TT>\today</TT>!</TT> instead of +<TT>|<TT>\today</TT>|</TT> since it doesn't recognise +<TT>\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 Binary files differindex 565321b9a17..69afe1db94d 100644 --- a/Master/texmf-dist/doc/latex/makedtx/makedtx.pdf +++ 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 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 <A HREF="manual.html#sec:install">2</A> describes how to install the -<TT>makedtx</TT> bundle, Section <A HREF="manual.html#sec:makedtx">3</A> gives an overview of the <TT>makedtx.pl</TT> -Perl script, Section <A HREF="manual.html#sec:creatdtx">4</A> describes the <TT>creatdtx</TT> package, Section <A HREF="manual.html#sec:examples">5</A> -illustrates the use of the <TT>makedtx</TT> bundle with examples and Section <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>=><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>=></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=>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=>foo.sty" -src "barsrc\.sty=>bar.sty" -doc foodoc.tex foo -</PRE> -Alternatively, you can use Perl-type regular expressions: -<PRE> -makedtx.pl -src "(.*)src\.sty=>\1.sty" -doc foodoc.tex foo -</PRE> -(Note the use of double quotes to prevent shell expansion.) Appendix <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=>\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>\askforoverwritetrue</TT> in the installation script. - -<P> -</DD> -<DT><STRONG><TT>-noaskforoverwrite</TT></STRONG></DT> -<DD>uses <TT>\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>\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>\StopEventually</TT>. -For example: <code>-stopeventually "\\PrintIndex"</code> will result in the -line: <TT>\StopEventually</TT><code>{\PrintIndex}</code>. -If <TT>makedtx.pl</TT> encounters a <TT>\StopEventually</TT> command within the document, this will be used instead. -If there is no <TT>\StopEventually</TT> command in the document and the <TT>-stopeventually</TT> switch is absent -<TT>\StopEventually</TT><code>{}</code> will be inserted in the DTX file. - -<P> -</DD> -<DT><STRONG><TT>-setambles</TT> <TT>"</TT><I>expr</I><TT>=></TT><I>text</I><TT>"</TT></STRONG></DT> -<DD>Sets the pre- and postambles for files matching <I>expr</I> within -the <TT>\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=>\1.sty" -src "foobar.pl=>foobar.pl" --setambles "foobar\.pl=>\\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>=></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>\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>\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>\ifmakedtx</TT>{}{<TT>\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>\OnlyDescription</TT>, <TT>\RecordChanges</TT>, <TT>\MakeShortVerb</TT>, <TT>\DeleteShortVerb</TT>, <TT>\DoNotIndex</TT>, -<TT>\EnableCrossrefs</TT>, <TT>\CodelineIndex</TT>, <TT>\GetFileInfo</TT>, -<TT>\PrintChanges</TT>, <TT>\changes</TT>, <TT>\CheckSum</TT>, <TT>\DescribeMacro</TT> and <TT>\DescribeEnvironment</TT>. -So even if you don't use the <TT>\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>\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=>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=>dashdate.sty" - % -author "AN Other" - % -doc "source/manual.tex" - % dashdate - % Created on 2005/2/10 22:22 - %\fi - %\iffalse - %<*package> - %% \CharacterTable - %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z - %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z - %% Digits \0\1\2\3\4\5\6\7\8\9 - %% Exclamation \! Double quote \" Hash (number) \# - %% Dollar \$ Percent \% Ampersand \& - %% Acute accent \' Left paren \( Right paren \) - %% Asterisk \* Plus \+ Comma \, - %% Minus \- Point \. Solidus \/ - %% Colon \: Semicolon \; Less than \< - %% Equals \= Greater than \> Question mark \? - %% Commercial at \@ Left bracket \[ Backslash \\ - %% Right bracket \] Circumflex \^ Underscore \_ - %% Grave accent \` Left brace \{ Vertical bar \| - %% Right brace \} Tilde \~} - %</package> - %\fi - % \iffalse - % Doc-Source file to use with LaTeX2e - % Copyright (C) 2005 AN Other, all rights reserved. - % \fi - % \iffalse - %<*driver> - \documentclass{ltxdoc} - - \begin{document} - \DocInput{dashdate.dtx} - \end{document} - %</driver> - %\fi - %\title{A Sample Package} - %\author{AN Other} - %\maketitle - % - %The \texttt{dashdate} package redefines "\today" - %to produce the current date in the form: yyyy-m-d. - %\end{document} - % - %\StopEventually{} - %\section{The Code} - % \begin{macrocode} - %<*dashdate.sty> - % \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} - %</dashdate.sty> - % \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) = &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=>dashdate.sty" --src "dashdate\.perl=>dashdate.perl" --setambles "dashdate\.perl=>\\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\.(.*)=>dashdate.\1" --setambles "dashdate\.perl=>\\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> [<A - HREF="manual.html#Kopka98">2</A>, Appendix D] -or <I>The LaTeX companion</I> [<A - HREF="manual.html#Goossens93">1</A>, Chapter 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 "(.+)\.(.+)=>\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>\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>\end</TT><code>{document}</code> -or the command <TT>\ifmakedtx</TT> in a <TT>\verb</TT> command, or by having the <TT>\ifmakedtx</TT> command -on the same line as <TT>\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>\iffalse</TT> ... <TT>\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>></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>=></code> separator in the argument of the <TT>-src</TT> switch. - -<P> -</LI> -<LI><TT>-src argument ... invalid (too many => specified)</TT> - -<P> -You have used too many <code>=></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]+)=>abc.\1"</code> -will be equivalent to: -<PRE> --src "abcsrc.sty=>abc.sty" -src "abcsrc.bst=>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\.(.+)=>abc.\1"</code> -will be equivalent to: -<PRE> --src "abcsrc.sty=>abc.sty" -src "abcsrc.bst=>abc.bst" -src "abcsrc.perl=>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=>foo\1.sty"</code> -will be equivalent to: -<PRE> --src "foosrc.sty=>foo.sty" -src "foobarsrc.sty=>foobar.sty" -</PRE> - -<P> -</LI> -<LI><code>-src "(.+)src\.(.+)=>\1.\2"</code> -will be equivalent to -<PRE> --src "abcsrc.sty=>abc.sty" --src "abcsrc.bst=>abc.bst" --src "abcsrc.perl=>abc.perl" --src "foosrc.sty=>foo.sty" --src "foobarsrc.sty=>foobar.sty" -</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 Goossens, Frank Mittelbach and Alexander Samarin. -Addison-Wesley 1993. - -<P> -<P></P><DT><A NAME="Kopka98">2</A> -<DD> A guide to LaTeX. Helmut Kopka and Patrick W. 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>\verb!<TT>\today</TT>!</TT> instead of -<TT>|<TT>\today</TT>|</TT> since it doesn't recognise <TT>\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> |