summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexmk
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-04-11 22:45:11 +0000
committerKarl Berry <karl@freefriends.org>2009-04-11 22:45:11 +0000
commit34d005dca21a959191bb56ff1b4b70cc022edb2a (patch)
treeece0e335ce6f8eeedc38e8950c5122e5757064fb /Master/texmf-dist/doc/support/latexmk
parent32f195b8cc3e111152dac092ced8c20ba6ba3fb3 (diff)
latexmk update (11apr)
git-svn-id: svn://tug.org/texlive/trunk@12697 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support/latexmk')
-rw-r--r--Master/texmf-dist/doc/support/latexmk/README4
-rw-r--r--Master/texmf-dist/doc/support/latexmk/latexmk.183
-rwxr-xr-xMaster/texmf-dist/doc/support/latexmk/latexmk.bat10
-rw-r--r--Master/texmf-dist/doc/support/latexmk/latexmk.pdfbin148039 -> 155123 bytes
-rw-r--r--Master/texmf-dist/doc/support/latexmk/latexmk.txt636
5 files changed, 452 insertions, 281 deletions
diff --git a/Master/texmf-dist/doc/support/latexmk/README b/Master/texmf-dist/doc/support/latexmk/README
index aa1cc45a7e4..7a3b07a87c4 100644
--- a/Master/texmf-dist/doc/support/latexmk/README
+++ b/Master/texmf-dist/doc/support/latexmk/README
@@ -1,4 +1,4 @@
-Hi, and thanks for checking out latexmk. (Version 4.01, 24 September 2008)
+Hi, and thanks for checking out latexmk. (Version 4.05, 10 April 2009)
Latexmk completely automates the process of generating a LaTeX document.
Essentially, it is a highly specialized cousin of the general make
@@ -88,7 +88,7 @@ I hope you find this useful.
John Collins
---------------------------- "latexmk -h" ----------------------------
-Latexmk 4.03: Automatic LaTeX document generation routine
+Latexmk 4.05: Automatic LaTeX document generation routine
Usage: latexmk [latexmk_options] [filename ...]
diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.1 b/Master/texmf-dist/doc/support/latexmk/latexmk.1
index 25132b0cfee..c50258b3f28 100644
--- a/Master/texmf-dist/doc/support/latexmk/latexmk.1
+++ b/Master/texmf-dist/doc/support/latexmk/latexmk.1
@@ -1,4 +1,4 @@
-.TH LATEXMK 1L "22 December 2008" ""
+.TH LATEXMK 1L "10 April 2009" ""
.SH NAME
latexmk \- generate LaTeX document
.SH SYNOPSIS
@@ -14,6 +14,9 @@ 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
@@ -808,9 +811,14 @@ filename specifications is possible.
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 [0]
+.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.
@@ -979,6 +987,39 @@ 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
@@ -1054,6 +1095,39 @@ Equivalent to the \fB-pdf-\fR, \fB-pdf\fR, \fB-pdfdvi\fR,
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.
@@ -1121,6 +1195,9 @@ corresponds to the process ID. The first word in the line is numbered
.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
@@ -1462,7 +1539,7 @@ 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.03).
+(Version 4.05).
Released version can be obtained from CTAN:
<http://www.tug.org/tex-archive/support/latexmk/>, and from the
diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.bat b/Master/texmf-dist/doc/support/latexmk/latexmk.bat
index 48e01d6e5e1..f119082adac 100755
--- a/Master/texmf-dist/doc/support/latexmk/latexmk.bat
+++ b/Master/texmf-dist/doc/support/latexmk/latexmk.bat
@@ -1,5 +1,5 @@
-Rem Execute latexmk.pl, searching for it in the PATH
-Rem Assume perl is in the PATH. If not, you should replace 'perl' by
-Rem the full pathname of the perl executable, e.g., 'C:\perl\bin\perl.exe'
-
-perl -S latexmk.pl %1 %2 %3 %4 %5 %6 %7 %8 %9
+Rem Execute latexmk.pl, searching for it in the PATH
+Rem Assume perl is in the PATH. If not, you should replace 'perl' by
+Rem the full pathname of the perl executable, e.g., 'C:\perl\bin\perl.exe'
+
+perl -S latexmk.pl %1 %2 %3 %4 %5 %6 %7 %8 %9
diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.pdf b/Master/texmf-dist/doc/support/latexmk/latexmk.pdf
index 1220cb0574e..d804f857a68 100644
--- a/Master/texmf-dist/doc/support/latexmk/latexmk.pdf
+++ b/Master/texmf-dist/doc/support/latexmk/latexmk.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.txt b/Master/texmf-dist/doc/support/latexmk/latexmk.txt
index 1e67ad04111..2248a598c3e 100644
--- a/Master/texmf-dist/doc/support/latexmk/latexmk.txt
+++ b/Master/texmf-dist/doc/support/latexmk/latexmk.txt
@@ -14,6 +14,8 @@ DESCRIPTION
and it issues the appropriate sequence of commands to generate a .dvi,
.ps, .pdf and/or hardcopy version of the document.
+ By default latexmk will run the commands necessary to generate a
+
Latexmk 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
@@ -56,8 +58,6 @@ DESCRIPTION
Latexmk 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.
-
@@ -70,6 +70,8 @@ DESCRIPTION
LATEXMK(1L) LATEXMK(1L)
+ files.
+
Latexmk is highly configurable, both from the command line and in con-
figuration files, so that it can accommodate a wide variety of user
needs and system configurations. Default values are set according to
@@ -122,12 +124,10 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE
-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.
-
- 22 December 2008 2
+ 10 April 2009 2
@@ -136,6 +136,8 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE
LATEXMK(1L) LATEXMK(1L)
+ is OK unless your toner cartridge is getting low.
+
-bs <scale>
A decimal number that specifies how large the banner message
will be printed. Experimentation is necessary to get the right
@@ -189,11 +191,10 @@ LATEXMK(1L) LATEXMK(1L)
-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,
- 22 December 2008 3
+ 10 April 2009 3
@@ -202,6 +203,7 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
+ ".dviF". All extra processing (e.g. conversion to postscript,
preview, printing) will then be performed on this filtered dvi
file.
@@ -259,7 +261,7 @@ LATEXMK(1L) LATEXMK(1L)
- 22 December 2008 4
+ 10 April 2009 4
@@ -322,10 +324,11 @@ LATEXMK(1L) LATEXMK(1L)
$lpr_pdf configuration variables to see how to set the commands
for printing.
+ This option is incompatible with the -pv and -pvc options, so it
- 22 December 2008 5
+ 10 April 2009 5
@@ -334,7 +337,6 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
- This option is incompatible with the -pv and -pvc options, so it
turns them off.
-pdf Generate pdf version of document using pdflatex.
@@ -388,19 +390,19 @@ LATEXMK(1L) LATEXMK(1L)
viewer will be used. This option is incompatible with the -p
and -pvc options, so it turns them off.
+ -pv- Turn off -pv.
- 22 December 2008 6
+ 10 April 2009 6
-LATEXMK(1L) LATEXMK(1L)
+LATEXMK(1L) LATEXMK(1L)
- -pv- Turn off -pv.
-pvc Run a file previewer and continually update the .dvi, .ps,
and/or .pdf files whenever changes are made to source files (see
@@ -454,21 +456,21 @@ LATEXMK(1L) LATEXMK(1L)
during this second step. Thus an initialization file specified
with the -r option can override both the standard initialization
files and previously specified options. But all of these can be
+ overridden by later options.
+ The contents of the RC file just comprise a piece of code in the
- 22 December 2008 7
+ 10 April 2009 7
-LATEXMK(1L) LATEXMK(1L)
+LATEXMK(1L) LATEXMK(1L)
- overridden by later options.
- The contents of the RC file just comprise a piece of code in the
Perl programming language (typically a sequence of assignment
statements); they are executed when the -r option is encountered
during latexmk's parsing of its command line. See the -e option
@@ -521,20 +523,19 @@ EXAMPLES
keep running, watching for
source file changes.
+ % latexmk -c # remove .aux, .log, .bbl, .blg, .dvi,
+ .pdf, .ps & .bbl files
- 22 December 2008 8
-
+ 10 April 2009 8
-LATEXMK(1L) LATEXMK(1L)
- % latexmk -c # remove .aux, .log, .bbl, .blg, .dvi,
- .pdf, .ps & .bbl files
+LATEXMK(1L) LATEXMK(1L)
CONFIGURATION/INITIALIZATION (RC) FILES
@@ -587,21 +588,22 @@ HOW TO SET VARIABLES IN INITIALIZATION FILES
for the setting of a numeric variable, and
+ @default_files = ('paper', 'paper1');
+ for the setting of an array of strings. It is possible to append an
+ item to an array variable as follows:
- 22 December 2008 9
+ 10 April 2009 9
-LATEXMK(1L) LATEXMK(1L)
- @default_files = ('paper', 'paper1');
- for the setting of an array of strings. It is possible to append an
- item to an array variable as follows:
+LATEXMK(1L) LATEXMK(1L)
+
push @default_files, 'paper2';
@@ -653,10 +655,15 @@ FORMAT OF COMMAND SPECIFICATIONS
%T The name of the primary tex file.
+ 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 doc-
+ ument with several bibliographies, the bibliography files will have a
+ variety of names. Since bibtex is invoked with the basename of the
- 22 December 2008 10
+ 10 April 2009 10
@@ -665,11 +672,6 @@ FORMAT OF COMMAND SPECIFICATIONS
LATEXMK(1L) LATEXMK(1L)
- 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 doc-
- ument 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
@@ -721,21 +723,22 @@ LATEXMK(1L) LATEXMK(1L)
Using MS-Windows file associations: A useful trick under modern ver-
sions of MS-Windows (e.g., WinXP) is to use just the command
+ $dvi_previewer = 'start %S';
+ Under recent versions of MS-Windows, this will cause to be run whatever
+ program the system has associated with dvi files. (The same applies
- 22 December 2008 11
+ 10 April 2009 11
-LATEXMK(1L) LATEXMK(1L)
- $dvi_previewer = 'start %S';
+LATEXMK(1L) LATEXMK(1L)
+
- 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.)
Not using a certain command: If a command is not to be run, the command
@@ -788,9 +791,13 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES
and the postscript file is always generated, even if it is newer
than the dvi file.
+ $banner_intensity [0.95]
+ Equivalent to the -bi option, this is a decimal number between 0
+ and 1 that specifies how dark to print the banner message. 0 is
- 22 December 2008 12
+
+ 10 April 2009 12
@@ -799,9 +806,6 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES
LATEXMK(1L) LATEXMK(1L)
- $banner_intensity [0.95]
- Equivalent to the -bi 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 car-
tridge isn't running too low.
@@ -854,20 +858,20 @@ LATEXMK(1L) LATEXMK(1L)
$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.
- 22 December 2008 13
+ 10 April 2009 13
-LATEXMK(1L) LATEXMK(1L)
+LATEXMK(1L) LATEXMK(1L)
- in the log file). It will also include files made from these
- first generation generated files.
$cleanup_mode [0]
If nonzero, specifies cleanup mode: 1 for full cleanup, 2 for
@@ -921,10 +925,13 @@ LATEXMK(1L) LATEXMK(1L)
are because @default_files is an array variable, i.e., a
sequence of filename specifications is possible.
+ $dvi_filter [empty]
+ The dvi file filter to be run on the newly produced dvi file
+ before other processing. Equivalent to specifying the -dF
- 22 December 2008 14
+ 10 April 2009 14
@@ -933,65 +940,65 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
- $dvi_filter [empty]
- The dvi file filter to be run on the newly produced dvi file
- before other processing. Equivalent to specifying the -dF
option.
- $dvi_mode [0]
+ $dvi_mode [See below for default]
If nonzero, generate a dvi version of the document. Equivalent
to the -dvi option.
+ 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.
+
$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
+ 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.]
$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 sys-
+ of Windows, this will cause to be run whatever command the sys-
tem has associated with .dvi files.]
$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 dif-
+ to use the dvipdfm command, which needs its arguments in a dif-
ferent order:
$dvipdf = "dvipdfm %O -o %D %S";
- WARNING: The default dvipdf script generates pdf files with
+ 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
+ That script should be modified to give dvips the options "-P
pdf" to ensure that type 1 fonts are used in the pdf file.
$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
+ 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".
$dvips_landscape ["dvips -tlandscape %O -o %D %S"]
- The program to used as a filter to convert a .dvi file to a .ps
+ The program to used as a filter to convert a .dvi file to a .ps
file in landscape mode.
$dvips_pdf_switch ["-P pdf"]
- Switch(es) for dvips program when pdf file is to be generated
+ Switch(es) for dvips program when pdf file is to be generated
from ps file.
$dvips_silent_switch ["-q"]
Switch(es) for dvips program when silent mode is on.
$dvi_update_command [""]
- When the dvi previewer is set to be updated by running a com-
- mand, this is the command that is run. See the information for
- the variable $dvi_update_method for further information, and see
- information on the variable $pdf_update_method for an example
+ When the dvi previewer is set to be updated by running a com-
+ mand, this is the command that is run. See the information for
- 22 December 2008 15
+ 10 April 2009 15
@@ -1000,65 +1007,65 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
+ the variable $dvi_update_method for further information, and see
+ information on the variable $pdf_update_method for an example
for the analogous case of a pdf previewer.
$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
+ How the dvi viewer updates its display when the dvi file has
+ changed. The values here apply equally to the
$pdf_update_method and to the $ps_update_method 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
- $dvi_update_signal. The default value under UNIX is suitable
+ 2 => Send the signal, whose number is in the variable
+ $dvi_update_signal. The default value under UNIX is suitable
for xdvi.
- 3 => Viewer cannot do an update, because it locks the file.
+ 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 speci-
+ 4 => run a command to do the update. The command is speci-
fied by the variable $dvi_update_command.
- See information on the variable $pdf_update_method for an exam-
+ See information on the variable $pdf_update_method for an exam-
ple of updating by command.
- $dvi_update_signal [Under UNIX: SIGUSR1, which is a system-dependent
+ $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 $dvi_update_method. The default value is the one
+ 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 $dvi_update_method. The default value is the one
appropriate for xdvi on a UNIX system.
$fdb_ext ["fdb_latexmk"]
- The extension of the file which latexmk generates to contain a
- database of information on source files. You will not normally
+ The extension of the file which latexmk generates to contain a
+ database of information on source files. You will not normally
need to change this.
$force_mode [0]
- If nonzero, continue processing past minor latex errors includ-
+ If nonzero, continue processing past minor latex errors includ-
ing unrecognized cross references. Equivalent to specifying the
-f option.
- @generated_exts [( aux , bbl , idx , ind , lof , lot , out , toc ,
+ @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,
+ 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
+ This list has two uses: (a) to set the kinds of file to be
deleted in a cleanup operation (with the -c, -C, -CA, -g and -gg
- options), and (b) in the determination of whether a rerun of
+ 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 latexmk needs to
- distinguish user-generated and automatically generated files; it
+ 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
- 22 December 2008 16
+ 10 April 2009 16
@@ -1067,35 +1074,37 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
- determines the automatically generated files as those with
+ error in a source .tex file during the run. So latexmk 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
+ 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
+ adds the extension "end" to the list of predefined generated
+ extensions. (This extension is used by the RevTeX package, for
example.)
$go_mode [0]
- If nonzero, process files regardless of timestamps, and is then
+ If nonzero, process files regardless of timestamps, and is then
equivalent to the -g option.
%hash_calc_ignore_pattern
!!!This variable is for experts only!!!
- The general rule latexmk 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, latex sees that the eps file has changed, and
- therefore reruns latex. This causes an infinite loop, only
- exited becaues latexmk has a limit on the number of runs to
+ The general rule latexmk 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, latex sees that the eps file has changed, and
+ therefore reruns latex. This causes an infinite loop, only
+ exited becaues latexmk 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.
@@ -1104,28 +1113,26 @@ LATEXMK(1L) LATEXMK(1L)
$hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: ';
This creates a rule for files with extension .eps about lines to
- ignore. The left-hand side is a Perl idiom for setting an item
- in a hash. Note that the file extension is specified without a
+ ignore. The left-hand side is a Perl 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 contain-
- ing a regular expresssion. (See documentation on Perl 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
+ ing a regular expresssion. (See documentation on Perl 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 .eps has changed.
$kpsewhich ["kpsewhich %S"]
- The program called to locate a source file when the name alone
- is not sufficient. Most filenames used by latexmk have suffi-
- cient path information to be found directly. But sometimes,
- notably when the file, but not its path is known. The program
+ The program called to locate a source file when the name alone
+ is not sufficient. Most filenames used by latexmk have suffi-
+ cient path information to be found directly. But sometimes,
+ notably when the file, but not its path is known. The program
specified by $kpsewhich is used to find it.
- See also the @BIBINPUTS variable for another way that latexmk
- also uses to try to locate files; it applies only in the case of
- 22 December 2008 17
+ 10 April 2009 17
@@ -1134,41 +1141,89 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
+ See also the @BIBINPUTS variable for another way that latexmk
+ also uses to try to locate files; it applies only in the case of
.bib files.
$landscape_mode [0]
If nonzero, run in landscape mode, using the landscape mode pre-
- viewers and dvi to postscript converters. Equivalent to the -l
+ viewers and dvi to postscript converters. Equivalent to the -l
option. Normally not needed with current previewers.
$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
+ 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";
+ %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
+
+ (For Perl experts: %latex_input_extensions is a hash whose keys
+ are the extensions. The values are irrelevant.) Two subrou-
+ tines are provided for manipulating this and the related vari-
+ able %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 cus-
+ tom dependency for latexmk, and should also have done the appro-
+ priate 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.
+
+
$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 "-inter-
- action=batchmode -c-style-errors", as used by MikTeX and fpTeX.
+ Switch(es) for the LaTeX processing program when silent mode is
+ on. Under MS-Windows, the default value is changed to "-inter-
+ action=batchmode -c-style-errors", as used by MikTeX and fpTeX.
+
+
+
+
+ 10 April 2009 18
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
$lpr ["lpr %O %S" under UNIX/LINUX, "NONE lpr" under MS-WINDOWS]
The command to print postscript files.
- Under MS-Windows (unlike UNIX/LINUX), there is no standard pro-
+ Under MS-Windows (unlike UNIX/LINUX), there is no standard pro-
gram 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 vari-
- able $lpr. The double quotes are part of the string passed to
- the operating system to get the command obeyed; this is neces-
+ 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 vari-
+ able $lpr. The double quotes are part of the string passed to
+ the operating system to get the command obeyed; this is neces-
sary because one part of the command name ("Program Files") con-
tains a space which would otherwise be misinterpreted.
@@ -1178,108 +1233,143 @@ LATEXMK(1L) LATEXMK(1L)
$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
+ 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
+ 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 mis-
interpreted.
+ $makeindex ["makeindex %O -o %D %S"]
+ The index processing program.
+ $max_repeat [5]
+ The maximum number of times latexmk 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.
- 22 December 2008 18
+ (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.)
+ $new_viewer_always [0]
+ This variable applies to latexmk only in continuous-preview
+ mode. If $new_viewer_always is 0, latexmk will check for a pre-
+ viously running previewer on the same file, and if one is run-
+ ning will not start a new one. If $new_viewer_always is non-
+ 10 April 2009 19
-LATEXMK(1L) LATEXMK(1L)
- $makeindex ["makeindex %O -o %D %S"]
- The index processing program.
- $max_repeat [5]
- The maximum number of times latexmk 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.)
+LATEXMK(1L) LATEXMK(1L)
- $new_viewer_always [0]
- This variable applies to latexmk only in continuous-preview
- mode. If $new_viewer_always is 0, latexmk will check for a pre-
- viously running previewer on the same file, and if one is run-
- ning will not start a new one. If $new_viewer_always is non-
- zero, this check will be skipped, and latexmk will behave as if
+
+ zero, this check will be skipped, and latexmk will behave as if
no viewer is running.
$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 pdfla-
+ If zero, do NOT generate a pdf version of the document. If
+ equal to 1, generate a pdf version of the document using pdfla-
tex. If equal to 2, generate a pdf version of the document from
the ps file, by using the command specified by the $ps2pdf vari-
- able. If equal to 3, generate a pdf version of the document
+ able. If equal to 3, generate a pdf version of the document
from the dvi file, by using the command specified by the $dvipdf
variable.
Equivalent to the -pdf-, -pdf, -pdfdvi, -pdfps options.
$pdflatex ["pdflatex %O %S"]
- The LaTeX processing program in the version that makes a pdf
+ The LaTeX processing program in the version that makes a pdf
file instead of a dvi file.
+ %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
+
+ (For Perl experts: %pdflatex_input_extensions is a hash whose
+ keys are the extensions. The values are irrelevant.) Two sub-
+ routines 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. (Natu-
+ rally with such an extension, you should have made an appropri-
+ ate 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 pdfla-
+ tex and its graphics/graphicx packages.)
+
+
$pdflatex_silent_switch ["-interaction=batchmode"]
- Switch(es) for the pdflatex program (specified in the variable
+ Switch(es) for the pdflatex program (specified in the variable
$pdflatex 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.
- $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 asso-
- ciated with .pdf files.]
- WARNING: 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 latexmk's previous-continuous mode (option
- -pvc) under MS-windows. This problem does not occur if
- ghostview, gv or gsview is used to view pdf files.
+ 10 April 2009 20
- 22 December 2008 19
+LATEXMK(1L) LATEXMK(1L)
+ value is changed to "-interaction=batchmode -c-style-errors", as
+ used by MikTeX and fpTeX.
-LATEXMK(1L) LATEXMK(1L)
+ $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 asso-
+ ciated with .pdf files.]
+ WARNING: 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 latexmk's previous-continuous mode (option
+ -pvc) under MS-windows. This problem does not occur if
+ ghostview, gv or gsview is used to view pdf files.
$pdf_update_command [""]
- When the pdf previewer is set to be updated by running a com-
- mand, this is the command that is run. See the information for
+ When the pdf previewer is set to be updated by running a com-
+ mand, this is the command that is run. See the information for
the variable $pdf_update_method.
$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 $dvi_update_method
+ How the pdf viewer updates its display when the pdf file has
+ changed. See the information on the variable $dvi_update_method
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 $pdf_update_command, and
- for the value 2, to specify update by signal, the signal is
+ so that for the value 4, to run a command to do the update, the
+ command is specified by the variable $pdf_update_command, and
+ for the value 2, to specify update by signal, the signal is
specified by $pdf_update_signal.)
Note that acroread under MS-Windows (but not UNIX) locks the pdf
@@ -1292,48 +1382,52 @@ LATEXMK(1L) LATEXMK(1L)
$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
+ 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 set-
ting sets the update command.
- $pdf_update_signal [Under UNIX: SIGHUP, which is a system-dependent
+ $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 $pdf_update_method. The default value is the one
+ 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 $pdf_update_method. The default value is the one
appropriate for gv on a UNIX system.
$pid_position[1 under UNIX, -1 under MS-Windows]
- The variable $pid_position is used to specify which word in
- lines of the output from $pscmd 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. Set-
- ting the variable to -1 is used to indicate that $pscmd is not
- to be used.
+ The variable $pid_position is used to specify which word in
+ lines of the output from $pscmd corresponds to the process ID.
- $postscript_mode [0]
- If nonzero, generate a postscript version of the document.
- Equivalent to the -ps option.
- $preview_continuous_mode [0]
- If nonzero, run a previewer to view the document, and continue
- running latexmk to keep .dvi up-to-date. Equivalent to the -pvc
- option. Which previewer is run depends on the other settings,
- see the command line options -view=, and the variable $view.
+ 10 April 2009 21
- 22 December 2008 20
+LATEXMK(1L) LATEXMK(1L)
-LATEXMK(1L) LATEXMK(1L)
+ 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. Set-
+ ting the variable to -1 is used to indicate that $pscmd is not
+ to be used.
+ $postscript_mode [0]
+ If nonzero, generate a postscript version of the document.
+ Equivalent to the -ps option.
+
+ If some other request is made for which a postscript file is needed,
+ then $postscript_mode will be set to 1.
+
+ $preview_continuous_mode [0]
+ If nonzero, run a previewer to view the document, and continue
+ running latexmk to keep .dvi up-to-date. Equivalent to the -pvc
+ option. Which previewer is run depends on the other settings,
+ see the command line options -view=, and the variable $view.
$preview_mode [0]
If nonzero, run a previewer to preview the document. Equivalent
@@ -1375,6 +1469,17 @@ LATEXMK(1L) LATEXMK(1L)
postscript file before other processing. Equivalent to specify-
ing the -pF option.
+
+
+ 10 April 2009 22
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
$ps_previewer ["start gv %O %S", but "start %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
@@ -1390,18 +1495,6 @@ LATEXMK(1L) LATEXMK(1L)
of gv under different names, e.g., ggv, kghostview, etc, but
perhaps not one called gv.
-
-
-
- 22 December 2008 21
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
$ps_previewer_landscape ["start gv -swap %O %S", but "start %O %S"
under MS-WINDOWS]
The command to invoke a ps-previewer in landscape mode.
@@ -1444,6 +1537,18 @@ LATEXMK(1L) LATEXMK(1L)
Directory to store temporary files that latexmk may generate
while running.
+
+
+
+ 10 April 2009 23
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
The default under MSWindows (including cygwin), is to set
$tmpdir to the value of the first of whichever of the system
environment variables TMPDIR or TEMP exists, otherwise to the
@@ -1459,16 +1564,6 @@ LATEXMK(1L) LATEXMK(1L)
generated is to be used (among dvi, ps and pdf).
-
- 22 December 2008 22
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
CUSTOM DEPENDENCIES
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
@@ -1511,6 +1606,18 @@ CUSTOM DEPENDENCIES
It is invoked whenever latexmk detects that a run of latex/pdflatex
needs to read a file, like a graphics file, whose extension is the to-
+
+
+
+ 10 April 2009 24
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
extension of a custom dependency. Then latexmk 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
@@ -1524,18 +1631,6 @@ CUSTOM DEPENDENCIES
those without knowledge of the Perl programming language. Of course,
experts could do something much more elaborate.
-
-
-
- 22 December 2008 23
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
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.
@@ -1581,27 +1676,27 @@ LATEXMK(1L) LATEXMK(1L)
system("fig2dev -Lps '$_[0].fig' '$_[0].eps'");
}
- This causes the invocation of the fig2dev program to have quoted file-
- names; it should therefore work with filenames containing spaces. How-
- ever, 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.
- 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
+ 10 April 2009 25
- 22 December 2008 24
+LATEXMK(1L) LATEXMK(1L)
-LATEXMK(1L) LATEXMK(1L)
+ This causes the invocation of the fig2dev program to have quoted file-
+ names; it should therefore work with filenames containing spaces. How-
+ ever, 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.
+ 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 {
@@ -1649,25 +1744,27 @@ LATEXMK(1L) LATEXMK(1L)
be perpetually out-of-date. This situation, of circular dependencies,
is endemic to latex, and latexmk 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 .nnd (or and .aux
- file, etc) that changes on each new run, then you will have a problem.
- For real experts: See the %hash_cal_ignore_pattern if you have to deal
- with such problems.
- Glossaries can be dealt with similarly.
+ 10 April 2009 26
- 22 December 2008 25
+LATEXMK(1L) LATEXMK(1L)
-LATEXMK(1L) LATEXMK(1L)
+ 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 .nnd (or and .aux
+ file, etc) that changes on each new run, then you will have a problem.
+ For real experts: See the %hash_cal_ignore_pattern if you have to deal
+ with such problems.
+
+ Glossaries can be dealt with similarly.
OLD METHOD OF DEFINING CUSTOM DEPENDENCIES
@@ -1718,17 +1815,10 @@ BUGS
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.)
-
-AUTHOR
- Current version, by John Collins (username collins at node
- phys.psu.edu). (Version 4.03).
- 22 December 2008 26
+ 10 April 2009 27
@@ -1737,6 +1827,14 @@ AUTHOR
LATEXMK(1L) LATEXMK(1L)
+ 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.)
+
+AUTHOR
+ Current version, by John Collins (username collins at node
+ phys.psu.edu). (Version 4.05).
+
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/>.
@@ -1791,10 +1889,6 @@ LATEXMK(1L) LATEXMK(1L)
-
-
-
-
- 22 December 2008 27
+ 10 April 2009 28