diff options
Diffstat (limited to 'Master/texmf-dist')
| -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 | ||||
| -rw-r--r-- | Master/texmf-dist/source/latex/makedtx/makedtx.dtx | 729 | ||||
| -rw-r--r-- | Master/texmf-dist/source/latex/makedtx/makedtx.ins | 6 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/makedtx/creatdtx.sty | 2 |
9 files changed, 1550 insertions, 1132 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> diff --git a/Master/texmf-dist/source/latex/makedtx/makedtx.dtx b/Master/texmf-dist/source/latex/makedtx/makedtx.dtx index 4aa7c7c4f26..3e6ec676341 100644 --- a/Master/texmf-dist/source/latex/makedtx/makedtx.dtx +++ b/Master/texmf-dist/source/latex/makedtx/makedtx.dtx @@ -1,16 +1,18 @@ %\iffalse -% makedtx.dtx generated using makedtx version 0.9b (c) Nicola Talbot +% makedtx.dtx generated using makedtx version 0.93b (c) Nicola Talbot % Command line args: -% -dir "source" -% -v "1" +% -macrocode ".*\.p.*l" % -src "creatdtx.(.*)=>creatdtx.\1" % -src "makedtx=>makedtx.pl" % -author "Nicola Talbot" -% -macrocode ".*\.p.*l" +% -v "1" +% -dir "source" % -setambles ".*\.p.*l=>\nopreamble\nopostamble" -% -doc "source/manual.tex" +% -comment "ARRAY(0x91ff234)" +% -doc "manual.tex" +% -codetitle "creatdtx.sty code" % makedtx -% Created on 2005/2/13 21:58 +% Created on 2007/8/2 15:16 %\fi %\iffalse %<*package> @@ -33,7 +35,7 @@ %\fi % \iffalse % Doc-Source file to use with LaTeX2e -% Copyright (C) 2005 Nicola Talbot, all rights reserved. +% Copyright (C) 2007 Nicola Talbot, all rights reserved. % \fi % \iffalse %<*driver> @@ -41,76 +43,97 @@ \usepackage[colorlinks, bookmarks, + hyperindex=false, bookmarksopen, pdfauthor={Nicola Talbot}, pdftitle={makedtx : a Perl script to help create a DTX file from source code}]{hyperref} -\OnlyDescription\newcommand{\switch}[1]{\textsf{-#1}} +\renewcommand{\usage}[1]{\textit{\hyperpage{#1}}} +\renewcommand{\main}[1]{\hyperpage{#1}} +\newcommand{\see}[2]{\emph{see} #1} +\makeatletter +\def\index@prologue{\section*{Index}} +\makeatother +\RecordChanges +\PageIndex +\CodelineNumbered \newcommand{\latextohtml}{\LaTeX2HTML} +\newcommand{\switch}[1]{\texttt{-#1}\index{makedtx switches=\texttt{makedtx} switches>#1=\texttt{-#1}}} +\newcommand{\ics}[1]{\cs{#1}\SpecialMainIndex{#1}} +\CheckSum{8} -\newcommand{\cmdname}[1]{\texttt{\symbol{92}#1}} \begin{document} \DocInput{makedtx.dtx} \end{document} %</driver> %\fi -% -% -%\title{makedtx : a Perl script to help create a DTX file from source code} -%\author{Nicola Talbot} -%\date{11th February 2005} +%\title{makedtx v0.93b : a Perl script to help create a DTX +%file from source code} +%\author{Nicola Talbot\\ +%\url{http://theoval.cmp.uea.ac.uk/~nlct/}} +%\date{2nd August 2007} %\maketitle % %\tableofcontents % %\begin{abstract} -%The \texttt{makedtx} 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. +%The \texttt{makedtx} 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. %\end{abstract} % %\section{Introduction} % %\changes{0.9}{2005/02/11}{Initial beta release}% -%Authors of \LaTeXe\ 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 \texttt{.sty}, \texttt{.cls}, \texttt{.def} etc files. -%However, having the documentation and code bundled together can cause -%problems if a developer wants to, say, use \texttt{ispell} to spell check -%the documentation, or convert the documentation to a format other than DVI, -%PostScript or PDF (such as HTML). -% -%Why should I want to convert my documentation to HTML when I can just use PDF\LaTeX? -%The more general purpose packages that I write (such as \texttt{datetime} and \texttt{glossary}) -%I upload to CTAN, however most of the packages I write are specific to the School -%of Computing Sciences at the University of East Anglia, so these I keep on my web site, -%and as some of the faculty either don't have a PDF plug in or prefer to view HTML rather -%the PDF documents, I have taken to writing both PDF and HTML versions of my package documentation. -%However, \latextohtml\ doesn't work on a \texttt{.dtx} file so I used to convert them manually -%which is fine for one or two small documents, but becomes rather cumbersome as soon as I have large -%documents or a lot of packages. Therefore I decided to write the documentation separately, and -%use a Perl script to bundle everything together. It also has the added convenience in that I don't -%have to keep copying and pasting the character table every time I write a new package, and it saves -%the laborious task of writing the installation script\footnote{or at least, it's laborious if there -%are rather a lot of files associated with a package}. -% -%This document is structured as follows: Section~\ref{sec:install} describes how to install the -%\texttt{makedtx} bundle, Section~\ref{sec:makedtx} gives an overview of the \texttt{makedtx.pl} -%Perl script, Section~\ref{sec:creatdtx} describes the \texttt{creatdtx} package, Section~\ref{sec:examples} -%illustrates the use of the \texttt{makedtx} bundle with examples and Section~\ref{sec:problems} -%gives a list of possible errors and their solutions. +%Authors of \LaTeXe\ 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 \texttt{.sty}, \texttt{.cls}, \texttt{.def} +%etc files. However, having the documentation and code bundled +%together can cause problems if a developer wants to, say, use +%\texttt{ispell} to spell check the documentation, or convert the +%documentation to a format other than DVI, PostScript or PDF (such as +%HTML). +% +%Why should I want to convert my documentation to HTML when I can just +%use PDF\LaTeX? The more general purpose packages that I write (such +%as \texttt{datetime} and \texttt{glossary}) I upload to CTAN, however +%most of the packages I write are specific to the School of Computing +%Sciences at the University of East Anglia, so these I keep on my web +%site, and as some of the faculty either don't have a PDF plug in or +%prefer to view HTML rather than PDF documents, I have taken to writing +%both PDF and HTML versions of my package documentation. However, +%\latextohtml\ doesn't work on a \texttt{.dtx} file so I used to +%convert them manually which is fine for one or two small documents, +%but becomes rather cumbersome as soon as I have large documents or a +%lot of packages. Therefore I decided to write the documentation +%separately, and use a Perl script to bundle everything together. It +%also has the added convenience in that I don't have to keep copying +%and pasting the character table every time I write a new package, and +%it saves the laborious task of writing the installation +%script\footnote{or at least, it's laborious if there are rather a lot +%of files associated with a package}. +% +%This document is structured as follows: Section~\ref{sec:install} +%describes how to install the \texttt{makedtx} bundle, +%Section~\ref{sec:makedtx} gives an overview of the \texttt{makedtx.pl} +%Perl script, Section~\ref{sec:creatdtx} describes the +%\texttt{creatdtx} package, Section~\ref{sec:examples} illustrates the +%use of the \texttt{makedtx} bundle with examples and +%Section~\ref{sec:problems} gives a list of possible errors and their +%solutions. % %\section{Installation}\label{sec:install} % -%You need to download both \texttt{makedtx.dtx} and \texttt{makedtx.ins}, and -%run the installation script through \LaTeX:\par -%\texttt{latex makedtx.ins} +%You need to download both \texttt{makedtx.dtx} and +%\texttt{makedtx.ins}, and run the installation script through +%\LaTeX:\par \texttt{latex makedtx.ins} % %The following files will be created: %\begin{description} @@ -119,38 +142,51 @@ %\item[\texttt{creatdtx.perl}] Corresponding Perl script for use with LaTeX2HTML %\end{description} % -%If you are using UNIX/Linux etc you will need to make \texttt{makedtx.pl} executable using -%\texttt{chmod}:\par\vspace{6pt}\noindent\texttt{chmod a+x makedtx.pl}\par\vspace{6pt}\noindent and place it somewhere on your path. If \texttt{perl} is located somewhere other than \texttt{/usr/bin/} -%you will need to edit the first line of \texttt{makedtx.pl}. (If you don't know where \texttt{perl} is -%located, you can use the command: \texttt{which perl}.) The package \texttt{creatdtx.sty} needs to be placed somewhere -%on the \LaTeX\ path and \texttt{creatdtx.perl} should be placed in a directory searched by \latextohtml. -%(See the \latextohtml\ documentation for details.) +%If you are using UNIX/Linux etc you will need to make +%\texttt{makedtx.pl} executable using +%\texttt{chmod}:\par\vspace{6pt}\noindent\texttt{chmod a+x +%makedtx.pl}\par\vspace{6pt}\noindent and place it somewhere on your +%path. If \texttt{perl} is located somewhere other than +%\texttt{/usr/bin/} you will need to edit the first line of +%\texttt{makedtx.pl}. (If you don't know where \texttt{perl} is +%located, you can use the command: \texttt{which perl}.) The package +%\texttt{creatdtx.sty} needs to be placed somewhere on the \LaTeX\ path +%and \texttt{creatdtx.perl} should be placed in a directory searched by +%\latextohtml. (See the \latextohtml\ documentation for details.) % %\section{makedtx.pl}\label{sec:makedtx} % %The Perl script \texttt{makedtx.pl} has the following syntax:\par -%\texttt{makedtx.pl [\meta{options}] -src "\meta{expr1}=>\meta{expr2}" -doc \meta{filename} \meta{basename}} +%\texttt{makedtx.pl} \oarg{options} \switch{src} +%\texttt{"}\meta{expr1}\verb|=>|\meta{expr2}\texttt{"} +%\switch{doc} \meta{filename} \meta{basename} % %\subsection{Compulsory Arguments} % -%The very last argument \meta{basename} is the basename of the \texttt{.dtx} and \texttt{.ins} files you want -%to create. The \switch{doc} \meta{filename} switch indicates the file containing the documentation and -%\switch{src} \verb!"!\meta{expr1}\verb+=>+\meta{expr2}\verb'"' indicates the original source file(s), -%given by \meta{expr1}, and the corresponding file name when it has been extracted from the \texttt{.dtx} file, -%given by \meta{expr2}. This switch is a little complicated, so -%it's best described using examples. -% -%Suppose you have your documentation in the file \texttt{foodoc.tex}, and the original source code is in the -%file \texttt{foosrc.sty}. You want to create the files \texttt{foo.dtx} and \texttt{foo.ins}. When you -%\LaTeX\ \texttt{foo.dtx} you want the documentation as specified in \texttt{foodoc.tex} and when -%you \LaTeX\ \texttt{foo.ins} you want the file \texttt{foo.sty} to be created, using the code specified -%in \texttt{foosrc.sty}. You will need to do: +%The very last argument \meta{basename} is the basename of the +%\texttt{.dtx} and \texttt{.ins} files you want to create. The +%\switch{doc} \meta{filename} switch indicates the file containing the +%documentation and \switch{src} +%\verb!"!\meta{expr1}\verb+=>+\meta{expr2}\verb'"' indicates the +%original source file(s), given by \meta{expr1}, and the corresponding +%file name when it has been extracted from the \texttt{.dtx} file, +%given by \meta{expr2}. This switch is a little complicated, so it's +%best described using examples. +% +%Suppose you have your documentation in the file \texttt{foodoc.tex}, +%and the original source code is in the file \texttt{foosrc.sty}. You +%want to create the files \texttt{foo.dtx} and \texttt{foo.ins}. When +%you \LaTeX\ \texttt{foo.dtx} you want the documentation as specified +%in \texttt{foodoc.tex} and when you \LaTeX\ \texttt{foo.ins} you want +%the file \texttt{foo.sty} to be created, using the code specified in +%\texttt{foosrc.sty}. You will need to do: %\begin{verbatim} %makedtx.pl -src "foosrc\.sty=>foo.sty" -doc foodoc.tex foo %\end{verbatim} % -%You may have multiple invocations of the \switch{src} switch. For example, suppose you also have the -%file \texttt{barsrc.sty} which you want to be extracted from the \texttt{.dtx} file as \texttt{bar.sty}, +%You may have multiple invocations of the \switch{src} switch. For +%example, suppose you also have the file \texttt{barsrc.sty} which you +%want to be extracted from the \texttt{.dtx} file as \texttt{bar.sty}, %you can do: %\begin{verbatim} %makedtx.pl -src "foosrc\.sty=>foo.sty" -src "barsrc\.sty=>bar.sty" -doc foodoc.tex foo @@ -159,35 +195,44 @@ %\begin{verbatim} %makedtx.pl -src "(.*)src\.sty=>\1.sty" -doc foodoc.tex foo %\end{verbatim} -%(Note the use of double quotes to prevent shell expansion.) Appendix~\ref{sec:prex} gives a brief -%overview of Perl regular expressions for the uninitiated. +%(Note the use of double quotes to prevent shell expansion.) +%Appendix~\ref{sec:prex} gives a brief overview of Perl regular +%expressions for the uninitiated. % %\subsection{Options} % %\begin{description} %\item[\switch{h} or \switch{help}] Prints on-line help, and exits. % +%\item[\switch{version}] Prints version number, and exits. +%\changes{0.93}{2007/08/02}{version switch added}% +% %\item[\switch{v}] Uses verbose mode. % -%\item[\switch{dir} \meta{name}] Specifies directory containing source files, as specified by the \switch{src} switch. -%For example, suppose you have source files -%\texttt{foo.sty}, \texttt{bar.sty} in the subdirectory \texttt{sourcefiles} -%you can do: +%\item[\switch{dir} \meta{name}] Specifies directory containing source +%files, as specified by the \switch{src} switch. For example, suppose +%you have source files \texttt{foo.sty}, \texttt{bar.sty} in the +%subdirectory \texttt{sourcefiles} you can do: %\begin{verbatim} %makedtx.pl -dir sourcefiles -src "(.*)\.sty=>\1.sty" -doc foodoc.tex foo %\end{verbatim} % -%\item[\switch{op} \meta{character}] sets the Perl pattern matching operator (the default is set to \texttt{=} symbol since the -%\texttt{/} character is used as the directory divider). +%\item[\switch{op} \meta{character}] sets the Perl pattern matching +%operator (the default is set to \texttt{=} symbol since the \texttt{/} +%character is used as the directory divider). % -%\item[\switch{askforoverwrite}] uses \cmdname{askforoverwritetrue} in the installation script. +%\item[\switch{askforoverwrite}] uses \ics{askforoverwritetrue} in +%the installation script. % -%\item[\switch{noaskforoverwrite}] uses \cmdname{askforoverwritefalse} in the installation script (default). +%\item[\switch{noaskforoverwrite}] uses \ics{askforoverwritefalse} +%in the installation script (default). % -%\item[\switch{noins}] Don't create the installation script (\texttt{.ins} file). This is useful if you want to tweak the -%file manually and you don't want your modifications overwritten. +%\item[\switch{noins}] Don't create the installation script +%(\texttt{.ins} file). This is useful if you want to tweak the file +%manually and you don't want your modifications overwritten. % -%\item[\switch{preamble} \meta{text}] Set the preamble to \texttt{text}. The default preamble is:\par +%\item[\switch{preamble} \meta{text}] Set the preamble to +%\texttt{text}. The default preamble is:\par %\begin{ttfamily} %Copyright (C) \meta{date} \meta{author}, all rights reserved. %If you modify this file, you must change its name first. @@ -197,86 +242,138 @@ %etc. %\end{ttfamily} % -%where \meta{date} is the copyright date, and \meta{author} is the author's name (see below). +%where \meta{date} is the copyright date, and \meta{author} is the +%author's name (see below). +% +%\item[\switch{postamble} \meta{text}] Set the postamble to +%\texttt{text}. If this is omitted the \ics{postamble} command is +%omitted from the installation script. % -%\item[\switch{postamble} \meta{text}] Set the postamble to \texttt{text}. If this is omitted the \cmdname{postamble} -%command is omitted from the installation script. +%\item[\switch{author} \meta{name}] The author's name (as used in the +%default preamble). If omitted the user's name is used. % -%\item[\switch{author} \meta{name}] The author's name (as used in the default preamble). If omitted the user's name is used. +%\item[\switch{date} \meta{text}] The copyright date (as used in the +%default preamble). If omitted the current year is used. % -%\item[\switch{date} \meta{text}] The copyright date (as used in the default preamble). If omitted the current -%year is used. +%\item[\switch{stopeventually} \meta{text}] Insert \meta{text} into the +%argument of \ics{StopEventually}. For example: +%\verb+-stopeventually "\\PrintIndex"+ will result in the line: +%\cs{StopEventually}\verb"{\PrintIndex}". If \texttt{makedtx.pl} +%encounters a \cs{StopEventually} command within the document, +%this will be used instead. If there is no \cs{StopEventually} +%command in the document and the \switch{stopeventually} switch is +%absent \cs{StopEventually}\marg{} will be inserted in the DTX +%file. % -%\item[\switch{stopeventually} \meta{text}] Insert \meta{text} into the argument of \cmdname{StopEventually}. -%For example: \verb+-stopeventually "\\PrintIndex"+ will result in the -%line: \cmdname{StopEventually}\verb"{\PrintIndex}". -%If \texttt{makedtx.pl} encounters a \cmdname{StopEventually} command within the document, this will be used instead. -%If there is no \cmdname{StopEventually} command in the document and the \switch{stopeventually} switch is absent -%\cmdname{StopEventually}\verb"{}" will be inserted in the DTX file. +%\item[\switch{prefinale} \meta{text}] +%\changes{0.91}{2006/07/21}{prefinale switch added}% +%Inset \meta{text} immediately prior to \cs{Finale} +%in the dtx file. % %\item[\switch{setambles} \texttt{"}\meta{expr}\texttt{=\symbol{62}}\meta{text}\texttt{"}] -%Sets the pre- and postambles for files matching \meta{expr} within -%the \cmdname{file} command in the installation script. To illustrate this, let's suppose you have source files -%\texttt{foo.sty}, \texttt{bar.sty} and \texttt{foobar.pl} in the subdirectory \texttt{sourcefiles}. Since -%\texttt{foo.sty} and \texttt{bar.sty} are \LaTeX\ files, they should have pre- and postambles, but \texttt{foobar.pl} -%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: +%Sets the pre- and postambles for files matching \meta{expr} within the +%\cs{file} command in the installation script. To illustrate this, +%let's suppose you have source files \texttt{foo.sty}, \texttt{bar.sty} +%and \texttt{foobar.pl} in the subdirectory \texttt{sourcefiles}. +%Since \texttt{foo.sty} and \texttt{bar.sty} are \LaTeX\ files, they +%should have pre- and postambles, but \texttt{foobar.pl} 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: %\begin{verbatim} %makedtx.pl -dir sourcefiles -src "(.*)\.sty=>\1.sty" -src "foobar.pl=>foobar.pl" %-setambles "foobar\.pl=>\\nopreamble\\nopostamble" -doc foodoc.tex foo %\end{verbatim} -%(Note that the line is only broken to fit it onto the page, and there should be no line break when entering -%at the command prompt.) -% -%If the argument to \switch{setambles} contains the string \verb"\\nopreamble", the character table will be -%excluded from the corresponding files. So, in the above example, when you do: \verb"latex foo.ins" the -%resulting files \texttt{foo.sty} and \texttt{bar.sty} will contain the character table, but \texttt{foobar.pl} -%won't. (If for some reason you don't want a preamble but you do want the character table included -%use \verb"\\usepreamble\\empty" instead of \verb'\\nopreamble'. Conversely, if you want a preamble but don't -%want the character table do something like \verb"\\nopreamble\\usepreamble\\defaultpreamble", although I can't think -%of a good reason for wanting either of these situations.) -% -%Note that the \verb"=>"\meta{text} part is optional. If it is omitted, \meta{text} is assumed to be empty. -% -%\item[\switch{macrocode} \texttt{"}\meta{expr}\texttt{"}] If source file matches the Perl regular expression given by \meta{expr}, -%the source code is inserted into a \texttt{macrocode} environment in the DTX file. +%(Note that the line is only broken to fit it onto the page, and there +%should be no line break when entering at the command prompt.) +% +%If the argument to \switch{setambles} contains the string +%\verb"\\nopreamble", the character table will be excluded from the +%corresponding files. So, in the above example, when you do: +%\verb"latex foo.ins" the resulting files \texttt{foo.sty} and +%\texttt{bar.sty} will contain the character table, but +%\texttt{foobar.pl} won't. (If for some reason you don't want a +%preamble but you do want the character table included use +%\verb"\\usepreamble\\empty" instead of \verb'\\nopreamble'. +%Conversely, if you want a preamble but don't want the character table +%do something like \verb"\\nopreamble\\usepreamble\\defaultpreamble", +%although I can't think of a good reason for wanting either of these +%situations.) +% +%Note that the \verb"=>"\meta{text} part is optional. If it is +%omitted, \meta{text} is assumed to be empty. +% +%\item[\switch{macrocode} \texttt{"}\meta{expr}\texttt{"}] If source +%file matches the Perl regular expression given by \meta{expr}, the +%source code is inserted into a \texttt{macrocode} environment in the +%DTX file. +% +%\item[\switch{comment} \texttt{"}\meta{expr}\texttt{"}] +%\changes{0.93}{2007/08/02}{comment switch added}% +%If the source file matches the Perl regular expression given by +%\meta{expr}, the source code will be inserted between \cs{iffalse} +%\cs{fi} 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 +%\switch{comment} switch will typically need to be used in conjunction +%with \switch{macrocode}. +% +%\item[\switch{codetitle} \texttt{"}\meta{title}\texttt{"}] +%\changes{0.93}{2007/08/02}{Added codetitle switch}% +%This sets the title for the code section. The default is +%\texttt{The Code}. %\end{description} % %\section{The creatdtx Package} %\label{sec:creatdtx} % -%The documentation source code, as specified using the \switch{doc} switch will typically be a standard -%\LaTeX\ document using the \texttt{ltxdoc} class file. Unlike the DTX file, there is no \cmdname{DocInput} command, -%and the lines do not begin with a percent symbol, which means that the document can be, say, passed to the -%\latextohtml\ converter, or some other application that would otherwise be confused by a DTX file. The \texttt{creatdtx} -%package can be used in this document using +%The documentation source code, as specified using the \switch{doc} +%switch will typically be a standard \LaTeX\ document using the +%\texttt{ltxdoc} class file. Unlike the DTX file, there is no +%\ics{DocInput} command, and the lines do not begin with a percent +%symbol, which means that the document can be, say, passed to the +%\latextohtml\ converter, or some other application that would +%otherwise be confused by a DTX file. The \texttt{creatdtx} package +%can be used in this document using %\begin{verbatim} %\usepackage{creatdtx} %\end{verbatim} -%although this package will be not be included in the DTX file by \texttt{makedtx.pl}. -%There is only one command defined in this package: -%\cmdname{ifmakedtx}\texttt{\{\meta{dtx text}\}\{\meta{non dtx text}\}}. -%The first argument \meta{dtx text} will be copied to the DTX file by \texttt{makedtx.pl}, but the second argument -%\meta{non dtx text} won't. -%However, if you \LaTeX\ the document, the first argument will be ignored, and the second argument will be used. -% -%For example, if your code (in \texttt{foodoc.tex}) contains the line:\par\vspace{6pt}\noindent\texttt{\cmdname{ifmakedtx}\{\}\{\cmdname{usepackage}\{html\}\}} -%\par\vspace{6pt}\noindent the \texttt{html} package will only be loaded if you \LaTeX\ \texttt{foodoc.tex}, but not when you \LaTeX\ +%although this package will be not be included in the DTX file by +%\texttt{makedtx.pl}. There is only one command defined in this +%package:\ics{ifmakedtx}\marg{dtx text}\marg{non dtx text}. The first +%argument \meta{dtx text} will be copied to the DTX file by +%\texttt{makedtx.pl}, but the second argument \meta{non dtx text} +%won't. However, if you \LaTeX\ the document, the first argument will +%be ignored, and the second argument will be used. +% +%For example, if your code (in \texttt{foodoc.tex}) contains the +%line:\par\vspace{6pt}\noindent\texttt{\cs{ifmakedtx}\{\}\{\cs{usepackage}\{html\}\}} +%\par\vspace{6pt}\noindent the \texttt{html} package will only be +%loaded if you \LaTeX\ \texttt{foodoc.tex}, but not when you \LaTeX\ %\texttt{foo.dtx}. % -%The Perl script \texttt{creatdtx.perl} ignores the following commands (and any associated arguments): -%\cmdname{OnlyDescription}, \cmdname{RecordChanges}, \cmdname{MakeShortVerb}, \cmdname{DeleteShortVerb}, \cmdname{DoNotIndex}, -%\cmdname{EnableCrossrefs}, \cmdname{CodelineIndex}, \cmdname{GetFileInfo}, -%\cmdname{PrintChanges}, \cmdname{changes}, \cmdname{CheckSum}, \cmdname{DescribeMacro} and \cmdname{DescribeEnvironment}. -%So even if you don't use the \cmdname{ifmakedtx} command, using the \texttt{creatdtx} package will help ensure that -%extraneous text does not appear in the HTML document when using \latextohtml. +%The Perl script \texttt{creatdtx.perl} ignores the following commands +%(and any associated arguments): \ics{OnlyDescription}, +%\ics{RecordChanges}, \ics{MakeShortVerb}, \ics{DeleteShortVerb}, +%\ics{DoNotIndex}, \ics{EnableCrossrefs}, \ics{CodelineIndex}, +%\ics{GetFileInfo}, \ics{PrintChanges}, \ics{changes}, \ics{CheckSum}, +%\ics{DescribeMacro} and \ics{DescribeEnvironment}. So even if you don't +%use the \cs{ifmakedtx} command, using the \texttt{creatdtx} package +%will help ensure that extraneous text does not appear in the HTML +%document when using \latextohtml. +% +%As from version 0.93b, \texttt{creatdtx.perl} also defines the +%commands \ics{cs}, \ics{marg}, \ics{oarg} and \ics{parg}, since there +%is no \latextohtml\ implementation of the \texttt{ltxdoc} class file. % %\section{Examples} %\label{sec:examples} % -%Let's first consider a very simple example. Suppose you want to create a package that redefines \cmdname{today} -%so that the date is displayed in the form: yyyy-m-d. Let's call this package \texttt{dashdate}. The file -%\texttt{dashdate.sty} should look something like: +%Let's first consider a very simple example. Suppose you want to +%create a package that redefines \cs{today} so that the date is +%displayed in the form: yyyy-m-d. Let's call this package +%\texttt{dashdate}. The file \texttt{dashdate.sty} should look +%something like: %\begin{verbatim} % % First define package: % % \begin{macrocode} @@ -288,9 +385,12 @@ % \renewcommand{\today}{\the\year-\the\month-\the\day} % % \end{macrocode} %\end{verbatim} -%Now let's make some (very brief) documentation. Let's call the file, say \texttt{manual.tex}\footnote{Note: if you -%want to use \latextohtml\ on this document, you will need to use, e.g., \cmdname{verb}\texttt{!\cmdname{today}!} instead of -%\texttt{\symbol{124}\cmdname{today}\symbol{124}} since it doesn't recognise \cmdname{MakeShortVerb}.}: +%Now let's make some (very brief) documentation. Let's call the file, +%say \texttt{manual.tex}\footnote{Note: if you want to use +%\latextohtml\ on this document, you will need to use, e.g., +%\cs{verb}\texttt{!\cs{today}!} instead of +%\texttt{\symbol{124}\cs{today}\symbol{124}} since it doesn't recognise +%\ics{MakeShortVerb}.}: %\begin{verbatim} %\documentclass{ltxdoc} %\usepackage{creatdtx} @@ -304,13 +404,15 @@ %to produce the current date in the form: yyyy-m-d. %\end{document} %\end{verbatim} -%Suppose you have saved \texttt{dashdate.sty} and \texttt{manual.tex} in the subdirectory \texttt{source}. You -%can now create the \texttt{.dtx} and \texttt{.ins} file using the command: +%Suppose you have saved \texttt{dashdate.sty} and \texttt{manual.tex} +%in the subdirectory \texttt{source}. You can now create the +%\texttt{.dtx} and \texttt{.ins} file using the command: %\begin{verbatim} %makedtx.pl -author "AN Other" -dir source -src "dashdate\.sty=>dashdate.sty" %-doc source/manual.tex dashdate %\end{verbatim} -%The file \texttt{dashdate.dtx} is created, and contains the following code: +%The file \texttt{dashdate.dtx} is created, and contains the following +%code: %\begin{verbatim} % %\iffalse % % dashdate.dtx generated using makedtx.pl version 0.9b (c) Nicola Talbot @@ -364,9 +466,11 @@ % % % %\StopEventually{} % %\section{The Code} +% %\iffalse % % \begin{macrocode} % %<*dashdate.sty> % % \end{macrocode} +% %\fi % % First define package: % % \begin{macrocode} % \NeedsTeXFormat{LaTeX2e} @@ -376,9 +480,11 @@ % % \begin{macrocode} % \renewcommand{\today}{\the\year-\the\month-\the\day} % % \end{macrocode} +% %\iffalse % % \begin{macrocode} % %</dashdate.sty> % % \end{macrocode} +% %\fi % %\Finale % \endinput %\end{verbatim} @@ -404,19 +510,21 @@ % % \endbatchfile %\end{verbatim} -%Note that the command \verb"\usepackage{creatdtx}" has not been transcribed to \texttt{dashdate.dtx} -%(although in this simple example it's not really needed). +%Note that the command \verb"\usepackage{creatdtx}" has not been +%transcribed to \texttt{dashdate.dtx} (although in this simple example +%it's not really needed). % -%Now let's extend the example: -%suppose you want to create an analogous Perl script for use with \latextohtml. -%This will need to be called \texttt{dashdate.perl} and will look something like: +%Now let's extend the example: suppose you want to create an analogous +%Perl script for use with \latextohtml. This will need to be called +%\texttt{dashdate.perl} and will look something like: %\begin{verbatim} %package main; % %sub do_cmd_today{ +% local($_) = @_; % local($today) = &get_date(); % $today =~ s|(\d+)/(\d+)/(\d+)|$3-$1-$2|; -% $_ = $today; +% "$today$_"; %} % %1; @@ -428,26 +536,43 @@ %-setambles "dashdate\.perl=>\\nopreamble\\nopostamble" %-macrocode "dashdate\.perl" -doc source/manual.tex dashdate %\end{verbatim} -%(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: +%(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: %\begin{verbatim} %makedtx.pl -author "AN Other" -dir source -src "dashdate\.(.*)=>dashdate.\1" %-setambles "dashdate\.perl=>\\nopreamble\\nopostamble" -macrocode "dashdate\.perl" %-doc source/manual.tex dashdate %\end{verbatim} -%Note the use of the \switch{setambles} switch which suppresses the insertion of text at the start and -%end of the Perl script which would only confuse Perl. Note also the use of the \switch{macrocode} -%switch. This is not needed for \texttt{dashdate.sty} since it has already been included in the source -%code, but since \% is not a comment character in Perl, the \texttt{macrocode} environment -%is not included in the source code, and needs to be added. -%(If you are unfamiliar with DocStrip and the use of the \texttt{macrocode} environment, -%I suggest you read either \emph{A guide to \LaTeX}~\cite[Appendix~D]{Kopka98} -%or \emph{The \LaTeX\ companion}~\cite[Chapter~14]{Goossens93}) -% -%As another example, consider the \texttt{datetime} package. Version 2.42 of this package has 2 \texttt{.sty} files -%and 42 \texttt{.def} files. The documentation is written in the file \texttt{manual.tex}, and the \texttt{.sty} -%and \texttt{.def} files are saved in a subdirectory called \texttt{source}. Since these are the only files in this -%directory, they can easily be merged into one \texttt{.dtx} file using: +%Note the use of the \switch{setambles} switch which suppresses the +%insertion of text at the start and end of the Perl script which would +%only confuse Perl. Note also the use of the \switch{macrocode} +%switch. This is not needed for \texttt{dashdate.sty} since it has +%already been included in the source code, but since \% is not a +%comment character in Perl, the \texttt{macrocode} environment is not +%included in the source code, and needs to be added. (If you are +%unfamiliar with DocStrip and the use of the \texttt{macrocode} +%environment, I suggest you read either \emph{A guide to +%\LaTeX}~\cite[Appendix~D]{Kopka98} or \emph{The \LaTeX\ +%companion}~\cite[Chapter~14]{Goossens93}.) +% +%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 \switch{macrocode} switch, you would then also need to use +%the \switch{comment} switch: +%\begin{verbatim} +%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 +%\end{verbatim} +% +%As another example, consider the \texttt{datetime} package. Version +%2.42 of this package has 2 \texttt{.sty} files and 42 \texttt{.def} +%files. The documentation is written in the file \texttt{manual.tex}, +%and the \texttt{.sty} and \texttt{.def} files are saved in a +%subdirectory called \texttt{source}. Since these are the only files +%in this directory, they can easily be merged into one \texttt{.dtx} +%file using: %\begin{verbatim} %makedtx.pl -author "Nicola Talbot" -dir source -src "(.+)\.(.+)=>\1.\2" %-doc manual.tex datetime @@ -461,30 +586,35 @@ %\begin{verbatim} %latex2html -split 0 -nonavigation -nofootnode -numbered_footnotes -noinfo manual %\end{verbatim} -%Any minor differences between the HTML and PDF versions are dealt by using \cmdname{ifmakedtx} in -%the original file \texttt{manual.tex}. +%Any minor differences between the HTML and PDF versions are dealt by +%using \cs{ifmakedtx} in the original file \texttt{manual.tex}. % %\section{Troubleshooting} %\label{sec:problems} % -%The \texttt{makedtx} bundle has only been tested under Linux using Perl v5.6.0. There are no guarantees whether -%or not it will work on other operating systems or on different versions (in fact, there are no guarantees or -%warranties at all). +%The \texttt{makedtx} bundle has only been tested under Linux using +%Perl v5.6.0. There are no guarantees whether or not it will work on +%other operating systems or on different versions (in fact, there are +%no guarantees or warranties at all). % %\subsection{Known Bugs} % -%It's possible to confuse \texttt{makedtx.pl} by placing either the command \cmdname{end}\verb"{document}" -%or the command \cmdname{ifmakedtx} in a \cmdname{verb} command, or by having the \cmdname{ifmakedtx} command -%on the same line as \cmdname{begin}\verb"{document}". You will also need to take care about lines beginning -%with a percent symbol (\%) in the documentation, as this will get converted into a line beginning with \verb"%%" -%in the \texttt{.dtx} file, which has a special meaning. Either place a space immediately prior the percent symbol, -%or do \verb"\relax%" if you really don't want the extra space (or place your comment in an \cmdname{iffalse} \ldots\ \cmdname{fi} -%conditional). +%It's possible to confuse \texttt{makedtx.pl} by placing either the +%command \cs{end}\marg{document} or the command \ics{ifmakedtx} in a +%\cs{verb} command, or by having the \ics{ifmakedtx} command on the same +%line as \cs{begin}\marg{document}. You will also need to take care +%about lines beginning with a percent symbol (\%) in the documentation, +%as this will get converted into a line beginning with \verb"%%" in the +%\texttt{.dtx} file, which has a special meaning. Either place a space +%immediately prior the percent symbol, or do \verb"\relax%" if you +%really don't want the extra space (or place your comment in an +%\cs{iffalse} \ldots\ \cs{fi} conditional). % %\subsection{Possible errors encountered using \texttt{makedtx.pl}} % -%Note: be careful to use double quotes around arguments that contain characters that the shell might -%try interpreting, e.g.\ \verb"*" or \verb'>'. +%Note: be careful to use double quotes around arguments that contain +%characters that the shell might try interpreting, e.g.\ \verb"*" or +%\verb'>'. % %Syntax error messages: %\begin{enumerate} @@ -503,12 +633,13 @@ % %\item \texttt{-src \ldots\ argument invalid (no output file specified)} % -%You have omitted the \verb"=>" separator in the argument of the \switch{src} switch. +%You have omitted the \verb"=>" separator in the argument of the +%\switch{src} switch. % %\item \texttt{-src argument \ldots\ invalid (too many => specified)} % -%You have used too many \verb"=>" separators in the argument of the \switch{src} switch. -%(Similarly for the \switch{setambles} switch.) +%You have used too many \verb"=>" separators in the argument of the +%\switch{src} switch. (Similarly for the \switch{setambles} switch.) %\end{enumerate} % %\appendix @@ -579,46 +710,81 @@ % %\end{itemize} % -%\begin{thebibliography}{1} +%\StopEventually{\phantomsection\addcontentsline{toc}{section}{\refname} +%\csname begin\endcsname{thebibliography}{1} %\bibitem{Goossens93} The \LaTeX\ companion. Michel~Goossens, Frank~Mittelbach and Alexander~Samarin. %Addison-Wesley 1993. % %\bibitem{Kopka98} A guide to \LaTeX. Helmut~Kopka and Patrick~W.~Daly. Addison-Wesley 1998. -%\end{thebibliography} -% -%\section*{Contact Details} -%\addcontentsline{toc}{section}{Contact Details} -% -%\begin{tabular}{l} -%Dr Nicola Talbot\\ -%School of Computing Sciences\\ -%University of East Anglia\\ -%Norwich. NR4 7TJ\\ -%United Kingdom\\ -%\url{http://theoval.cmp.uea.ac.uk/~nlct/} -%\end{tabular} +%\csname end\endcsname{thebibliography} +%\PrintChanges +%\phantomsection\addcontentsline{toc}{section}{Index} +%\PrintIndex} +% % % % -%\StopEventually{} -%\section{The Code} +%\section{creatdtx.sty code} +%\iffalse % \begin{macrocode} %<*creatdtx.perl> % \end{macrocode} +%\fi +%\iffalse % \begin{macrocode} # 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 # {} @@ -631,23 +797,28 @@ GetFileInfo # {} CheckSum # {} DescribeMacro # {} DescribeEnvironment # {} -MakeShortVerb # {} -DeleteShortVerb # {} DoNotIndex # {} changes # {} # {} # {} +DeleteShortVerb # {} +MakeShortVerb # {} _IGNORED_CMDS_ 1; % \end{macrocode} +%\fi +%\iffalse % \begin{macrocode} %</creatdtx.perl> % \end{macrocode} +%\fi +%\iffalse % \begin{macrocode} %<*creatdtx.sty> % \end{macrocode} -% This is the code for the \texttt{creatdtx} package. This package should not be -% used in a .dtx file. First define the -% package: +%\fi +% This is the code for the \texttt{creatdtx} package. This +% package should not be used in a .dtx file. +% First define the package: % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{creatdtx}[2005/02/11 v0.9b (N.L.C. Talbot)] @@ -661,39 +832,48 @@ _IGNORED_CMDS_ \providecommand{\StopEventually}{} \renewcommand{\StopEventually}[1]{#1} % \end{macrocode} +%\iffalse % \begin{macrocode} %</creatdtx.sty> % \end{macrocode} +%\fi +%\iffalse % \begin{macrocode} %<*makedtx.pl> % \end{macrocode} +%\fi +%\iffalse % \begin{macrocode} #!/usr/bin/perl # 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 +# -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 = "="; @@ -702,8 +882,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); @@ -713,7 +895,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") { @@ -771,6 +957,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 "") @@ -786,19 +984,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]; @@ -813,7 +1011,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) @@ -841,11 +1039,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"; @@ -893,7 +1094,7 @@ while (<DOC>) { $beginline = $1; - ($group,$restofline,$done) = getnextgroup($2); + ($group,$restofline,$done) = &getnextgroup($2); $startline = $.; @@ -905,7 +1106,7 @@ while (<DOC>) $restofline = $restofline . $nextline; - ($group,$restofline,$done) = getnextgroup($restofline); + ($group,$restofline,$done) = &getnextgroup($restofline); } else { @@ -917,7 +1118,7 @@ while (<DOC>) $beginline = $beginline . $group; - ($group,$restofline,$done) = getnextgroup($restofline); + ($group,$restofline,$done) = &getnextgroup($restofline); while (!$done) { @@ -927,7 +1128,7 @@ while (<DOC>) $restofline = $restofline . $nextline; - ($group,$restofline,$done) = getnextgroup($restofline); + ($group,$restofline,$done) = &getnextgroup($restofline); } else { @@ -986,7 +1187,7 @@ while (<DOC>) { $beginline = $1; - ($group,$restofline,$done) = getnextgroup($2); + ($group,$restofline,$done) = &getnextgroup($2); $startline = $.; @@ -998,7 +1199,7 @@ while (<DOC>) $restofline = $restofline . $nextline; - ($group,$restofline,$done) = getnextgroup($restofline); + ($group,$restofline,$done) = &getnextgroup($restofline); } else { @@ -1010,7 +1211,7 @@ while (<DOC>) $beginline = $beginline . $group; - ($group,$restofline,$done) = getnextgroup($restofline); + ($group,$restofline,$done) = &getnextgroup($restofline); while (!$done) { @@ -1020,7 +1221,7 @@ while (<DOC>) $restofline = $restofline . $nextline; - ($group,$restofline,$done) = getnextgroup($restofline); + ($group,$restofline,$done) = &getnextgroup($restofline); } else { @@ -1054,7 +1255,7 @@ if ($stopfound==0) print DTX "\%\\StopEventually{$stopeventually}\n"; } -print DTX "\%\\section{The Code}\n"; +print DTX "\%\\section{$codetitle}\n"; @srcdirfile = glob("$srcdir/*"); @@ -1068,14 +1269,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) @@ -1084,7 +1285,7 @@ foreach $source (@source) $_ = $srcdirfile; - $expr = "s$patternop$fileexp$patternop$outfile$patternop"; + $expr = "s$patternop$fileexp$patternop$outfile$patternop"; if (eval($expr)) { @@ -1099,11 +1300,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) { @@ -1125,9 +1339,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; @@ -1136,6 +1357,7 @@ foreach $source (@source) } } +print DTX "\%$prefinale\n" if ($prefinale); print DTX "\%\\Finale\n"; print DTX "\\endinput\n"; @@ -1145,7 +1367,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"; @@ -1232,18 +1454,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"; @@ -1266,15 +1488,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"; @@ -1284,7 +1510,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"; @@ -1293,11 +1519,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; } @@ -1318,7 +1544,7 @@ sub getnextgroup { my($curline) = @_; - $curline = eatinitialspaces($curline); + $curline = &eatinitialspaces($curline); # check to see if current string is blank @@ -1486,8 +1712,11 @@ sub getnextgroup } 1; % \end{macrocode} +%\fi +%\iffalse % \begin{macrocode} %</makedtx.pl> % \end{macrocode} +%\fi %\Finale \endinput diff --git a/Master/texmf-dist/source/latex/makedtx/makedtx.ins b/Master/texmf-dist/source/latex/makedtx/makedtx.ins index 0b9a5f88b97..60632620fc5 100644 --- a/Master/texmf-dist/source/latex/makedtx/makedtx.ins +++ b/Master/texmf-dist/source/latex/makedtx/makedtx.ins @@ -1,8 +1,8 @@ -% makedtx.ins generated using makedtx version 0.9b 2005/2/13 21:58 +% makedtx.ins generated using makedtx version 0.93b 2007/8/2 15:16 \input docstrip \preamble -Copyright (C) 2005 Nicola Talbot, all rights reserved. +Copyright (C) 2007 Nicola Talbot, 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 @@ -14,8 +14,8 @@ etc. \generate{\file{creatdtx.sty}{\usepreamble\defaultpreamble \usepostamble\defaultpostamble\from{makedtx.dtx}{creatdtx.sty,package}} -\file{makedtx.pl}{\nopreamble\nopostamble\from{makedtx.dtx}{makedtx.pl}} \file{creatdtx.perl}{\nopreamble\nopostamble\from{makedtx.dtx}{creatdtx.perl}} +\file{makedtx.pl}{\nopreamble\nopostamble\from{makedtx.dtx}{makedtx.pl}} } \endbatchfile diff --git a/Master/texmf-dist/tex/latex/makedtx/creatdtx.sty b/Master/texmf-dist/tex/latex/makedtx/creatdtx.sty index 548f38669fb..a90cd7a772c 100644 --- a/Master/texmf-dist/tex/latex/makedtx/creatdtx.sty +++ b/Master/texmf-dist/tex/latex/makedtx/creatdtx.sty @@ -5,7 +5,7 @@ %% The original source files were: %% %% makedtx.dtx (with options: `creatdtx.sty,package') -%% Copyright (C) 2005 Nicola Talbot, all rights reserved. +%% Copyright (C) 2007 Nicola Talbot, 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 |