summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexmk
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-07-03 22:51:15 +0000
committerKarl Berry <karl@freefriends.org>2013-07-03 22:51:15 +0000
commit6f3c3fa59abecd6b5efdc4bc76dd364cfa16d1da (patch)
tree68963723244d29f9adb7e27ce3087a495a70ee52 /Master/texmf-dist/doc/support/latexmk
parent52145c9a54e8526420e0c231bdc344828f2f70a5 (diff)
latexmk (3jul13)
git-svn-id: svn://tug.org/texlive/trunk@31087 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support/latexmk')
-rw-r--r--Master/texmf-dist/doc/support/latexmk/CHANGES14
-rw-r--r--Master/texmf-dist/doc/support/latexmk/INSTALL2
-rw-r--r--Master/texmf-dist/doc/support/latexmk/README9
-rw-r--r--Master/texmf-dist/doc/support/latexmk/example_rcfiles/README27
-rw-r--r--Master/texmf-dist/doc/support/latexmk/example_rcfiles/exceltex_latexmkrc64
-rw-r--r--Master/texmf-dist/doc/support/latexmk/example_rcfiles/lualatex_latexmkrc20
-rw-r--r--Master/texmf-dist/doc/support/latexmk/example_rcfiles/pythontex-latexmkrc48
-rw-r--r--Master/texmf-dist/doc/support/latexmk/example_rcfiles/xelatex_latexmkrc2
-rw-r--r--Master/texmf-dist/doc/support/latexmk/latexmk.pdfbin124523 -> 131290 bytes
-rw-r--r--Master/texmf-dist/doc/support/latexmk/latexmk.txt1841
10 files changed, 1140 insertions, 887 deletions
diff --git a/Master/texmf-dist/doc/support/latexmk/CHANGES b/Master/texmf-dist/doc/support/latexmk/CHANGES
index a7ed053be72..d2607265011 100644
--- a/Master/texmf-dist/doc/support/latexmk/CHANGES
+++ b/Master/texmf-dist/doc/support/latexmk/CHANGES
@@ -395,3 +395,17 @@ From v. 4.34 to 4.35
Correct bug that when the --gg option is used, the rule database
from the old fdb file was used instead of being cleared.
+From v. 4.35 to 4.37
+ Correct failure that happens when name of current directory
+ contains characters with special meaning in regular expression.
+ -rules option now works with -pvc
+ Add -lualatex option, like -xelatex.
+ File specifications in $clean_ext and $clean_full_ext are allowed
+ to contain wildcards.
+ Warnings are given when rc file is a directory instead of a file.
+ Correct bug that if revtex4-1.cls is used, footnotes are set to
+ be in the bibliography, and latexmk's aux_dir or out_dir is set,
+ then latexmk fails to run bibtex when needed, because the
+ relevant bib file is not found.
+ Other minor corrections and code improvements.
+ Documentation updates and corrections.
diff --git a/Master/texmf-dist/doc/support/latexmk/INSTALL b/Master/texmf-dist/doc/support/latexmk/INSTALL
index 16aefc347bd..92fb994529a 100644
--- a/Master/texmf-dist/doc/support/latexmk/INSTALL
+++ b/Master/texmf-dist/doc/support/latexmk/INSTALL
@@ -1,6 +1,6 @@
INSTALLING latexmk
==================
- (Version 4.35, 11 November 2012)
+ (Version 4.37, 2 July 2013)
John Collins
Physics Department
diff --git a/Master/texmf-dist/doc/support/latexmk/README b/Master/texmf-dist/doc/support/latexmk/README
index db5cf8413c3..3d9c51d3a3a 100644
--- a/Master/texmf-dist/doc/support/latexmk/README
+++ b/Master/texmf-dist/doc/support/latexmk/README
@@ -1,5 +1,5 @@
-Latexmk, version 4.35, 11 November 2012
----------------------------------------
+Latexmk, version 4.37, 2 July 2013
+----------------------------------
Latexmk completely automates the process of generating a LaTeX
document. Essentially, it is a highly specialized cousin of the
@@ -92,7 +92,7 @@ NOTES:-
John Collins
---------------------------- "latexmk -h" ----------------------------
-Latexmk 4.35: Automatic LaTeX document generation routine
+Latexmk 4.37: Automatic LaTeX document generation routine
Usage: latexmk [latexmk_options] [filename ...]
@@ -198,7 +198,10 @@ Usage: latexmk [latexmk_options] [filename ...]
-view=none - no viewer is used
-view=ps - viewer is for ps
-view=pdf - viewer is for pdf
+ -lualatex - use lualatex for processing files to pdf
+ and turn pdf mode on, dvi/ps modes off
-xelatex - use xelatex for processing files to pdf
+ and turn pdf mode on, dvi/ps modes off
filename = the root filename of LaTeX document
diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/README b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/README
index 816526efd8a..61aa7832dba 100644
--- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/README
+++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/README
@@ -33,3 +33,30 @@ NOTES:
safety against special characters in filenames. The double quotes
appear not to cause problems in all situations that I have tried.
+5. Note that the files for exceltex and pythontex illustrate an answer
+ to an issue that arises in the following generic situation:
+ a. A LaTeX package wants to use an external program to do some
+ processing. It does this by writing a control file that is used
+ by the external program.
+ b. The user is to run the external program after a first run of
+ latex/pdflatex (etc). It generates some files that are to be
+ read by a subsequent compilation of the TeX document.
+ c. It is desired to do the run of the external program and
+ to do the extra run of latex/pdflatex only when necessary.
+ d. Possibly there are further dependencies on files used by the
+ external program.
+ The third problem is handled nicely by latexmk's normal mechanisms,
+ but it is necessary to persuade it to create a suitable rule to run
+ the external program. A nice trick with custom dependencies,
+ illustrated by exceltex and pythontex examples, gets the rule set
+ up. The exceltex shows how dependencies on other files can be
+ determined.
+
+6. Further assistance for latexmk can be provided when style files
+ provide suitable messages about missing files. See the
+ exceltex1.sty and pythontex1.sty files for examples of what is
+ needed. These files are modifications of exceltex.sty and
+ pythontex.sty that provide the necessary assistance. (The versions
+ were the ones current on 30 April 2013.)
+
+
diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/exceltex_latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/exceltex_latexmkrc
new file mode 100644
index 00000000000..e1cf68424fa
--- /dev/null
+++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/exceltex_latexmkrc
@@ -0,0 +1,64 @@
+# This shows how to use the exceltex package with latexmk
+#
+# Exceltex is a package that enables LaTeX documents to use data from
+# Excel spreadsheets. It has two parts: a LaTeX package in a file
+# named exceltex.sty and a (Perl) script named exceltex. The custom
+# dependency given below enables latexmk to call the exceltex script
+# whenever appropriate.
+#
+# The functioning is as follows: The main tex file uses the package
+# exceltex to specify the use of the contents of cells in an xls
+# spreadsheet. It does this by writing a specification of the cells to
+# a file with extension excltx. The script exceltex reads this,
+# extracts the data from the spreadsheet(s), and writes them in files
+# that are read during the next compilation of the main document. (The
+# exceltex package, with its script, is part of the current version of
+# TeXLive, as of 2012.)
+#
+# In addition to running the exceltex script, the subroutine defined
+# below also reads the excltx file to find the names of the
+# spreadsheet files used. It then uses an internal subroutine of
+# latexmk to add these files to the source-file list of the custom
+# dependency. Thus if the spreadsheet file (or files) changes, even
+# without any other changes, latexmk will know to rerun exceltex and
+# then recompile the main tex file if necessary.
+#
+# Notes:
+# 1. See
+# http://tex.stackexchange.com/questions/107764/exceltex-dependencies-in-latexmk
+# for the motivation, and see the exceltex documentation for an
+# example of the use of the exceltex package.
+# 2. You may find you need to install certain Perl modules in
+# order for the exceltex script to work; these modules are needed
+# for parsing excel spreadsheets. You'll need to examine
+# documentation for Perl to find out how to do this.
+
+
+add_cus_dep('excltx', 'tex', 0, 'excel2tex');
+sub excel2tex {
+ # This subroutine is a fudge, because it from latexmk's point of
+ # view, it makes the main .tex file depend on the .excltx file.
+ # But it doesn't actually make the .tex file, but is used for its
+ # side effects in creating other files. The dependence is a way
+ # of triggering the rule to be run whenever the .excltx file
+ # changes, and to do this before running latex/pdflatex again.
+
+ # First find dependency/ies on .xls files, by parsing the .excltx file,
+ my $Hsource = new FileHandle;
+ my %xls = ();
+ my $source = "$_[0].excltx";
+ if (! open $Hsource, "<$source") {
+ warn "excel2tex subroutine: Could not read '$source'\n";
+ return 1;
+ }
+ while ( <$Hsource> ) {
+ if ( /^\s*;/ ) { next; }
+ if ( /^\s*[ct]:[^:]*\:([^!]*)!/ ) { $xls{$1} = 1; }
+ }
+ close $Hsource;
+ foreach (keys %xls) {
+ rdb_ensure_file( $rule, $_ );
+ }
+ return system("exceltex \"$_[0]\"") ;
+}
+
diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/lualatex_latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/lualatex_latexmkrc
new file mode 100644
index 00000000000..5a0a088c61b
--- /dev/null
+++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/lualatex_latexmkrc
@@ -0,0 +1,20 @@
+# This shows how to use lualatex (http://en.wikipedia.org/wiki/XeTeX)
+# with latexmk. Lualatex uses Unicode and "supporting modern font
+# technologies such as OpenType or Apple Advanced Typography.
+#
+# WARNING: latexmk.pl is changing, and plans to have more internal
+# support for lualatex.
+#
+# Since lualatex only produces pdf files, it is a replacement for
+# pdflatex. To make it your default typesetting engine within latexmk
+# you will not only need to set the $pdflatex variable to require the
+# use of lualatex, but also to turn on production of pdf files and to
+# turn off the production of dvi and ps files, as in the following
+# code:
+
+
+$pdflatex = 'lualatex %O %S';
+$pdf_mode = 1;
+$postscript_mode = $dvi_mode = 0;
+
+
diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/pythontex-latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/pythontex-latexmkrc
new file mode 100644
index 00000000000..8a3d3f1ad26
--- /dev/null
+++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/pythontex-latexmkrc
@@ -0,0 +1,48 @@
+# This shows how to use the pythontex package with latexmk
+
+# This version has a fudge on the latex and pdflatex commands that
+# allows the pythontex custom dependency to work even when $out_dir
+# is used to set the output directory. Without the fudge (done by
+# trickery symbolic links) the custom dependency for using pythontex
+# will not be detected.
+
+add_cus_dep('pytxcode', 'tex', 0, 'pythontex');
+sub pythontex {
+ # This subroutine is a fudge, because it from latexmk's point of
+ # view, it makes the main .tex file depend on the .pytxcode file.
+ # But it doesn't actually make the .tex file, but is used for its
+ # side effects in creating other files. The dependence is a way
+ # of triggering the rule to be run whenever the .pytxcode file
+ # changes, and to do this before running latex/pdflatex again.
+ return system("pythontex.py \"$_[0]\"") ;
+}
+
+
+$pdflatex = 'internal mylatex %R %Z pdflatex %O %S';
+$latex = 'internal mylatex %R %Z latex %O %S';
+sub mylatex {
+ my $root = shift;
+ my $dir_string = shift;
+ my $code = "$root.pytxcode";
+ my $result = "pythontex-files-$root";
+ if ($dir_string) {
+ warn "mylatex: Making symlinks to fool cus_dep creation\n";
+ unlink $code;
+ if (-l $result) {
+ unlink $result;
+ }
+ elsif (-d $result) {
+ unlink glob "$result/*";
+ rmdir $result;
+ }
+ symlink $dir_string.$code, $code;
+ if ( ! -e $dir_string.$result ) { mkdir $dir_string.$result; }
+ symlink $dir_string.$result, $result;
+ }
+ else {
+ foreach ($code, $result) { if (-l) { unlink; } }
+ }
+ return system @_;
+}
+
+
diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/xelatex_latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/xelatex_latexmkrc
index 896c7c5e310..ddc721c00f7 100644
--- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/xelatex_latexmkrc
+++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/xelatex_latexmkrc
@@ -2,7 +2,7 @@
# with latexmk. Xelatex uses Unicode and "supporting modern font
# technologies such as OpenType or Apple Advanced Typography.
#
-# WARNING: latexmk.pl is changing, and plans to have internal
+# WARNING: latexmk.pl is changing, and plans to have more internal
# support for xelatex.
#
# Since xelatex only produces pdf files, it is a replacement for
diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.pdf b/Master/texmf-dist/doc/support/latexmk/latexmk.pdf
index 13be83f23e4..08e59651c45 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 50ce0195a07..487c6c057a3 100644
--- a/Master/texmf-dist/doc/support/latexmk/latexmk.txt
+++ b/Master/texmf-dist/doc/support/latexmk/latexmk.txt
@@ -1,9 +1,4 @@
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
NAME
latexmk - generate LaTeX document
@@ -23,88 +18,89 @@ DESCRIPTION
file.
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
- on-screen view of the compiled document.
+ In that case the latex program (or one of its relatives), etc, are
+ rerun whenever one of the source files is modified, and the previewer
+ automatically updates the on-screen view of the compiled document.
Latexmk determines which are the source files by examining the log
file. (Optionally, it also examines the list of input and output files
- generated by the -recorder option of modern versions of latex and
- pdflatex. See the documentation for the -recorder option of latexmk
- below.) When latexmk is run, it examines properties of the source
- files, and if any have been changed since the last document generation,
- latexmk 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, latexmk will also run bibtex,
- biber, and/or makeindex. In addition, latexmk 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.
-
- Latexmk has two different previewing options. In the simple -pv
- 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
+ generated by the -recorder option of modern versions of latex (and
+ pdflatex, xelatex, lualatex, etc). See the documentation for the
+ -recorder option of latexmk below.) When latexmk is run, it examines
+ properties of the source files, and if any have been changed since the
+ last document generation, latexmk will run the various LaTeX processing
+ programs as necessary. In particular, it will repeat the run of latex
+ (or a related program)) 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,
+ latexmk will also run bibtex, biber, and/or makeindex. In addition,
+ latexmk can be configured to generate other necessary files. For exam-
+ ple, from an updated figure file it can automatically generate a file
+ in encapsulated postscript or another suitable format for reading by
+ LaTeX.
+
+ Latexmk has two different previewing options. In the simple -pv
+ 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.
- The second previewing option is the powerful -pvc option (mnemonic:
+ The second previewing option is the powerful -pvc option (mnemonic:
"preview continuously"). In this case, latexmk runs continuously, reg-
- ularly monitoring all the source files to see if any have changed.
- Every time a change is detected, latexmk runs all the programs neces-
+ ularly monitoring all the source files to see if any have changed.
+ Every time a change is detected, latexmk runs all the programs neces-
sary to generate a new version of the document. A good previewer (like
gv) will then automatically update its display. Thus the user can sim-
ply edit a file and, when the changes are written to disk, latexmk com-
- pletely automates the cycle of updating the .dvi (and possibly the .ps
+ pletely 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.
+ 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
- 11 November 2012 1
+ 1
-LATEXMK(1L) LATEXMK(1L)
+LATEXMK(1L) LATEXMK(1L)
- WYSIWYG, but usefully close.
- 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.
- 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 generated dvi
+ 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 generated dvi
and postscript files. (See the options -dF and -pF, and the documenta-
- tion for the $dvi_filter and $ps_filter configuration variables.)
- These capabilities are leftover from older versions of latexmk. More
- flexibility can be obtained in current versions, since the command
- strings for running latex, pdflatex, etc can now be configured to run
+ tion for the $dvi_filter and $ps_filter configuration variables.)
+ These capabilities are leftover from older versions of latexmk. More
+ flexibility can be obtained in current versions, since the command
+ strings for running latex, pdflatex, etc can now be configured to run
multiple commands. This also extends the possibility of postprocessing
generated files to pdf files. 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
+ 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
the operating system, so latexmk often works without special configura-
- tion on MS-Windows, cygwin, Linux, OS-X, and other UNIX systems
+ tion on MS-Windows, cygwin, Linux, OS-X, and other UNIX systems
(notably Solaris).
- A very annoying complication handled very reliably by Latexmk, is that
- LaTeX is a multiple pass system. On each run, LaTeX reads in informa-
+ A very annoying complication handled very reliably by latexmk, is that
+ LaTeX is a multiple pass system. On each run, LaTeX reads in informa-
tion 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
+ 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, latexmk 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 latexmk generates an extra
+ on the source files, and a symptom is that latexmk generates an extra
file (with extension .fdb_latexmk, by default) that contains the source
file information.
@@ -117,17 +113,21 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE
All options can be introduced by single or double "-" characters, e.g.,
"latexmk -help" or "latexmk --help".
- Note: In addition to the options in the list below, latexmk recognizes
- almost all the options recognized by the latex and pdflatex programs in
- one of both of their current TeXLive and MiKTeX implementations. Some
- of the options for these programs also trigger special action or behav-
- ior by latexmk, in which case they are in this list. Otherwise, they
- are just passed through to a called latex or pdflatex program. Run
- latexmk with the -showextraoptions to get a list of the options that
+ Note 1: In addition to the options in the list below, latexmk recog-
+ nizes almost all the options recognized by the latex, pdflatex programs
+ (and their relatives) in their current TeXLive and MiKTeX implementa-
+ tions. Some of the options for these programs also trigger special
+ action or behavior by latexmk, in which case they have specific expla-
+ nations in this document. Otherwise, they are just passed through to a
+ called latex or pdflatex program. Run latexmk with the -showextraop-
+ tions to get a list of the options that latexmk accepts and that are
+ simply passed through to latex or pdflatex (etc). See also the expla-
+ nation of the -showextraoptions option for more information.
- 11 November 2012 2
+
+ 2 July 2013 2
@@ -136,21 +136,30 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE
LATEXMK(1L) LATEXMK(1L)
- latexmk accepts and that are simply passed through to latex or pdfla-
- tex. See also the explanation of the -showextraoptions option for more
- information.
+ Note 2: In this documentation, the program pdflatex is often referred
+ to. Users of programs like lualatex and xelatex should know that from
+ latexmk's point of view, these other programs behave like pdflatex,
+ i.e., they make a pdf file from a tex file, etc. So whenever pdflatex
+ is mentioned without mention of the other programs, the statements
+ apply equally to lualatex, xelatex, and any other similar programs.
+ Latexmk can be easily configured to use whichever of these programs is
+ needed. See the documentation for the following options: -pdfla-
+ tex="COMMAND", -lualatex, and -xelatex, and also see the documentation
+ for the $pdflatex configuration variable. At present latexmk cannot do
+ automatic detection of which program is to be used.
+
Definitions of options and arguments
- file One or more files can be specified. If no files are specified,
- latexmk will, by default, run on all files in the current work-
- ing directory with a ".tex" extension. This behavior can be
+ file One or more files can be specified. If no files are specified,
+ latexmk will, by default, run on all files in the current work-
+ ing directory with a ".tex" extension. This behavior can be
changed: see the description concerning the @default_files vari-
- able in the section "List of configuration variables usable in
+ able in the section "List of configuration variables usable in
initialization files".
- If a file is specified without an extension, then the ".tex" extension
+ 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
@@ -160,15 +169,15 @@ LATEXMK(1L) LATEXMK(1L)
-auxdir=FOO or -aux-directory=FOO
- Sets the directory for auxiliary output files of (pdf)latex
- (.aux, .log etc). This achieves its effect by the -aux-direc-
- tory option of (pdf)latex, which currently is only implemented
+ Sets the directory for auxiliary output files of (pdf)latex
+ (.aux, .log etc). This achieves its effect by the -aux-direc-
+ tory option of (pdf)latex, which currently is only implemented
on the MiKTeX version of (pdf)latex.
- See also the -outdir/-output-directory options, and the
+ See also the -outdir/-output-directory options, and the
$aux_dir, $out_dir, and $search_path_separator configuration
- variables of latexmk. In particular, see the documentation of
- $out_dir for some complications on what directory names are
+ variables of latexmk. In particular, see the documentation of
+ $out_dir for some complications on what directory names are
suitable.
@@ -177,23 +186,16 @@ LATEXMK(1L) LATEXMK(1L)
When the source file uses bbl files for bibliography, run bibtex
or biber as needed to regenerate the bbl files.
- This property can also be configured by setting the $bibtex_use
+ This property can also be configured by setting the $bibtex_use
variable to 2 in a configuration file
-bibtex-
Never run bibtex or biber.
- A common use for this option is when a document comes from an
- external source, complete with its bbl file(s), and the user
- does not have the corresponding bib files available. In this
- situation use of the -bibtex- option will prevent latexmk from
- trying to run bibtex or biber, which would result in overwriting
- of the bbl files.
-
- 11 November 2012 3
+ 2 July 2013 3
@@ -202,43 +204,50 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
+ A common use for this option is when a document comes from an
+ external source, complete with its bbl file(s), and the user
+ does not have the corresponding bib files available. In this
+ situation use of the -bibtex- option will prevent latexmk from
+ trying to run bibtex or biber, which would result in overwriting
+ of the bbl files.
+
-bibtex-cond
- When the source file uses bbl file(s) for the bibliography, run
- bibtex or biber as needed to regenerate the bbl files, but only
- if the relevant bib file(s) exist. Thus when the bib files are
- not available, bibtex or biber is not run, thereby avoiding
+ When the source file uses bbl file(s) for the bibliography, run
+ bibtex or biber as needed to regenerate the bbl files, but only
+ if the relevant bib file(s) exist. Thus when the bib files are
+ not available, bibtex or biber is not run, thereby avoiding
overwriting of the bbl file(s). This is the default setting.
- (Note that it is possible for latexmk to decide that the bib
- file does not exist, even though the bib file does exist and
- bibtex or biber finds it. The problem is that the bib file may
- not be in the current directory but in some search path; the
+ (Note that it is possible for latexmk to decide that the bib
+ file does not exist, even though the bib file does exist and
+ bibtex or biber finds it. The problem is that the bib file may
+ not be in the current directory but in some search path; the
places latexmk and bibtex or biber cause to be searched need not
- be identical. On modern installations of TeX and related pro-
- grams this problem should not arise, since latexmk uses the
+ be identical. On modern installations of TeX and related pro-
+ grams this problem should not arise, since latexmk uses the
kpsewhich program to do the search, and kpsewhich should use the
- same search path as bibtex and biber. If this problem arises,
+ same search path as bibtex and biber. If this problem arises,
use the -bibtex option when invoking latexmk.)
-bm <message>
- A banner message to print diagonally across each page when con-
- verting the dvi file to postscript. The message must be a sin-
- gle argument on the command line so be careful with quoting spa-
- ces and such.
+ A banner message to print diagonally across each page when con-
+ verting the dvi file to postscript. The message must be a sin-
+ gle argument on the command line so be careful with quoting
+ spaces and such.
- Note that if the -bm option is specified, the -ps option is
+ Note that if the -bm option is specified, the -ps option is
assumed.
-bi <intensity>
- How dark to print the banner message. A decimal number between
+ 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.
-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
+ 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 charac-
ter messages.
@@ -248,18 +257,13 @@ LATEXMK(1L) LATEXMK(1L)
-c Clean up (remove) all regeneratable files generated by latex and
bibtex or biber 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 @generated_exts configuration variable. In addition,
- files with extensions by the $clean_ext configuration variable
- are removed.
+ a combination of log files, aux files, latexmk's database file
+ of source file information, and those with extensions specified
+ in the @generated_exts configuration variable. In addition,
- This cleanup is instead of a regular make. See the -gg option
- if you want to do a cleanup then a make.
-
- 11 November 2012 4
+ 2 July 2013 4
@@ -268,38 +272,75 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
- If $bibtex_use is set to 0 or 1, bbl files are counted as non-
+ files specified by the $clean_ext configuration variable are
+ removed.
+
+ This cleanup is instead of a regular make. See the -gg option
+ if you want to do a cleanup then a make.
+
+ If $bibtex_use is set to 0 or 1, bbl files are counted as non-
regeneratable.
- If $cleanup_includes_cusdep_generated is nonzero, regeneratable
- files are considered as including those generated by custom
- dependencies and are also deleted. Otherwise these files are
+ If $cleanup_includes_cusdep_generated is nonzero, regeneratable
+ files are considered as including those generated by custom
+ dependencies and are also deleted. Otherwise these files are
not deleted.
-C Clean up (remove) all regeneratable files generated by latex and
- bibtex or biber. This is the same as the -c option with the
- addition of dvi, postscript and pdf files, and those with exten-
- sions in the $clean_full_ext configuration variable.
+ bibtex or biber. This is the same as the -c option with the
+ addition of dvi, postscript and pdf files, and those specified
+ in the $clean_full_ext configuration variable.
- This cleanup is instead of a regular make. See the -gg option
+ This cleanup is instead of a regular make. See the -gg option
if you want to do a cleanup than a make.
- If $bibtex_use is set to 0 or 1, bbl files are counted as non-
+ If $bibtex_use is set to 0 or 1, bbl files are counted as non-
regeneratable.
- If $cleanup_includes_cusdep_generated is nonzero, regeneratable
- files are considered as including those generated by custom
- dependencies and are also deleted. Otherwise these files are
+ If $cleanup_includes_cusdep_generated is nonzero, regeneratable
+ files are considered as including those generated by custom
+ dependencies and are also deleted. Otherwise these files are
not deleted.
- -CA (Obsolete). Now equivalent to the -C option. See that option
+ -CA (Obsolete). Now equivalent to the -C option. See that option
for details.
+ -cd Change to the directory containing the main source file before
+ processing it. Then all the generated files (aux, log, dvi,
+ pdf, etc) will be relative to the source file.
+
+ This option is particularly useful when latexmk is invoked from
+ a GUI configured to invoke latexmk with a full pathname for the
+ source file.
+
+ -cd- Do NOT change to the directory containing the main source file
+ before processing it. Then all the generated files (aux, log,
+ dvi, pdf, etc) will be relative to the current directory rather
+ than the source file.
+
+ This is the default behavior and corresponds to the behavior of
+ the latex and pdflatex programs. However, it is not desirable
+ behavior when latexmk is invoked by a GUI configured to invoke
+ latexmk with a full pathname for the source file. See the -cd
+ option.
+
-CF Remove the file containing the database of source file informa-
tion, before doing the other actions requested.
-d Set draft mode. This prints the banner message "DRAFT" across
your page when converting the dvi file to postscript. Size and
+
+
+
+ 2 July 2013 5
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
intensity can be modified with the -bs and -bi options. The -bm
option will override this option as this is really just a short
way of specifying:
@@ -323,17 +364,6 @@ LATEXMK(1L) LATEXMK(1L)
See the section "USING latexmk WITH make" for an example of how
to use a dependency list with make.
-
-
- 11 November 2012 5
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
Users familiar with GNU automake and gcc will find that the
-deps option is very similar in its purpose and results to the
-M option to gcc. (In fact, latexmk also has options -M, -MF,
@@ -369,8 +399,20 @@ LATEXMK(1L) LATEXMK(1L)
-diagnostics
Print detailed diagnostics during a run. This may help for
- debugging problems or to understand latexmk's behavior in diffi-
- cult situations.
+ debugging problems or to understand latexmk's behavior in
+
+
+
+ 2 July 2013 6
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ difficult situations.
-dvi Generate dvi version of document.
@@ -388,18 +430,6 @@ LATEXMK(1L) LATEXMK(1L)
ment statements separated by semicolons.
The code is executed when the -e option is encountered during
-
-
-
- 11 November 2012 6
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
latexmk's parsing of its command line. See the -r option for a
way of executing initialization code from a file. An error
results in latexmk stopping. Multiple instances of the -r and
@@ -439,178 +469,197 @@ LATEXMK(1L) LATEXMK(1L)
found an error which will not be resolved by further processing,
no further processing is carried out.
- -f- Turn off the forced processing-past-errors such as is set by the
- -f option. This could be used to override a setting in a con-
- figuration file.
+ Note: "Further processing" means the running of other programs
+ or the rerunning of latex (etc) that would be done if no errors
- -g Force latexmk to process document fully, even under situations
- where latexmk 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.
- -g- Turn off -g.
- -gg "Super go mode" or "clean make": clean out generated files as if
- -C had been given, and then do a regular make.
+ 2 July 2013 7
+
- 11 November 2012 7
+LATEXMK(1L) LATEXMK(1L)
+ had occurred. If instead, or additionally, you want the latex
+ (etc) program not to pause for user input after an error, you
+ should arrange this by an option that is passed to the program,
+ e.g., by latexmk's option -interaction=nonstopmode.
+ -f- Turn off the forced processing-past-errors such as is set by the
+ -f option. This could be used to override a setting in a con-
+ figuration file.
-LATEXMK(1L) LATEXMK(1L)
+ -g Force latexmk to process document fully, even under situations
+ where latexmk 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.
+ -g- Turn off -g.
+
+ -gg "Super go mode" or "clean make": clean out generated files as if
+ -C had been given, and then do a regular make.
-h, -help
Print help information.
-jobname=STRING
- Set the basename of output files(s) to STRING, instead of the
+ Set the basename of output files(s) to STRING, instead of the
default, which is the basename of the specified TeX file.
- This is like the same option for current implementations of the
- latex and pdflatex, and the passing of this option to these pro-
- grams is part of latexmk's implementation of -jobname.
+ This is like the same option for current implementations of the
+ latex, pdflatex, etc, and the passing of this option to these
+ programs is part of latexmk's implementation of -jobname.
-l Run in landscape mode, using the landscape mode for the preview-
- ers and the dvi to postscript converters. This option is not
- normally needed nowadays, since current previewers normally
+ ers and the dvi to postscript converters. This option is not
+ normally needed nowadays, since current previewers normally
determine this information automatically.
-l- Turn off -l.
-latex="COMMAND"
This sets the string specifying the command to run latex, and is
- typically used to add desired options. Since the string nor-
+ typically used to add desired options. Since the string nor-
mally contains spaces, it should be quoted, e.g.,
- latex -latex="latex --shell-escape %O %S" foo.tex
+ latexmk -latex="latex --shell-escape %O %S" foo.tex
- The specification of the contents of the string are the same as
- for the $latex configuration variable. Depending on your oper-
- ating system and the command-line shell you are using, you may
- need to change the single quotes to double quotes (or something
+ The specification of the contents of the string are the same as
+ for the $latex configuration variable. Depending on your oper-
+ ating system and the command-line shell you are using, you may
+ need to change the single quotes to double quotes (or something
else).
To set the command for running pdflatex (rather than the command
for latex) see the -pdflatex option.
- Note that the effect of this option can also be achieved by
+ Note that the effect of this option can also be achieved by
using the -e option with a suitable line of Perl code to set the
$latex variable. See the explanation of the -e option.
- -M Show list of dependent files after processing. This is equiva-
- lent to the -deps option.
- -MF file
- If a list of dependents is made, the -MF specifies the file to
- write it to.
- -MP If a list of dependents is made, includes phony target for each
- source file. If you use the dependents list in a Makefile, the
- dummy rules work around errors make gives if you remove header
- files without updating the Makefile to match.
+ 2 July 2013 8
+
- -new-viewer
- When in continuous-preview mode, always start a new viewer to
- view the generated file. By default, latexmk will, in
- 11 November 2012 8
+LATEXMK(1L) LATEXMK(1L)
+ -lualatex
+ Use lualatex. That is, use lualatex to process the source
+ file(s) to pdf (in place of pdflatex). This option is exactly
+ equivalent to specifying the following sequence of options:
+ -pdflatex="lualatex %O %S" -pdf -dvi- -ps-
-LATEXMK(1L) LATEXMK(1L)
+ -M Show list of dependent files after processing. This is equiva-
+ lent to the -deps option.
+ -MF file
+ If a list of dependents is made, the -MF specifies the file to
+ write it to.
- continuous-preview mode, test for a previously running previewer
- for the same file and not start a new one if a previous pre-
- viewer 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 direc-
- tory). This option turns off the default behavior.
+ -MP If a list of dependents is made, includes phony target for each
+ source file. If you use the dependents list in a Makefile, the
+ dummy rules work around errors make gives if you remove header
+ files without updating the Makefile to match.
+
+ -new-viewer
+ When in continuous-preview mode, always start a new viewer to
+ view the generated file. By default, latexmk will, in continu-
+ ous-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.
-new-viewer-
- The inverse of the -new-viewer option. It puts latexmk in its
+ The inverse of the -new-viewer option. It puts latexmk in its
normal behavior that in preview-continuous mode it checks for an
already-running previewer.
-nobibtex
Never run bibtex or biber.
- A common use for this option is when a document comes from an
- external source, complete with its bbl file(s), and the user
- does not have the corresponding bib files available. In this
- situation use of the -nobibtex option will prevent latexmk from
+ A common use for this option is when a document comes from an
+ external source, complete with its bbl file(s), and the user
+ does not have the corresponding bib files available. In this
+ situation use of the -nobibtex option will prevent latexmk from
trying to run bibtex or biber, which would result in overwriting
of the bbl files.
-norc Turn off the automatic reading of initialization (rc) files.
- N.B. Normally the initialization files are read and obeyed, and
- then command line options are obeyed in the order they are
- encountered. Then -norc is an exception to this rule: it is
+ N.B. Normally the initialization files are read and obeyed, and
+ then command line options are obeyed in the order they are
+ encountered. Then -norc is an exception to this rule: it is
acted on first, no matter where is occurs on the command line.
-outdir=FOO or -output-directory=FOO
- Sets the directory for the output files of (pdf)latex. This
- achieves its effect by the -output-directory option of
- (pdf)latex, which currently (Dec. 2011) is implemented on the
+ Sets the directory for the output files of (pdf)latex. This
+ achieves its effect by the -output-directory option of
+ (pdf)latex, which currently (Dec. 2011) is implemented on the
common versions of (pdf)latex, i.e., MiKTeX and TeXLive. It may
- not be present in other versions.
- See also the -auxdir/-aux-directory options, and the $aux_dir,
- $out_dir, and $search_path_separator configuration variables of
- latexmk. In particular, see the documentation of $out_dir for
- some complications on what directory names are suitable.
+ 2 July 2013 9
- -p Print out the document. By default it is the generated
- postscript file that is printed. But you can use the -print=...
- option to print the dvi or pdf files instead, and you can con-
- figure this in a start up file (by setting the $print_type vari-
- able).
- However, printing is enabled by default only under UNIX/LINUX
- systems, where the default is to use the lpr command. In
+LATEXMK(1L) LATEXMK(1L)
- 11 November 2012 9
+ not be present in other versions.
+ See also the -auxdir/-aux-directory options, and the $aux_dir,
+ $out_dir, and $search_path_separator configuration variables of
+ latexmk. In particular, see the documentation of $out_dir for
+ some complications on what directory names are suitable.
-LATEXMK(1L) LATEXMK(1L)
-
+ -p Print out the document. By default it is the generated
+ postscript file that is printed. But you can use the -print=...
+ option to print the dvi or pdf files instead, and you can con-
+ figure this in a start up file (by setting the $print_type vari-
+ able).
- 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 con-
- figured the print commands used by latexmk. This can be non-
- trivial. See the documentation on the $lpr, $lpr_dvi, and
- $lpr_pdf configuration variables to see how to set the commands
+ However, printing is enabled by default only under UNIX/LINUX
+ systems, where the default is to use the lpr command. In gen-
+ eral, 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 con-
+ figured the print commands used by latexmk. This can be non-
+ trivial. See the documentation on the $lpr, $lpr_dvi, and
+ $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
turns them off.
- -pdf Generate pdf version of document using pdflatex. (See the
- -xelatex if you wish to use xelatex to make your pdf file(s).)
+
+ -pdf Generate pdf version of document using pdflatex. (If you wish
+ to use lualatex or xelatex, you can use whichever of the options
+ -lualatex or -xelatex applies.) To configure latexmk to have
+ such behavior by default, see the section on "Configuration/ini-
+ tialization (rc) files".
+
-pdfdvi
Generate pdf version of document from the dvi file, by default
@@ -629,48 +678,59 @@ LATEXMK(1L) LATEXMK(1L)
is typically used to add desired options. Since the string nor-
mally contains spaces, it should be quoted, e.g.,
- latex -pdf -pdflatex="pdflatex --shell-escape %O %S"
+ latexmk -pdf -pdflatex="pdflatex --shell-escape %O %S"
foo.tex
The specification of the contents of the string are the same as
for the $pdflatex configuration variable. Depending on your
operating system and the command-line shell you are using, you
- may need to change the single quotes to double quotes (or some-
- thing else).
- To set the command for running latex (rather than the command
- for pdflatex) see the -latex option.
- Note that the effect of this option can also be achieved by
- using the -e option with a suitable line of Perl code to set the
- $pdflatex variable. See the explanation of the -e option.
- -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.
+ 2 July 2013 10
+
- -ps Generate postscript version of document.
+LATEXMK(1L) LATEXMK(1L)
+
+
+ may need to change the single quotes to double quotes (or some-
+ thing else).
- 11 November 2012 10
+ This option can also be used to set a program to be used instead
+ of the standard pdflatex program, e.g.,
+ latexmk -pdf -pdflatex="lualatex %O %S" foo.tex
+ to use lualatex or
+ latexmk -pdf -pdflatex="xelatex %O %S" foo.tex
+ to use xelatex.
-LATEXMK(1L) LATEXMK(1L)
+ To set the command for running latex (rather than the command
+ for pdflatex) see the -latex option.
+
+ Note that the effect of this option can also be achieved by
+ using the -e option with a suitable line of Perl code to set the
+ $pdflatex variable. See the explanation of the -e option.
+
+ -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.
+ -ps Generate postscript version of document.
-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
+ 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.)
- -pF Postscript file filtering. The argument to this option is a
- filter which will generate a filtered postscript file with the
+ -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.
@@ -683,69 +743,69 @@ LATEXMK(1L) LATEXMK(1L)
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
+ depend on your command interpreter, as used by the particular
version of perl and the operating system on your computer.
- -pv Run file previewer. If the -view option is used, this will
- select the kind of file to be previewed (dvi, ps or pdf). Oth-
- erwise the viewer views the "highest" kind of file selected, by
- the -dvi, -ps, -pdf, -pdfps options, in the order dvi, ps, pdf
- (low to high). If no file type has been selected, the dvi pre-
- viewer will be used. This option is incompatible with the -p
+ -pv Run file previewer. If the -view option is used, this will
+ select the kind of file to be previewed (dvi, ps or pdf). Oth-
+ erwise the viewer views the "highest" kind of file selected, by
+ the -dvi, -ps, -pdf, -pdfps options, in the order dvi, ps, pdf
+ (low to high). If no file type has been selected, the dvi pre-
+ viewer will be used. This option is incompatible with the -p
and -pvc options, so it turns them off.
-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
- 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 -pv option. The preview-continuous option -pvc
- 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 -p and -pv options, so it turns these
- options off.
- The -pvc option also turns off force mode (-f), as is normally
- best for continuous preview mode. If you really want force
- mode, use the options in the order -pvc -f.
- With a good previewer the display will be automatically updated.
- (Under some but not all 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.
+ 2 July 2013 11
- 11 November 2012 11
+LATEXMK(1L) LATEXMK(1L)
+ -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 -pv option. The preview-continuous option -pvc
+ 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 -p and -pv options, so it turns these
+ options off.
-LATEXMK(1L) LATEXMK(1L)
+ The -pvc option also turns off force mode (-f), as is normally
+ best for continuous preview mode. If you really want force
+ mode, use the options in the order -pvc -f.
+ With a good previewer the display will be automatically updated.
+ (Under some but not all 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 different viewer: SumatraPDF and
+ 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 different viewer: SumatraPDF and
gsview are good possibilities.
- There are some other methods for arranging an update, notably
- useful for many versions of xdvi and xpdf. These are best set
+ There are some other methods for arranging an update, notably
+ useful for many versions of xdvi and xpdf. These are best set
in latexmk's configuration; see below.
- Note that if latexmk dies or is stopped by the user, the
+ Note that if latexmk dies or is stopped by the user, the
"forked" previewer will continue to run. Successive invocations
- with the -pvc option will not fork new previewers, but latexmk
- will normally use the existing previewer. (At least this will
- happen when latexmk is running under an operating system where
- it knows how to determine whether an existing previewer is run-
+ with the -pvc option will not fork new previewers, but latexmk
+ will normally use the existing previewer. (At least this will
+ happen when latexmk is running under an operating system where
+ it knows how to determine whether an existing previewer is run-
ning.)
-pvc- Turn off -pvc.
@@ -753,49 +813,49 @@ LATEXMK(1L) LATEXMK(1L)
-quiet Same as -silent
-r <rcfile>
- Read the specified initialization file ("RC file") before pro-
+ Read the specified initialization file ("RC file") before pro-
cessing.
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 -r option, it is read
- during this second step. Thus an initialization file specified
+ -- 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 -r option, it is read
+ 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
- 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
- for a way of giving initialization code directly on latexmk's
- command line. An error results in latexmk stopping. Multiple
- instances of the -r and -e options can be used, and they are
- executed in the order they appear on the command line.
+ Perl programming language (typically a sequence of assignment
- -recorder
- Use the -recorder option with latex and pdflatex. In (most)
- modern versions of these programs, this results in a file of
- extension .fls containing a list of the files that these pro-
- grams have read and written. Latexmk will then use this file to
- improve its detection of source files and generated files after
- a run of latex or pdflatex.
- For further information, see the documentation for the $recorder
+ 2 July 2013 12
- 11 November 2012 12
+LATEXMK(1L) LATEXMK(1L)
-LATEXMK(1L) LATEXMK(1L)
+ statements); they are executed when the -r option is encountered
+ during latexmk's parsing of its command line. See the -e option
+ for a way of giving initialization code directly on latexmk's
+ command line. An error results in latexmk stopping. Multiple
+ instances of the -r and -e options can be used, and they are
+ executed in the order they appear on the command line.
+ -recorder
+ Use the -recorder option with latex and pdflatex. In (most)
+ modern versions of these programs, this results in a file of
+ extension .fls containing a list of the files that these pro-
+ grams have read and written. Latexmk will then use this file to
+ improve its detection of source files and generated files after
+ a run of latex or pdflatex.
+ For further information, see the documentation for the $recorder
configuration variable.
-recorder-
@@ -804,87 +864,87 @@ LATEXMK(1L) LATEXMK(1L)
-rules Show a list of latemk's rules and dependencies after processing.
-rules-
- Do not show a list of latexmk's rules and dependencies after
+ Do not show a list of latexmk's rules and dependencies after
processing. (This is the default.)
-showextraoptions
- Show the list of extra latex and pdflatex options that latexmk
- recognizes. These are options for the latex and pdflatex that
- latexmk recognizes, but simply passes through to these programs
- when they are run. These options are (currently) a combination
+ Show the list of extra latex and pdflatex options that latexmk
+ recognizes. These are options for the latex and pdflatex that
+ latexmk recognizes, but simply passes through to these programs
+ when they are run. These options are (currently) a combination
of those allowed by the TeXLive and MiKTeX implementations. (If
- a particular option is given to latexmk but is not handled by
+ a particular option is given to latexmk but is not handled by
the particular implementation of latex or pdflatex that is being
- used, that program will probably give an error message.) These
+ used, that program will probably give an error message.) These
options are very numerous, but are not listed in this documenta-
tion because they have no effect on latexmk's actions.
- There are a few options (-includedirectory=dir, -initialize,
- -ini) that are not recognized, either because they don't fit
+ There are a few options (-includedirectory=dir, -initialize,
+ -ini) that are not recognized, either because they don't fit
with latexmk's intended operations, or because they need special
- processing by latexmk that isn't implemented (at least, not
+ processing by latexmk that isn't implemented (at least, not
yet).
- There are also options that are accepted by latex etc, but
+ There are also options that are accepted by latex etc, but
instead trigger actions by latexmk: -help, -version.
Finally, there are certain options for latex and pdflatex (e.g.,
- -recorder) that trigger special actions or behavior by latexmk
- itself as well as being passed in some form to the called latex
- and pdflatex program, or that affect other programs as well.
- These options do have entries in this documentation. These
+ -recorder) that trigger special actions or behavior by latexmk
+ itself as well as being passed in some form to the called latex
+ and pdflatex program, or that affect other programs as well.
+ These options do have entries in this documentation. These
options are: -jobname=STRING, -aux-directory=dir, -output-direc-
tory=DIR, -quiet, and -recorder.
-silent
Run commands silently, i.e., with options that reduce the amount
- of diagnostics generated. For example, with the default set-
- tings, the command "latex -interaction=batchmode" is used for
- latex.
+ of diagnostics generated. For example, with the default
- Also reduce the number of informational messages that latexmk
- generates.
- To change the options used to make the commands run silently,
- you need to configure latexmk with changed values of its config-
- uration variables, the relevant ones being $bib-
- tex_silent_switch, $biber_silent_switch, $dvipdf_silent_switch,
+ 2 July 2013 13
- 11 November 2012 13
+LATEXMK(1L) LATEXMK(1L)
-LATEXMK(1L) LATEXMK(1L)
+ settings, the command "latex -interaction=batchmode" is used for
+ latex.
+ Also reduce the number of informational messages that latexmk
+ generates.
+ To change the options used to make the commands run silently,
+ you need to configure latexmk with changed values of its config-
+ uration variables, the relevant ones being $bib-
+ tex_silent_switch, $biber_silent_switch, $dvipdf_silent_switch,
$dvips_silent_switch, $latex_silent_switch, $makein-
dex_silent_switch, and $pdflatex_silent_switch.
-use-make
- When after a run of latex or pdflatex, there are warnings about
+ When after a run of latex or pdflatex, there are warnings about
missing files (e.g., as requested by the LaTeX \input, \include,
- and \includgraphics), latexmk tries to make them by a custom
+ and \includgraphics), latexmk tries to make them by a custom
dependency. If no relevant custom dependency with an appropriate
- source file is found, and if the -use-make option is set, then
- latexmk will try as a resort using the make program to try to
+ source file is found, and if the -use-make option is set, then
+ latexmk will try as a resort using the make program to try to
make the missing files.
- Note that the filename may be specified without an extension,
- e.g., by \includegraphics{drawing} in a LaTeX file. In that
- case, latexmk will try making drawing.ext with ext set in turn
- to the possible extensions that are relevant for latex (or as
+ Note that the filename may be specified without an extension,
+ e.g., by \includegraphics{drawing} in a LaTeX file. In that
+ case, latexmk will try making drawing.ext with ext set in turn
+ to the possible extensions that are relevant for latex (or as
appropriate pdflatex).
- See also the documentation for the $use_make_for_missing_files
+ See also the documentation for the $use_make_for_missing_files
configuration variable.
-use-make-
- Do not use the make program to try to make missing files.
+ Do not use the make program to try to make missing files.
(Default.)
-v, -version
@@ -898,36 +958,38 @@ LATEXMK(1L) LATEXMK(1L)
the -pv or -pvc switches). The default is to view the "highest"
kind of requested file (in the order dvi, ps, pdf).
+
-xelatex
Use xelatex. That is, use xelatex to process the source file(s)
- to pdf (in place of pdflatex). This option is exactly equiva-
+ to pdf (in place of pdflatex). This option is exactly equiva-
lent to specifying the following sequence of options:
- -pdflatex="xelatex %O %S" -pdf -dvi- -ps
+ -pdflatex="xelatex %O %S" -pdf -dvi- -ps-
- The preview-continuous option -pvc can only work with one file. So in
- this case you will normally only specify one filename on the command
- line.
+ Compatibility between options
- Options -p, -pv and -pvc are mutually exclusive. So each of these
- options turns the others off.
+ The preview-continuous option -pvc can only work with one file. So in
+ this case you will normally only specify one filename on the command
+ line.
-EXAMPLES
- % latexmk thesis # run latex enough times to resolve
+ 2 July 2013 14
- 11 November 2012 14
+LATEXMK(1L) LATEXMK(1L)
-LATEXMK(1L) LATEXMK(1L)
+ Options -p, -pv and -pvc are mutually exclusive. So each of these
+ options turns the others off.
+EXAMPLES
+ % latexmk thesis # run latex enough times to resolve
cross-references
% latexmk -pvc -ps thesis# run latex enough times to resolve
@@ -947,6 +1009,71 @@ LATEXMK(1L) LATEXMK(1L)
+HOW TO CHANGE THE WAY LATEXMK BEHAVES, DEALING WITH PROBLEMS, ETC
+ Some possibilities:
+
+ a. If you get a strange error, do look carefully at the output that is
+ on the screen and in log files. While there is much that is notori-
+ ously verbose in the output of latex (and that is added to by latexmk),
+ the verbosity is there for a reason: to enable the user to diagnose
+ problems. Latexmk does repeat some messages at the end of a run that
+ it thinks would otherwise be easy to miss in the middle of other out-
+ put.
+
+ b. If latexmk doesn't do things the way you would like, the first step
+ in finding out what to do is to look in this documentation at the list
+ of command line options and then at the sections on configuration/ini-
+ tialization files. A lot of latexmk's behavior is configurable to deal
+ with particular situations. (But there is a lot of reading.)
+
+ c. Further tricks can involve replacing the standard commands that
+ latexmk by other commands or scripts.
+
+ d. For possible examples of code for use in an RC file, see the direc-
+ tory example_rcfiles in the distribution of latexmk (e.g., at
+ http://www.ctan.org/tex-archive/support/latexmk/example_rcfiles). Even
+ if these examples don't do what you want, they may provide suitable
+ inspiration.
+
+ e. There's a useful trick that can be used when you are lualatex
+ instead of pdflatex (and in some related situations). The problem is
+ that latexmk won't notice a dependency on a file, bar.baz say, that is
+ input by the lua code in your document instead of by the LaTeX part.
+ (Thus if you change bar.baz and rerun latexmk, then latexmk will think
+ no files have changed and not rerun lualatex, whereas if you had
+ '\input{bar.baz}' in the LaTeX part of the document, latexmk would
+ notice the change.) One solution is just to put the following some-
+ where in the LaTeX part of the document:
+
+
+
+ 2 July 2013 15
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ \typeout{(bar.baz)}
+
+ This puts a line in the log file that latexmk will treat as implying
+ that the file bar.baz was read. (At present I don't know a way of
+ doing this automatically.) Of course, if the file has a different
+ name, change bar.baz to the name of your file.
+
+ f. Look on tex.stackexchange, i.e., at http://tex.stackex-
+ change.com/questions/tagged/latexmk Someone may have already solved
+ your problem.
+
+ g. Ask a question at tex.stackexchange.com.
+
+ h. Or ask me (the author of latexmk). My e-mail is at the end of this
+ documentation.
+
+
+
CONFIGURATION/INITIALIZATION (RC) FILES
Latexmk can be customized using initialization files, which are read at
startup in the following order:
@@ -958,7 +1085,7 @@ CONFIGURATION/INITIALIZATION (RC) FILES
"/usr/local/share/latexmk/LatexMk",
"/usr/local/lib/latexmk/LatexMk".
On a MS-WINDOWS system it looks for "C:\latexmk\LatexMk".
- On a cygwin system (i.e., a MS-Windows system in which perl is that
+ On a cygwin system (i.e., a MS-Windows system in which Perl is that
of cygwin), latexmk reads for the first it finds of
"/cygdrive/c/latexmk/LatexMk",
"/opt/local/share/latexmk/LatexMk",
@@ -982,10 +1109,17 @@ CONFIGURATION/INITIALIZATION (RC) FILES
Each RC file is a sequence of Perl 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 Latexmk. Straightforward cases can be handled without
+ knowledge of the Perl 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 -r
+ option can override previous options but can be itself overridden by
- 11 November 2012 15
+ 2 July 2013 16
@@ -994,19 +1128,12 @@ CONFIGURATION/INITIALIZATION (RC) FILES
LATEXMK(1L) LATEXMK(1L)
- settings of Latexmk. Straightforward cases can be handled without
- knowledge of the Perl 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 -r
- option can override previous options but can be itself overridden by
later options on the command line. There is also the -e option, which
allows initialization code to be specified in latexmk's command line.
For possible examples of code for in an RC file, see the directory
example_rcfiles in the distribution of latexmk (e.g., at
- http://ctan.tug.org/tex-archive/support/latexmk/example_rcfiles).
+ http://www.ctan.org/tex-archive/support/latexmk/example_rcfiles).
HOW TO SET VARIABLES IN INITIALIZATION FILES
@@ -1048,18 +1175,6 @@ HOW TO SET VARIABLES IN INITIALIZATION FILES
FORMAT OF COMMAND SPECIFICATIONS
Some of the variables set the commands that latexmk uses for carrying
out its work, for example to generate a dvi file from a tex file or to
-
-
-
- 11 November 2012 16
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
view a postscript file. This section describes some important features
of how the commands are specified.
@@ -1073,6 +1188,18 @@ LATEXMK(1L) LATEXMK(1L)
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,
+
+
+
+ 2 July 2013 17
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
and %O will be replaced by any options that latexmk has decided to use
for this command. (E.g., if you used the -silent option it would
replace %O by "-interaction=batchmode".)
@@ -1114,18 +1241,6 @@ LATEXMK(1L) LATEXMK(1L)
replaced by the source filename, which in this case would be the name
of a postscript file to be viewed.
-
-
-
- 11 November 2012 17
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
Appropriate quoting will be applied to the filename substitutions, so
you mustn't supply them yourself even if the names of your files have
spaces in them. (But if your TeX filenames have spaces in them, beware
@@ -1144,8 +1259,21 @@ LATEXMK(1L) LATEXMK(1L)
$bibtex = 'bibtex %O %B';
- Generally, you should use %B rather than %R. Similarly for most pur-
- poses, the name %T of the primary texfile is not a useful placeholder.
+ Generally, you should use %B rather than %R. Similarly for most
+
+
+
+ 2 July 2013 18
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ purposes, the name %T of the primary texfile is not a useful place-
+ holder.
See the default values in the section "List of configuration variables
usable in initialization files" for what is normally the most appropri-
@@ -1180,18 +1308,6 @@ LATEXMK(1L) LATEXMK(1L)
problem.
Command names containing spaces: Under MS-Windows it is common that the
-
-
-
- 11 November 2012 18
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
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
@@ -1211,11 +1327,23 @@ LATEXMK(1L) LATEXMK(1L)
rules for dealing with forward slashes in strings in the Perl lan-
guage.)
- Command names under Cygwin: If latexmk is executed by Cygwin's perl,
+ Command names under Cygwin: If latexmk is executed by Cygwin's Perl,
be particularly certain that pathnames in commands have forward slashes
not the usual backslashes for the separator of pathname components.
See the above examples. Backslashes often get misinterpreted by the
Unix shell used by Cygwin's Perl to execute external commands. Forward
+
+
+
+ 2 July 2013 19
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
slashes don't suffer from this problem, and (when quoted, as above) are
equally acceptable to MS-Windows.
@@ -1247,17 +1375,6 @@ LATEXMK(1L) LATEXMK(1L)
enabled. Then you might use the following line in an initialization
file:
-
-
- 11 November 2012 19
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
$latex = 'latex --src-specials %O %S';
@@ -1287,6 +1404,18 @@ LATEXMK(1L) LATEXMK(1L)
%B';
This definition assumes you are using a UNIX-like system (which
+
+
+
+ 2 July 2013 20
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
includes Linux and OS-X), so that the two commands to be run are sepa-
rated by the semicolon in the middle of the string.
@@ -1312,18 +1441,6 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES
unfortunately.)
This use of a temporary file solves a problem that the making of
-
-
-
- 11 November 2012 20
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
these files can occupy a substantial time. If a viewer sees
that the file has changed, it reads the new file, and this can
cause havoc if the program writing the file has not yet finished
@@ -1359,6 +1476,18 @@ LATEXMK(1L) LATEXMK(1L)
(pdf)latex.
See also the documentation of $out_dir for some complications on
+
+
+
+ 2 July 2013 21
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
what directory names are suitable.
@@ -1378,18 +1507,6 @@ LATEXMK(1L) LATEXMK(1L)
black, 1 is white. The default is just right if your toner car-
tridge isn't running too low.
-
-
-
- 11 November 2012 21
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
$banner_message ["DRAFT"]
The banner message to print across each page when converting the
dvi file to postscript. This is equivalent to the -bm option.
@@ -1432,29 +1549,28 @@ LATEXMK(1L) LATEXMK(1L)
$biber ["biber %O %S"]
The biber processing program.
- $biber_silent_switch ["--onlylog"]
- Switch(es) for the biber processing program when silent mode is
- on.
- $bibtex ["bibtex %O %S"]
- The BibTeX processing program.
-
- $bibtex_silent_switch ["-terse"]
- Switch(es) for the BibTeX processing program when silent mode is
- on.
+ 2 July 2013 22
- 11 November 2012 22
+LATEXMK(1L) LATEXMK(1L)
+ $biber_silent_switch ["--onlylog"]
+ Switch(es) for the biber processing program when silent mode is
+ on.
-LATEXMK(1L) LATEXMK(1L)
+ $bibtex ["bibtex %O %S"]
+ The BibTeX processing program.
+ $bibtex_silent_switch ["-terse"]
+ Switch(es) for the BibTeX processing program when silent mode is
+ on.
$bibtex_use [1]
Under what conditions to run BibTeX or biber. When latexmk dis-
@@ -1499,21 +1615,17 @@ LATEXMK(1L) LATEXMK(1L)
$clean_ext [""]
Extra extensions of files for latexmk to remove when any of the
clean-up options (-c or -C) is selected. The value of this
- variable is a string containing the extensions separated by spa-
- ces.
+ variable is a string containing the extensions separated by
+ spaces.
It is also possible to specify a more general pattern of file to
- be deleted, by using the place holder %R, as in commands. Thus
- setting
+ be deleted, by using the place holder %R, as in commands, and it
+ is also possible to use wildcards. Thus setting
- $clean_ext = "out %R-blx.bib";
-
- in an initialization file will imply that when a clean-up opera-
- tion is specified, not only is the standard set of files
- 11 November 2012 23
+ 2 July 2013 23
@@ -1522,9 +1634,13 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
- deleted, but also files of the form FOO.out and FOO-blx.bib,
- where FOO stands for the basename of the file being processed
- (as in FOO.tex).
+ $clean_ext = "out %R-blx.bib %R-figures*.log";
+
+ in an initialization file will imply that when a clean-up opera-
+ tion is specified, not only is the standard set of files
+ deleted, but also files of the form FOO.out, FOO-blx.bib, and
+ %R-figures*.log, where FOO stands for the basename of the file
+ being processed (as in FOO.tex).
$clean_full_ext [""]
@@ -1577,19 +1693,19 @@ LATEXMK(1L) LATEXMK(1L)
window to know the status of the compilation.
+ @cus_dep_list [()]
+ Custom dependency list -- see section on "Custom Dependencies".
- 11 November 2012 24
+ 2 July 2013 24
-LATEXMK(1L) LATEXMK(1L)
- @cus_dep_list [()]
- Custom dependency list -- see section on "Custom Dependencies".
+LATEXMK(1L) LATEXMK(1L)
@default_files [("*.tex")]
@@ -1630,6 +1746,13 @@ LATEXMK(1L) LATEXMK(1L)
Whether to display a list(s) of dependencies at the end of a
run.
+ $do_cd [0]
+ Whether to change working directory to the directory specified
+ for the main source file before processing it. The default
+ behavior is not to do this, which is the same as the behavior of
+ latex and pdflatex programs. This variable is set by the -cd
+ and -cd- options on latexmk's command line.
+
$dvi_filter [empty]
The dvi file filter to be run on the newly produced dvi file
before other processing. Equivalent to specifying the -dF
@@ -1642,10 +1765,16 @@ LATEXMK(1L) LATEXMK(1L)
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
- 11 November 2012 25
+ 2 July 2013 25
@@ -1654,12 +1783,6 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
- 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
with .dvi files.]
@@ -1707,19 +1830,6 @@ LATEXMK(1L) LATEXMK(1L)
of the $dvips_pdf_switch -- see below -- will be included in the
options substituted for "%O".
-
-
-
-
- 11 November 2012 26
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
$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.
@@ -1736,6 +1846,18 @@ LATEXMK(1L) LATEXMK(1L)
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
+
+
+
+ 2 July 2013 26
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
for the analogous case of a pdf previewer.
$dvi_update_method [2 under UNIX, 1 under MS-Windows]
@@ -1774,18 +1896,6 @@ LATEXMK(1L) LATEXMK(1L)
$force_mode [0]
If nonzero, continue processing past minor latex errors includ-
ing unrecognized cross references. Equivalent to specifying the
-
-
-
- 11 November 2012 27
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
-f option.
@generated_exts [( aux , bbl , idx , ind , lof , lot , out , toc ,
@@ -1811,6 +1921,18 @@ LATEXMK(1L) LATEXMK(1L)
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
+
+
+
+ 2 July 2013 27
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
line in an RC file. E.g.,
push @generated_exts, "end";
@@ -1834,24 +1956,12 @@ LATEXMK(1L) LATEXMK(1L)
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, that is
- only terminated becaues latexmk has a limit on the number of
+ only terminated because 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.
You can instruct latex to ignore the offending line as follows:
-
-
-
- 11 November 2012 28
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
$hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: ';
This creates a rule for files with extension .eps about lines to
@@ -1879,7 +1989,7 @@ LATEXMK(1L) LATEXMK(1L)
It may happen that a pattern to be ignored is specified in, for
example, in a system or user initialization file, and you wish
- to remove this in a file read later. To do this, you use perl's
+ to remove this in a file read later. To do this, you use Perl's
delete function, e.g.,
delete $hash_calc_ignore_pattern{'eps'};
@@ -1887,57 +1997,58 @@ LATEXMK(1L) LATEXMK(1L)
$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 .bib files are found from the log file of a bibtex
- or biber run, the name of the file, but not its path is known.
- The program specified by $kpsewhich is used to find it.
+ is not sufficient. Most filenames used by latexmk have
- 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
- 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
- program used, but also specify options to the program. E.g.,
+ 2 July 2013 28
- 11 November 2012 29
+LATEXMK(1L) LATEXMK(1L)
+ sufficient path information to be found directly. But some-
+ times, notably when .bib files are found from the log file of a
+ bibtex or biber run, the name of the file, but not its path is
+ known. The program specified by $kpsewhich is used to find it.
-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
+ 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
+ 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
+ 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
+ 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 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
+ (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' );
@@ -1946,36 +2057,28 @@ LATEXMK(1L) LATEXMK(1L)
add_input_ext( 'latex', 'asdf' );
- add the extension 'asdf to latex_input_extensions. (Naturally
+ 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
+ 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
+ Switch(es) for the LaTeX processing program when silent mode is
on.
- If you use MikTeX, you may prefer the results if you configure
- the options to include -c-style-errors, e.g., by the following
+ If you use MikTeX, you may prefer the results if you configure
+ the options to include -c-style-errors, e.g., by the following
line in an initialization file
$latex_silent_switch = "-interaction=batchmode -c-style-
errors";
- $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-
- 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
-
-
- 11 November 2012 30
+ 2 July 2013 29
@@ -1984,16 +2087,22 @@ LATEXMK(1L) LATEXMK(1L)
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-
+ 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.
@@ -2003,13 +2112,13 @@ 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.
@@ -2023,25 +2132,30 @@ LATEXMK(1L) LATEXMK(1L)
The index processing program.
$makeindex_silent_switch ["-q"]
- Switch(es) for the index processing program when silent mode is
+ Switch(es) for the index processing program when silent mode is
on.
$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
+ 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
+ resolve cross-references, etc. The default value covers all
normal cases.
- (Note that the "etc" covers a lot of cases where one run of
+ (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.)
$MSWin_back_slash [1]
- This configuration variable only has an effect when latexmk is
+ This configuration variable only has an effect when latexmk is
+ running under MS-Windows. It determines whether, when a command
+ is executed under MS-Windows, there should be substituted "\"
+ for the separator character between components of a directory
+ name. Internally, latexmk uses "/" for the directory separator
+ character, which is the character used by Unix-like systems.
- 11 November 2012 31
+ 2 July 2013 30
@@ -2050,105 +2164,108 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
- running under MS-Windows. It determines whether, when a command
- is executed under MS-Windows, there should be substituted "\"
- for the separator character between components of a directory
- name. Internally, latexmk uses "/" for the directory separator
- character, which is the character used by Unix-like systems.
-
For many programs under MS-Windows, both "\" and "/" are accept-
- able as the directory separator character. But some programs
- only accept "\". So for safety latexmk makes a translation, by
- default. It is conceivable that under certain situations this
- is undesirable, so the configuration can be changed. (A possi-
- ble example might be when some of the software is implemented
+ able as the directory separator character. But some programs
+ only accept "\". So for safety latexmk makes a translation, by
+ default. It is conceivable that under certain situations this
+ is undesirable, so the configuration can be changed. (A possi-
+ ble example might be when some of the software is implemented
using Cygwin, which provides an Unix-like environment inside MS-
Windows.)
$new_viewer_always [0]
- This variable applies to latexmk only in continuous-preview
+ 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
+ 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
no viewer is running.
$out_dir [""]
- The directory in which output files are to be written by a run
+ The directory in which output files are to be written by a run
of (pdf)latex. See also the variable $aux_dir.
- The effect of this variable (when non-blank) is achieved by
- using the -output-directory option of (pdf)latex. This exists
- in the usual current (Dec. 2011) implementations of TeX, i.e.,
+ The effect of this variable (when non-blank) is achieved by
+ using the -output-directory option of (pdf)latex. This exists
+ in the usual current (Dec. 2011) implementations of TeX, i.e.,
MiKTeX and TeXLive. But it may not be present in other versions.
- Commonly, the directory specified for output files is a subdi-
+ Commonly, the directory specified for output files is a subdi-
rectory of the current working directory. However, if you spec-
- ify some other directory, e.g., "/tmp/foo" or "../output", be
- aware that this could cause problems, e.g., with makeindex or
- bibtex. This is because modern versions of these programs, by
- default, will refuse to work when they find that they are asked
- to write to a file in a directory that appears not to be the
+ ify some other directory, e.g., "/tmp/foo" or "../output", be
+ aware that this could cause problems, e.g., with makeindex or
+ bibtex. This is because modern versions of these programs, by
+ default, will refuse to work when they find that they are asked
+ to write to a file in a directory that appears not to be the
current working directory or one of its subdirectories. This is
- part of security measures by the whole TeX system that try to
+ part of security measures by the whole TeX system that try to
prevent malicious or errant TeX documents from incorrectly mess-
ing with a user's files. If for $out_dir or $aux_dir you really
- do need to specify an absolute pathname (e.g., "/tmp/foo") or a
+ do need to specify an absolute pathname (e.g., "/tmp/foo") or a
path (e.g., "../output") that includes a higher-level directory,
- then you need to disable the security measures (and assume any
- risks). This can be done by temporarily setting the operating
- system's environment variable openout_any to "a" (as in "all"),
+ then you need to disable the security measures (and assume any
+ risks). This can be done by temporarily setting the operating
+ system's environment variable openout_any to "a" (as in "all"),
to override the default "paranoid" setting.
$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-
+ 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
+ from the dvi file, by using the command specified by the $dvipdf
+ variable.
+ Equivalent to the -pdf-, -pdf, -pdfdvi, -pdfps options.
- 11 November 2012 32
+ $pdflatex ["pdflatex %O %S"]
+ The LaTeX processing program in a version that makes a pdf file
+ instead of a dvi file.
+ An example of the use of this variable is to arrange for luala-
+ tex, xelatex or some similar program to be used instead of
+ 2 July 2013 31
-LATEXMK(1L) LATEXMK(1L)
- 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
- from the dvi file, by using the command specified by the $dvipdf
- variable.
- Equivalent to the -pdf-, -pdf, -pdfdvi, -pdfps options.
+LATEXMK(1L) LATEXMK(1L)
- $pdflatex ["pdflatex %O %S"]
- The LaTeX processing program in the version that makes a pdf
- file instead of a dvi file.
- An example of the use of this variable is to arrange for xelatex
- to be used instead of pdflatex, when you could set
+ pdflatex. Note that lualatex and xelatex only produce .pdf
+ files (and not .dvi), so to use them you will also need to turn
+ on production of .pdf files, and to turn off the production of
+ .dvi (and .ps) files, either by command line options or by suit-
+ able settings in a configuration file. Thus to use lualatex, the
+ following settings are appropriate:
+
+ $pdflatex = "lualatex %O %S";
+ $pdf_mode = 1; $postscript_mode = $dvi_mode = 0;
+
+ To use xelatex, the corresponding settings are:
$pdflatex = "xelatex %O %S";
+ $pdf_mode = 1; $postscript_mode = $dvi_mode = 0;
- Note that xelatex only produces .pdf files (and not .dvi), so to
- use it you will also need to turn on production of .pdf files,
- and to turn off the production of .dvi (and .ps) files, either
- by command line options or by the following settings in an ini-
- tialization file
+ Another use of the same variable is to add certain options to
+ the command line for the program, e.g.,
- $pdf_mode = 1; $postscript_mode = $dvi_mode = 0;
+ $pdflatex = "pdflatex --shell-escape %O %S";
%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
+ 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
@@ -2170,18 +2287,6 @@ LATEXMK(1L) LATEXMK(1L)
removes the extension 'tex' from pdflatex_input_extensions
-
-
-
- 11 November 2012 33
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
add_input_ext( 'pdflatex', 'asdf' );
add the extension 'asdf to pdflatex_input_extensions. (Natu-
@@ -2201,6 +2306,18 @@ LATEXMK(1L) LATEXMK(1L)
line in an initialization file
$latex_silent_switch = "-interaction=batchmode -c-style-
+
+
+
+ 2 July 2013 32
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
errors";
@@ -2236,18 +2353,6 @@ LATEXMK(1L) LATEXMK(1L)
in yourself, whenever it is needed.
-
-
-
- 11 November 2012 34
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
$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
@@ -2279,6 +2384,17 @@ LATEXMK(1L) LATEXMK(1L)
ting sets the update command.
+
+
+ 2 July 2013 33
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
$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
@@ -2301,19 +2417,6 @@ LATEXMK(1L) LATEXMK(1L)
If some other request is made for which a postscript file is
needed, then $postscript_mode will be set to 1.
-
-
-
-
- 11 November 2012 35
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
$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
@@ -2342,8 +2445,8 @@ LATEXMK(1L) LATEXMK(1L)
the previewer about file changes).
Each line of the output of this command is assumed to correspond
- to one process. See the $pid_position variable for how the
- process number is determined.
+ to one process. See the $pid_position variable for how the pro-
+ cess number is determined.
The default for pscmd is "NONE" under MS-Windows and cygwin
(i.e., the command is not used), "ps --width 200 -f -u
@@ -2356,32 +2459,32 @@ LATEXMK(1L) LATEXMK(1L)
Command to convert ps to pdf file.
$ps_filter [empty]
- The postscript file filter to be run on the newly produced post-
- script file before other processing. Equivalent to specifying
- the -pF option.
+ The postscript file filter to be run on the newly produced
+ postscript file before other processing. Equivalent to
- $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
- 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
+ 2 July 2013 34
- 11 November 2012 36
+LATEXMK(1L) LATEXMK(1L)
-LATEXMK(1L) LATEXMK(1L)
+ specifying the -pF option.
+ $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
+ associated with .ps files.)
- different ways of writing this option. You can configure this
- variable apppropriately.
+ 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 dif-
+ ferent ways of writing this option. You can configure this
+ variable appropriately.
WARNING: Linux systems may have installed one (or more) versions
of gv under different names, e.g., ggv, kghostview, etc, but
@@ -2435,9 +2538,11 @@ LATEXMK(1L) LATEXMK(1L)
quotes. If this variable is 1 (or any other value Perl regards
as true), then quoting is done. Otherwise quoting is omitted.
+ The quoting method used by latexmk is tested to work correctly
- 11 November 2012 37
+
+ 2 July 2013 35
@@ -2446,7 +2551,6 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
- 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
@@ -2500,18 +2604,6 @@ LATEXMK(1L) LATEXMK(1L)
operating system; in that case you'll need to find out what is
needed, and set $search_path_separator explicitly. (The same
goes, of course, for unusual operating systems that are not in
-
-
-
- 11 November 2012 38
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
the MSWin, Linux, OS-X, Unix collection.)
@@ -2528,6 +2620,17 @@ LATEXMK(1L) LATEXMK(1L)
This is an obsolete variable, replaced by the @default_files
variable.
+
+
+ 2 July 2013 36
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
For backward compatibility, if you choose to set $tex-
file_search, it is a string of space-separated filenames, and
then latexmk replaces @default_files with the filenames in $tex-
@@ -2566,18 +2669,6 @@ LATEXMK(1L) LATEXMK(1L)
$view ["default"]
Which kind of file is to be previewed if a previewer is used.
-
-
-
- 11 November 2012 39
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
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).
@@ -2610,6 +2701,17 @@ CUSTOM DEPENDENCIES
The extension of the file we are converting to (e.g. "eps"). It
is specified without a period.
+
+
+ 2 July 2013 37
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
must: If non-zero, the file from which we are converting must exist,
if it doesn't exist latexmk will give an error message and exit
unless the -f option is specified. If must is zero and the file
@@ -2632,25 +2734,13 @@ CUSTOM DEPENDENCIES
with respect to the corresponding source file.
To make the new destination file, the Perl subroutine specified in the
-
-
-
- 11 November 2012 40
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
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 Perl programming language. Of course,
experts could do something much more elaborate.
- One other item in each custom-dependency rule labelled "must" above
+ One other item in each custom-dependency rule labeled "must" above
specifies how the rule should be applied when the source file fails to
exist.
@@ -2658,7 +2748,7 @@ LATEXMK(1L) LATEXMK(1L)
add_cus_dep( 'fig', 'eps', 0, 'fig2eps' );
sub fig2eps {
- system( "fig2dev -Leps
+ system( "fig2dev -Leps \"$_[0].fig\" \"$_[0].eps\"" );
}
The first line adds a custom dependency that converts a file with
@@ -2691,17 +2781,10 @@ LATEXMK(1L) LATEXMK(1L)
add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' );
sub fig2pdf {
- system( "fig2dev -Lpdf
- }
-
- Note 1: In the command lines given in the system commands in the above
- examples, double quotes have been inserted around the file names
- (implemented by ' of the program against special characters in file-
- names. Very often these quotes are not necessary, i.e., they can be
- 11 November 2012 41
+ 2 July 2013 38
@@ -2710,205 +2793,200 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
- omitted. But it is normally safer to keep them in. Even though the
- rules for quoting vary between operating systems, command shells and
- individual pieces of software, the quotes in the above examples do not
- cause problems in the cases I have tested.
+ system( "fig2dev -Lpdf \"$_[0].fig\" \"$_[0].pdf\"" );
+ }
- Note 2: One case in which the quotes are important is when the files
- are in a subdirectory and your operating system is Microsoft Windows.
- Then the separator character for directory components can be either a
- forward slash '/' or Microsoft's more usual backward slash sanity from
- software like MiKTeX that mixes both directory separators; but their
+ Note 1: In the command lines given in the system commands in the above
+ examples, double quotes have been inserted around the file names
+ (implemented by '\"' in the Perl language). They immunize the running
+ of the program against special characters in filenames. Very often
+ these quotes are not necessary, i.e., they can be omitted. But it is
+ normally safer to keep them in. Even though the rules for quoting vary
+ between operating systems, command shells and individual pieces of
+ software, the quotes in the above examples do not cause problems in the
+ cases I have tested.
+
+ Note 2: One case in which the quotes are important is when the files
+ are in a subdirectory and your operating system is Microsoft Windows.
+ Then the separator character for directory components can be either a
+ forward slash '/' or Microsoft's more usual backward slash sanity from
+ software like MiKTeX that mixes both directory separators; but their
correct use normally requires quoted filenames. (See a log file from a
- run of MiKTeX (at least in v. 2.9) for an example of the use of both
+ run of MiKTeX (at least in v. 2.9) for an example of the use of both
directory separators.)
- 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.
+ 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
+ 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
- latexmk concerning index files. The only index-file conversion built-
+ Another example of a custom dependency overcomes a limitation of
+ latexmk concerning index files. The only index-file conversion built-
in to latexmk is from an ".idx" file written on one run of latex/pdfla-
- tex to an ".ind" file to be read in on a subsequent run. But with the
+ tex 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. Latexmk 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{spe-
+ example if your latex file uses the command "\newindex{spe-
cial}{ndx}{nnd}{Special index}" you will need to convert files with the
- extension .ndx to .nnd. The following lines in an initialization RC
+ extension .ndx to .nnd. 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
+ system( "makeindex -o \"$_[0].nnd\" \"$_[0].ndx\"" );
}
- (You will need to modify this code if you use filenames with spaces in
+ (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 con-
+ Those of you with experience with Makefiles, will undoubtedly be con-
cerned that the .ndx file is written during a run of latex/pdflatex and
- is always later than the .nnd last read in. Thus the .nnd appears to
- be perpetually out-of-date. This situation, of circular dependencies,
+ is always later than the .nnd last read in. Thus the .nnd appears to
+ 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
- 11 November 2012 42
+ 2 July 2013 39
-LATEXMK(1L) LATEXMK(1L)
+LATEXMK(1L) LATEXMK(1L)
- 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.
OLD METHOD OF DEFINING CUSTOM DEPENDENCIES
- In previous versions of latexmk, the only method of defining custom
- dependencies was to directly manipulate the table of custom dependen-
+ In previous versions of latexmk, the only method of defining custom
+ dependencies was to directly manipulate the table of custom dependen-
cies. This is contained in the @cus_dep_list array. It is an array of
- strings, and each string in the array has four items in it, each sepa-
- rated by a space, the from-extension, the to-extension, the "must"
- item, and the name of the subroutine for the custom dependency. These
+ strings, and each string in the array has four items in it, each sepa-
+ rated 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.
An example of the old method of defining custom dependencies is as fol-
- lows. It is the code in an RC file to ensure automatic conversion of
+ lows. It is the code in an RC file to ensure automatic conversion of
.fig files to .eps files:
push @cus_dep_list, "fig eps 0 fig2eps";
sub fig2eps {
- system( "fig2dev -Lps
+ 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
+ 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.
USING latexmk WITH make
- This section is targeted only at advanced users who use the make pro-
+ This section is targeted only at advanced users who use the make pro-
gram for complex projects, as for software development, with the depen-
dencies specified by a Makefile.
- Now the basic task of latexmk is to run the appropriate programs to
- make a viewable version of a LaTeX document. However, the usual make
- program is not suited to this purpose for at least two reasons. First
+ Now the basic task of latexmk is to run the appropriate programs to
+ make a viewable version of a LaTeX document. However, the usual make
+ program is not suited to this purpose for at least two reasons. First
is that the use of LaTeX involves circular dependencies (e.g., via .aux
files), and these cannot be handled by the standard make program. Sec-
- ond is that in a large document the set of source files can change
- quite frequently, particularly with included graphics files; in this
- situation keeping a Makefile manually updated is inappropriate and
- error-prone, especially when the depedencies can be determined automat-
- ically. Latexmk solves both of these problems robustly.
-
+ ond is that in a large document the set of source files can change
+ quite frequently, particularly with included graphics files; in this
+ situation keeping a Makefile manually updated is inappropriate and
+ error-prone, especially when the dependencies can be determined auto-
+ matically. Latexmk solves both of these problems robustly.
+
+ Thus for many standard LaTeX documents latexmk can be used by itself
+ without the make program. In a complex project it simply needs to be
+ suitably configured. A standard configuration would be to define cus-
+ tom dependencies to make graphics files from their source files (e.g.,
+ as created by the xfig program). Custom dependencies are latexmk's
+ equivalent of pattern rules in Makefiles.
+ Nevertheless there are projects for which a Makefile is appropriate,
+ and it is useful to know how to use latexmk from a Makefile. A typical
+ example would be to generate documentation for a software project.
+ Potentially the interaction with the rest of the rules in the Makefile
+ could be quite complicated, for example if some of the source files for
+ a LaTeX document are generated by the project's software.
+ In this section, I give a couple of examples of how latexmk can be use-
+ fully invoked from a Makefile. The examples use specific features of
+ current versions of GNU make, which is the default on both linux and
+ OS-X systems. They may need modifications for other versions of make.
- 11 November 2012 43
+ The simplest method is simply to delegate all the relevant tasks to
+ latexmk, as is suitable for a straightforward LaTeX document. For this
+ a suitable Makefile is like
+ 2 July 2013 40
-LATEXMK(1L) LATEXMK(1L)
- Thus for many standard LaTeX documents latexmk can be used by itself
- without the make program. In a complex project it simply needs to be
- suitably configured. A standard configuration would be to define cus-
- tom dependencies to make graphics files from their source files (e.g.,
- as created by the xfig program). Custom dependencies are latexmk's
- equivalent of pattern rules in Makefiles.
- Nevertheless there are projects for which a Makefile is appropriate,
- and it is useful to know how to use latexmk from a Makefile. A typical
- example would be to generate documentation for a software project.
- Potentially the interaction with the rest of the rules in the Makefile
- could be quite complicated, for example if some of the source files for
- a LaTeX document are generated by the project's software.
-
- In this section, I give a couple of examples of how latexmk can be use-
- fully invoked from a Makefile. The examples use specific features of
- current versions of GNU make, which is the default on both linux and
- OS-X systems. They may need modifications for other versions of make.
+LATEXMK(1L) LATEXMK(1L)
- The simplest method is simply to delegate all the relevant tasks to
- latexmk, as is suitable for a straightforward LaTeX document. For this
- a suitable Makefile is like
.PHONY : FORCE_MAKE
all : try.pdf
%.pdf : %.tex FORCE_MAKE
latexmk -pdf -dvi- -ps- $<
- (Note: the last line must be introduced by a tab for the Makefile to
- function correctly!) Naturally, if making try.pdf from its associated
- LaTeX file try.tex were the only task to be performed, a direct use of
- latexmk without a Makefile would normally be better. The benefit of
- using a Makefile for a LaTeX document would be in a larger project,
+ (Note: the last line must be introduced by a tab for the Makefile to
+ function correctly!) Naturally, if making try.pdf from its associated
+ LaTeX file try.tex were the only task to be performed, a direct use of
+ latexmk without a Makefile would normally be better. The benefit of
+ using a Makefile for a LaTeX document would be in a larger project,
where lines such as the above would be only be a small part of a larger
Makefile.
The above example has a pattern rule for making a .pdf file from a .tex
- file, and it is defined to use latexmk in the obvious way. There is a
+ file, and it is defined to use latexmk in the obvious way. There is a
conventional default target named "all", with a prerequisite of
- try.pdf. So when make is invoked, by default it makes try.pdf. The
- only complication is that there may be many source files beyond
+ try.pdf. So when make is invoked, by default it makes try.pdf. The
+ only complication is that there may be many source files beyond
try.tex, but these aren't specified in the Makefile, so changes in them
- will not by themselves cause latexmk to be invoked. Instead, the pat-
- tern rule is equipped with a "phony" prerequisite FORCE_MAKE; this has
- the effect of causing the rule to be always out-of-date, so that
- latexmk is always run. It is latexmk that decides whether any action
- is needed, e.g., a rerun of pdflatex. Effectively the Makefile dele-
+ will not by themselves cause latexmk to be invoked. Instead, the pat-
+ tern rule is equipped with a "phony" prerequisite FORCE_MAKE; this has
+ the effect of causing the rule to be always out-of-date, so that
+ latexmk is always run. It is latexmk that decides whether any action
+ is needed, e.g., a rerun of pdflatex. Effectively the Makefile dele-
gates all decisions to latexmk, while make has no knowledge of the list
- of source files except for primary LaTeX file for the document. If
- there are, for example, graphics files to be made, these must be made
+ of source files except for primary LaTeX file for the document. If
+ there are, for example, graphics files to be made, these must be made
by custom dependencies configured in latexmk.
- But something better is needed in more complicated situations, for
- example, when the making of graphics files needs to be specified by
-
-
-
- 11 November 2012 44
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
- rules in the Makefile. To do this, one can use a Makefile like the
+ But something better is needed in more complicated situations, for
+ example, when the making of graphics files needs to be specified by
+ rules in the Makefile. To do this, one can use a Makefile like the
following:
TARGETS = document1.pdf document2.pdf
@@ -2927,51 +3005,50 @@ LATEXMK(1L) LATEXMK(1L)
%.pdf : %.fig
fig2dev -Lpdf $< $@
- (Again, the lines containing the commands for the rules should be
+ (Again, the lines containing the commands for the rules should be
started with tabs.) This example was inspired by how GNU automake han-
dles automatic dependency tracking of C source files.
- After each run of latexmk, dependency information is put in a file in
- the .deps subdirectory. The Makefile causes these dependency files to
+ After each run of latexmk, dependency information is put in a file in
+ the .deps subdirectory. The Makefile causes these dependency files to
be read by make, which now has the full dependency information for each
- target .pdf file. To make things less trivial it is specificed that
- two files document1.pdf and document2.pdf are the targets. The depen-
+ target .pdf file. To make things less trivial it is specificed that
+ two files document1.pdf and document2.pdf are the targets. The depen-
dency files are .deps/document1.pdfP and .deps/document2.pdfP.
- There is now no need for the phony prerequisite for the rule to make
+ There is now no need for the phony prerequisite for the rule to make
.pdf files from .tex files. But I have added a rule to make .pdf files
- from .fig files produced by the xfig program; these are commonly used
- for graphics insertions in LaTeX documents. Latexmk is arranged to
- output a dependency file after each run. It is given the -recorder
+ from .fig files produced by the xfig program; these are commonly used
+ for graphics insertions in LaTeX documents. Latexmk is arranged to
+ output a dependency file after each run. It is given the -recorder
option, which improves its detection of files generated during a run of
- pdflatex; such files should not be in the dependency list. The -e
- options are used to turn off all custom dependencies, and to document
- this. Instead the -use-make is used to delegate the making of missing
- files to make itself.
+ pdflatex; such files should not be in the dependency list. The -e
+ options are used to turn off all custom dependencies, and to document
- Suppose in the LaTeX file there is a command \includegraphics{graph},
- and an xfig file "graph.fig" exists. On a first run, pdflatex reports
- a missing file, named "graph". Latexmk succeeds in making "graph.pdf"
- by calling "make graph.pdf", and after completion of its work, it lists
- "fig.pdf" among the dependents of the file latexmk is making. Then let
- "fig.fig" be updated, and then let make be run. Make first remakes
- "fig.pdf", and only then reruns latexmk.
-
- Thus we now have a method by which all the subsidiary processing is
- delegated to make.
+ 2 July 2013 41
- 11 November 2012 45
+LATEXMK(1L) LATEXMK(1L)
+ this. Instead the -use-make is used to delegate the making of missing
+ files to make itself.
+ Suppose in the LaTeX file there is a command \includegraphics{graph},
+ and an xfig file "graph.fig" exists. On a first run, pdflatex reports
+ a missing file, named "graph". Latexmk succeeds in making "graph.pdf"
+ by calling "make graph.pdf", and after completion of its work, it lists
+ "fig.pdf" among the dependents of the file latexmk is making. Then let
+ "fig.fig" be updated, and then let make be run. Make first remakes
+ "fig.pdf", and only then reruns latexmk.
-LATEXMK(1L) LATEXMK(1L)
+ Thus we now have a method by which all the subsidiary processing is
+ delegated to make.
SEE ALSO
@@ -2979,35 +3056,35 @@ SEE ALSO
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:
+ its creation is started but before the file is complete. Work around:
manually refresh (or reopen) display. Or use one of the other preview-
ers and update methods.
- (The following isn't really a bug, but concerns features of preview-
- ers.) Preview continuous mode only works perfectly with certain pre-
- viewers: 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 latexmk to use suma-
+ (The following isn't really a bug, but concerns features of preview-
+ ers.) Preview continuous mode only works perfectly with certain pre-
+ viewers: 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 latexmk to use suma-
trapdf instead.)
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
+ 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.35).
+ Current version, by John Collins (username collins at node
+ phys.psu.edu). (Version 4.37).
- Released version can be obtained from CTAN: <http://www.tug.org/tex-ar-
- chive/support/latexmk/>, and from the author's website
+ Released version can be obtained from CTAN: <http://www.ctan.org/tex-
+ archive/support/latexmk/>, and from the author's website
<http://www.phys.psu.edu/~collins/software/latexmk/>.
Modifications and enhancements by Evan McLean (Version 2.0)
Original script called "go" by David J. Musliner (RCS Version 3.2)
@@ -3031,6 +3108,6 @@ AUTHOR
- 11 November 2012 46
+ 2 July 2013 42