add man page of latexmk to texfm/doc/man/man1 and to the tlpsrc file

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

1 files changed, 1609 insertions, 0 deletions

diff --git a/Master/texmf/doc/man/man1/latexmk.1 b/Master/texmf/doc/man/man1/latexmk.1
new file mode 100644
index 00000000000..5ef13279d0e
--- /dev/null
+++ b/Master/texmf/doc/man/man1/latexmk.1
@@ -0,0 +1,1609 @@
+.TH LATEXMK 1L "24 November 2009" ""
+.SH NAME
+latexmk \- generate LaTeX document
+.SH SYNOPSIS
+.B latexmk [options] [file ...] 
+.SH DESCRIPTION
+.I Latexmk
+completely automates the process of compiling a LaTeX document.
+Essentially, it is like a specialized relative of the general
+\fImake\fR utility, but one which determines dependencies
+automatically and has some other very useful features.  In its basic
+mode of operation \fIlatexmk\fR is given the name of the primary
+source file for a document, and it issues the appropriate sequence of
+commands to generate a .dvi, .ps, .pdf and/or hardcopy version of the
+document.  
+.PP
+By default \fIlatexmk\fR will run the commands necessary to generate a
+.dvi file.
+.PP
+\fILatexmk\fR can also be set to run continuously with a suitable
+previewer.  In that case the LaTeX program, etc, are rerun whenever
+one of the source files is modified, and the previewer automatically
+updates the on-screen view of the compiled document.
+.PP
+\fILatexmk\fR determines which are the source files by examining the
+log file.  When \fIlatexmk\fR is run, it examines properties of the
+source files, and if any have been changed since the last document
+generation, \fIlatexmk\fR will run the various LaTeX processing
+programs as necessary.  In particular, it will repeat the run of LaTeX
+(or pdflatex) often enough to resolve all cross references; depending
+on the macro packages used.  With some macro packages and document
+classes, four, or even more, runs may be needed. If necessary,
+\fIlatexmk\fR will also run bibtex and/or makeindex.  In addition,
+\fIlatexmk\fR can be configured to generate other necessary files.
+For example, from an updated figure file it can automatically generate
+a file in encapsulated postscript or another suitable format for
+reading by LaTeX.
+.PP
+\fILatexmk\fR has two different previewing options.  In the simple
+\fB-pv\fR option, a dvi, postscript or pdf previewer is automatically
+run after generating the dvi, postscript or pdf version of the
+document.  The type of file to view is selected according to
+configuration settings and command line options.
+.PP
+The second previewing option is the powerful \fB-pvc\fR option
+(mnemonic: "preview continuously").  In this case, \fIlatexmk\fR runs
+continuously, regularly monitoring all the source files to see if any
+have changed.  Every time a change is detected, \fIlatexmk\fR runs all
+the programs necessary to generate a new version of the document.  A
+good previewer (like \fIgv\fR) will then automatically update its
+display.  Thus the user can simply edit a file and, when the changes
+are written to disk, \fIlatexmk\fR completely automates the cycle of
+updating the .dvi (and possibly the .ps and .pdf) file, and refreshing
+the previewer's display.  It's not quite WYSIWYG, but usefully close.
+.PP
+For other previewers, the user may have to manually make the previewer
+update its display, which can be (some versions of xdvi and gsview) as
+simple as forcing a redraw of its display.
+.PP
+\fILatexmk\fR has the ability to print a banner in gray diagonally
+across each page when making the postscript file.  It can also, if
+needed, call an external program to do other postprocessing on the
+generated files.
+.PP
+\fILatexmk\fR is highly configurable, both from the command line and
+in configuration files, so that it can accommodate a wide variety of
+user needs and system configurations.  Default values are set
+according to the operating system, so \fIlatexmk\fR often works 
+without special configuration on MS-Windows, cygwin, Linux, OS-X, and
+other UNIX systems (notably Solaris).
+.PP
+A very annoying complication handled very reliably by \fILatexmk\fR,
+is that LaTeX is a multiple pass system.  On each run, LaTeX reads in
+information generated on a previous run, for things like cross
+referencing and indexing.  In the simplest cases, a second run of
+LaTeX suffices, and often the log file contains a message about the
+need for another pass.  However, there is a wide variety of add-on
+macro packages to LaTeX, with a variety of behaviors.  The result is
+to break simple-minded determinations of how many runs are needed and
+of which programs.  In its new version, \fIlatexmk\fR has a highly
+general and efficient solution to these issues.  The solution involves
+retaining between runs information on the source files, and a symptom
+is that \fIlatexmk\fR generates an extra file (with extension
+\fR.fdb_latexmk\fR, by default) that contains the source file
+information.
+
+.SH LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE
+(All options can be introduced by single or double "-" characters,
+e.g., "latexmk -help" or "latexmk --help".)
+.TP
+.B file
+One or more files can be specified.  If no files are specified,
+\fIlatexmk\fR will, by default, run on all files in the current working directory
+with a ".tex" extension.  This behavior can be changed: see the
+description concerning the \fI@default_files\fR variable in the
+section "List of configuration variables usable in initialization
+files". 
+.PP
+If a file is specified without an extension, then the ".tex" extension
+is automatically added, just as LaTeX does.  Thus, if you specify:
+
+	latexmk foo
+
+then \fIlatexmk\fR will operate on the file "foo.tex".  
+.TP
+.B -bm <message>
+A banner message to print diagonally across each page when converting
+the dvi file to postscript.  The message must be a single argument on
+the command line so be careful with quoting spaces and such.
+
+Note that if the \fB-bm\fR option is specified, the \fB-ps\fR option is
+assumed.
+.TP
+.B -bi <intensity>
+How dark to print the banner message.  A decimal number between 0 and 1.
+0 is black and 1 is white.  The default is 0.95, which is OK unless your
+toner cartridge is getting low.
+.TP
+.B -bs <scale>
+A decimal number that specifies how large the banner message will be
+printed.  Experimentation is necessary to get the right scale for your
+message, as a rule of thumb the scale should be about equal to 1100
+divided by the number of characters in the message.  The default is 220.0
+which is just right for 5 character messages.
+.TP 
+.B -commands
+List the commands used by \fIlatexmk\fR for processing files, and then
+exit. 
+.TP 
+.B -c
+Clean up (remove) all regeneratable files generated by \fIlatex\fR and
+\fIbibtex\fR except dvi, postscript and pdf.  These files are a
+combination of log files, aux files, latexmk's database file of source
+file information, 
+and those with extensions
+specified in the \fI@generated_exts\fR configuration variable.  In addition,
+files with extensions by the \fI$clean_ext\fR configuration variable are
+removed.  
+
+This cleanup is instead of a regular make.  See the \fB-gg\fR option
+if you want to do a cleanup then a make.
+.TP 
+.B -C
+Clean up (remove) all regeneratable files generated by \fIlatex\fR and
+\fIbibtex\fR.  This is the same as the \fB-c\fR option with the
+addition of dvi, postscript and pdf files, and those with extensions
+in the \fI$clean_full_ext\fR configuration variable.
+
+This cleanup is instead of a regular make.  See the \fB-gg\fR option
+if you want to do a cleanup than a make.
+.TP 
+.B -CA
+Clean up (remove) absolutely all regeneratable files.  It is now
+equivalent to the \fB-C\fR option
+
+This cleanup is instead of a regular make.  
+See the \fB-gg\fR option if you want to do a cleanup then a
+make.
+.TP 
+.B -CF
+Remove the file containing the database of source file information,
+before doing the other actions requested.
+.TP 
+.B -d
+Set draft mode.  This prints the banner message "DRAFT" across your
+page when converting the dvi file to postscript.  Size and intensity
+can be modified with the \fB-bs\fR and \fB-bi\fR options.  The \fB-bm\fR
+option will override this option as this is really just a short way of
+specifying:
+
+	latexmk -bm DRAFT
+
+Note that if the \fB-d\fR option is specified, the \fB-ps\fR option is
+assumed.
+.TP
+.B -dF
+Dvi file filtering.  The argument to this option is a filter which will
+generate a filtered dvi file with the extension ".dviF".  All extra
+processing (e.g. conversion to postscript, preview, printing) will then
+be performed on this filtered dvi file.
+
+Example usage: To use dviselect to select only the even pages of the dvi file:
+
+	latexmk -dF 'dviselect even' foo.tex
+.TP
+.B -diagnostics
+Print detailed diagnostics during a run.  This may help for debugging
+problems or to understand \fI.latexmk\fR's behavior in difficult
+situations. 
+.TP
+.B -dvi
+Generate dvi version of document.
+.TP
+.B -dvi-
+Turn off generation of dvi version of document.  (This may get
+overridden, if some other file is made (e.g., a .ps file) that is
+generated from the dvi file, or if no generated file at all is
+requested.) 
+.TP
+.B -e <code>
+Execute the specified initialization code before processing.  The code
+is \fIPerl\fR code of the same form as is used in \fIlatexmk\fR's
+initialization files -- for more details, see the information on the
+\fB-r\fR option, and the section about "Configuration/initialization
+(RC) files".  The code is typically a sequence of assignment
+statements separated by semicolons.
+
+The code is executed when the \fB-e\fR option is encountered during
+\fIlatexmk\fR's parsing of its command line.  See the \fB-r\fR option
+for a way of executing initialization code from a file.  An error
+results in \fIlatexmk\fR stopping.  Multiple instances of the \fB-r\fR
+and \fB-e\fR options can be used, and they are executed in the order
+they appear on the command line.
+
+Some care is needed to deal with proper quoting of special characters
+in the code on the command line.  For example, suppose you want
+to set the latex command to use its -shell-escape option, then under
+UNIX/LINUX you could use the line
+
+	latexmk -e '$latex=q/latex %O -shell-escape %S/' file.tex
+
+Note that the single quotes block normal UNIX/LINUX command shells
+from treating the characters inside the quotes as special.
+(In this example, the q/.../ construct is a
+\fIPerl\fR idiom equivalent to using 
+single quotes.  This avoids the complications of getting a quote
+character inside an already quoted string in a way that is independent
+of both the shell and the operating-system.)
+
+The above command line will NOT work under MS-Windows with cmd.exe or
+command.com or 4nt.exe.  For MS-Windows with these command shells you
+could use
+
+	latexmk -e "$latex=q/latex %O -shell-escape %S/" file.tex
+
+or
+
+	latexmk -e "$latex='latex %O -shell-escape %S'" file.tex
+
+The last two examples will NOT work with UNIX/LINUX command shells.
+.TP
+.B -f
+Force \fIlatexmk\fR to continue document processing despite errors.
+Normally, when \fIlatexmk\fR detects that LaTeX or another program has
+found an error which will not be resolved by further processing, no
+further processing is carried out.
+.TP
+.B -f-
+Turn off the forced processing-past-errors such as is set by the
+\fB-f\fR option.  This could be used to override a setting in a
+configuration file.
+.TP
+.B -g
+Force \fIlatexmk\fR to process document fully, even under situations
+where \fIlatexmk\fR would normally decide that no changes in the
+source files have occurred since the previous run. 
+This option is useful, for example, if you change some options and
+wish to reprocess the files.
+.TP
+.B -g-
+Turn off \fB-g\fR.
+.TP
+.B -gg
+"Super go mode" or "clean make": clean out generated files as if
+\fB-CA\fR had been given, and then do a regular make.
+.TP
+.B -h, -help
+Print help information.
+.TP
+.B -l
+Run in landscape mode, using the landscape mode for the previewers and
+the dvi to postscript converters.  This option is not normally needed
+nowadays, since current previewers normally determine this information
+automatically. 
+.TP
+.B -l-
+Turn off \fB-l\fR.
+.TP
+.B -new-viewer
+When in continuous-preview mode, always start a new viewer to view the
+generated file.  By default, \fIlatexmk\fR will, in continuous-preview
+mode, test for a previously running previewer for the same file and
+not start a new one if a previous previewer is running.  However, its
+test sometimes fails (notably if there is an already-running previewer
+that is viewing a file of the same name as the current file, but in a
+different directory).  This option turns off the default behavior.
+.TP
+.B -new-viewer-
+The inverse of the \fB-new-viewer\fR option.  It puts \fIlatexmk\fR
+in its normal behavior that in preview-continuous mode it checks for
+an already-running previewer.  
+.TP
+.B -p
+Print out the document.  By default it is
+the generated postscript file that is printed.  But you can use the
+\fB-print=...\fR option to print the dvi or pdf files instead, and you
+can configure this in a start up file (by setting the
+\fI$print_type\fR variable).  
+
+However, printing is enabled by default only under UNIX/LINUX systems,
+where the default is to use the lpr command.  In general, the correct
+behavior for printing very much depends on your system's software.  In
+particular, under MS-Windows you must have suitable program(s)
+available, and you must have configured the print commands used by
+\fIlatexmk\fR.  This can be non-trivial.  See the documentation on the
+\fI$lpr\fR, \fI$lpr_dvi\fR, and \fI$lpr_pdf\fR configuration variables
+to see how to set the commands for printing.
+
+This option is incompatible with the \fB-pv\fR and \fB-pvc\fR options,
+so it turns them off. 
+.TP
+.B -pdf
+Generate pdf version of document using pdflatex.
+.TP
+.B -pdfdvi
+Generate pdf version of document from the dvi file, by default using dvipdf.
+.TP
+.B -pdfps
+Generate pdf version of document from the ps file, by default using
+ps2pdf. 
+.TP
+.B -pdf-
+Turn off generation of pdf version of document.  
+(This can be used to override a setting in a configuration file.
+It may get overridden if some other option requires the generation of
+a pdf file.)
+.TP
+.B -print=dvi, -print=ps, -print=pdf
+Define which kind of file is printed.  This option also ensures that
+the requisite file is made, and turns on printing.  The default is to
+print a postscript file.
+.TP
+.B -ps
+Generate postscript version of document.
+.TP
+.B -ps-
+Turn off generation of postscript version of document.
+This can be used to override a setting in a configuration file.
+(It may get overridden by some other option that requires a postscript
+file, for example a request for printing.)
+.TP
+.B -pF
+Postscript file filtering.  The argument to this option is a filter
+which will generate a filtered postscript file with the extension
+".psF".  All extra processing (e.g. preview, printing) will then be
+performed on this filtered postscript file.
+
+Example of usage: Use psnup to print two pages on the one page:
+
+	latexmk -ps -pF 'psnup -2' foo.tex
+
+or
+
+	latexmk -ps -pF "psnup -2" foo.tex
+
+Whether to use single or double quotes round the "psnup -2" will
+depend on your command interpreter, as used by the particular version
+of perl and the operating system on your computer.
+.TP
+.B -pv
+Run file previewer.  If the \fB-view\fR option is used, this will select
+the kind of file to be previewed (dvi, ps or pdf).
+Otherwise the viewer views the "highest" kind of file selected, by the
+\fB-dvi\fR, \fB-ps\fR, \fB-pdf\fR, \fB-pdfps\fR options, in the
+order dvi, ps, pdf (low to high).
+If no file type has been selected, the dvi previewer will be used.
+This option is incompatible with the \fB-p\fR and \fB-pvc\fR options,
+so it turns them off.
+.TP
+.B -pv-
+Turn off \fB-pv\fR.
+.TP
+.B -pvc
+Run a file previewer and continually update the .dvi, .ps, and/or .pdf
+files whenever changes are made to source files (see the Description
+above).  Which of these files is generated and which is viewed is
+governed by the other options, and is the same as for the \fB-pv\fR
+option. 
+The preview-continuous option \fB-pvc\fR can only work with one file.
+So in this case you will normally only specify one filename on
+the command line.  It is also incompatible with the 
+\fB-p\fR and \fB-pv\fR options, so it turns these options off
+
+With a good previewer the display will be automatically updated.
+(Under \fIsome but not all\fR versions of UNIX/Linux "gv -watch" does
+this for postscript files; this can be set by a configuration
+variable.  This would also work for pdf files except for an apparent
+bug in gv that causes an error when the newly updated pdf file is
+read.)  Many other previewers will need a manual update.
+
+Important note: the acroread program on MS-Windows locks the pdf file,
+and prevents new versions being written, so it is a bad idea to use
+acroread to view pdf files in preview-continuous mode.  It is better
+to use a dvi or ps viewer, as set by one of the \fB-view=dvi\fR and
+\fB-view=ps\fR options.
+
+There are some other methods for arranging an update, notably useful
+for many versions of xdvi and xpdf.  These are best set in
+\fIlatexmk\fR's configuration; see below. 
+
+Note that if \fIlatexmk\fR dies or is stopped by the user, the
+"forked" previewer will continue to run.  Successive invocations with
+the \fB-pvc\fR option will not fork new previewers, but \fIlatexmk\fR
+will normally use the existing previewer.  (At least this will happen
+when \fIlatexmk\fR is running under an operating system where it knows
+how to determine whether an existing previewer is running.)
+.TP
+.B -pvc-
+Turn off \fB-pvc\fR.
+.TP
+.B -quiet
+Same as -silent
+.TP
+.B -r <rcfile>
+Read the specified initialization file ("RC file") before processing.
+
+Be careful about the ordering: (1) Standard initialization files --
+see the section below on "Configuration/initialization (RC) files" --
+are read first.  (2) Then the options on the command line are acted on
+in the order they are given.  Therefore if an initialization file is
+specified by the \fB-r\fR option, it is read during this second step.
+Thus an initialization file specified with the \fB-r\fR option can
+override both the standard initialization files and \fIpreviously\fR
+specified options.  But all of these can be overridden by \fIlater\fR
+options.
+
+The contents of the RC file just comprise a piece of code in the
+\fIPerl\fR programming language
+(typically a sequence of assignment statements); they are executed
+when the \fB-r\fR option is encountered during \fIlatexmk\fR's parsing
+of its command line.  See the \fB-e\fR option for a way of giving
+initialization code directly on \fIlatexmk\fR's command line.  An
+error results in \fIlatexmk\fR stopping.  Multiple instances of the
+\fB-r\fR and \fB-e\fR options can be used, and they are executed in
+the order they appear on the command line.
+.TP
+.B -silent
+Run commands silently, i.e., with options that reduce the amount of
+diagnostics generated.  For example, with the default settings for
+commands under UNIX, the command "latex -interaction=batchmode" is used
+for latex.
+
+Also reduce the number of informational messages that \fIlatexmk\fR
+generates. 
+.TP
+.B -v, -version
+Print version number of \fIlatexmk\fR.
+.TP
+.B -verbose
+Opposite of \fB-silent\fR.  This is the default setting.
+.TP
+.B -view=default, -view=dvi, -view=ps, -view=pdf
+Set the kind of file used when previewing is requested (e.g., by the
+\fB-pv\fR or \fB-pvc\fR switches).  The default is to view the "highest"
+kind of requested file (in the order dvi, ps, pdf).  
+.PP
+The preview-continuous option \fB-pvc\fR can only work with one file.
+So in this case you will normally only specify one filename on
+the command line.  
+.PP
+Options \fB-p\fR, \fB-pv\fR and \fB-pvc\fR are mutually exclusive.  So
+each of these options turns the others off.
+
+.SH EXAMPLES
+.nf
+.ta 2i
+% \fBlatexmk thesis\fR		\fI# run latex enough times to resolve
+				cross-references\fR 
+
+% \fBlatexmk -pvc -ps thesis\fR	\fI# run latex enough times to resolve
+					cross-references, make a postscript
+					file, start a previewer.  Then
+					watch for changes in the source
+					file thesis.tex and any files it
+					uses.  After any changes rerun latex
+					the appropriate number of times and
+					remake the postscript file.  If latex
+					encounters an error, latexmk will
+					keep running, watching for
+					source file changes.
+
+% \fBlatexmk -c\fR		\fI# remove .aux, .log, .bbl, .blg, .dvi, 
+					.pdf, .ps & .bbl files\fR
+
+
+.SH CONFIGURATION/INITIALIZATION (RC) FILES
+.PP
+\fILatexmk\fR can be customized using initialization files, which are
+read at startup in the following order:
+.PP
+1) The system RC file, if it exists.  
+   On a UNIX system, \fIlatexmk\fR searches for following places for its
+system RC file, in the following order, and reads the first it finds:
+   "/opt/local/share/latexmk/LatexMk",
+   "/usr/local/share/latexmk/LatexMk",
+   "/usr/local/lib/latexmk/LatexMk".
+   On a MS-WINDOWS system it looks for "C:\\latexmk\\LatexMk".
+.PP
+2) The user's RC file, "$HOME/.latexmkrc", if it exists.  Here $HOME
+is the value of the environment variable HOME.  On UNIX and clones
+(including LINUX), this variable is set by the system; on MS-Windows,
+the user may choose to set it.
+.PP
+3) The RC file in the current working directory.  This file can be
+named either "latexmkrc" or ".latexmkrc", and the first of these to be
+found is used, if any.
+.PP
+4) Any RC file(s) specified on the command line with the \fB-r\fR option.
+.PP
+Each RC file is a sequence of \fIPerl\fR commands.  Naturally, a user can use
+this in creative ways.  But for most purposes, one simply uses a
+sequence of assignment statements that override some of the built-in
+settings of \fILatexmk\fR.  Straightforward cases can be handled
+without knowledge of the \fIPerl\fR language by using the examples in this
+document as templates.  Comment lines are introduced by the "#"
+character.
+
+Note that command line options are obeyed in the order in which
+they are written; thus any RC file specified on the command line with
+the \fB-r\fR option can override previous options but can be itself
+overridden by later options on the command line.  There is also the
+\fB-e\fR option, which allows initialization code to be specified in
+\fIlatexmk\fR's command line.
+
+.SH HOW TO SET VARIABLES IN INITIALIZATION FILES
+.PP
+The important variables that can be configured are described in the
+section "List of configuration variables usable in initialization
+files".  Syntax for setting these variables is of the following forms:
+.PP
+	$bibtex = 'bibtex %O %B';
+.PP
+for the setting of a string variable, 
+.PP
+	$preview_mode = 1;
+.PP
+for the setting of a numeric variable, and
+.PP
+	@default_files = ('paper', 'paper1');
+.PP
+for the setting of an array of strings.  It is possible to append an
+item to an array variable as follows:
+
+	push @default_files, 'paper2';
+
+Note that simple "scalar" variables have names that begin with a $
+character and array variables have names that begin with a @
+character. Each statement ends with a semicolon.
+
+Strings should be enclosed in single quotes.  (You could use double
+quotes, as in many programming languages.  But then the \fIPerl\fR
+programming language brings into play some special rules for
+interpolating variables into strings.  People not fluent in \fIPerl\fR
+will want to avoid these complications.)
+
+You can do much more complicated things, but for this you will need to
+consult a manual for the \fIPerl\fR programming language.  
+
+
+
+.SH FORMAT OF COMMAND SPECIFICATIONS
+
+Some of the variables set the commands that \fIlatexmk\fR uses for
+carrying out its work, for example to generate a dvi file from a tex
+file or to view a postscript file.  This section describes some
+important features of how the commands are specified.
+
+\fBPlaceholders\fR:  Supposed you wanted \fIlatexmk\fR to use the
+command elatex in place of the regular latex command, and suppose
+moreover that you wanted to give it the option "--shell-escape".  You
+could do this by the following setting:
+.PP
+     $latex = 'elatex --shell-escape %O %S';
+.PP
+The two items starting with the % character are placeholders.  These
+are substituted by appropriate values before the command is run.  Thus
+%S will be replaced by the source file that elatex will be applied to,
+and %O will be replaced by any options that \fIlatexmk\fR has decided
+to use for this command.  (E.g., if you used the -silent option it
+would replace %O by "-interaction=batchmode".)
+
+The available placeholders are:
+.TP
+.B %B
+base of filename for current command.  E.g., if a postscript file
+document.ps is being made from the dvi file document.dvi, then the
+basename is document.
+.TP
+.B %D
+destination file (e.g., the name of the postscript file when
+converting a dvi file to postscript).
+.TP
+.B %O
+options
+.TP
+.B %R
+root filename.  This is the base name for the main tex file.  
+.TP
+.B %S
+source file (e.g., the name of the dvi file when converting a dvi file
+to ps).
+.TP
+.B %T
+The name of the primary tex file.
+.PP
+If for some reason you need a literal % character in your string not
+subject to the above rules, use a pair of these characters.  Thus with
+the command specification $ps_previewer = 'latex -ad=%%Sfile.ad %S',
+the %%S will become %S when the command is executed, but the %S will
+be replaced by the source filename, which in this case would be the
+name of a postscript file to be viewed. 
+.PP
+Appropriate quoting will be applied to the filename substitutions, so
+you mustn't supply them yourself even if you the names of your have
+spaces in them.  (But if your TeX filenames have spaces in them,
+beware that many versions of the TeX program cannot correctly handle
+filenames containing spaces.)  In case latexmk's quoting does not work
+correctly on your system, you can turn it off -- see the documentation
+for the variable \fI$quote_filenames\fR.
+.PP
+The distinction between %B and %R needs a bit of care, since they are
+often the same, but not always.  For example on a simple document, the
+basename of a bibtex run is the same as for the texfile.  But in a
+document with several bibliographies, the bibliography files will have
+a variety of names.  Since bibtex is invoked with the basename of the
+bibliography file, the setting for the bibtex command should therefore
+be 
+.PP
+     $bibtex = 'bibtex %O %B';
+.PP
+Generally, you should use %B rather than %R.  Similarly for most
+purposes, the name %T of the primary texfile is not a useful
+placeholder.
+
+See the default values in the section "List of configuration variables
+usable in initialization files" for what is normally the most
+appropriate usage. 
+
+If you omit to supply any placeholders whatever in the specification
+of a command, \fIlatexmk\fR will supply what its author thinks are
+appropriate defaults.  This gives compatibility with configuration
+files for previous versions of \fIlatexmk\fR, which didn't use
+placeholders.
+
+\fB"Detaching" a command\fR: Normally when \fIlatexmk\fR runs a
+command, it waits for the command to run to completion.  This is
+appropriate for commands like latex, of course.  But for previewers,
+the command should normally run detached, so that \fIlatexmk\fR gets
+the previewer running and then returns to its next task (or exits if
+there is nothing else to do).  To achieve this effect of detaching a
+command, you need to precede the command name with "start ", as in
+.PP
+     $dvi_previewer = 'start xdvi %O %S';
+.PP
+This will be translated to whatever is appropriate for your operating
+system.
+
+Notes: (1) In some circumstances, \fIlatex\fR will always run a
+command detached.  This is the case for a previewer in preview
+continuous mode, since otherwise previewing continuously makes no
+sense.  (2) This precludes the possibility of running a command named
+start.  (3) If the word start occurs more than once at the beginning
+of the command string, that is equivalent to having just one.  (4)
+Under cygwin, some complications happen, since cygwin amounts to a
+complicated merging of UNIX and MS-Windows.  See the source code for
+how I've handled the problem.
+
+\fBCommand names containing spaces\fR: Under MS-Windows it is common
+that the name of a command includes spaces, since software is often
+installed in a subdirectory of "C:\Program Files".  Such command names
+should be enclosed in double quotes, as in
+.PP
+     $lpr_pdf = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p %S';
+.PP
+\fBUsing MS-Windows file associations\fR: A useful trick under modern
+versions of MS-Windows (e.g., WinXP) is to use just the command
+'start' by itself:
+.PP
+     $dvi_previewer = 'start %S';
+.PP
+Under recent versions of MS-Windows, this will cause to be run
+whatever program the system has associated with dvi files.  (The same
+applies for a postscript viewer and a pdf viewer.)  
+
+\fBNot using a certain command\fR: If a command is not to be run, the
+command name NONE is used, as in
+.PP
+     $lpr  = 'NONE lpr';
+.PP
+This typically is used when an appropriate command does not exist on
+your system.  The string after the "NONE" is effectively a comment.
+
+\fBOptions to commands\fR:
+Setting the name of a command can be used not only for changing the
+name of the command called, but also to add options to command.
+Suppose you want \fIlatexmk\fR to use latex with source specials
+enabled.  Then you might use the following line in an initialization
+file:
+.PP
+     $latex = 'latex --src-specials %O %S';
+.PP
+
+\fBAdvanced tricks\fR: Normally one specifies a single command for the
+commands invoked by \fIlatexmk\fR.  Naturally, if there is some
+complicated additional processing you need to do in your special
+situation, you can write a script (or batch file) to do the
+processing, and then configure \fIlatexmk\fR to use your script in
+place of the standard program.
+
+It is also possible to configure \fIlatexmk\fR to run multiple
+commands.  For example, if when running pdflatex to generate a pdf
+file from a tex file you need to run another program after pdflatex to
+perform some extra processing, you could do something like:
+
+     $pdflatex = 'pdflatex --shell-escape %O %S; pst2pdf_for_latexmk %B';
+
+This definition assumes you are using a UNIX-like system, so that the
+two commands to be run are separated by the semicolon in the middle of
+the string.  
+
+
+.SH LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES
+.PP
+Default values are indicated in brackets.
+.TP
+.B $banner [0]
+If nonzero, the banner message is printed across each page when
+converting the dvi file to postscript.  Without modifying the variable
+\fI$banner_message\fR, this is equivalent to specifying the \fB-d\fR
+option.
+
+Note that if \fB$banner\fR is nonzero, the \fB$postscript_mode\fR is
+assumed and the postscript file is always generated, even if it is newer
+than the dvi file.
+.TP
+.B $banner_intensity [0.95]
+Equivalent to the \fB-bi\fR option, this is a decimal number between 0
+and 1 that specifies how dark to print the banner message. 0 is black,
+1 is white.  The default is just right if your toner cartridge isn't
+running too low.
+.TP
+.B $banner_message ["DRAFT"]
+The banner message to print across each page when converting the dvi
+file to postscript.  This is equivalent to the \fB-bm\fR option.
+.TP
+.B $banner_scale [220.0]
+A decimal number that specifies how large the banner message will be
+printed.  Experimentation is necessary to get the right scale for your
+message, as a rule of thumb the scale should be about equal to 1100
+divided by the number of characters in the message.  The Default is
+just right for 5 character messages.  This is equivalent to the
+\fB-bs\fR option.
+.TP
+.B @BIBINPUTS
+This is an array variable, now mostly obsolete, that specifies
+directories where 
+\fIlatexmk\fR should look for .bib files.  By default it is set from
+the BIBINPUTS environment variable of the operating system.  If that
+environment variable is not set, a single element list consisting of
+the current directory is set.  The format of the directory names
+depends on your operating system, of course.  Examples for setting
+this variable are:
+
+        @BIBINPUTS = ( ".", "C:\\bibfiles" );
+        @BIBINPUTS = ( ".", "\\\\server\\bibfiles" );
+        @BIBINPUTS = ( ".", "C:/bibfiles" );
+        @BIBINPUTS = ( ".", "//server/bibfiles" );
+        @BIBINPUTS = ( ".", "/usr/local/texmf/bibtex/bib" );
+
+Note that under MS Windows, either a forward slash "/" or a backward
+slash "\(rs" can be used to separate pathname components, so the first
+two and the second two examples are equivalent.  Each backward slash
+should be doubled to avoid running afoul of \fIPerl\fR's rules for writing
+strings. 
+.PP
+\fIImportant note:\fR This variable is now mostly obsolete in the
+current version of \fIlatexmk\fR, 
+since it has a better method of searching for files using the
+kpsewhich command.  However, if your system is an unusual one without
+the kpsewhich command, you may need to set the variable \fI@BIBINPUTS\fR.
+.TP
+.B $bibtex ["bibtex %O %S"]
+The BibTeX processing program.
+.TP
+.B $bibtex_silent_switch ["-terse"]
+\fBSwitch(es)\fR for the BibTeX processing program when silent mode is on.
+.TP
+.B $cleanup_includes_generated [0]
+If nonzero, specifies that cleanup also deletes files that are
+detected in log file as being generated (see the \\openout lines in
+the log file).  It will also include files made from these first
+generation generated files.
+.TP
+.B $cleanup_mode [0]
+If nonzero, specifies cleanup mode: 1 for full cleanup, 2 for cleanup
+except for dvi, ps and pdf files, 3 for cleanup except for dep and aux
+files.  (There is also extra cleaning as specified by the
+\fI$clean_ext\fR, \fI$clean_full_ext\fR and \fI@generated_exts\fR
+variables.)
+.PP
+This variable is equivalent to specifying one of
+the \fB-c\fR, \fB-c1\fR, or \fB-C\fR options.  But there should be no need
+to set this variable from an RC file.
+.TP
+.B $clean_ext [""]
+Extra extensions of files for \fIlatexmk\fR to remove when any of the
+clean-up options (\fB-c\fR, \fB-c1\fR, or \fB-C\fR) is selected.
+The value of this variable is a string containing the extensions
+separated by spaces.
+.TP
+.B $clean_full_ext [""]
+Extra extensions of files for \fIlatexmk\fR to remove when the \fB-C\fR
+option is selected, i.e., extensions of files to remove when the .dvi,
+etc files are to be cleaned-up.
+.TP
+.B @cus_dep_list [()]
+Custom dependency list -- see section on "Custom Dependencies".
+.TP
+.B @default_files [("*.tex")]
+Default list of files to be processed.  
+
+Normally, if no filenames are specified on the command line,
+\fIlatexmk\fR processes all tex files specified in the \fI@default_files\fR
+variable, which by default is set to all tex files ("*.tex") in the
+current directory.  This is a convenience: just run \fIlatexmk\fR and
+it will process an appropriate set of files.  But sometimes you want
+only some of these files to be processed.  In this case you set the
+\fI@default_files\fR in an initialization file
+(e.g., the file "latexmkrc" in the current directory).  Then if no
+files are specified on the command line then the files you specify by
+setting \fI@default_files\fR are processed.
+
+Three examples:
+
+     @default_files = ("paper_current");
+
+     @default_files = ("paper1", "paper2.tex");
+
+     @default_files = ("*.tex", "*.dtx");
+
+Note that more than file may be given, and that the default extension
+is ".tex".  Wild cards are allowed.  The parentheses are because
+\fI@default_files\fR is an array variable, i.e., a sequence of
+filename specifications is possible.
+.TP
+.B $dvi_filter [empty]
+The dvi file filter to be run on the newly produced dvi file before
+other processing.  Equivalent to specifying the \fB-dF\fR option.
+.TP
+.B $dvi_mode [See below for default]
+If nonzero, generate a dvi version of the document.  
+Equivalent to the \fB-dvi\fR option.
+.PP
+The variable $dvi_mode defaults to 0, but if no explicit requests are
+made for other types of file (postscript, pdf), then $dvi_mode will be
+set to 1.  In addition, if a request for a file for which a .dvi file
+is a prerequisite, then $dvi_mode will be set to 1.  
+.TP
+.B $dvi_previewer ["start xdvi %O %S" under UNIX]
+The command to invoke a dvi-previewer.
+[Default is "start" under MS-WINDOWS; under more recent versions of
+Windows, this will cause to be run whatever command the system has
+associated with .dvi files.] 
+.TP
+.B $dvi_previewer_landscape ["start xdvi %O %S"]
+The command to invoke a dvi-previewer in landscape mode.
+[Default is "start" under MS-WINDOWS; under more recent versions of
+Windows, this will cause to be run whatever command the system has
+associated with .dvi files.] 
+.TP
+.B $dvipdf ["dvipdf %O %S %D"]
+Command to convert dvi to pdf file.  A common reconfiguration is to
+use the dvipdfm command, which needs its arguments in a different order:
+
+     $dvipdf = "dvipdfm %O -o %D %S";
+
+WARNING: The default dvipdf script generates pdf files with bitmapped
+fonts, which do not look good when viewed by acroread.  That script
+should be modified to give dvips the options "-P pdf" to ensure that
+type 1 fonts are used in the pdf file.
+.TP
+.B $dvips ["dvips %O -o %D %S"]
+The program to used as a filter to convert a .dvi file to a .ps file.  
+If pdf is going to be generated from pdf, then the value of the
+$dvips_pdf_switch -- see below -- will be included in the options
+substituted for "%O".
+.TP
+.B $dvips_landscape ["dvips -tlandscape %O -o %D %S"]
+The program to used as a filter to convert a .dvi file to a .ps file
+in landscape mode.
+.TP
+.B $dvips_pdf_switch ["-P pdf"]
+Switch(es) for dvips program when pdf file is to be generated from
+ps file. 
+.TP
+.B $dvips_silent_switch ["-q"]
+Switch(es) for dvips program when silent mode is on.
+.TP
+.B $dvi_update_command [""]
+When the dvi previewer is set to be updated by running a command, this
+is the command that is run.  See the information for the variable
+\fI$dvi_update_method\fR for further information, and see information
+on the variable \fI$pdf_update_method\fR for an example for the
+analogous case of a pdf previewer.
+.TP
+.B $dvi_update_method [2 under UNIX, 1 under MS-Windows]
+How the dvi viewer updates its display when the dvi file has changed.
+The values here apply equally to the \fI$pdf_update_method\fR and to
+the \fI$ps_update_method\fR variables.
+    0 => update is automatic, 
+    1=> manual update by user, which may only mean a mouse click on the
+viewer's window or may mean a more serious action.
+    2 => Send the signal, whose number is in the variable
+\fI$dvi_update_signal\fR.  The default value under UNIX is
+suitable for xdvi. 
+    3 => Viewer cannot do an update, because it locks the file. (As with
+acroread under MS-Windows.)
+    4 => run a command to do the update.  The command is specified by
+the variable \fI$dvi_update_command\fR.   
+
+See information on the variable \fI$pdf_update_method\fR for an
+example of updating by command.
+.TP
+.B $dvi_update_signal [Under UNIX: SIGUSR1, which is a system-dependent value]
+The number of the signal that is sent to the dvi viewer when it is
+updated by sending a signal -- see the information on the variable
+\fI$dvi_update_method\fR.  The default value is the one appropriate
+for xdvi on a UNIX system.
+.TP
+.B $fdb_ext ["fdb_latexmk"]
+The extension of the file which \fIlatexmk\fR generates to contain a
+database of information on source files.  You will not normally need
+to change this.
+.TP
+.B $force_mode [0]
+If nonzero, continue processing past minor \fIlatex\fR errors 
+including unrecognized cross references.  Equivalent to specifying the
+\fB-f\fR option.
+.TP
+.B @generated_exts [( "aux", "bbl", "idx", "ind", "lof", "lot", "out", "toc", $fdb_ext )]
+This contains a list of extensions for files that are generated during
+a LaTeX run and that are read in by LaTeX in later runs, either
+directly or indirectly. 
+
+This list has two uses: (a) to set the kinds of file to be deleted in
+a cleanup operation (with the \fB-c\fR, \fB-C\fR, \fB-CA\fR, \fB-g\fR
+and \fB-gg\fR options), and (b) in the determination of whether a
+rerun of (pdf)LaTeX is needed after a run that gives an error.
+
+(Normally, a change of a source file during a run should provoke a
+rerun.  This includes a file generated by LaTeX, e.g., an aux file,
+that is read in on subsequent runs.  But after a run that results in
+an error, a new run should occur until the user has made a change in
+the files.  But the user may have corrected an error in a source .tex
+file during the run.  So \fIlatexmk\fR needs to distinguish
+user-generated and automatically generated files; it determines the
+automatically generated files as those with extensions in the list in
+@generated_exts.)
+
+A convenient way to add an extra extension to the list, without losing
+the already defined ones is to use a push command in the line in an
+RC file.  E.g.,
+
+                push @generated_exts, "end";
+
+adds the extension "end" to the list of predefined generated
+extensions.  (This extension is used by the RevTeX package, for
+example.) 
+.TP
+.B $go_mode [0]
+If nonzero, process files regardless of timestamps, and is then
+equivalent to the \fB-g\fR option.
+.TP
+.B %hash_calc_ignore_pattern
+\fB!!!This variable is for experts only!!!\fR
+
+The general rule \fIlatexmk\fR uses for determining when an extra run
+of some program is needed is that one of the source files has changed.
+But consider for example a latex package that causes an encapsulated
+postscript file (an "eps" file) to be made that is to be read in on
+the next run.  The file contains a comment line giving its creation
+date and time.  On the next run the time changes, \fIlatex\fR sees
+that the eps file has changed, and therefore reruns latex.  This
+causes an infinite loop, only exited becaues \fIlatexmk\fR has a limit
+on the number of runs to guard against pathological situations.
+
+But the changing line has no real effect, since it is a comment.  You
+can instruct \fIlatex\fR to ignore the offending line as follows:
+
+   $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: ';
+
+This creates a rule for files with extension \fI.eps\fR about lines to
+ignore.  The left-hand side is a \fIPerl\fR idiom for setting an item
+in a hash.  Note that the file extension is specified without a
+period.  The value, on the right-hand side, is a string containing a
+regular expresssion.  (See documentation on \fIPerl\fR for how they
+are to be specified in general.)  This particular regular expression
+specifies that lines beginning with "%%CreationDate: " are to be
+ignored in deciding whether a file of the given extension \fI.eps\fR
+has changed.
+.TP
+.B $kpsewhich ["kpsewhich %S"]
+The program called to locate a source file when the name alone is not
+sufficient.  Most filenames used by \fIlatexmk\fR have sufficient path
+information to be found directly.  But sometimes, notably when
+.bib files are found from the log file of a bibtex run, the name of
+the file, but not its path is known.  The program specified by
+$kpsewhich is used to find it.  
+
+See also the \fI@BIBINPUTS\fR variable for another way that \fIlatexmk\fR
+also uses to try to locate files; it applies only in the case of .bib
+files.
+.TP
+.B $landscape_mode [0]
+If nonzero, run in landscape mode, using the landscape mode previewers and
+dvi to postscript converters.  Equivalent to the \fB-l\fR option.
+Normally not needed with current previewers.
+.TP
+.B $latex ["latex %O %S"]
+The LaTeX processing program.  Note that as with other programs, you
+can use this variable not just to change the name of the program used,
+but also specify options to the program.  E.g.,
+
+	$latex = "latex --src-specials";
+.TP
+.B %latex_input_extensions
+This variable specifies the extensions tried by latexmk when it finds
+that a LaTeX run resulted in an error that a file has not been found,
+and the file is given without an extension.  This typically happens when
+LaTeX commands of the form \input{file} or \includegraphics{figure},
+when the relevant source file does not exist.
+
+In this situation, latexmk searches for custom dependencies to make
+the missing file(s), but restricts it to the extensions specified by
+the variable %latex_input_extensions.  The default extensions are
+'tex' and 'eps'.
+
+(For Perl experts: %latex_input_extensions is a hash whose keys are
+the extensions.  The values are irrelevant.)  Two subroutines are
+provided for manipulating this and the related variable
+%pdflatex_input_extensions, add_input_ext and remove_input_ext.  They
+are used as in the following examples are possible lines in an
+initialization file:
+
+    remove_input_ext( 'latex', 'tex' );
+
+removes the extension 'tex' from latex_input_extensions
+
+    add_input_ext( 'latex', 'asdf' );
+
+add the extension 'asdf to latex_input_extensions.  (Naturally with
+such an extension, you should have made an appropriate custom
+dependency for latexmk, and should also have done the appropriate
+programming in the LaTeX source file to enable the file to be read.
+The standard extensions are handled by LaTeX and its graphics/graphicx
+packages. 
+
+.TP
+.B $latex_silent_switch ["-interaction=batchmode"]
+Switch(es) for the LaTeX processing program when silent mode is on.
+Under MS-Windows, the default value is changed to 
+"-interaction=batchmode -c-style-errors", as used by MikTeX and fpTeX.
+.TP
+.B $lpr ["lpr  %O %S" under UNIX/LINUX, \(dqNONE lpr\(dq under MS-WINDOWS]
+The command to print postscript files.
+
+Under MS-Windows (unlike UNIX/LINUX), there is no standard program for
+printing files.  But there are ways you can do it.  For example, if
+you have gsview installed, you could use it with the option "/p":
+
+    $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
+
+If gsview is installed in a different directory, you will need to make
+the appropriate change.  Note the combination of single and double
+quotes around the name.  The single quotes specify that this is a
+string to be assigned to the configuration variable \fI$lpr\fR.  The double
+quotes are part of the string passed to the operating system to get
+the command obeyed; this is necessary because one part of the command
+name ("Program Files") contains a space which would otherwise be
+misinterpreted.
+.TP
+.B $lpr_dvi ["NONE lpr_dvi"]
+The printing program to print dvi files.
+.TP
+.B $lpr_pdf ["NONE lpr_pdf"]
+The printing program to print pdf files.
+
+Under MS-Windows you could set this to use gsview, if it is installed,
+e.g.,
+
+    $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
+
+If gsview is installed in a different directory, you will need to make
+the appropriate change.  Note the double quotes around the name: this
+is necessary because one part of the command name ("Program Files")
+contains a space which would otherwise be misinterpreted. 
+
+.TP
+.B $makeindex ["makeindex %O -o %D %S"]
+The index processing program.
+.TP
+.B $max_repeat  [5]
+The maximum number of times \fIlatexmk\fR will run latex/pdflatex
+before deciding that there may be an infinite loop and that it needs
+to bail out, rather than rerunning latex/pdflatex again to resolve
+cross-references, etc.  The default value covers all normal cases.
+
+(Note that the "etc" covers a lot of cases where one run of
+latex/pdflatex generates files to be read in on a later run.)
+.TP
+.B $new_viewer_always [0]
+This variable applies to \fIlatexmk\fR \fBonly\fR in
+continuous-preview mode.  If \fI$new_viewer_always\fR is 0,
+\fIlatexmk\fR will check for a previously running previewer on the
+same file, and if one is running will not start a new one.  If
+\fI$new_viewer_always\fR is non-zero, this check will be skipped, and
+\fIlatexmk\fR will behave as if no viewer is running.
+.TP
+.B $pdf_mode [0]
+If zero, do NOT generate a pdf version of the document.
+If equal to 1, generate a pdf version of the document using pdflatex.  
+If equal to 2, generate a pdf version of the document from the ps
+file, by using the command specified by the \fI$ps2pdf\fR variable.  
+If equal to 3, generate a pdf version of the document from the dvi
+file, by using the command specified by the \fI$dvipdf\fR variable.  
+
+Equivalent to the \fB-pdf-\fR, \fB-pdf\fR, \fB-pdfdvi\fR, 
+\fB-pdfps\fR options.
+.TP
+.B $pdflatex ["pdflatex %O %S"]
+The LaTeX processing program in the version that makes a pdf file instead
+of a dvi file.
+.TP
+.B %pdflatex_input_extensions
+This variable specifies the extensions tried by latexmk when it finds
+that a pdfLaTeX run resulted in an error that a file has not been found,
+and the file is given without an extension.  This typically happens when
+LaTeX commands of the form \input{file} or \includegraphics{figure},
+when the relevant source file does not exist.
+
+In this situation, latexmk searches for custom dependencies to make
+the missing file(s), but restricts it to the extensions specified by
+the variable %pdflatex_input_extensions.  The default extensions are
+'tex', 'pdf', 'jpg, and 'png'.
+
+(For Perl experts: %pdflatex_input_extensions is a hash whose keys are
+the extensions.  The values are irrelevant.)  Two subroutines are
+provided for manipulating this and the related variable
+%latex_input_extensions, add_input_ext and remove_input_ext.  They
+are used as in the following examples are possible lines in an
+initialization file:
+
+    remove_input_ext( 'pdflatex', 'tex' );
+
+removes the extension 'tex' from pdflatex_input_extensions
+
+    add_input_ext( 'pdflatex', 'asdf' );
+
+add the extension 'asdf to pdflatex_input_extensions.  (Naturally with
+such an extension, you should have made an appropriate custom
+dependency for latexmk, and should also have done the appropriate
+programming in the LaTeX source file to enable the file to be read.
+The standard extensions are handled by pdflatex and its graphics/graphicx
+packages.)
+
+.TP
+.B $pdflatex_silent_switch  ["-interaction=batchmode"]
+Switch(es) for the pdflatex program (specified in the variable
+\fI$pdflatex\fR when silent mode is on.
+Under MS-Windows, the default value is changed to 
+"-interaction=batchmode -c-style-errors", as used by MikTeX and fpTeX.
+.TP
+.B $pdf_previewer ["start acroread %O %S"]
+The command to invoke a pdf-previewer.
+[Default is changed to "start" on MS-WINDOWS; under more recent versions of
+Windows, this will cause to be run whatever command the system has
+associated with .pdf files.]  
+
+\fBWARNING\fR: Potential problem under MS-Windows:
+if acroread is used as the pdf previewer, and it is
+actually viewing a pdf file, the pdf file cannot be updated.  Thus
+makes acroread a bad choice of previewer if you use \fIlatexmk\fR's
+previous-continuous mode (option \fB-pvc\fR) under MS-windows.
+This problem does not occur if ghostview, gv or gsview is used to
+view pdf files.
+.TP
+.B $pdf_update_command [""]
+When the pdf previewer is set to be updated by running a command, this
+is the command that is run.  See the information for the variable
+\fI$pdf_update_method\fR. 
+.TP
+.B $pdf_update_method [1 under UNIX, 3 under MS-Windows]
+How the pdf viewer updates its display when the pdf file has
+changed. See the information on the variable \fI$dvi_update_method\fR
+for the codes.  (Note that information needs be changed slightly so
+that for the value 4, to run a command to do the update, the command
+is specified by the variable \fI$pdf_update_command\fR, and for the
+value 2, to specify update by signal, the signal is specified by
+\fI$pdf_update_signal\fR.)
+
+Note that acroread under MS-Windows (but not UNIX) locks the pdf file, so
+the default value is then 3.  
+
+Arranging to use a command to get a previewer explicitly updated
+requires three variables to be set.  For example:
+
+    $pdf_previewer = "start xpdf -remote %R %O %S";
+    $pdf_update_method = 4;
+    $pdf_update_command = "xpdf -remote %R -reload";
+
+The first setting arranges for the xpdf program to be used in its
+"remote server mode", with the server name specified as the rootname
+of the TeX file.  The second setting arranges for updating to be done
+in response to a command, and the third setting sets the update command.
+
+.TP
+.B $pdf_update_signal [Under UNIX: SIGHUP, which is a system-dependent value]
+The number of the signal that is sent to the pdf viewer when it is
+updated by sending a signal -- see the information on the variable
+\fI$pdf_update_method\fR.  The default value is the one appropriate
+for gv on a UNIX system.
+.TP
+.B $pid_position[1 under UNIX, -1 under MS-Windows]     
+The variable \fI$pid_position\fR is used to
+specify which word in lines of the output from \fI$pscmd\fR
+corresponds to the process ID.  The first word in the line is numbered
+0.  The default value of 1 (2nd word in line) is correct for Solaris
+2.6 and Linux.  Setting the variable to -1 is used to indicate that
+\fI$pscmd\fR is not to be used.
+.TP
+.B $postscript_mode [0]
+If nonzero, generate a postscript version of the document.  
+Equivalent to the \fB-ps\fR option.
+.PP
+If some other request is made for which a postscript file is needed,
+then $postscript_mode will be set to 1.
+.TP
+.B $preview_continuous_mode [0]
+If nonzero, run a previewer to view the document, and
+continue running \fIlatexmk\fR to keep .dvi up-to-date.  Equivalent to
+the \fB-pvc\fR option.
+Which previewer is run depends on the other settings, see the command
+line options \fB-view=\fR, and the variable \fI$view\fR.  
+.TP
+.B $preview_mode [0]
+If nonzero, run a previewer to preview the document.
+Equivalent to the \fB-pv\fR option.  
+Which previewer is run depends on the other settings, see the command
+line options \fB-view=\fR, and the variable \fI$view\fR.  
+.TP
+.B $printout_mode [0]
+If nonzero, print the document using \fIlpr\fR.  Equivalent to the
+\fB-p\fR option.  This is recommended \fBnot\fR to be set from an RC
+file, otherwise you could waste lots of paper.
+.TP
+.B $print_type = ["ps"]
+Type of file to printout: possibilities are "dvi", "none", "pdf", or "ps".  
+.TP
+.B $pscmd
+Command used to get all the processes currently run by the user.  The
+-pvc option uses the command specified by the variable \fI$pscmd\fR to
+determine if there is an already running previewer, and to find the
+process ID (needed if \fIlatexmk\fR needs to signal the previewer
+about file changes).  
+
+Each line of the output of this command is assumed to correspond to
+one process.  See the \fI$pid_position\fR variable for how the process
+number is determined.
+
+The default for \fIpscmd\fR is "NONE" under MS-Windows and cygwin
+(i.e., the command is not used), "ps --width 200 -f -u $ENV{USER}"
+under linux, "ps -ww -u $ENV{USER}" under darwin (Macintosh OS-X), and
+"ps -f -u $ENV{USER}" under other operating systems (including other
+flavors of UNIX).  In these specifications "$ENV{USER}" is substituted
+by the username.
+.TP
+.B $ps2pdf ["ps2pdf  %O %S %D"]
+Command to convert ps to pdf file.  
+.TP
+.B $ps_filter [empty]
+The postscript file filter to be run on the newly produced postscript
+file before other processing.  Equivalent to specifying the \fB-pF\fR
+option.
+.TP
+.B $ps_previewer ["start gv %O %S", but \(dqstart %O %S" under MS-WINDOWS]
+The command to invoke a ps-previewer.  (The default under MS-WINDOWS
+will cause to be run whatever command the system has associated 
+with .ps files.)
+
+Note that gv could be used with the -watch option updates its display
+whenever the postscript file changes, whereas ghostview does not.
+However, different versions of gv have slightly different ways of
+writing this option.  You can configure this variable apppropriately.
+
+\fBWARNING\fR: Linux systems may have installed one (or more) versions
+of gv under different names, e.g., ggv, kghostview, etc, but perhaps
+not one called gv.  
+.TP
+.B $ps_previewer_landscape ["start gv -swap %O %S", but \(dqstart %O %S" under MS-WINDOWS]
+The command to invoke a ps-previewer in landscape mode.
+.TP
+.B $ps_update_command [""]
+When the postscript previewer is set to be updated by running a command, this
+is the command that is run.  See the information for the variable
+\fI$ps_update_method\fR. 
+.TP
+.B $ps_update_method [0 under UNIX, 1 under MS-Windows]
+How the postscript viewer updates its display when the ps file has
+changed. See the information on the variable \fI$dvi_update_method\fR
+for the codes.  (Note that information needs be changed slightly so
+that for the value 4, to run a command to do the update, the command
+is specified by the variable \fI$ps_update_command\fR, and for the
+value 2, to specify update by signal, the signal is specified by
+\fI$ps_update_signal\fR.)
+
+.TP
+.B $ps_update_signal [Under UNIX: SIGHUP, which is a system-dependent value]
+The number of the signal that is sent to the pdf viewer when it is
+updated by sending a signal -- see \fI$ps_update_method\fR.  The
+default value is the one appropriate for gv on a UNIX system.
+.TP
+.B $quote_filenames [1]
+This specifies whether substitutions for placeholders in command
+specifications (as in \fI$pdflatex\fR) are surrounded by double
+quotes.  If this variable is 1 (or any other value Perl regards as
+true), then quoting is done.  Otherwise quoting is omitted.  
+.PP
+The quoting method used by latexmk is tested to work correctly under
+UNIX systems (including Linux and Mac OS-X) and under MS-Windows.  It
+allows the use of filenames containing special characters, notably
+spaces.  (But note that many versions of LaTeX and PdfLaTeX cannot
+correctly deal with TeX files whose names contain spaces.  Latexmk's
+quoting only ensures that such filenames are correctly treated by the
+operating system in passing arguments to programs.)
+.TP
+.B $sleep_time [2]
+The time to sleep (in seconds) between checking for source file 
+changes when running the \fB-pvc\fR option.
+.TP
+.B $texfile_search [""]
+This is an obsolete variable, replaced by the \fI@default_files\fR
+variable.  
+
+For backward compatibility, if you choose to set
+\fI$texfile_search\fR, it is a string of space-separated filenames, and
+then \fIlatexmk\fR replaces \fI@default_files\fR with the filenames in
+\fI$texfile_search\fR to which is added "*.tex".
+.TP
+.B $tmpdir [See below for default]
+Directory to store temporary files that \fIlatexmk\fR may generate while
+running.  
+
+The default under MSWindows (including cygwin), is to set
+\fI$tmpdir\fR to the value of the first of whichever of the system
+environment variables TMPDIR or TEMP exists, otherwise to the current
+directory.  Under other operating systems (expected to be UNIX/Linux,
+including OS-X), the default is the value of the system environment
+variable TMPDIR if it exists, otherwise "/tmp".
+.TP
+.B $view ["default"]
+Which kind of file is to be previewed if a previewer is used.  The
+possible values are "default", "dvi", "ps", "pdf".  The value 
+of "default" means that the "highest" of the kinds of file generated is
+to be used (among dvi, ps and pdf).
+
+.SH CUSTOM DEPENDENCIES
+.PP
+In any RC file a set of custom dependencies can be set up to convert a
+file with one extension to a file with another.  An example use of this
+would be to allow \fIlatexmk\fR to convert a \fI.fig\fR file to
+\fI.eps\fR to be included in the \fI.tex\fR file.  
+
+The old method of configuring \fIlatexmk\fR was to directly manipulate
+the \fB@cus_dep_list\fR array that contains information defining the
+custom dependencies.  This method still works.  But now there are 
+subroutines that allow convenient manipulations of the custom
+dependency list.  These are
+
+    add_cus_dep( fromextension, toextension, must, subroutine )
+    remove_cus_dep( fromextension, toextension )
+    show_cus_dep()
+
+The custom dependency is a list of rules, each of which is specified
+as follow:
+.TP
+.B from extension:
+The extension of the file we are converting from (e.g. "fig").
+It is specified without a period.
+.TP
+.B to extension:
+The extension of the file we are converting to (e.g. "eps").
+It is specified without a period.
+.TP
+.B must:
+If non-zero, the file from which we are converting \fBmust\fR exist, if it
+doesn't exist \fIlatexmk\fR will give an error message and exit unless
+the \fB-f\fR option is specified.  If \fImust\fR is zero and the file
+we are converting from doesn't exist, then no action is taken.
+.TP
+.B function:
+The name of the subroutine that \fIlatexmk\fR should call to perform the
+file conversion.  The first argument to the subroutine is the base name
+of the file to be converted without any extension.  The subroutines are
+declared in the syntax of \fIPerl\fR.  The function should return 0 if
+it was successful and a nonzero number if it failed.
+.PP
+It is invoked whenever \fIlatexmk\fR detects that a run of
+latex/pdflatex needs to read a file, like a graphics file, whose
+extension is the to-extension of a custom dependency.  Then
+\fIlatexmk\fR examines whether a file exists with the same name, but
+with the corresponding from-extension, as specified in the
+custom-dependency rule.  If it does, then whenever the destination
+file (the one with the to-extension) is out-of-date with respect to
+the corresponding source file.
+
+To make the new destination file, the \fIPerl\fR subroutine specified in the
+rule is invoked, with an argument that is the base name of the files
+in question.  Simple cases just involve a subroutine invoking an
+external program; this can be done by following the templates below,
+even by those without knowledge of the \fIPerl\fR programming language.  Of
+course, experts could do something much more elaborate.
+
+One other item in each custom-dependency rule labelled "must" above
+specifies how the rule should be applied when the source file fails to
+exist.
+
+A simple and typical example of code in an initialization rcfile is
+
+    add_cus_dep( 'fig', 'eps', 0, 'fig2eps' );
+    sub fig2eps {
+        system("fig2dev -Leps $_[0].fig $_[0].eps"); 
+    }
+
+The first line adds a custom dependency that converts a file with
+extension "fig", as created by the xfig program, to an encapsulated
+postscript file, with extension "eps".  The remaining lines define a
+subroutine that carries out the conversion.  If a rule for converting
+"fig" to "eps" files already exists (e.g., from a previously read-in
+initialization file), the \fIlatexmk\fR will delete this rule before
+making the new one.
+
+Suppose \fIlatexmk\fR is using this rule to convert a file
+"figure.fig" to "figure.eps".  Then it will invoke the fig2eps
+subroutine defined in the above code with a single argument "figure",
+which is the basename of each of the files (possibly with a path
+component).  This argument is referred to by \fIPerl\fR as $_[0].  In
+the example above, the subroutine uses the \fIPerl\fR command system
+to invoke the program fig2dev.  The double quotes around the string
+are a \fIPerl\fR idiom that signify that each string of the form of a
+variable name, $_[0] in this case, is to be substituted by its value.
+
+If the return value of the subroutine is non-zero, then \fIlatexmk\fR
+will assume an error occurred during the execution of the subroutine.
+In the above example, no explicit return value is given, and instead
+the return value is the value returned by the last (and only)
+statement, i.e., the invocation of system, which returns the value 0
+on success.
+
+If you use filenames with spaces in them, and if your LaTeX system and
+all other relevant software correctly handle such filenames, then you
+could put single quotes around filenames in the command line that is
+executed:
+
+    add_cus_dep( 'fig', 'eps', 0, 'fig2eps' );
+    sub fig2eps {
+        system("fig2dev -Lps '$_[0].fig' '$_[0].eps'");
+    }
+
+This causes the invocation of the \fIfig2dev\fR program to have quoted
+filenames; it should therefore work with filenames containing spaces.
+\fBHowever, not all software deals correctly with filenames that
+contain spaces.  Moreover, the rules, if any, for quoting filenames
+vary between operating systems, command shells and individual pieces
+of software, so this code may not always work.\fR
+
+If you use pdflatex instead of latex, then you will probably prefer to
+convert your graphics files to pdf format, in which case you would
+replace the above code in an initialization file by
+
+    add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' );
+    sub fig2pdf {
+        system("fig2dev -Lpdf $_[0].fig $_[0].pdf"); 
+    }
+
+If you have some general custom dependencies defined in the system or
+user initialization file, you may find that for a particular project
+they are undesirable.  So you might want to delete the unneeded ones.
+For example, you remove any "fig" to "eps" rule by the line
+
+    remove_cus_dep( 'fig', 'eps' );
+
+If you have complicated sets of custom dependencies, you may want to
+get a listing of the custom dependencies.  This is done by using the
+line 
+
+    show_cus_dep();
+
+in an initialization file. 
+
+Another example of a custom dependency overcomes a limitation of
+\fIlatexmk\fR concerning index files.  The only index-file conversion
+built-in to \fIlatexmk\fR is from an ".idx" file written on one run of
+latex/pdflatex to an ".ind" file to be read in on a subsequent run.
+But with the index.sty package you can create extra indexes with
+extensions that you configure.  \fILatexmk\fR does not know how to
+deduce the extensions from the information it has.  But you can easily
+write a custom dependency.  For example if your latex file uses the
+command "\\newindex{special}{ndx}{nnd}{Special index}" you will need to
+convert files with the extension \fI.ndx\fR to \fI.nnd\fR.  The
+following lines in an initialization RC file will cause this to
+happen: 
+
+    add_cus_dep('ndx', 'nnd', 0, 'makendx2nnd');
+    sub makendx2nnd {
+        system("makeindex -o $_[0].nnd $_[0].ndx");
+    }
+
+(You will need to modify this code if you use filenames
+with spaces in them, to provide correct quoting of the filenames.)
+
+Those of you with experience with Makefiles, will undoubtedly be
+concerned that the \fI.ndx\fR file is written during a run of
+latex/pdflatex and is always later than the \fI.nnd\fR last read in.
+Thus the \fI.nnd\fR appears to be perpetually out-of-date.  This
+situation, of circular dependencies, is endemic to latex, and
+\fIlatexmk\fR in its current version works correctly with circular
+dependencies.  It examines the contents of the files (by use of an md5
+checksum), and only does a remake when the file contents have actually
+changed.
+
+Of course if you choose to write random data to the \fI.nnd\fR (or and
+\fI.aux\fR file, etc) that changes on each new run, then you will have
+a problem.  For real experts: See the \fI%hash_cal_ignore_pattern\fR
+if you have to deal with such problems.
+
+Glossaries can be dealt with similarly.
+
+.SH OLD METHOD OF DEFINING CUSTOM DEPENDENCIES
+In previous versions of \fIlatexmk\fR, the only method of defining
+custom dependencies was to directly manipulate the table of custom
+dependencies.  This is contained in the \fB@cus_dep_list\fR array.  It
+is an array of strings, and each string in the array has four items in
+it, each separated by a space, the from-extension, the to-extension,
+the "must" item, and the name of the subroutine for the custom
+dependency.  These were all defined above.
+.PP
+An example of the old method of defining custom dependencies is as
+follows. It is the code in an RC file to ensure automatic conversion
+of \fI.fig\fR files to \fI.eps\fR files:
+
+    push @cus_dep_list, "fig eps 0 fig2eps";
+    sub fig2eps {
+        system("fig2dev -Lps $_[0].fig $_[0].eps");
+    }
+
+This method still works, and is equivalent to the earlier code using
+the add_cus_dep subroutine, except that it doesn't delete any previous
+custom-dependency for the same conversion.  So the new method is
+preferable.
+
+.SH SEE ALSO
+latex(1), bibtex(1).
+.SH BUGS
+Sometimes a viewer (gv) tries to read an updated .ps or .pdf file
+after its creation is started but before the file is complete.  Work
+around: manually refresh (or reopen) display.  Or use one of the other
+previewers and update methods.  
+
+(The following isn't really a bug, but concerns features of previewers.)
+Preview continuous mode only works perfectly with certain previewers:
+Xdvi on UNIX/LINUX works for dvi files.  
+Gv on UNIX/LINUX works for both postscript and pdf.
+Ghostview on UNIX/LINUX needs a manual update (reopen); it views
+postscript and pdf. 
+Gsview under MS-Windows works for both postscript and pdf, 
+but only reads the updated file when its screen is refreshed.
+Acroread under UNIX/LINUX views pdf, but the file needs to be closed
+and reopened to view an updated version.
+Under MS-Windows, acroread locks its input file and so the
+pdf file cannot be updated.  (Remedy: configure \fIlatexmk\fR to use gsview
+instead.) 
+.SH THANKS TO
+Authors of previous versions.  Many users with their feedback, and
+especially 
+David Coppit (username david at node coppit.org) who made many useful
+suggestions that contributed to version 3, and Herbert Schulz.
+(Please note that the
+e-mail addresses are not written in their standard form to avoid being
+harvested by worms and viruses.)
+.SH AUTHOR
+Current version, by John Collins (username collins at node phys.psu.edu).
+(Version 4.11).
+
+Released version can be obtained from CTAN:
+<http://www.tug.org/tex-archive/support/latexmk/>, and from the
+author's website <http://www.phys.psu.edu/~collins/software/latexmk/>.
+.br
+Modifications and enhancements by Evan McLean (Version 2.0)
+.br
+Original script called "go" by David J. Musliner (RCS Version 3.2)
+
+\"  LocalWords:  fR fIlatexmk dvi ps fILatexmk pdflatex bibtex makeindex fB pv
+\"  LocalWords:  pvc fIgv xdvi gsview cygwin fdb TP tex bm bs fIlatex fIbibtex
+\"  LocalWords:  gg regeneratable dep exts dF dviF dviselect fI fR's lpr pdfps
+\"  LocalWords:  pdfdvi dvipdf pF psF psnup fIsome gv acroread xpdf rcfile cus
+\"  LocalWords:  batchmode latexmkrc elatex basename texfile WinXP BIBINPUTS
+\"  LocalWords:  kpsewhich BibTeX dtx dvipdfm dvips fpTeX MikTeX fBWARNING pid
+\"  LocalWords:  pscmd fIlpr fBnot ENV OSX SIGHUP tmpdir MSWindows tmp eps dev
+\"  LocalWords:  fImust fIperl Lps fIfig