summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexmk/latexmk.txt
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-03-22 23:35:00 +0000
committerKarl Berry <karl@freefriends.org>2011-03-22 23:35:00 +0000
commit95b6c856b96c6328dc0e449574046ef4218c9f23 (patch)
tree801301fe5272c05157403c30fc6a34352c2e3184 /Master/texmf-dist/doc/support/latexmk/latexmk.txt
parentc231b52342d5ce2940f7d8b66a94ffd87ad016a0 (diff)
latexmk (22mar11)
git-svn-id: svn://tug.org/texlive/trunk@21806 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support/latexmk/latexmk.txt')
-rw-r--r--Master/texmf-dist/doc/support/latexmk/latexmk.txt1510
1 files changed, 906 insertions, 604 deletions
diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.txt b/Master/texmf-dist/doc/support/latexmk/latexmk.txt
index 7ef1258c7b1..8ccb793ca4b 100644
--- a/Master/texmf-dist/doc/support/latexmk/latexmk.txt
+++ b/Master/texmf-dist/doc/support/latexmk/latexmk.txt
@@ -23,42 +23,42 @@ DESCRIPTION
on-screen view of the compiled document.
Latexmk determines which are the source files by examining the log
- file. 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
+ 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
+ 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
+ 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
+ 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,
-
1
@@ -70,43 +70,45 @@ DESCRIPTION
LATEXMK(1L) LATEXMK(1L)
- call an external program to do other postprocessing on the generated
+ Latexmk has the ability to print a banner in gray diagonally across
+ each page when making the postscript file. It can also, if needed,
+ call an external program to do other postprocessing on the generated
files.
- 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.
LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE
- (All options can be introduced by single or double "-" characters,
+ (All options can be introduced by single or double "-" characters,
e.g., "latexmk -help" or "latexmk --help".)
- 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
@@ -117,17 +119,16 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE
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
- 3 February 2011 2
+ 21 March 2011 2
@@ -136,49 +137,50 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE
LATEXMK(1L) LATEXMK(1L)
- 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
+ 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
+ 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.
@@ -188,12 +190,12 @@ 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
+ a combination of log files, aux files, latexmk's database file
+ of source file information, and those with extensions specified
- 3 February 2011 3
+ 21 March 2011 3
@@ -202,64 +204,65 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
- in the @generated_exts configuration variable. In addition,
- files with extensions by the $clean_ext configuration variable
+ in the @generated_exts configuration variable. In addition,
+ files with extensions by the $clean_ext configuration variable
are removed.
- 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 then 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.
-C Clean up (remove) all regeneratable files generated by latex and
- bibtex or biber. This is the same as the -c option with the
+ 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.
- 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 Clean up (remove) absolutely all regeneratable files. It is now
- equivalent to the -C option. See that option for details.
+ -CA (Obsolete). Now equivalent to the -C option. See that option
+ for details.
- -CF Remove the file containing the database of source file informa-
+ -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
+ -d Set draft mode. This prints the banner message "DRAFT" across
+ your page when converting the dvi file to postscript. Size and
intensity can be modified with the -bs and -bi options. The -bm
- option will override this option as this is really just a short
+ option will override this option as this is really just a short
way of specifying:
latexmk -bm DRAFT
- Note that if the -d option is specified, the -ps option is
+ Note that if the -d option is specified, the -ps option is
assumed.
- -dF Dvi file filtering. The argument to this option is a filter
- which will generate a filtered dvi file with the extension
- ".dviF". All extra processing (e.g. conversion to postscript,
- preview, printing) will then be performed on this filtered dvi
- file.
+ -deps Show a list of dependent files after processing. This is in the
+ form of a dependency list of the form used by the make program,
+ and it is therefore suitable for use in a Makefile. It gives an
+ overall view of the files without listing intermediate files, as
+ well as latexmk can determine them.
+ By default the list of dependent files is sent to stdout (i.e.,
- 3 February 2011 4
+ 21 March 2011 4
@@ -268,204 +271,238 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
+ normally to the screen unless you've redirected latexmk's out-
+ put). But you can set the filename where the list is sent by
+ the -deps-out= option.
+
+ See the section "USING latexmk WITH make" for an example of how
+ to use a dependency list with make.
+
+ 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.
+
+ -dependents
+ Equivalent to -deps.
+
+ -deps- Do not show a list of dependent files after processing. (This
+ is the default.)
+
+ -dependents-
+ Equivalent to -deps-.
+
+ -deps-out=FILENAME
+ Set the filename to which the list of dependent files is writ-
+ ten. If the FILENAME argument is omitted or set to '-', then
+ the output is sent to stdout.
+
+ Use of this option also turns on the output of the list of
+ dependent files after processing.
+
+ -dF Dvi file filtering. The argument to this option is a filter
+ which will generate a filtered dvi file with the extension
+ ".dviF". All extra processing (e.g. conversion to postscript,
+ preview, printing) will then be performed on this filtered dvi
+ file.
+
Example usage: To use dviselect to select only the even pages of
the dvi file:
latexmk -dF 'dviselect even' foo.tex
-diagnostics
- Print detailed diagnostics during a run. This may help for
+ Print detailed diagnostics during a run. This may help for
debugging problems or to understand latexmk's behavior in diffi-
cult situations.
-dvi Generate dvi version of document.
- -dvi- Turn off generation of dvi version of document. (This may get
- overridden, if some other file is made (e.g., a .ps file) that
- is generated from the dvi file, or if no generated file at all
+ -dvi- Turn off generation of dvi version of document. (This may get
+ overridden, if some other file is made (e.g., a .ps file) that
+ is generated from the dvi file, or if no generated file at all
is requested.)
-e <code>
- Execute the specified initialization code before processing.
- The code is Perl code of the same form as is used in latexmk's
+ Execute the specified initialization code before processing.
+ The code is Perl code of the same form as is used in latexmk's
initialization files -- for more details, see the information on
- the -r option, and the section about "Configuration/initializa-
- tion (RC) files". The code is typically a sequence of assign-
- ment statements separated by semicolons.
- The code is executed when the -e option is encountered during
- 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
- -e options can be used, and they are executed in the order they
- appear on the command line.
- Some care is needed to deal with proper quoting of special char-
- acters in the code on the command line. For example, suppose
- you want to set the latex command to use its -shell-escape
- option, then under UNIX/LINUX you could use the line
- latexmk -e '$latex=q/latex %O -shell-escape %S/' file.tex
+ 21 March 2011 5
- Note that the single quotes block normal UNIX/LINUX command
- shells from treating the characters inside the quotes as spe-
- cial. (In this example, the q/.../ construct is a Perl idiom
- equivalent to using single quotes. This avoids the complica-
- tions of getting a quote character inside an already quoted
- string in a way that is independent of both the shell and the
- operating-system.)
- The above command line will NOT work under MS-Windows with
- cmd.exe or command.com or 4nt.exe. For MS-Windows with these
- command shells you could use
- latexmk -e "$latex=q/latex %O -shell-escape %S/" file.tex
- or
+LATEXMK(1L) LATEXMK(1L)
- 3 February 2011 5
+ the -r option, and the section about "Configuration/initializa-
+ tion (RC) files". The code is typically a sequence of assign-
+ ment statements separated by semicolons.
+ The code is executed when the -e option is encountered during
+ 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
+ -e options can be used, and they are executed in the order they
+ appear on the command line.
+ Some care is needed to deal with proper quoting of special char-
+ acters in the code on the command line. For example, suppose
+ you want to set the latex command to use its -shell-escape
+ option, then under UNIX/LINUX you could use the line
+
+ latexmk -e '$latex=q/latex %O -shell-escape %S/' file.tex
+ Note that the single quotes block normal UNIX/LINUX command
+ shells from treating the characters inside the quotes as spe-
+ cial. (In this example, the q/.../ construct is a Perl idiom
+ equivalent to using single quotes. This avoids the complica-
+ tions of getting a quote character inside an already quoted
+ string in a way that is independent of both the shell and the
+ operating-system.)
+ The above command line will NOT work under MS-Windows with
+ cmd.exe or command.com or 4nt.exe. For MS-Windows with these
+ command shells you could use
-LATEXMK(1L) LATEXMK(1L)
+ latexmk -e "$latex=q/latex %O -shell-escape %S/" file.tex
+ or
latexmk -e "$latex='latex %O -shell-escape %S'" file.tex
- The last two examples will NOT work with UNIX/LINUX command
+ The last two examples will NOT work with UNIX/LINUX command
shells.
- -f Force latexmk to continue document processing despite errors.
+ -f Force latexmk to continue document processing despite errors.
Normally, when latexmk detects that LaTeX or another program has
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-
+ -f option. This could be used to override a setting in a con-
figuration file.
- -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
+ -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.
+
+
+
+ 21 March 2011 6
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
-gg "Super go mode" or "clean make": clean out generated files as if
- -CA had been given, and then do a regular make.
+ -C had been given, and then do a regular make.
-h, -help
Print help information.
-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.
-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
+ 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
+ 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
-
-
-
- 3 February 2011 6
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
- 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.
-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-
+ 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 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
+ 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.
+
+
+ 21 March 2011 7
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
-pdf Generate pdf version of document using pdflatex.
-pdfdvi
- Generate pdf version of document from the dvi file, by default
+ Generate pdf version of document from the dvi file, by default
using dvipdf.
- -pdfps Generate pdf version of document from the ps file, by default
+ -pdfps Generate pdf version of document from the ps file, by default
using ps2pdf.
- -pdf- Turn off generation of pdf version of document. (This can be
- used to override a setting in a configuration file. It may get
+ -pdf- Turn off generation of pdf version of document. (This can be
+ used to override a setting in a configuration file. It may get
overridden if some other option requires the generation of a pdf
file.)
-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
+ 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)
-
-
-
- 3 February 2011 7
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
will then be performed on this filtered postscript file.
Example of usage: Use psnup to print two pages on the one page:
@@ -477,69 +514,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,
+ -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 Description above). Which of these files is generated and
- 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 dvi or ps viewer, as set by one of
- the -view=dvi and -view=ps options.
+ 21 March 2011 8
- There are some other methods for arranging an update, notably
- useful for many versions of xdvi and xpdf. These are best set
- 3 February 2011 8
+LATEXMK(1L) LATEXMK(1L)
+ 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.
-LATEXMK(1L) LATEXMK(1L)
+ 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 dvi or ps viewer, as set by one of
+ the -view=dvi and -view=ps options.
+ 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.
@@ -547,50 +584,92 @@ 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
+
+
+
+ 21 March 2011 9
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ 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
+ 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-
+ Do not use the -recorder option with latex and pdflatex.
+
+ -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
+ processing. (This is the default.)
+
-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
+ of diagnostics generated. For example, with the default set-
+ tings, the command "latex -interaction=batchmode" is used for
latex.
- Also reduce the number of informational messages that latexmk
+ Also reduce the number of informational messages that latexmk
generates.
- To change the options used to make the commands run silently,
+ 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-
+ uration variables, the relevant ones being $bib-
tex_silent_switch, $biber_silent_switch, $dvips_silent_switch,
$latex_silent_switch, and $pdflatex_silent_switch.
- -v, -version
- Print version number of latexmk.
+ -use-make
+ 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
+ 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
+ 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
- 3 February 2011 9
+ 21 March 2011 10
@@ -599,6 +678,18 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
+ appropriate pdflatex).
+
+ 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.
+ (Default.)
+
+ -v, -version
+ Print version number of latexmk.
+
-verbose
Opposite of -silent. This is the default setting.
@@ -607,11 +698,11 @@ 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).
- 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
+ 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.
- Options -p, -pv and -pvc are mutually exclusive. So each of these
+ Options -p, -pv and -pvc are mutually exclusive. So each of these
options turns the others off.
@@ -643,21 +734,10 @@ CONFIGURATION/INITIALIZATION (RC) FILES
1) The system RC file, if it exists.
On a UNIX system, latexmk searches for following places for its sys-
tem RC file, in the following order, and reads the first it finds:
- "/opt/local/share/latexmk/LatexMk",
- "/usr/local/share/latexmk/LatexMk",
- "/usr/local/lib/latexmk/LatexMk".
- On a MS-WINDOWS system it looks for "C:\latexmk\LatexMk".
- 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",
- "/usr/local/share/latexmk/LatexMk",
- "/usr/local/lib/latexmk/LatexMk".
-
- 3 February 2011 10
+ 21 March 2011 11
@@ -666,34 +746,45 @@ CONFIGURATION/INITIALIZATION (RC) FILES
LATEXMK(1L) LATEXMK(1L)
+ "/opt/local/share/latexmk/LatexMk",
+ "/usr/local/share/latexmk/LatexMk",
+ "/usr/local/lib/latexmk/LatexMk".
+ On a MS-WINDOWS system it looks for "C:\latexmk\LatexMk".
+ 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",
+ "/usr/local/share/latexmk/LatexMk",
+ "/usr/local/lib/latexmk/LatexMk".
+
2) The user's RC file, "$HOME/.latexmkrc", if it exists. Here $HOME is
- the value of the environment variable HOME. On UNIX and clones
- (including LINUX), this variable is set by the system; on MS-Windows,
+ the value of the environment variable HOME. On UNIX and clones
+ (including LINUX), this variable is set by the system; on MS-Windows,
the user may choose to set it.
- 3) The RC file in the current working directory. This file can be
- named either "latexmkrc" or ".latexmkrc", and the first of these to be
+ 3) The RC file in the current working directory. This file can be
+ named either "latexmkrc" or ".latexmkrc", and the first of these to be
found is used, if any.
4) Any RC file(s) specified on the command line with the -r option.
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
+ 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
+ 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
+ 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.
HOW TO SET VARIABLES IN INITIALIZATION FILES
- The important variables that can be configured are described in the
- section "List of configuration variables usable in initialization
+ The important variables that can be configured are described in the
+ section "List of configuration variables usable in initialization
files". Syntax for setting these variables is of the following forms:
$bibtex = 'bibtex %O %B';
@@ -706,92 +797,83 @@ HOW TO SET VARIABLES IN INITIALIZATION FILES
@default_files = ('paper', 'paper1');
- for the setting of an array of strings. It is possible to append an
+ for the setting of an array of strings. It is possible to append an
item to an array variable as follows:
push @default_files, 'paper2';
- Note that simple "scalar" variables have names that begin with a $
- character and array variables have names that begin with a @ character.
- Each statement ends with a semicolon.
- Strings should be enclosed in single quotes. (You could use double
- quotes, as in many programming languages. But then the Perl program-
- ming language brings into play some special rules for interpolating
- variables into strings. People not fluent in Perl will want to avoid
- these complications.)
+ 21 March 2011 12
- 3 February 2011 11
+LATEXMK(1L) LATEXMK(1L)
-LATEXMK(1L) LATEXMK(1L)
+ Note that simple "scalar" variables have names that begin with a $
+ character and array variables have names that begin with a @ character.
+ Each statement ends with a semicolon.
+ Strings should be enclosed in single quotes. (You could use double
+ quotes, as in many programming languages. But then the Perl program-
+ ming language brings into play some special rules for interpolating
+ variables into strings. People not fluent in Perl will want to avoid
+ these complications.)
- You can do much more complicated things, but for this you will need to
+ You can do much more complicated things, but for this you will need to
consult a manual for the Perl programming language.
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
+ 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
view a postscript file. This section describes some important features
of how the commands are specified.
Placeholders: Supposed you wanted latexmk to use the command elatex in
- place of the regular latex command, and suppose moreover that you
- wanted to give it the option "--shell-escape". You could do this by
+ place of the regular latex command, and suppose moreover that you
+ wanted to give it the option "--shell-escape". You could do this by
the following setting:
$latex = 'elatex --shell-escape %O %S';
- The two items starting with the % character are placeholders. These
- are substituted by appropriate values before the command is run. Thus
- %S will be replaced by the source file that elatex will be applied to,
- and %O will be replaced by any options that latexmk has decided to use
- for this command. (E.g., if you used the -silent option it would
+ The two items starting with the % character are placeholders. These
+ are substituted by appropriate values before the command is run. Thus
+ %S will be replaced by the source file that elatex will be applied to,
+ and %O will be replaced by any options that latexmk has decided to use
+ for this command. (E.g., if you used the -silent option it would
replace %O by "-interaction=batchmode".)
The available placeholders are:
- %B base of filename for current command. E.g., if a postscript
- file document.ps is being made from the dvi file document.dvi,
+ %B base of filename for current command. E.g., if a postscript
+ file document.ps is being made from the dvi file document.dvi,
then the basename is document.
- %D destination file (e.g., the name of the postscript file when
+ %D destination file (e.g., the name of the postscript file when
converting a dvi file to postscript).
%O options
%R root filename. This is the base name for the main tex file.
- %S source file (e.g., the name of the dvi file when converting a
+ %S source file (e.g., the name of the dvi file when converting a
dvi file to ps).
%T The name of the primary tex file.
- If for some reason you need a literal % character in your string not
- subject to the above rules, use a pair of these characters. Thus with
- the command specification $ps_previewer = 'latex -ad=%%Sfile.ad %S',
- the %%S will become %S when the command is executed, but the %S will be
- replaced by the source filename, which in this case would be the name
- of a postscript file to be viewed.
-
- Appropriate quoting will be applied to the filename substitutions, so
- you mustn't supply them yourself even if you the names of your have
- spaces in them. (But if your TeX filenames have spaces in them, beware
- that many versions of the TeX program cannot correctly handle filenames
+ If for some reason you need a literal % character in your string not
+ subject to the above rules, use a pair of these characters. Thus with
- 3 February 2011 12
+ 21 March 2011 13
@@ -800,90 +882,99 @@ FORMAT OF COMMAND SPECIFICATIONS
LATEXMK(1L) LATEXMK(1L)
- containing spaces.) In case latexmk's quoting does not work correctly
- on your system, you can turn it off -- see the documentation for the
+ the command specification $ps_previewer = 'latex -ad=%%Sfile.ad %S',
+ the %%S will become %S when the command is executed, but the %S will be
+ replaced by the source filename, which in this case would be the name
+ of a postscript file to be viewed.
+
+ Appropriate quoting will be applied to the filename substitutions, so
+ you mustn't supply them yourself even if you the names of your have
+ spaces in them. (But if your TeX filenames have spaces in them, beware
+ that many versions of the TeX program cannot correctly handle filenames
+ containing spaces.) In case latexmk's quoting does not work correctly
+ on your system, you can turn it off -- see the documentation for the
variable $quote_filenames.
- The distinction between %B and %R needs a bit of care, since they are
- often the same, but not always. For example on a simple document, the
+ The distinction between %B and %R needs a bit of care, since they are
+ often the same, but not always. For example on a simple document, the
basename of a bibtex run is the same as for the texfile. But in a doc-
- ument with several bibliographies, the bibliography files will have a
- variety of names. Since bibtex is invoked with the basename of the
- bibliography file, the setting for the bibtex command should therefore
+ ument with several bibliographies, the bibliography files will have a
+ variety of names. Since bibtex is invoked with the basename of the
+ bibliography file, the setting for the bibtex command should therefore
be
$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 pur-
+ poses, the name %T of the primary texfile is not a useful placeholder.
- See the default values in the section "List of configuration variables
+ See the default values in the section "List of configuration variables
usable in initialization files" for what is normally the most appropri-
ate usage.
If you omit to supply any placeholders whatever in the specification of
- a command, latexmk will supply what its author thinks are appropriate
+ a command, latexmk will supply what its author thinks are appropriate
defaults. This gives compatibility with configuration files for previ-
ous versions of latexmk, which didn't use placeholders.
- "Detaching" a command: Normally when latexmk runs a command, it waits
+ "Detaching" a command: Normally when latexmk runs a command, it waits
for the command to run to completion. This is appropriate for commands
like latex, of course. But for previewers, the command should normally
- run detached, so that latexmk gets the previewer running and then
+ run detached, so that latexmk gets the previewer running and then
returns to its next task (or exits if there is nothing else to do). To
- achieve this effect of detaching a command, you need to precede the
+ achieve this effect of detaching a command, you need to precede the
command name with "start ", as in
$dvi_previewer = 'start xdvi %O %S';
- This will be translated to whatever is appropriate for your operating
+ This will be translated to whatever is appropriate for your operating
system.
- Notes: (1) In some circumstances, latex will always run a command
+ Notes: (1) In some circumstances, latex will always run a command
detached. This is the case for a previewer in preview continuous mode,
- since otherwise previewing continuously makes no sense. (2) This pre-
- cludes the possibility of running a command named start. (3) If the
- word start occurs more than once at the beginning of the command
- string, that is equivalent to having just one. (4) Under cygwin, some
- complications happen, since cygwin amounts to a complicated merging of
- UNIX and MS-Windows. See the source code for how I've handled the
- problem.
+ since otherwise previewing continuously makes no sense. (2) This pre-
+ cludes the possibility of running a command named start. (3) If the
+ word start occurs more than once at the beginning of the command
+ string, that is equivalent to having just one. (4) Under cygwin, some
+ complications happen, since cygwin amounts to a complicated merging of
+ UNIX and MS-Windows. See the source code for how I've handled the
- Command names containing spaces: Under MS-Windows it is common that the
- name of a command includes spaces, since software is often installed in
- a subdirectory of "C:\Program Files". Such command names should be
- enclosed in double quotes, as in
- $lpr_pdf = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p
+ 21 March 2011 14
- 3 February 2011 13
+LATEXMK(1L) LATEXMK(1L)
-LATEXMK(1L) LATEXMK(1L)
+ problem.
+ Command names containing spaces: Under MS-Windows it is common that the
+ name of a command includes spaces, since software is often installed in
+ a subdirectory of "C:\Program Files". Such command names should be
+ enclosed in double quotes, as in
+ $lpr_pdf = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p
%S';
- (Note about the above example: Forward slashes are equivalent to back-
- slashes in filenames under MS-Windows, provided that the filename is
- inside double quotes. It is easier to use forward slashes in examples
- like the one above, since then one does not have to worry about the
- rules for dealing with forward slashes in strings in the Perl lan-
+ (Note about the above example: Forward slashes are equivalent to back-
+ slashes in filenames under MS-Windows, provided that the filename is
+ inside double quotes. It is easier to use forward slashes in examples
+ like the one above, since then one does not have to worry about the
+ rules for dealing with forward slashes in strings in the Perl lan-
guage.)
- Using MS-Windows file associations: A useful trick under modern ver-
+ Using MS-Windows file associations: A useful trick under modern ver-
sions of MS-Windows (e.g., WinXP) is to use just the command 'start' by
itself:
$dvi_previewer = 'start %S';
Under recent versions of MS-Windows, this will cause to be run whatever
- program the system has associated with dvi files. (The same applies
+ program the system has associated with dvi files. (The same applies
for a postscript viewer and a pdf viewer.)
Not using a certain command: If a command is not to be run, the command
@@ -891,47 +982,48 @@ LATEXMK(1L) LATEXMK(1L)
$lpr = 'NONE lpr';
- This typically is used when an appropriate command does not exist on
+ This typically is used when an appropriate command does not exist on
your system. The string after the "NONE" is effectively a comment.
Options to commands: Setting the name of a command can be used not only
for changing the name of the command called, but also to add options to
- command. Suppose you want latexmk to use latex with source specials
- enabled. Then you might use the following line in an initialization
+ command. Suppose you want latexmk to use latex with source specials
+ enabled. Then you might use the following line in an initialization
file:
$latex = 'latex --src-specials %O %S';
- Advanced tricks: Normally one specifies a single command for the com-
- mands invoked by latexmk. Naturally, if there is some complicated
+ Advanced tricks: Normally one specifies a single command for the com-
+ mands invoked by latexmk. Naturally, if there is some complicated
additional processing you need to do in your special situation, you can
write a script (or batch file) to do the processing, and then configure
latexmk to use your script in place of the standard program.
It is also possible to configure latexmk to run multiple commands. For
- example, if when running pdflatex to generate a pdf file from a tex
- file you need to run another program after pdflatex to perform some
+ example, if when running pdflatex to generate a pdf file from a tex
+ file you need to run another program after pdflatex to perform some
extra processing, you could do something like:
- $pdflatex = 'pdflatex --shell-escape %O %S; pst2pdf_for_latexmk
- %B';
+ $pdflatex = 'pdflatex --shell-escape %O %S; pst2pdf_for_latexmk
- This definition assumes you are using a UNIX-like system, so that the
- two commands to be run are separated by the semicolon in the middle of
- the string.
+ 21 March 2011 15
- 3 February 2011 14
+LATEXMK(1L) LATEXMK(1L)
+ %B';
+
+ This definition assumes you are using a UNIX-like system, so that the
+ two commands to be run are separated by the semicolon in the middle of
+ the string.
-LATEXMK(1L) LATEXMK(1L)
LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES
@@ -939,27 +1031,27 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES
$always_view_file_via_temporary [0]
Whether ps and pdf files are initially to be made in a temporary
- directory and then moved to the final location. (This applies
+ directory and then moved to the final location. (This applies
to dvips, dvipdf, and ps2pdf operations, and the filtering oper-
- ators on dvi and ps files. It does not apply to pdflatex,
+ ators on dvi and ps files. It does not apply to pdflatex,
unfortunately.)
This use of a temporary file solves a problem that the making of
- these files can occupy a substantial time. If a viewer sees
- that the file has changed, it reads the new file, and this can
+ 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
its work.
See the $pvc_view_file_via_temporary variable for a setting that
- applies only if preview-continuous mode (-pvc option) is used.
+ applies only if preview-continuous mode (-pvc option) is used.
See $tmpdir for the setting of the directory where the temporary
file is created.
$banner [0]
- If nonzero, the banner message is printed across each page when
- converting the dvi file to postscript. Without modifying the
- variable $banner_message, this is equivalent to specifying the
+ If nonzero, the banner message is printed across each page when
+ converting the dvi file to postscript. Without modifying the
+ variable $banner_message, this is equivalent to specifying the
-d option.
Note that if $banner is nonzero, the $postscript_mode is assumed
@@ -968,7 +1060,7 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES
$banner_intensity [0.95]
Equivalent to the -bi option, this is a decimal number between 0
- and 1 that specifies how dark to print the banner message. 0 is
+ and 1 that specifies how dark to print the banner message. 0 is
black, 1 is white. The default is just right if your toner car-
tridge isn't running too low.
@@ -977,22 +1069,15 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES
dvi file to postscript. This is equivalent to the -bm option.
$banner_scale [220.0]
- A decimal number that specifies how large the banner message
- will be printed. Experimentation is necessary to get the right
- scale for your message, as a rule of thumb the scale should be
- about equal to 1100 divided by the number of characters in the
- message. The Default is just right for 5 character messages.
- This is equivalent to the -bs option.
-
- @BIBINPUTS
- This is an array variable, now mostly obsolete, that specifies
- directories where latexmk should look for .bib files. By
- default it is set from the BIBINPUTS environment variable of the
- operating system. If that environment variable is not set, a
+ A decimal number that specifies how large the banner message
+ will be printed. Experimentation is necessary to get the right
+ scale for your message, as a rule of thumb the scale should be
+ about equal to 1100 divided by the number of characters in the
+ message. The Default is just right for 5 character messages.
- 3 February 2011 15
+ 21 March 2011 16
@@ -1001,7 +1086,14 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES
LATEXMK(1L) LATEXMK(1L)
- single element list consisting of the current directory is set.
+ This is equivalent to the -bs option.
+
+ @BIBINPUTS
+ This is an array variable, now mostly obsolete, that specifies
+ directories where latexmk should look for .bib files. By
+ default it is set from the BIBINPUTS environment variable of the
+ operating system. If that environment variable is not set, a
+ single element list consisting of the current directory is set.
The format of the directory names depends on your operating sys-
tem, of course. Examples for setting this variable are:
@@ -1011,13 +1103,13 @@ LATEXMK(1L) LATEXMK(1L)
@BIBINPUTS = ( ".", "//server/bibfiles" );
@BIBINPUTS = ( ".", "/usr/local/texmf/bibtex/bib" );
- Note that under MS Windows, either a forward slash "/" or a
- backward slash "\" can be used to separate pathname components,
- so the first two and the second two examples are equivalent.
- Each backward slash should be doubled to avoid running afoul of
+ Note that under MS Windows, either a forward slash "/" or a
+ backward slash "\" can be used to separate pathname components,
+ so the first two and the second two examples are equivalent.
+ Each backward slash should be doubled to avoid running afoul of
Perl's rules for writing strings.
- Important note: This variable is now mostly obsolete in the current
+ Important note: This variable is now mostly obsolete in the current
version of latexmk, since it has a better method of searching for files
using the kpsewhich command. However, if your system is an unusual one
without the kpsewhich command, you may need to set the variable @BIBIN-
@@ -1027,7 +1119,7 @@ LATEXMK(1L) LATEXMK(1L)
The biber processing program.
$biber_silent_switch ["--onlylog"]
- Switch(es) for the biber processing program when silent mode is
+ Switch(es) for the biber processing program when silent mode is
on.
$bibtex ["bibtex %O %S"]
@@ -1039,28 +1131,21 @@ LATEXMK(1L) LATEXMK(1L)
$bibtex_use [1]
Under what conditions to run BibTeX or biber. When latexmk dis-
- covers from the log file that one (or more) BibTeX/biber-gener-
- ated bibliographies are used, it can run BibTeX or biber when-
- ever it appears necessary to regenerate the bbl file(s) from
+ covers from the log file that one (or more) BibTeX/biber-gener-
+ ated bibliographies are used, it can run BibTeX or biber when-
+ ever it appears necessary to regenerate the bbl file(s) from
their source bib database file(s).
- But sometimes, the bib file(s) are not available (e.g., for a
- document obtained from an external archive), but the bbl files
- are provided. In that case use of BibTeX or biber will result
- in incorrect overwriting of the precious bbl files. The vari-
- able $bibtex_use controls whether this happens. Its possible
+ But sometimes, the bib file(s) are not available (e.g., for a
+ document obtained from an external archive), but the bbl files
+ are provided. In that case use of BibTeX or biber will result
+ in incorrect overwriting of the precious bbl files. The vari-
+ able $bibtex_use controls whether this happens. Its possible
values are: 0: never use BibTeX or biber. 1: only use BibTeX or
- biber if the bib files exist. 2: run BibTeX or biber whenever
- it appears necessary to update the bbl files, without testing
- for the existence of the bib files.
-
- $cleanup_includes_cusdep_generated [0]
- If nonzero, specifies that cleanup also deletes files that are
- generated by custom dependencies. (When doing a clean up, e.g.,
- 3 February 2011 16
+ 21 March 2011 17
@@ -1069,66 +1154,66 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
+ biber if the bib files exist. 2: run BibTeX or biber whenever
+ it appears necessary to update the bbl files, without testing
+ for the existence of the bib files.
+
+ $cleanup_includes_cusdep_generated [0]
+ If nonzero, specifies that cleanup also deletes files that are
+ generated by custom dependencies. (When doing a clean up, e.g.,
by use of the -C option, custom dependencies are those listed in
the .fdb_latexmk file from a previous run.)
$cleanup_includes_generated [0]
- If nonzero, specifies that cleanup also deletes files that are
- detected in log file as being generated (see the \openout lines
- in the log file). It will also include files made from these
+ If nonzero, specifies that cleanup also deletes files that are
+ detected in log file as being generated (see the \openout lines
+ in the log file). It will also include files made from these
first generation generated files.
$cleanup_mode [0]
- If nonzero, specifies cleanup mode: 1 for full cleanup, 2 for
- cleanup except for dvi, ps and pdf files, 3 for cleanup except
- for dep and aux files. (There is also extra cleaning as speci-
- fied by the $clean_ext, $clean_full_ext and @generated_exts
+ If nonzero, specifies cleanup mode: 1 for full cleanup, 2 for
+ cleanup except for dvi, ps and pdf files, 3 for cleanup except
+ for dep and aux files. (There is also extra cleaning as speci-
+ fied by the $clean_ext, $clean_full_ext and @generated_exts
variables.)
- This variable is equivalent to specifying one of the -c or -C options.
+ This variable is equivalent to specifying one of the -c or -C options.
But there should be no need to set this variable from an RC file.
$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
+ 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
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
+ be deleted, by using the place holder %R, as in commands. 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
- deleted, but also files of the form FOO.out and FOO-blx.bib,
- where FOO stands for the basename of the file being processed
+ tion is specified, not only is the standard set of files
+ 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_full_ext [""]
- Extra extensions of files for latexmk to remove when the -C
+ Extra extensions of files for latexmk to remove when the -C
option is selected, i.e., extensions of files to remove when the
.dvi, etc files are to be cleaned-up.
@cus_dep_list [()]
- Custom dependency list -- see section on "Custom Dependencies".
+ Custom dependency list -- see section on "Custom Dependencies".
@default_files [("*.tex")]
Default list of files to be processed.
- Normally, if no filenames are specified on the command line,
- latexmk processes all tex files specified in the @default_files
- variable, which by default is set to all tex files ("*.tex") in
- the current directory. This is a convenience: just run latexmk
- and it will process an appropriate set of files. But sometimes
- you want only some of these files to be processed. In this case
- you set the @default_files in an initialization file (e.g., the
- 3 February 2011 17
+ 21 March 2011 18
@@ -1137,8 +1222,15 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
- file "latexmkrc" in the current directory). Then if no files
- are specified on the command line then the files you specify by
+ Normally, if no filenames are specified on the command line,
+ latexmk processes all tex files specified in the @default_files
+ variable, which by default is set to all tex files ("*.tex") in
+ the current directory. This is a convenience: just run latexmk
+ and it will process an appropriate set of files. But sometimes
+ you want only some of these files to be processed. In this case
+ you set the @default_files in an initialization file (e.g., the
+ file "latexmkrc" in the current directory). Then if no files
+ are specified on the command line then the files you specify by
setting @default_files are processed.
Three examples:
@@ -1149,11 +1241,15 @@ LATEXMK(1L) LATEXMK(1L)
@default_files = ("*.tex", "*.dtx");
- Note that more than file may be given, and that the default
- extension is ".tex". Wild cards are allowed. The parentheses
+ Note that more than file may be given, and that the default
+ extension is ".tex". Wild cards are allowed. The parentheses
are because @default_files is an array variable, i.e., a
sequence of filename specifications is possible.
+ $dependents_list [0]
+ Whether to display a list(s) of dependencies at the end of a
+ run.
+
$dvi_filter [empty]
The dvi file filter to be run on the newly produced dvi file
before other processing. Equivalent to specifying the -dF
@@ -1182,31 +1278,31 @@ LATEXMK(1L) LATEXMK(1L)
$dvipdf ["dvipdf %O %S %D"]
Command to convert dvi to pdf file. A common reconfiguration is
- to use the dvipdfm command, which needs its arguments in a dif-
- ferent order:
+ to use the dvipdfm command, which needs its arguments in a
- $dvipdf = "dvipdfm %O -o %D %S";
- WARNING: The default dvipdf script generates pdf files with
- bitmapped fonts, which do not look good when viewed by acroread.
- That script should be modified to give dvips the options "-P
- pdf" to ensure that type 1 fonts are used in the pdf file.
- $dvips ["dvips %O -o %D %S"]
- The program to used as a filter to convert a .dvi file to a .ps
- file. If pdf is going to be generated from pdf, then the value
+ 21 March 2011 19
- 3 February 2011 18
+LATEXMK(1L) LATEXMK(1L)
+ different order:
-LATEXMK(1L) LATEXMK(1L)
+ $dvipdf = "dvipdfm %O -o %D %S";
+ WARNING: The default dvipdf script generates pdf files with
+ bitmapped fonts, which do not look good when viewed by acroread.
+ That script should be modified to give dvips the options "-P
+ pdf" to ensure that type 1 fonts are used in the pdf file.
+ $dvips ["dvips %O -o %D %S"]
+ The program to used as a filter to convert a .dvi file to a .ps
+ file. If pdf is going to be generated from pdf, then the value
of the $dvips_pdf_switch -- see below -- will be included in the
options substituted for "%O".
@@ -1253,6 +1349,17 @@ LATEXMK(1L) LATEXMK(1L)
variable $dvi_update_method. The default value is the one
appropriate for xdvi on a UNIX system.
+
+
+ 21 March 2011 20
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
$fdb_ext ["fdb_latexmk"]
The extension of the file which latexmk generates to contain a
database of information on source files. You will not normally
@@ -1266,18 +1373,6 @@ LATEXMK(1L) LATEXMK(1L)
@generated_exts [( aux , bbl , idx , ind , lof , lot , out , toc ,
$fdb_ext )]
This contains a list of extensions for files that are generated
-
-
-
- 3 February 2011 19
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
during a LaTeX run and that are read in by LaTeX in later runs,
either directly or indirectly.
@@ -1322,6 +1417,18 @@ LATEXMK(1L) LATEXMK(1L)
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
+
+
+
+ 21 March 2011 21
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
runs to guard against pathological situations.
But the changing line has no real effect, since it is a comment.
@@ -1337,18 +1444,6 @@ LATEXMK(1L) LATEXMK(1L)
they are to be specified in general.) This particular regular
expression specifies that lines beginning with "%%CreationDate:
" are to be ignored in deciding whether a file of the given
-
-
-
- 3 February 2011 20
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
extension .eps has changed.
There is only one regular expression available for each exten-
@@ -1392,6 +1487,18 @@ LATEXMK(1L) LATEXMK(1L)
$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
+
+
+
+ 21 March 2011 22
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
program used, but also specify options to the program. E.g.,
$latex = "latex --src-specials";
@@ -1409,17 +1516,6 @@ LATEXMK(1L) LATEXMK(1L)
specified by the variable %latex_input_extensions. The default
extensions are 'tex' and 'eps'.
-
-
- 3 February 2011 21
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
(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-
@@ -1461,6 +1557,18 @@ LATEXMK(1L) LATEXMK(1L)
example, if you have gsview installed, you could use it with the
option "/p":
+
+
+
+ 21 March 2011 23
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
$lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
If gsview is installed in a different directory, you will need
@@ -1479,18 +1587,6 @@ LATEXMK(1L) LATEXMK(1L)
The printing program to print pdf files.
Under MS-Windows you could set this to use gsview, if it is
-
-
-
- 3 February 2011 22
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
installed, e.g.,
$lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
@@ -1502,6 +1598,10 @@ LATEXMK(1L) LATEXMK(1L)
interpreted.
+ $make ["make"]
+ The make processing program.
+
+
$makeindex ["makeindex %O -o %D %S"]
The index processing program.
@@ -1527,6 +1627,18 @@ 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
+
+
+
+ 21 March 2011 24
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
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
@@ -1551,17 +1663,6 @@ LATEXMK(1L) LATEXMK(1L)
specified by the variable %pdflatex_input_extensions. The
default extensions are 'tex', 'pdf', 'jpg, and 'png'.
-
-
- 3 February 2011 23
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
(For Perl experts: %pdflatex_input_extensions is a hash whose
keys are the extensions. The values are irrelevant.) Two sub-
routines are provided for manipulating this and the related
@@ -1598,6 +1699,18 @@ LATEXMK(1L) LATEXMK(1L)
$pdf_previewer ["start acroread %O %S"]
The command to invoke a pdf-previewer. [Default is changed to
"start" on MS-WINDOWS; under more recent versions of Windows,
+
+
+
+ 21 March 2011 25
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
this will cause to be run whatever command the system has asso-
ciated with .pdf files.]
@@ -1622,17 +1735,6 @@ LATEXMK(1L) LATEXMK(1L)
for the value 2, to specify update by signal, the signal is
specified by $pdf_update_signal.)
-
-
- 3 February 2011 24
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
Note that acroread under MS-Windows (but not UNIX) locks the pdf
file, so the default value is then 3.
@@ -1669,6 +1771,18 @@ LATEXMK(1L) LATEXMK(1L)
If nonzero, generate a postscript version of the document.
Equivalent to the -ps option.
+
+
+
+ 21 March 2011 26
+
+
+
+
+
+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.
@@ -1693,17 +1807,6 @@ LATEXMK(1L) LATEXMK(1L)
Type of file to printout: possibilities are "dvi", "none",
"pdf", or "ps".
-
-
- 3 February 2011 25
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
$pscmd Command used to get all the processes currently run by the user.
The -pvc option uses the command specified by the variable
$pscmd to determine if there is an already running previewer,
@@ -1740,6 +1843,18 @@ LATEXMK(1L) LATEXMK(1L)
ferent ways of writing this option. You can configure this
variable apppropriately.
+
+
+
+ 21 March 2011 27
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
WARNING: Linux systems may have installed one (or more) versions
of gv under different names, e.g., ggv, kghostview, etc, but
perhaps not one called gv.
@@ -1763,18 +1878,6 @@ LATEXMK(1L) LATEXMK(1L)
signal, the signal is specified by $ps_update_signal.)
-
-
-
- 3 February 2011 26
-
-
-
-
-
-LATEXMK(1L) LATEXMK(1L)
-
-
$ps_update_signal [Under UNIX: SIGHUP, which is a system-dependent
value]
The number of the signal that is sent to the pdf viewer when it
@@ -1801,43 +1904,93 @@ LATEXMK(1L) LATEXMK(1L)
ing only ensures that such filenames are correctly treated by the oper-
ating system in passing arguments to programs.)
+ $recorder [0]
+ Whether to use the -recorder option to latex and pdflatex. Use
+ of this option results in a file of extension .fls containing a
+ list of the files that these programs 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 pdfla-
+ tex.
+
+ It is generally recommended to use this option (or to configure
+ the $recorder variable to be on.) But it only works if
+ (pdf)latex supports the -recorder option, which is true for most
+
+
+
+ 21 March 2011 28
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ current implementations
+
+ Note about the name of the .fls file: Most implementations of
+ (pdf)latex produce an .fls file with the same basename as the
+ main document's LaTeX, e.g., for Document.tex, the .fls file is
+ Document.fls. However, some implementations instead produce
+ files named for the program, i.e., latex.fls or pdflatex.fls.
+ In this second case, latexmk copies the latex.fls or pdfla-
+ tex.fls to a file with the basename of the main LaTeX document,
+ e.g., Document.fls.
+
$sleep_time [2]
- The time to sleep (in seconds) between checking for source file
+ The time to sleep (in seconds) between checking for source file
changes when running with the -pvc option. This is subject to a
- minimum of one second delay, except that zero delay is also
+ minimum of one second delay, except that zero delay is also
allowed.
- A value of exactly 0 gives no delay, and typically results in
+ A value of exactly 0 gives no delay, and typically results in
100% CPU usage, which may not be desirable.
$texfile_search [""]
- This is an obsolete variable, replaced by the @default_files
+ This is an obsolete variable, replaced by the @default_files
variable.
- For backward compatibility, if you choose to set $tex-
- file_search, it is a string of space-separated filenames, and
+ 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-
file_search to which is added "*.tex".
$tmpdir [See below for default]
- Directory to store temporary files that latexmk may generate
+ Directory to store temporary files that latexmk may generate
while running.
- The default under MSWindows (including cygwin), is to set
- $tmpdir to the value of the first of whichever of the system
- environment variables TMPDIR or TEMP exists, otherwise to the
- current directory. Under other operating systems (expected to
- be UNIX/Linux, including OS-X), the default is the value of the
- system environment variable TMPDIR if it exists, otherwise
+ The default under MSWindows (including cygwin), is to set
+ $tmpdir to the value of the first of whichever of the system
+ environment variables TMPDIR or TEMP exists, otherwise to the
+ current directory. Under other operating systems (expected to
+ be UNIX/Linux, including OS-X), the default is the value of the
+ system environment variable TMPDIR if it exists, otherwise
"/tmp".
+ $use_make_for_missing_files [0]
+ Whether to use make to try and make files that are missing after
+ a run of latex or pdflatex, and for which a custom dependency
+ has not been found. This is generally useful only when latexmk
+ is used as part of a bigger project which is built by using the
+ make program.
+
+ Note that once a missing file has been made, no further calls to
+ make will be made on a subsequent run of latexmk to update the
+ file. Handling this problem is the job of a suitably defined
+ Makefile. See the section "USING latexmk WITH make" for how to
+ do this. The intent of calling make from latexmk is merely to
+ detect dependencies.
+
$view ["default"]
Which kind of file is to be previewed if a previewer is used.
The possible values are "default", "dvi", "ps", "pdf". The
+ value of "default" means that the "highest" of the kinds of file
+ generated is to be used (among dvi, ps and pdf).
- 3 February 2011 27
+ 21 March 2011 29
@@ -1846,10 +1999,6 @@ LATEXMK(1L) LATEXMK(1L)
LATEXMK(1L) LATEXMK(1L)
- value of "default" means that the "highest" of the kinds of file
- generated is to be used (among dvi, ps and pdf).
-
-
CUSTOM DEPENDENCIES
In any RC file a set of custom dependencies can be set up to convert a
file with one extension to a file with another. An example use of this
@@ -1905,23 +2054,22 @@ CUSTOM DEPENDENCIES
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
+ specifies how the rule should be applied when the source file fails to
+ exist.
+ A simple and typical example of code in an initialization rcfile is
- 3 February 2011 28
-
+ 21 March 2011 30
-LATEXMK(1L) LATEXMK(1L)
- One other item in each custom-dependency rule labelled "must" above
- specifies how the rule should be applied when the source file fails to
- exist.
+LATEXMK(1L) LATEXMK(1L)
- A simple and typical example of code in an initialization rcfile is
add_cus_dep( 'fig', 'eps', 0, 'fig2eps' );
sub fig2eps {
@@ -1976,24 +2124,24 @@ LATEXMK(1L) LATEXMK(1L)
add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' );
sub fig2pdf {
system("fig2dev -Lpdf $_[0].fig $_[0].pdf");
+ }
+ If you have some general custom dependencies defined in the system or
+ user initialization file, you may find that for a particular project
+ they are undesirable. So you might want to delete the unneeded ones.
+ For example, you remove any "fig" to "eps" rule by the line
- 3 February 2011 29
+ 21 March 2011 31
-LATEXMK(1L) LATEXMK(1L)
- }
+LATEXMK(1L) LATEXMK(1L)
- 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' );
@@ -2046,26 +2194,26 @@ 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-
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
+ 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
+ .fig files to .eps files:
- 3 February 2011 30
+ 21 March 2011 32
-LATEXMK(1L) LATEXMK(1L)
- separated by a space, the from-extension, the to-extension, the "must"
- item, and the name of the subroutine for the custom dependency. These
- were all defined above.
+LATEXMK(1L) LATEXMK(1L)
- 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
- .fig files to .eps files:
push @cus_dep_list, "fig eps 0 fig2eps";
sub fig2eps {
@@ -2078,39 +2226,188 @@ LATEXMK(1L) LATEXMK(1L)
preferable.
+
+
+USING latexmk WITH make
+ 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
+ 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.
+
+ 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.
+
+ 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
+
+
+
+ 21 March 2011 33
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ 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
+ 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.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-
+ 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
+ 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
+ rules in the Makefile. To do this, one can use a Makefile like the
+ following:
+
+ TARGETS = document1.pdf document2.pdf
+ DEPS_DIR = .deps
+ LATEXMK = latexmk -recorder -use-make -deps \
+ -e 'warn qq(In Makefile, turn off custom dependencies0;' \
+ -e '@cus_dep_list = ();' \
+ -e 'show_cus_dep();'
+ all : $(TARGETS)
+ $(foreach file,$(TARGETS),$(eval -include $(DEPS_DIR)/$(file)P))
+ $(DEPS_DIR) :
+ mkdir $@
+ %.pdf : %.tex
+ if [ ! -e $(DEPS_DIR) ]; then mkdir $(DEPS_DIR); fi
+ $(LATEXMK) -pdf -dvi- -ps- -deps-out=$(DEPS_DIR)/$@P $<
+ %.pdf : %.fig
+ fig2dev -Lpdf $< $@
+
+ (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
+ 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-
+ dency files are .deps/document1.pdfP and .deps/document2.pdfP.
+
+ 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
+ option, which improves its detection of files generated during a run of
+ pdflatex; such files should not be in the dependency list. The -e
+
+
+
+ 21 March 2011 34
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ 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.
+
+ 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.
+
+
SEE ALSO
latex(1), bibtex(1).
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 gsview
+ (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 gsview
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.22e).
+ Current version, by John Collins (username collins at node
+ phys.psu.edu). (Version 4.23).
- Released version can be obtained from CTAN: <http://www.tug.org/tex-
+ Released version can be obtained from CTAN: <http://www.tug.org/tex-
archive/support/latexmk/>, and from the author's website
<http://www.phys.psu.edu/~collins/software/latexmk/>.
Modifications and enhancements by Evan McLean (Version 2.0)
@@ -2121,7 +2418,11 @@ AUTHOR
- 3 February 2011 31
+
+
+
+
+ 21 March 2011 35
@@ -2192,6 +2493,7 @@ LATEXMK(1L) LATEXMK(1L)
- 3 February 2011 32
+
+ 21 March 2011 36