diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex')
-rw-r--r-- | Master/texmf-dist/doc/latex/makedtx/CHANGES | 19 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/makedtx/README | 32 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/makedtx/creatdtx.perl | 72 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/makedtx/makedtx-manual.html | 971 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/makedtx/makedtx.pdf | bin | 202740 -> 0 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/makedtx/makedtx.pl | 979 |
6 files changed, 0 insertions, 2073 deletions
diff --git a/Master/texmf-dist/doc/latex/makedtx/CHANGES b/Master/texmf-dist/doc/latex/makedtx/CHANGES deleted file mode 100644 index cbd18311fda..00000000000 --- a/Master/texmf-dist/doc/latex/makedtx/CHANGES +++ /dev/null @@ -1,19 +0,0 @@ -version 0.94 (2007/08/19) : - - * Default preamble changed to one which conforms with the - LaTeX Project Public License (LPPL) - * license switch added - -version 0.93 (2007/08/02) : - - * version switch added - * comment switch added - * codetitle switch added - -version 0.91 (2006/07/21) : - - * prefinale switch added - -version 0.9 (2005/02/11) : - - * Initial beta release diff --git a/Master/texmf-dist/doc/latex/makedtx/README b/Master/texmf-dist/doc/latex/makedtx/README deleted file mode 100644 index e4abbba5d90..00000000000 --- a/Master/texmf-dist/doc/latex/makedtx/README +++ /dev/null @@ -1,32 +0,0 @@ -makedtx v0.94b : a Perl script to help create .dtx and .ins files - -Last Modified : 19 August 2007 - -Author : Nicola Talbot - -Files : makedtx.dtx - documented source file - makedtx.ins - installation script - - -The makedtx bundle is provided to help LaTeX2e developers to write the code and -documentation in separate files, and then combine them into a single .dtx -file for distribution. It automatically generates the character table, and also -writes the associated installation (.ins) script. - -To extract the code do: - -latex makedtx.ins - -To extract the documentation do: - -pdflatex makedtx.dtx -pdflatex makedtx.dtx - -Read the documentation for installation instructions. - -This material is subject to the LaTeX Project Public License. -See http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html for -the details of that license. - -http://theoval.cmp.uea.ac.uk/~nlct/ - diff --git a/Master/texmf-dist/doc/latex/makedtx/creatdtx.perl b/Master/texmf-dist/doc/latex/makedtx/creatdtx.perl deleted file mode 100644 index 9149cba164b..00000000000 --- a/Master/texmf-dist/doc/latex/makedtx/creatdtx.perl +++ /dev/null @@ -1,72 +0,0 @@ -# creatdtx.perl LaTeX2HTML file corresponding to creatdtx.sty package -# author : Nicola Talbot -# date : 2nd August 2007 - -package main; - -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 # {} -OnlyDescription -RecordChanges -PrintChanges -EnableCrossRefs -CodelineIndex -GetFileInfo # {} -CheckSum # {} -DescribeMacro # {} -DescribeEnvironment # {} -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 deleted file mode 100644 index 4438c92c219..00000000000 --- a/Master/texmf-dist/doc/latex/makedtx/makedtx-manual.html +++ /dev/null @@ -1,971 +0,0 @@ -<!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.94b : a Perl script to help create a DTX file from source code</TITLE> -<META NAME="description" CONTENT="makedtx v0.94b : 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.94b : 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>19th 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 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 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="#foot51"><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 -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> -<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 LaTeX 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 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"> -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> - <I>basename</I>.dtx - Copyright <I>date</I> <I>author</I> -</TT> -<P> -<TT>This work may be distributed and/or modified under the - conditions of the LaTeX Project Public License, either version 1.3 - of this license of (at your option) any later version. - The latest version of this license is in - http://www.latex-project.org/lppl.txt - and version 1.3 or later is part of all distributions of LaTeX - version 2005/12/01 or later. -</TT> -<P> -<TT>This work has the LPPL maintenance status `maintained'. -</TT> -<P> -<TT>The Current Maintainer of this work is <I>author</I>. -</TT> -<P> -<TT>This work consists of the files <I>basename</I>.dtx and - <I>basename</I>.ins and the derived files <I>file list</I>. -</TT> - -<P> -where <I>date</I> is the copyright date, and <I>author</I> is the -author's name (see below). - -<P> -<B>Note that this has been changed as of makedtx v0.94. -Older versions of makedtx do not conform to any of the free -licenses.</B> - -<P> -</DD> -<DT><STRONG><TT>-license</TT> <I>name</I></STRONG></DT> -<DD>This sets the preamble to -the license text for the license <I>name</I>. Currently <I>name</I> -may be either <TT>lppl</TT> (the default, which produces the -default preamble detailed above), <TT>bsd</TT> or <TT>gpl</TT>. -You may use either <TT>-license</TT> or <TT>-preamble</TT>, -but not both. (If you have used the <TT>-preamble</TT> switch, the -<TT>-license</TT> switch will be ignored.) - -<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 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>. - -<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 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 - 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 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> -<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 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 . - -<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="#foot477"><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.94b 2007/8/19 22:22 - \input docstrip - - \preamble - dashdate.dtx - Copyright 2007 AN Other - - This work may be distributed and/or modified under the - conditions of the LaTeX Project Public License, either version 1.3 - of this license of (at your option) any later version. - The latest version of this license is in - http://www.latex-project.org/lppl.txt - and version 1.3 or later is part of all distributions of LaTeX - version 2005/12/01 or later. - - This work has the LPPL maintenance status `maintained'. - - The Current Maintainer of this work is AN Other. - - This work consists of the files dashdate.dtx and - dashdate.ins and the derived file dashdate.sty. - \endpreamble - - \askforoverwritefalse - - \generate{\file{dashdate.sty}{\usepreamble\defaultpreamble - \usepostamble\defaultpostamble\from{dashdate.dtx}{dashdate.sty,package}} - } - - \endbatchfile -</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 -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> -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 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> - -<BR><HR><H4>Footnotes</H4> -<DL> -<DT><A NAME="foot51">... -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="foot477">...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-19 -</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 differdeleted file mode 100644 index 79a8b5e822b..00000000000 --- a/Master/texmf-dist/doc/latex/makedtx/makedtx.pdf +++ /dev/null diff --git a/Master/texmf-dist/doc/latex/makedtx/makedtx.pl b/Master/texmf-dist/doc/latex/makedtx/makedtx.pl deleted file mode 100644 index 41516e79920..00000000000 --- a/Master/texmf-dist/doc/latex/makedtx/makedtx.pl +++ /dev/null @@ -1,979 +0,0 @@ -#!/usr/bin/perl - -# File : makedtx -# Author : Nicola L. C. Talbot -# Date : 29 Oct 2004 -# Last Modified : 19 Aug 2007 -# Version : 0.94b - -# 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.94b"; - -# 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", -"prefinale=s", "codetitle=s", "comment=s@", -"version", "license=s") or &syntaxerror(); - -$srcdir = "."; -$patternop = "="; -$verbose = 0; -$noins = 0; -$askforoverwrite = 0; -$preamble = ""; -$postamble = ""; -$author = (getpwuid($<))[6] || 'Unknown'; -$stopeventually = ""; -$prefinale = ""; -$codetitle = "The Code"; -$license = "lppl"; - -($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst) = localtime(time); - -$year = $year + 1900; - -foreach $setting (keys %optctl) -{ - if (($setting eq "h") || ($setting eq "help")) - { - &help(); - } - elsif ($setting eq "version") - { - die "makedtx version $version\n"; - } - elsif ($setting eq "doc") - { - $docsrc = $optctl{$setting}; - } - elsif ($setting eq "src") - { - @source = @{ $optctl{$setting} }; - } - elsif ($setting eq "dir") - { - $srcdir = $optctl{$setting}; - } - elsif ($setting eq "op") - { - $patternop = $optctl{$setting}; - } - elsif ($setting eq "v") - { - $verbose = 1; - } - elsif ($setting eq "ins") - { - $noins = 1-$optctl{$setting}; - } - elsif ($setting eq "askforoverwrite") - { - $askforoverwrite = $optctl{$setting}; - } - elsif ($setting eq "preamble") - { - $preamble = $optctl{$setting}; - } - elsif ($setting eq "postamble") - { - $postamble = $optctl{$setting}; - } - elsif ($setting eq "setambles") - { - @setambles = @{ $optctl{$setting} }; - } - elsif ($setting eq "macrocode") - { - @macrocode = @{ $optctl{$setting} }; - } - elsif ($setting eq "author") - { - $author = $optctl{$setting}; - } - elsif ($setting eq "date") - { - $year = $optctl{$setting}; - } - elsif ($setting eq "stopeventually") - { - $stopeventually = $optctl{$setting}; - } - elsif ($setting eq "prefinale") - { - $prefinale = $optctl{$setting}; - } - elsif ($setting eq "codetitle") - { - $codetitle = $optctl{$setting}; - } - elsif ($setting eq "comment") - { - @comment = @{ $optctl{$setting} }; - } - elsif ($setting eq "license") - { - $license = $optctl{$setting}; - } -} - -if ($#ARGV != 0) -{ - print "No basename specified\n"; - &syntaxerror(); -} - -$basename = $ARGV[0]; - -if ($docsrc eq "") -{ - print "No document source specified (missing -doc)\n"; - &syntaxerror(); -} - -if ($#source == -1) -{ - print "No source code specified (missing -src)\n"; - &syntaxerror(); -} - -open DTX, ">$basename.dtx" or die "Can't open '$basename.dtx'\n"; - -if ($verbose) -{ - print "Documentation source : " . $docsrc . "\n"; -} - -# work out the derived files - - @srcdirfile = glob("$srcdir/*"); - - @derivedfiles = (); - - @outputfiles = (); - -$numoutput = 0; - -foreach $source (@source) -{ - ($infile, $outfile, $remainder) = split /=>/, $source; - - if ($outfile eq "") - { - print "-src $source argument invalid (no output file specified)\n"; - - &syntaxerror(); - } - - if (not ($remainder eq "")) - { - print "-src $source argument invalid (too many => specified)\n"; - - &syntaxerror(); - } - - foreach $srcdirfile (@srcdirfile) - { - $fileexp = $srcdir . "/" . $infile; - - $_ = $srcdirfile; - - $expr = "s$patternop$fileexp$patternop$outfile$patternop"; - - if (eval($expr)) - { - $thisoutfile = $_; - - $thisinfile = $srcdirfile; - - $file{$thisinfile} = $thisoutfile; - $derivedfiles[$numoutput]{'in'} = $thisinfile; - $derivedfiles[$numoutput]{'out'} = $thisoutfile; - $outputfiles[$numoutput] = $thisoutfile; - - $numoutput++; - } - } -} - -if ($preamble eq "") -{ - if ($license eq "lppl") - { - $preamble = <<_END_LICENSE - - $basename.dtx - Copyright $year $author - - This work may be distributed and/or modified under the - conditions of the LaTeX Project Public License, either version 1.3 - of this license of (at your option) any later version. - The latest version of this license is in - http://www.latex-project.org/lppl.txt - and version 1.3 or later is part of all distributions of LaTeX - version 2005/12/01 or later. - - This work has the LPPL maintenance status `maintained'. - - The Current Maintainer of this work is $author. - -_END_LICENSE - } - elsif ($license eq 'bsd') - { - $preamble = <<_END_LICENSE - - $basename.dtx - Copyright (c) $year $author - All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: -1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. -3. The name of the author may not be used to endorse or promote products - derived from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR -IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES -OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF -THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -_END_LICENSE - } - elsif ($license eq 'gpl') - { - $preamble = <<_END_LICENSE - - $basename.dtx - Copyright (c) $year $author - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - -_END_LICENSE - } - else - { - die "Unknown license '$license'\n". - "Known licenses: lppl, bsd, gpl"; - } - - $preamble .= " This work consists of the files " - . "$basename.dtx and $basename.ins and the derived " - . ($numoutput > 1 ? "files" : "file") - . " " . join(', ', @outputfiles) . ".\n"; -} - -open DOC, $docsrc or die "Can't open '$docsrc'\n"; - -print DTX "\%\\iffalse\n"; -print DTX "\% $basename.dtx generated using makedtx version $version (c) Nicola Talbot\n"; -print DTX "\% Command line args:\n"; - -foreach $setting (keys %optctl) -{ - if ($setting eq "src") - { - foreach $source (@source) - { - print DTX "\% -src \"$source\"\n"; - } - } - elsif ($setting eq "setambles") - { - foreach $setamble (@setambles) - { - print DTX "\% -setambles \"$setamble\"\n"; - } - } - elsif ($setting eq "macrocode") - { - foreach $macrocode (@macrocode) - { - print DTX "\% -macrocode \"$macrocode\"\n"; - } - } - elsif ($setting eq "comment") - { - foreach $comment (@comment) - { - print DTX "\% -comment \"$comment\"\n"; - } - } - else - { - $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"; -print DTX "\%<*package>\n"; -print DTX "\%\% \\CharacterTable\n"; -print DTX "\%\% {Upper-case \\A\\B\\C\\D\\E\\F\\G\\H\\I\\J\\K\\L\\M\\N\\O\\P\\Q\\R\\S\\T\\U\\V\\W\\X\\Y\\Z\n"; -print DTX "\%\% Lower-case \\a\\b\\c\\d\\e\\f\\g\\h\\i\\j\\k\\l\\m\\n\\o\\p\\q\\r\\s\\t\\u\\v\\w\\x\\y\\z\n"; -print DTX "\%\% Digits \\0\\1\\2\\3\\4\\5\\6\\7\\8\\9\n"; -print DTX "\%\% Exclamation \\! Double quote \\\" Hash (number) \\#\n"; -print DTX "\%\% Dollar \\\$ Percent \\\% Ampersand \\&\n"; -print DTX "\%\% Acute accent \\\' Left paren \\( Right paren \\)\n"; -print DTX "\%\% Asterisk \\* Plus \\+ Comma \\,\n"; -print DTX "\%\% Minus \\- Point \\. Solidus \\/\n"; -print DTX "\%\% Colon \\: Semicolon \\; Less than \\<\n"; -print DTX "\%\% Equals \\= Greater than \\> Question mark \\?\n"; -print DTX "\%\% Commercial at \\\@ Left bracket \\[ Backslash \\\\\n"; -print DTX "\%\% Right bracket \\] Circumflex \\^ Underscore \\_\n"; -print DTX "\%\% Grave accent \\\` Left brace \\{ Vertical bar \\|\n"; -print DTX "\%\% Right brace \\} Tilde \\~}\n"; -print DTX "\%</package>\n"; -print DTX "\%\\fi\n"; - -print DTX "\% \\iffalse\n"; -print DTX "\% Doc-Source file to use with LaTeX2e\n"; -print DTX "\% Copyright (C) $year $author, all rights reserved.\n"; -print DTX "\% \\fi\n"; - -# driver - -print DTX "\% \\iffalse\n"; -print DTX "\%<*driver>\n"; - -$indoc=0; - -while (<DOC>) -{ - s/\\usepackage{creatdtx}//; - - $restofline = $_; - - $beginline = ""; - $line = $restofline; - - while ($restofline =~ /(.*)\\ifmakedtx(.*)/) - { - $beginline = $1; - - ($group,$restofline,$done) = &getnextgroup($2); - - $startline = $.; - - while (!$done) - { - if ($nextline = <DOC>) - { - $line = $line . $nextline; - - $restofline = $restofline . $nextline; - - ($group,$restofline,$done) = &getnextgroup($restofline); - } - else - { - die "EOF found whilst scanning first argument to \\ifmakedtx on line $startline\n"; - } - } - - # print first arg, ignore second - - $beginline = $beginline . $group; - - ($group,$restofline,$done) = &getnextgroup($restofline); - - while (!$done) - { - if ($nextline = <DOC>) - { - $line = $line . $nextline; - - $restofline = $restofline . $nextline; - - ($group,$restofline,$done) = &getnextgroup($restofline); - } - else - { - die "EOF found whilst scanning second argument to \\ifmakedtx on line $startline\n"; - } - } - - $line = $restofline; - } - - $line = $beginline . $restofline; - - print DTX $line; - - if ($line=~/\\begin{document}/) - { - $indoc = 1; - - last; - } -} - -print DTX "\\DocInput{$basename.dtx}\n"; -print DTX "\\end{document}\n"; -print DTX "\%</driver>\n"; -print DTX "\%\\fi\n"; - -$inverb=0; -$stopfound=0; - -print DTX "\%"; - -while (<DOC>) -{ - if (/\\begin{verbatim}/) - { - $inverb=1; - } - - if (/\\end{verbatim}/) - { - $inverb=0; - } - - if (/\\StopEventually/ && ($inverb==0)) - { - $stopfound=1; - } - - $restofline = $_; - - $beginline = ""; - $line = $restofline; - - while ($restofline =~ /(.*)\\ifmakedtx(.*)/) - { - $beginline = $1; - - ($group,$restofline,$done) = &getnextgroup($2); - - $startline = $.; - - while (!$done) - { - if ($nextline = <DOC>) - { - $line = $line . $nextline; - - $restofline = $restofline . $nextline; - - ($group,$restofline,$done) = &getnextgroup($restofline); - } - else - { - die "EOF found whilst scanning first argument to \\ifmakedtx on line $startline\n"; - } - } - - # print first arg, ignore second - - $beginline = $beginline . $group; - - ($group,$restofline,$done) = &getnextgroup($restofline); - - while (!$done) - { - if ($nextline = <DOC>) - { - $line = $line . $nextline; - - $restofline = $restofline . $nextline; - - ($group,$restofline,$done) = &getnextgroup($restofline); - } - else - { - die "EOF found whilst scanning second argument to \\ifmakedtx on line $startline\n"; - } - } - - $line = $restofline; - } - - $line = $beginline . $restofline; - - if (($line=~/\\end{document}/) and not $inverb) - { - $indoc=0; - - $line=~s/\\end{document}//; - } - - $line=~s/\n/\n\%/mg; - - print DTX "$line"; -} - -close DOC; - -print DTX "\n"; - -if ($stopfound==0) -{ - print DTX "\%\\StopEventually{$stopeventually}\n"; -} - -print DTX "\%\\section{$codetitle}\n"; - -for (my $idx = 0; $idx <= $#derivedfiles; $idx++) -{ - $thisinfile = $derivedfiles[$idx]{'in'}; - $thisoutfile = $derivedfiles[$idx]{'out'}; - - if ($verbose) - { - print "$srcdirfile -> $_ \n"; - } - - 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) - { - if ($thisoutfile =~ m/$expr/) - { - print DTX "\% \\begin{macrocode}\n"; - - $macrocode = 1; - } - } - - while (<SRC>) - { - print DTX "$_"; - } - - if ($macrocode == 1) - { - 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; -} - -print DTX "\%$prefinale\n" if ($prefinale); -print DTX "\%\\Finale\n"; -print DTX "\\endinput\n"; - -close DTX; - -if (!$noins) -{ - open INS, ">$basename.ins" or die "Can't open '$basename.ins'\n"; - - print INS "\% $basename.ins generated using makedtx version $version $year/",$mon+1,"/$mday $hour:", $min<10?"0$min":$min,"\n"; - - print INS "\\input docstrip\n\n"; - print INS "\\preamble\n"; - print INS "$preamble\n"; - print INS "\\endpreamble\n\n"; - - if ($postamble ne "") - { - print INS "\\postamble\n"; - print INS "$postamble\n"; - print INS "\\endpostamble\n\n"; - } - - if ($askforoverwrite) - { - print INS "\\askforoverwritetrue\n\n"; - } - else - { - print INS "\\askforoverwritefalse\n\n"; - } - - print INS "\\generate{"; - - for (my $idx = 0; $idx <= $#derivedfiles; $idx++) - { - $file = $derivedfiles[$idx]{'in'}; - $outfile = $derivedfiles[$idx]{'out'}; - - print INS "\\file{$outfile}{"; - - $ambleset = 0; - $noamble = 0; - - foreach $setamble (@setambles) - { - ($fileexp, $amble, $remainder) = split /=>/, $setamble; - - if (not ($remainder eq "")) - { - die "-setambles $setamble argument invalid (too many => specified)\n"; - } - - if ($outfile =~ m/$fileexp/) - { - if ($verbose) - { - print "$fileexp matches $outfile -> setting \"$amble\"\n"; - } - - print INS $amble; - - $ambleset = 1; - - if ($amble =~ m/\\nopreamble/) - { - $noamble = 1; - } - } - } - - if (!$ambleset) - { - print INS "\\usepreamble\\defaultpreamble\n\\usepostamble\\defaultpostamble"; - } - - print INS "\\from{$basename.dtx}{$outfile"; - - if ($noamble == 0) - { - # this will add the character table to all files except those that use \nopreamble - - print INS ",package"; - } - - print INS "}}\n"; - } - - print INS "}\n\n"; - - print INS "\\endbatchfile\n"; - - close INS; -} - -sub syntaxerror -{ - die "Syntax : makedtx [options] <basename>\nUse -h for help\n"; -} - -sub help -{ - print "makedtx Help\n\n"; - - print "Current Version : $version\n\n"; - - print "usage : makedtx [options] -src \"<expr>=><expr>\" -doc <filename> <basename>\n\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"; - - print "-src \"<expr1>=><expr2>\"\n"; - print "The command line switch -src identifies the original source code and the name\n"; - print "of the file to which it will utimately be extracted on latexing the ins file\n"; - print "<expr1> can be a Perl expression, such as (foo)src.(sty), and <expr2> can\n"; - print "a Perl substitution style expression, such as $1.$2\n"; - print "Note that double quotes must be used to prevent shell expansion\n"; - print "Multiple invocations of -src are permitted\n"; - print "See examples below.\n\n"; - - print "-doc <filename>\n"; - print "The name of the documentation source code. This should be a LaTeX2e document\n\n"; - - print "Optional Arguments:\n\n"; - - print "-dir <directory> : search for source files in <directory>\n"; - print "-op <character> : set the pattern matching operator (default '$patternop')\n"; - print "-askforoverwrite : set askforoverwrite switch in INS file to true\n"; - print "-noaskforoverwrite : set askforoverwrite switch in INS file to false (default)\n"; - print "-preamble <text> : set the preamble. Standard one inserted if omitted\n"; - print "-postamble <text> : set the postamble.\n"; - print "-setambles \"<pattern>=><text>\" : set pre- and postambles to <text> if file matches pattern\n"; - print "-author <text> : name of author (inserted into standard preamble. User name inserted if omitted)\n"; - print "-date <text> : copyright date\n"; - print "-ins : create the ins file (default)\n"; - print "-noins : don't create the ins file\n"; - print "-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 "-license <license> : use the given license for the preamble.\n"; - print " Known licenses: lppl (default), bsd, gpl.\n"; - print "-h : help message\n"; - print "-v : verbose\n\n"; - - print "Examples:\n\n"; - - print "Example 1:\n"; - print "Documenation is in foodoc.tex\n"; - print "Source code is in foosrc.sty. The final extracted version should be \n"; - print "called foo.sty. The dtx file should be called foo.dtx and the ins file\n"; - print " should be called foo.ins\n\n"; - - print "makedtx -src \"foosrc\\.sty=>foo.sty\" -doc foodoc.tex foo\n\n"; - - print "Example 2:\n"; - print "Documenation is in bardoc.tex\n"; - print "Source code is in barsrc.sty. The final extracted version should be\n"; - print "called bar.sty. Source code is also in barsrc.bst. The final extracted\n"; - print "version should be called bar.bst. The dtx file should be called bar.dtx and\n"; - print "the ins file should be called bar.ins\n\n"; - - print "makedtx -src \"barsrc\\.sty=>bar.sty\" -src \"barsrc\\.bst=>bar.bst\" -doc bardoc.tex bar\n\n"; - - print "Or\n\n"; - - print "makedtx -src \"barsrc\\.(bst|sty)=>bar.\$1\" -doc bardoc.tex bar\n\n"; - - die; -} - -sub eatinitialspaces -{ - my ($STR) = @_; - - while (substr($STR,0,1) eq "\s") - { - $STR = substr($STR,1); - } - - return $STR; -} - -sub getnextgroup -{ - my($curline) = @_; - - $curline = &eatinitialspaces($curline); - - # check to see if current string is blank - - if ($curline!~/[^\s]+/m) - { - return ("","",0); - } - - if (($group = substr($curline,0,1)) ne "{") - { - # next group hasn't been delimited with braces - # return first non-whitespace character - - $curline = substr($curline,1); - - # unless it's a backslash, in which case get command name - - if ($group eq "\\") - { - if ($curline=~/([a-zA-Z]+)(^[a-zA-Z].*)/m) - { - $group = $1; - - $curline = $2; - } - else - { - # command is made up of backslash followed by symbol - - $curline=~/([\W_0-9\s\\])(.*)/m; - - $group = $1; - - $curline = $2; - } - } - - return ($group,$curline,1); - } - - my $pos=index($curline, "{"); - my $startpos=$pos; - my $posopen=0; - my $posclose=0; - - my $bracelevel = 1; - - my $done=0; - - while (!$done) - { - $pos++; - - $posopen = index($curline, "{", $pos); - - # check to make sure it's not a \{ - - while ((substr($curline, $posopen-1,1) eq "\\") and ($posopen > 0)) - { - # count how many backlashes come before it. - - $i = $posopen-1; - - $numbs = 1; - - while ((substr($curline, $i-1,1) eq "\\") and ($i > 0)) - { - $numbs++; - $i--; - } - - # is $numbs is odd, we have a \{, otherwise we have \\{ - - if ($numbs%2 == 0) - { - last; - } - else - { - $posopen = index($curline, "{", $posopen+1); - } - } - - $posclose= index($curline, "}", $pos); - - # check to make sure it's not a \} - - while ((substr($curline, $posclose-1,1) eq "\\") and ($posclose > 0)) - { - # count how many backlashes come before it. - - $i = $posclose-1; - - $numbs = 1; - - while ((substr($curline, $i-1,1) eq "\\") and ($i > 0)) - { - $numbs++; - $i--; - } - - # is $numbs is odd, we have a \}, otherwise we have \\} - - if ($numbs%2 == 0) - { - last; - } - else - { - $posclose = index($curline, "}", $posclose+1); - } - } - - if (($posopen==-1) and ($posclose==-1)) - { - $done=1; - } - elsif ($posopen==-1) - { - $pos=$posclose; - - $bracelevel--; - - if ($bracelevel==0) - { - $group = substr($curline, $startpos+1, $pos-$startpos-1); - - $curline = substr($curline, $pos+1); - - return ($group,$curline,1); - } - } - elsif ($posclose==-1) - { - $pos=$posopen; - - $bracelevel++; - } - elsif ($posopen<$posclose) - { - $pos=$posopen; - - $bracelevel++; - } - elsif ($posclose<$posopen) - { - $pos=$posclose; - - $bracelevel--; - - if ($bracelevel==0) - { - $group = substr($curline, $startpos+1, $pos-$startpos-1); - - $curline = substr($curline, $pos+1); - - return ($group,$curline,1); - } - } - } - - # closing brace must be on another line - - return ("", $curline, 0); -} -1; |