summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexmk/latexmk.1
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/support/latexmk/latexmk.1')
-rw-r--r--Master/texmf-dist/doc/support/latexmk/latexmk.11609
1 files changed, 0 insertions, 1609 deletions
diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.1 b/Master/texmf-dist/doc/support/latexmk/latexmk.1
deleted file mode 100644
index 5ef13279d0e..00000000000
--- a/Master/texmf-dist/doc/support/latexmk/latexmk.1
+++ /dev/null
@@ -1,1609 +0,0 @@
-.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