From 9400888610cff531773a7fea1602494e3e99c20f Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 3 Nov 2015 18:29:45 +0000 Subject: makedtx script (Rolf mail, 2 Nov 2015 19:08:19) git-svn-id: svn://tug.org/texlive/trunk@38769 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/support/makedtx/CHANGES | 19 + Master/texmf-dist/doc/support/makedtx/README | 32 + .../texmf-dist/doc/support/makedtx/creatdtx.perl | 72 ++ .../doc/support/makedtx/makedtx-manual.html | 971 +++++++++++++++++++++ Master/texmf-dist/doc/support/makedtx/makedtx.pdf | Bin 0 -> 202740 bytes 5 files changed, 1094 insertions(+) create mode 100644 Master/texmf-dist/doc/support/makedtx/CHANGES create mode 100644 Master/texmf-dist/doc/support/makedtx/README create mode 100644 Master/texmf-dist/doc/support/makedtx/creatdtx.perl create mode 100644 Master/texmf-dist/doc/support/makedtx/makedtx-manual.html create mode 100644 Master/texmf-dist/doc/support/makedtx/makedtx.pdf (limited to 'Master/texmf-dist/doc/support') diff --git a/Master/texmf-dist/doc/support/makedtx/CHANGES b/Master/texmf-dist/doc/support/makedtx/CHANGES new file mode 100644 index 00000000000..cbd18311fda --- /dev/null +++ b/Master/texmf-dist/doc/support/makedtx/CHANGES @@ -0,0 +1,19 @@ +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/support/makedtx/README b/Master/texmf-dist/doc/support/makedtx/README new file mode 100644 index 00000000000..e4abbba5d90 --- /dev/null +++ b/Master/texmf-dist/doc/support/makedtx/README @@ -0,0 +1,32 @@ +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/support/makedtx/creatdtx.perl b/Master/texmf-dist/doc/support/makedtx/creatdtx.perl new file mode 100644 index 00000000000..9149cba164b --- /dev/null +++ b/Master/texmf-dist/doc/support/makedtx/creatdtx.perl @@ -0,0 +1,72 @@ +# 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); + + "\$name$_"; +} + +sub do_cmd_marg{ + local($_) = @_; + local($arg); + + $arg = &missing_braces unless + (s/$next_pair_pr_rx/$arg=$2;''/eo); + + "{$arg}$_"; +} + +sub do_cmd_oarg{ + local($_) = @_; + local($arg); + + $arg = &missing_braces unless + (s/$next_pair_pr_rx/$arg=$2;''/eo); + + "[$arg]$_"; +} + +sub do_cmd_parg{ + local($_) = @_; + local($arg); + + $arg = &missing_braces unless + (s/$next_pair_pr_rx/$arg=$2;''/eo); + + "($arg)$_"; +} + +&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/support/makedtx/makedtx-manual.html b/Master/texmf-dist/doc/support/makedtx/makedtx-manual.html new file mode 100644 index 00000000000..4438c92c219 --- /dev/null +++ b/Master/texmf-dist/doc/support/makedtx/makedtx-manual.html @@ -0,0 +1,971 @@ + + + + + +makedtx v0.94b : a Perl script to help create a DTX file from source code + + + + + + + + + + + + + + +

makedtx v0.94b : a Perl script to help create a DTX +file from source code

+

Nicola Talbot +
http://theoval.cmp.uea.ac.uk/~nlct/

+

19th August 2007

+ +

+
+ +

+Contents +

+ + + + +

+ +

Abstract:

+
+The 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. +
+

+ +

+ +

+Introduction +

+ +

+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 .sty, .cls, .def +etc files. However, having the documentation and code bundled +together can cause problems if a developer wants to, say, use +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 PDFLaTeX? The more general purpose packages that I write (such +as datetime and 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, + doesn't work on a .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 +script1. + +

+This document is structured as follows: Section 2 +describes how to install the makedtx bundle, +Section 3 gives an overview of the makedtx.pl +Perl script, Section 4 describes the +creatdtx package, Section 5 illustrates the +use of the makedtx bundle with examples and +Section 6 gives a list of possible errors and their +solutions. + +

+ +


+Installation +

+ +

+You need to download both makedtx.dtx and +makedtx.ins, and run the installation script through +LaTeX: +

+latex makedtx.ins + +

+The following files will be created: +

+
makedtx.pl
+
Perl script +
+
creatdtx.sty
+
LaTeX package for use with makedtx.pl +
+
creatdtx.perl
+
Corresponding Perl script for use with LaTeX2HTML +
+
+ +

+If you are using UNIX/Linux etc you will need to make +makedtx.pl executable using +chmod: +

+
+
chmod a+x +makedtx.pl +

+
+
and place it somewhere on your +path. If perl is located somewhere other than +/usr/bin/ you will need to edit the first line of +makedtx.pl. (If you don't know where perl is +located, you can use the command: which perl.) The package +creatdtx.sty needs to be placed somewhere on the LaTeX path +and creatdtx.perl should be placed in a directory searched by +. (See the documentation for details.) + +

+ +


+makedtx.pl +

+ +

+The Perl script makedtx.pl has the following syntax: +

+makedtx.pl [options] -src +"expr1=>expr2" +-doc filename basename + +

+ +

+Compulsory Arguments +

+ +

+The very last argument basename is the basename of the +.dtx and .ins files you want to create. The +-doc filename switch indicates the file containing the +documentation and -src +"expr1=>expr2" indicates the +original source file(s), given by expr1, and the corresponding +file name when it has been extracted from the .dtx file, +given by expr2. This switch is a little complicated, so it's +best described using examples. + +

+Suppose you have your documentation in the file foodoc.tex, +and the original source code is in the file foosrc.sty. You +want to create the files foo.dtx and foo.ins. When +you LaTeX foo.dtx you want the documentation as specified +in foodoc.tex and when you LaTeX foo.ins you want +the file foo.sty to be created, using the code specified in +foosrc.sty. You will need to do: +

+makedtx.pl -src "foosrc\.sty=>foo.sty" -doc foodoc.tex foo
+
+ +

+You may have multiple invocations of the -src switch. For +example, suppose you also have the file barsrc.sty which you +want to be extracted from the .dtx file as bar.sty, +you can do: +

+makedtx.pl -src "foosrc\.sty=>foo.sty" -src "barsrc\.sty=>bar.sty" -doc foodoc.tex foo
+
+Alternatively, you can use Perl-type regular expressions: +
+makedtx.pl -src "(.*)src\.sty=>\1.sty" -doc foodoc.tex foo
+
+(Note the use of double quotes to prevent shell expansion.) +Appendix A gives a brief overview of Perl regular +expressions for the uninitiated. + +

+ +

+Options +

+ +

+

+
-h or -help
+
Prints on-line help, and exits. + +

+

+
-version
+
Prints version number, and exits. + +

+

+
-v
+
Uses verbose mode. + +

+

+
-dir name
+
Specifies directory containing source +files, as specified by the -src switch. For example, suppose +you have source files foo.sty, bar.sty in the +subdirectory sourcefiles you can do: +
+makedtx.pl -dir sourcefiles -src "(.*)\.sty=>\1.sty" -doc foodoc.tex foo
+
+ +

+

+
-op character
+
sets the Perl pattern matching +operator (the default is set to = symbol since the / +character is used as the directory divider). + +

+

+
-askforoverwrite
+
uses \askforoverwritetrue in +the installation script. + +

+

+
-noaskforoverwrite
+
uses \askforoverwritefalse +in the installation script (default). + +

+

+
-noins
+
Don't create the installation script +(.ins file). This is useful if you want to tweak the file +manually and you don't want your modifications overwritten. + +

+

+
-preamble text
+
Set the preamble to +text. The default preamble is: +

+ + basename.dtx + Copyright date 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. + +

+This work consists of the files basename.dtx and + basename.ins and the derived files file list. + + +

+where date is the copyright date, and author is the +author's name (see below). + +

+Note that this has been changed as of makedtx v0.94. +Older versions of makedtx do not conform to any of the free +licenses. + +

+

+
-license name
+
This sets the preamble to +the license text for the license name. Currently name +may be either lppl (the default, which produces the +default preamble detailed above), bsd or gpl. +You may use either -license or -preamble, +but not both. (If you have used the -preamble switch, the +-license switch will be ignored.) + +

+

+
-postamble text
+
Set the postamble to +text. If this is omitted the \postamble command is +omitted from the installation script. + +

+

+
-author name
+
The author's name (as used in the +default preamble). If omitted the user's name is used. + +

+

+
-date text
+
The copyright date (as used in the +default preamble). If omitted the current year is used. + +

+

+
-stopeventually text
+
Insert text into the +argument of \StopEventually. For example: +-stopeventually "\\PrintIndex" will result in the line: +\StopEventually{\PrintIndex}. If makedtx.pl +encounters a \StopEventually command within the document, +this will be used instead. If there is no \StopEventually +command in the document and the -stopeventually switch is +absent \StopEventually{} will be inserted in the DTX +file. + +

+

+
-prefinale text
+
Inset text immediately prior to \Finale +in the dtx file. + +

+

+
-setambles "expr=>text"
+
Sets the pre- and postambles for files matching expr within the +\file command in the installation script. To illustrate this, +let's suppose you have source files foo.sty, bar.sty +and foobar.pl in the subdirectory sourcefiles. +Since foo.sty and bar.sty are LaTeX files, they +should have pre- and postambles, but 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: +
+makedtx.pl -dir sourcefiles -src "(.*)\.sty=>\1.sty" -src "foobar.pl=>foobar.pl" 
+-setambles "foobar\.pl=>\\nopreamble\\nopostamble" -doc foodoc.tex foo
+
+(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 -setambles contains the string +\\nopreamble, the character table will be excluded from the +corresponding files. So, in the above example, when you do: +latex foo.ins the resulting files foo.sty and +bar.sty will contain the character table, but +foobar.pl won't. (If for some reason you don't want a +preamble but you do want the character table included use +\\usepreamble\\empty instead of \\nopreamble. +Conversely, if you want a preamble but don't want the character table +do something like \\nopreamble\\usepreamble\\defaultpreamble. + +

+Note that the =>text part is optional. If it is +omitted, text is assumed to be empty. + +

+

+
-macrocode "expr"
+
If source +file matches the Perl regular expression given by expr, the +source code is inserted into a macrocode environment in the +DTX file. + +

+

+
-comment "expr"
+
If the source file matches the Perl regular expression given by +expr, the source code will be inserted between \iffalse +\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 +-comment switch will typically need to be used in conjunction +with -macrocode. + +

+

+
-codetitle "title"
+
This sets the title for the code section. The default is +The Code. +
+
+ +

+ +

+
+The creatdtx Package +

+ +

+The documentation source code, as specified using the -doc +switch will typically be a standard LaTeX document using the +ltxdoc class file. Unlike the DTX file, there is no +\DocInput 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 creatdtx package +can be used in this document using +

+\usepackage{creatdtx}
+
+although this package will be not be included in the DTX file by +makedtx.pl. There is only one command defined in this +package:\ifmakedtx{dtx text}{non dtx text}. The first +argument dtx text will be copied to the DTX file by +makedtx.pl, but the second argument 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 foodoc.tex) contains the +line: +

+
+
\ifmakedtx{}{\usepackage{html}} + +

+
+
the html package will only be +loaded if you LaTeX foodoc.tex, but not when you LaTeX foo.dtx. + +

+The Perl script creatdtx.perl ignores the following commands +(and any associated arguments): \OnlyDescription, +\RecordChanges, \MakeShortVerb, \DeleteShortVerb, +\DoNotIndex, \EnableCrossrefs, \CodelineIndex, +\GetFileInfo, \PrintChanges, \changes, \CheckSum, +\DescribeMacro and \DescribeEnvironment. So even if you don't +use the \ifmakedtx command, using the creatdtx package +will help ensure that extraneous text does not appear in the HTML +document when using . + +

+As from version 0.93b, creatdtx.perl also defines the +commands \cs, \marg, \oarg and \parg, since there +is no implementation of the ltxdoc class file. + +

+ +

+
+Examples +

+ +

+Let's first consider a very simple example. Suppose you want to +create a package that redefines \today so that the date is +displayed in the form: yyyy-m-d. Let's call this package +dashdate. The file dashdate.sty should look +something like: +

+ % 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}
+
+Now let's make some (very brief) documentation. Let's call the file, +say manual.tex2: +
+\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}
+
+Suppose you have saved dashdate.sty and manual.tex +in the subdirectory source. You can now create the +.dtx and .ins file using the command: +
+makedtx.pl -author "AN Other" -dir source -src "dashdate\.sty=>dashdate.sty" 
+-doc source/manual.tex dashdate
+
+The file dashdate.dtx is created, and contains the following +code: +
+ %\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
+
+The installation file dashdate.ins looks like: +
+ % 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
+
+Note that the command \usepackage{creatdtx} has not been +transcribed to 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 . This will need to be called +dashdate.perl and will look something like: +

+package main;
+
+sub do_cmd_today{
+   local($_) = @_;
+   local($today) = &get_date();
+   $today =~ s|(\d+)/(\d+)/(\d+)|$3-$1-$2|;
+   "$today$_";
+}
+
+1;
+
+You will now need to call makedtx.pl as follows: +
+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
+
+(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: +
+makedtx.pl -author "AN Other" -dir source -src "dashdate\.(.*)=>dashdate.\1"
+-setambles "dashdate\.perl=>\\nopreamble\\nopostamble" -macrocode "dashdate\.perl"
+-doc source/manual.tex dashdate
+
+Note the use of the -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 -macrocode +switch. This is not needed for dashdate.sty since it has +already been included in the source code, but since % is not a +comment character in Perl, the 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 macrocode +environment, I suggest you read either A guide to +LaTeX [2, Appendix D] or The LaTeX companion [1, Chapter 14].) + +

+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 -macrocode switch, you would then also need to use +the -comment switch: +

+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
+
+ +

+As another example, consider the datetime package. Version +2.42 of this package has 2 .sty files and 42 .def +files. The documentation is written in the file manual.tex, +and the .sty and .def files are saved in a +subdirectory called source. Since these are the only files +in this directory, they can easily be merged into one .dtx +file using: +

+makedtx.pl -author "Nicola Talbot" -dir source -src "(.+)\.(.+)=>\1.\2" 
+-doc manual.tex datetime
+
+This creates the files datetime.dtx and datetime.ins which can then be distributed. The PDF version +of the documentation is obtained by doing: +
+pdflatex datetime.dtx
+
+and the HTML version (manual.html) is obtained by doing: +
+latex2html -split 0 -nonavigation -nofootnode -numbered_footnotes -noinfo manual
+
+Any minor differences between the HTML and PDF versions are dealt by +using \ifmakedtx in the original file manual.tex. + +

+ +

+
+Troubleshooting +

+ +

+The 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). + +

+ +

+Known Bugs +

+ +

+It's possible to confuse makedtx.pl by placing either the +command \end{document} or the command \ifmakedtx in a +\verb command, or by having the \ifmakedtx command on the same +line as \begin{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 %% in the +.dtx file, which has a special meaning. Either place a space +immediately prior the percent symbol, or do \relax% if you +really don't want the extra space (or place your comment in an +\iffalse ... \fi conditional). + +

+ +

+Possible errors encountered using makedtx.pl +

+ +

+Note: be careful to use double quotes around arguments that contain +characters that the shell might try interpreting, e.g. * or +>. + +

+Syntax error messages: + +

    +
  1. No document source specified (missing -doc) + +

    +You must use the -doc switch. + +

    +

  2. +
  3. No source code specified (missing -src) + +

    +You must specify at least one -src switch. + +

    +

  4. +
  5. No basename specified + +

    +You must specify the basename of the .dtx and .ins files. This should +be the last argument passed to makedtx.pl. + +

    +

  6. +
  7. -src ... argument invalid (no output file specified) + +

    +You have omitted the => separator in the argument of the +-src switch. + +

    +

  8. +
  9. -src argument ... invalid (too many => specified) + +

    +You have used too many => separators in the argument of the +-src switch. (Similarly for the -setambles switch.) +

  10. +
+ +

+ +

+ +

+
+Perl Regular Expressions +

+ +

+This section gives a very brief overview of Perl regular expressions. For more detail, look at the Perl +documentation (use man perlre for the man page.) + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
\Quote the next character
.Match any character
|Alternation
()Grouping
[]Character class
*Match 0 or more times
+Match 1 or more times
?Match 1 or 0 times
{n}Match exactly n times
{n,}Match at least n times
{n,m}Match at least n but no more than m times.
+ +

+In the replacement text, a backslash followed by a number n indicates the text from the nth group. + +

+For example, suppose you have the following files: +

+abcsrc.sty
+abcsrc.bst
+abcsrc.perl
+foosrc.sty
+foobarsrc.sty
+
+then if you pass the following switch to makedtx.pl: + + + +

+ +

+ + +

+Bibliography +

1 +
The LaTeX companion. Michel Goossens, Frank Mittelbach and Alexander Samarin. +Addison-Wesley 1993. + +

+

2 +
A guide to LaTeX. Helmut Kopka and Patrick W. Daly. Addison-Wesley 1998. +
+ +

Footnotes

+
+
... +script1
+
or at least, it's laborious if there are rather a lot +of files associated with a package + +
+
...manual.tex2
+
Note: if you want to use + on this document, you will need to use, e.g., +\verb!\today! instead of +|\today| since it doesn't recognise +\MakeShortVerb. + +
+


+
+Nicola L. C. Talbot. +School of Computing Sciences. +University of East Anglia. +Last Modified: 2007-08-19 +
+ + diff --git a/Master/texmf-dist/doc/support/makedtx/makedtx.pdf b/Master/texmf-dist/doc/support/makedtx/makedtx.pdf new file mode 100644 index 00000000000..79a8b5e822b Binary files /dev/null and b/Master/texmf-dist/doc/support/makedtx/makedtx.pdf differ -- cgit v1.2.3