summaryrefslogtreecommitdiff
path: root/support/latexmk/latexmk.txt
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/latexmk/latexmk.txt
Initial commit
Diffstat (limited to 'support/latexmk/latexmk.txt')
-rw-r--r--support/latexmk/latexmk.txt4620
1 files changed, 4620 insertions, 0 deletions
diff --git a/support/latexmk/latexmk.txt b/support/latexmk/latexmk.txt
new file mode 100644
index 0000000000..6f62542380
--- /dev/null
+++ b/support/latexmk/latexmk.txt
@@ -0,0 +1,4620 @@
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+NAME
+ latexmk - generate LaTeX document
+
+SYNOPSIS
+ latexmk [options] [file ...]
+
+DESCRIPTION
+ Latexmk completely automates the process of compiling a LaTeX document.
+ Essentially, it is like a specialized relative of the general make
+ utility, but one which determines dependencies automatically and has
+ some other very useful features. In its basic mode of operation la-
+ texmk is given the name of the primary source file for a document, and
+ it issues the appropriate sequence of commands to generate a .dvi, .ps,
+ .pdf and/or hardcopy version of the document.
+
+ By default latexmk will run the commands necessary to generate a .dvi
+ file.
+
+ Latexmk can also be set to run continuously with a suitable previewer.
+ In that case the latex program (or one of its relatives), etc, are re-
+ run whenever one of the source files is modified, and the previewer au-
+ tomatically updates the on-screen view of the compiled document.
+
+ Latexmk determines which are the source files by examining the log
+ file. (Optionally, it also examines the list of input and output files
+ generated by the -recorder option of modern versions of latex (and
+ pdflatex, xelatex, lualatex, etc). See the documentation for the
+ -recorder option of latexmk below.) When latexmk is run, it examines
+ properties of the source files, and if any have been changed since the
+ last document generation, latexmk will run the various LaTeX processing
+ programs as necessary. In particular, it will repeat the run of latex
+ (or a related program)) often enough to resolve all cross references;
+ depending on the macro packages used. With some macro packages and
+ document classes, four, or even more, runs may be needed. If necessary,
+ latexmk will also run bibtex, biber, and/or makeindex. In addition,
+ latexmk can be configured to generate other necessary files. For exam-
+ ple, from an updated figure file it can automatically generate a file
+ in encapsulated postscript or another suitable format for reading by
+ LaTeX.
+
+ Latexmk has two different previewing options. With the simple -pv op-
+ tion, 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:
+ "preview continuously"). In this case, latexmk runs continuously, reg-
+ ularly monitoring all the source files to see if any have changed. Ev-
+ ery time a change is detected, latexmk runs all the programs necessary
+ to generate a new version of the document. A good previewer will then
+ automatically update its display. Thus the user can simply edit a file
+ and, when the changes are written to disk, latexmk completely automates
+ the cycle of updating the .dvi (and/or the .ps and .pdf) file, and
+
+
+
+ 18 June 2019 1
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ refreshing the previewer's display. It's not quite WYSIWYG, but use-
+ fully close.
+
+ For other previewers, the user may have to manually make the previewer
+ update its display, which can be (e.g., with some versions of xdvi and
+ gsview) as simple as forcing a redraw of its display.
+
+ Latexmk has the ability to print a banner in gray diagonally across
+ each page when making the postscript file. It can also, if needed,
+ call an external program to do other postprocessing on generated dvi
+ and postscript files. (See the options -dF and -pF, and the documenta-
+ tion for the $dvi_filter and $ps_filter configuration variables.)
+ These capabilities are leftover from older versions of latexmk, but are
+ currently non-functional. More flexibility can be obtained in current
+ versions, since the command strings for running latex, pdflatex, etc
+ can now be configured to run multiple commands. This also extends the
+ possibility of postprocessing generated files.
+
+ 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. See
+ the section "Configuration/Initialization (rc) Files", and then the
+ later sections "How to Set Variables in Initialization Files", "Format
+ of Command Specifications", "List of Configuration Variables Usable in
+ Initialization Files", "Custom Dependencies", and "Advanced Configura-
+ tion"
+
+ 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 de-
+ terminations of how many runs are needed and of which programs. La-
+ texmk 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 file (with ex-
+ tension .fdb_latexmk, by default) that contains the source file infor-
+ mation.
+
+
+LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE
+ In general the command line to invoke latexmk has the form
+
+ latexmk [options] [file]
+
+ All options can be introduced by single or double "-" characters, e.g.,
+ "latexmk -help" or "latexmk --help".
+
+ Note 1: In addition to the options in the list below, latexmk recog-
+ nizes almost all the options recognized by the latex, pdflatex programs
+
+
+
+ 18 June 2019 2
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ (and their relatives) in their current TeXLive and MiKTeX implementa-
+ tions. Some of the options for these programs also trigger special ac-
+ tion or behavior by latexmk, in which case they have specific explana-
+ tions in this document. Otherwise, they are just passed through to a
+ called latex or pdflatex program. Run latexmk with the -showextraop-
+ tions to get a list of the options that latexmk accepts and that are
+ simply passed through to latex or pdflatex (etc). See also the expla-
+ nation of the -showextraoptions option for more information.
+
+ Note 2: In this documentation, the program pdflatex is often referred
+ to. Users of programs like lualatex and xelatex should know that from
+ latexmk's point of view, these other programs behave very like pdfla-
+ tex, i.e., they make a pdf file from a tex file, etc. So whenever
+ pdflatex is mentioned without mention of the other programs, the state-
+ ments apply equally to lualatex, xelatex, and any other similar pro-
+ grams. Latexmk can be easily configured to use whichever of these pro-
+ grams is needed. See the documentation for the following options:
+ -pdflua, -pdfxe, -lualatex, and -xelatex, and also see the documenta-
+ tion for the $pdflatex, $lualatex, and $xelatex configuration vari-
+ ables. At present latexmk does not do automatic detection of which
+ program is to be used.
+
+
+ Definitions of options and arguments
+
+
+ file One or more files can be specified. If no files are specified,
+ latexmk will, by default, run on all files in the current work-
+ ing directory with a ".tex" extension. This behavior can be
+ changed: see the description concerning the @default_files vari-
+ able in the section "List of configuration variables usable in
+ initialization files".
+
+ If a file is specified without an extension, then the ".tex" ex-
+ tension is automatically added, just as LaTeX does. Thus, if
+ you specify:
+
+ latexmk foo
+
+ then latexmk will operate on the file "foo.tex".
+
+ There are certain restrictions on what characters can be in a
+ filename; certain characters are either prohibited or problem-
+ atic for the latex etc programs. These characters are: "$",
+ "%", "\", "~", the double quote character, and the control char-
+ acters null, tab, form feed, carriage return, line feed, and
+ delete. In addition "&" is prohibited when it is the first
+ character of a filename.
+
+ Latexmk gives a fatal error when it detects any of the above
+ characters in the TeX filename(s) specified on the command line.
+ However before testing for illegal characters, latexmk removes
+ matching pairs of double quotes from a filename. This matches
+ the behavior of latex etc, and deals with problems that
+
+
+
+ 18 June 2019 3
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ occasionally result from filenames that have been incorrectly
+ quoted on the command line. In addition, under Microsoft Win-
+ dows, the forward slash character "\" is a directory separator,
+ so latexmk replaces it by a backward slash "/", which is also a
+ legal directory separator in Windows, and is accepted by latex
+ etc.
+
+
+ -auxdir=FOO or -aux-directory=FOO
+ Sets the directory for auxiliary output files of (pdf)latex
+ (.aux, .log etc). This achieves its effect by the -aux-direc-
+ tory option of (pdf)latex, which currently is only implemented
+ on the MiKTeX version of (pdf)latex.
+
+ See also the -outdir/-output-directory options, and the
+ $aux_dir, $out_dir, and $search_path_separator configuration
+ variables of latexmk. In particular, see the documentation of
+ $out_dir for some complications on what directory names are
+ suitable.
+
+ If you also use the -cd option, and the specified auxiliary out-
+ put directory is a relative path, then the path is interpreted
+ relative to the document directory.
+
+
+ -bibtex
+ 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
+ variable to 2 in a configuration file.
+
+
+ -bibtex-
+ Never run bibtex or biber. Also, always treat .bbl files as
+ precious, i.e., do not delete them in a cleanup operation.
+
+ 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.
+
+ This property can also be configured by setting the $bibtex_use
+ variable to 0 in a configuration file.
+
+
+ -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
+ overwriting of the bbl file(s). Also, always treat .bbl files
+
+
+
+ 18 June 2019 4
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ as precious, i.e., do not delete them in a cleanup operation.
+
+ This is the default setting. It can also be configured by set-
+ ting the $bibtex_use variable to 1 in a configuration file.
+
+ The reason for using this setting is that sometimes a .bbl file
+ is available containing the bibliography for a document, but the
+ .bib file is not available. An example would be for a scien-
+ tific journal where authors submit .tex and .bbl files, but not
+ the original .bib file. In that case, running bibtex or biber
+ would not work, and the .bbl file should be treated as a user
+ source file, and not as a file that can be regenerated on de-
+ mand.
+
+ (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
+ kpsewhich program to do the search, and kpsewhich should use the
+ same search path as bibtex and biber. If this problem arises,
+ use the -bibtex option when invoking latexmk.)
+
+ Note that this value does not work properly if the document uses
+ biber instead of bibtex. (There's a long story why not.)
+
+
+ -bibtex-cond1
+ The same as -bibtex-cond1 except that .bbl files are only
+ treated as precious if one or more bibfiles fails to exist.
+
+ Thus if all the bib files exist, bibtex or biber is run to gen-
+ erate .bbl files as needed, and then it is appropriate to delete
+ the bbl files in a cleanup operation since they can be re-gener-
+ ated.
+
+ This property can also be configured by setting the $bibtex_use
+ variable to 1.5 in a configuration file.
+
+
+ -bm <message>
+ A banner message to print diagonally across each page when con-
+ verting the dvi file to postscript. The message must be a sin-
+ gle argument on the command line so be careful with quoting spa-
+ ces and such.
+
+ Note that if the -bm option is specified, the -ps option is as-
+ sumed.
+
+
+ -bi <intensity>
+ How dark to print the banner message. A decimal number between
+
+
+
+ 18 June 2019 5
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ 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
+ message. The default is 220.0 which is just right for 5 charac-
+ ter messages.
+
+
+ -commands
+ List the commands used by latexmk for processing files, and then
+ exit.
+
+
+ -c Clean up (remove) all regeneratable files generated by latex and
+ bibtex or biber except dvi, postscript and pdf. These files are
+ a combination of log files, aux files, latexmk's database file
+ of source file information, and those with extensions specified
+ in the @generated_exts configuration variable. In addition,
+ files specified by the $clean_ext and @generated_exts configura-
+ tion variables are removed.
+
+ This cleanup is instead of a regular make. See the -gg option
+ if you want to do a cleanup then a make.
+
+ Treatment of .bbl files: If $bibtex_use is set to 0 or 1, bbl
+ files are always treated as non-regeneratable. If $bibtex_use
+ is set to 1.5, bbl files are counted as non-regeneratable condi-
+ tionally: If the bib file exists, then bbl files are regenerat-
+ able, and are deleted in a clean up. But if $bibtex_use is 1.5
+ and a bib file doesn't exist, then the bbl files are treated as
+ non-regeneratable and hence are not deleted.
+
+ In contrast, if $bibtex_use is set to 2, bbl files are always
+ treated as regeneratable, and are deleted in a cleanup.
+
+ Treatment of files generated by custom dependencies: If
+ $cleanup_includes_cusdep_generated is nonzero, regeneratable
+ files are considered as including those generated by custom de-
+ pendencies 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 ad-
+ dition of dvi, postscript and pdf files, and those specified in
+ the $clean_full_ext configuration variable.
+
+ This cleanup is instead of a regular make. See the -gg option
+ if you want to do a cleanup than a make.
+
+
+
+ 18 June 2019 6
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ See the -c option for the specification of whether or not .bbl
+ files are treated as non-regeneratable or regeneratable.
+
+ If $cleanup_includes_cusdep_generated is nonzero, regeneratable
+ files are considered as including those generated by custom de-
+ pendencies and are also deleted. Otherwise these files are not
+ deleted.
+
+
+ -CA (Obsolete). Now equivalent to the -C option. See that option
+ for details.
+
+
+ -cd Change to the directory containing the main source file before
+ processing it. Then all the generated files (.aux, .log, .dvi,
+ .pdf, etc) will be relative to the source file.
+
+ This option is particularly useful when latexmk is invoked from
+ a GUI configured to invoke latexmk with a full pathname for the
+ source file.
+
+ This option works by setting the $do_cd configuration variable
+ to one; you can set that variable if you want to configure la-
+ texmk to have the effect of the -cd option without specifying it
+ on the command line. See the documentation for that variable.
+
+
+ -cd- Do NOT change to the directory containing the main source file
+ before processing it. Then all the generated files (.aux, .log,
+ .dvi, .pdf, etc) will be relative to the current directory
+ rather than the source file.
+
+ This is the default behavior and corresponds to the behavior of
+ the latex and pdflatex programs. However, it is not desirable
+ behavior when latexmk is invoked by a GUI configured to invoke
+ latexmk with a full pathname for the source file. See the -cd
+ option.
+
+ This option works by setting the $do_cd configuration variable
+ to zero. See the documentation for that variable for more in-
+ formation.
+
+
+ -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
+ intensity can be modified with the -bs and -bi options. The -bm
+ option will override this option as this is really just a short
+ way of specifying:
+
+ latexmk -bm DRAFT
+
+
+
+ 18 June 2019 7
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ Note that if the -d option is specified, the -ps option is as-
+ sumed.
+
+
+ -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.,
+ 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. (In fact, latexmk also has options -M, -MF,
+ and -MP options that behave like those of 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 de-
+ pendent 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:
+
+
+
+
+ 18 June 2019 8
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ latexmk -dF "dviselect even" foo.tex
+
+
+ -diagnostics
+ Print detailed diagnostics during a run. This may help for de-
+ bugging 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
+ 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
+ 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 re-
+ sults in latexmk stopping. Multiple instances of the -r and -e
+ options can be used, and they are executed in the order they ap-
+ pear 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 op-
+ tion, 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 -e "$latex=q/latex %O -shell-escape %S/" file.tex
+
+
+
+
+ 18 June 2019 9
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ or
+
+ latexmk -e "$latex='latex %O -shell-escape %S'" file.tex
+
+ The last two examples will NOT work with UNIX/Linux command
+ shells.
+
+ (Note: the above examples show are to show how to use the -e to
+ specify initialization code to be executed. But the particular
+ effect can be achieved also by the use of the -latex option with
+ less problems in dealing with quoting.)
+
+
+ -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.
+
+ Note: "Further processing" means the running of other programs
+ or the rerunning of latex (etc) that would be done if no errors
+ had occurred. If instead, or additionally, you want the latex
+ (etc) program not to pause for user input after an error, you
+ should arrange this by an option that is passed to the program,
+ e.g., by latexmk's option -interaction=nonstopmode.
+
+
+ -f- Turn off the forced processing-past-errors such as is set by the
+ -f option. This could be used to override a setting in a con-
+ figuration file.
+
+
+ -g Force latexmk to process document fully, even under situations
+ where latexmk would normally decide that no changes in the
+ source files have occurred since the previous run. This option
+ is useful, for example, if you change some options and wish to
+ reprocess the files.
+
+
+ -g- Turn off -g.
+
+
+ -gg "Super go mode" or "clean make": clean out generated files as if
+ -C had been given, and then do a regular make.
+
+
+ -h, -help
+ Print help information.
+
+
+ -jobname=STRING
+ Set the basename of output files(s) to STRING, instead of the
+ default, which is the basename of the specified TeX file. (At
+ present, STRING should not contain spaces.)
+
+
+
+
+ 18 June 2019 10
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ This is like the same option for current implementations of the
+ latex, pdflatex, etc, and the passing of this option to these
+ programs is part of latexmk's implementation of -jobname.
+
+ There is one enhancement, that the STRING may contain the place-
+ holder '%A'. This will be substituted by the basename of the TeX
+ file. The primary purpose is when multiple files are specified
+ on the command line to latexmk, and you wish to use a jobname
+ with a different file-dependent value for each file. For exam-
+ ple, suppose you had .tex files test1.tex and test2.tex, and you
+ wished to compare the results of compilation by pdflatex and
+ those with xelatex. Then under a unix-type operating system you
+ could use the command line
+
+ latexmk -pdf -jobname=%A-pdflatex *.tex
+ latexmk -pdfxe -jobname=%A-xelatex *.tex
+
+ Then the .aux, .log, and .pdf files from the use of pdflatex
+ would have basenames test1-pdflatex and test2-pdflatex, while
+ from xelatex, the basenames would be test1-xelatex and test2-xe-
+ latex.
+
+ Under MS-Windows with cmd.exe, you would need to double the per-
+ cent sign, so that the percent character is passed to latexmk
+ rather than being used to substitute an environment variable:
+
+ latexmk -pdf -jobname=%%A-pdflatex *.tex
+ latexmk -pdfxe -jobname=%%A-xelatex *.tex
+
+
+ -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 de-
+ termine this information automatically.
+
+
+ -l- Turn off -l.
+
+
+ -latex="COMMAND"
+ This sets the string specifying the command to run latex, and is
+ typically used to add desired options. Since the string nor-
+ mally contains spaces, it should be quoted, e.g.,
+
+ latexmk -latex="latex --shell-escape %O %S" foo.tex
+
+ The specification of the contents of the string are the same as
+ for the $latex configuration variable. Depending on your oper-
+ ating system and the command-line shell you are using, you may
+ need to change the single quotes to double quotes (or something
+ else).
+
+ To set the command for running pdflatex (rather than the command
+ for latex) see the -pdflatex option.
+
+
+
+ 18 June 2019 11
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ -logfilewarninglist
+ -logfilewarnings After a run of (pdf)latex, give a list of warn-
+ ings about undefined citations and references (unless silent
+ mode is on).
+
+ See also the $silence_logfile_warnings configuration variable.
+
+
+ -logfilewarninglist-
+ -logfilewarnings- After a run of (pdf)latex, do not give a list
+ of warnings about undefined citations and references. (Default)
+
+ See also the $silence_logfile_warnings configuration variable.
+
+
+ -lualatex
+ Use lualatex. That is, use lualatex to process the source
+ file(s) to pdf. The generation of dvi and postscript files is
+ turned off.
+
+ This option is equivalent to using the following set of options
+
+ -pdflua -dvi- -ps-
+
+ (Note: Note that the method of implementation of this option,
+ but not its intended effect, differ from some earlier versions
+ of latexmk.)
+
+
+ -M Show list of dependent files after processing. This is equiva-
+ lent to the -deps option.
+
+
+ -MF file
+ If a list of dependents is made, the -MF specifies the file to
+ write it to.
+
+
+ -MP If a list of dependents is made, include a phony target for each
+ source file. If you use the dependents list in a Makefile, the
+ dummy rules work around errors the program make gives if you re-
+ move header files without updating the Makefile to match.
+
+
+ -new-viewer
+ When in continuous-preview mode, always start a new viewer to
+ view the generated file. By default, latexmk will, in continu-
+ ous-preview mode, test for a previously running previewer for
+ the same file and not start a new one if a previous previewer is
+ running. However, its test sometimes fails (notably if there is
+ an already-running previewer that is viewing a file of the same
+ name as the current file, but in a different directory). This
+ option turns off the default behavior.
+
+
+
+
+ 18 June 2019 12
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ -new-viewer-
+ 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. Equivalent to the -bibtex- option.
+
+
+ -norc Turn off the automatic reading of initialization (rc) files.
+
+ N.B. Normally the initialization files are read and obeyed, and
+ then command line options are obeyed in the order they are en-
+ countered. But -norc is an exception to this rule: it is acted
+ on first, no matter where it occurs on the command line.
+
+
+ -outdir=FOO or -output-directory=FOO
+
+ Sets the directory for the output files of (pdf)latex. This
+ achieves its effect by the -output-directory option of (pdf)la-
+ tex, which currently (Dec. 2011 and later) is implemented on the
+ common versions of (pdf)latex, i.e., MiKTeX and TeXLive. It may
+ not be present in other versions.
+
+ See also the -auxdir/-aux-directory options, and the $aux_dir,
+ $out_dir, and $search_path_separator configuration variables of
+ latexmk. In particular, see the documentation of $out_dir for
+ some complications on what directory names are suitable.
+
+ If you also use the -cd option, and the specified output direc-
+ tory is a relative path, then the path is interpreted relative
+ to the document directory.
+
+
+ -p Print out the document. By default the file to be printed is
+ the first in the list postscript, pdf, dvi that is being made.
+ But you can use the -print=... option to change the type of file
+ to be printed, and you can configure this in a start up file (by
+ setting the $print_type variable).
+
+ However, printing is enabled by default only under UNIX/Linux
+ systems, where the default is to use the lpr command and only on
+ postscript files. In general, the correct behavior for printing
+ very much depends on your system's software. In particular, un-
+ der MS-Windows you must have suitable program(s) available, and
+ you must have configured 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.
+
+
+
+ 18 June 2019 13
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ -pdf Generate pdf version of document using pdflatex. (If you wish
+ to use lualatex or xelatex, you can use whichever of the options
+ -pdflua, -pdfxe, -lualatex or -xelatex applies.) To configure
+ latexmk to have such behavior by default, see the section on
+ "Configuration/initialization (rc) files".
+
+
+ -pdfdvi
+ Generate pdf version of document from the dvi file, by default
+ using dvipdf.
+
+
+ -pdflua
+ Generate pdf version of document using lualatex.
+
+
+ -pdfps Generate pdf version of document from the .ps file, by default
+ using ps2pdf.
+
+
+ -pdfxe Generate pdf version of document using xelatex. Note that to
+ optimize processing time, latexmk uses xelatex to generate an
+ .xdv file rather than a pdf file directly. Only after possibly
+ multiple runs to generate a fully up-to-date .xdv file does la-
+ texmk then call xdvipdfmx to generate the final .pdf file.
+
+ (Note: When the document includes large graphics files, espe-
+ cially .png files, the last step can be quite time consuming,
+ even when the creation of the .xdv file by xelatex is fast. So
+ the use of the intermediate .xdv file can result in substantial
+ gains in procesing time, since the .pdf file is produced once
+ rather than on every run of xelatex. See the documentation on
+ the -pdfxe option for why an .xdv file is used.
+
+
+ -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.)
+
+ If after all options have been processed, pdf generation is
+ still turned off, then generation of a dvi file will be turned
+ on, and then the program used to compiled a document will be la-
+ tex (or, more precisely, whatever program is configured to be
+ used in the $latex configuration variable).
+
+
+ -pdflatex="COMMAND"
+ This sets the string specifying the command to run pdflatex, and
+ is typically used to add desired options. Since the string nor-
+ mally contains spaces, it should be quoted, e.g.,
+
+ latexmk -pdf -pdflatex="pdflatex --shell-escape %O %S"
+ foo.tex
+
+
+
+ 18 June 2019 14
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ The specification of the contents of the string are the same as
+ for the $pdflatex configuration variable. (The option -pdflatex
+ in fact sets the variable $pdflatex.) Depending on your operat-
+ ing system and the command-line shell you are using, you may
+ need to change the single quotes to double quotes (or something
+ else).
+
+ To set the command for running latex (rather than the command
+ for pdflatex) see the -latex option.
+
+
+ -pdflualatex="COMMAND"
+ This sets the string specifying the command to run lualatex. It
+ behaves like the -pdflatex option, but sets the variable $luala-
+ tex.
+
+
+ -pdfxelatex="COMMAND"
+ This sets the string specifying the command to run xelatex. It
+ behaves like the -pdflatex option, but sets the variable $xela-
+ tex.
+
+ Warning: It is important to ensure that the -no-pdf is used when
+ xelatex is invoked; see the explanation for the variable $xela-
+ tex for why this is necessary. If you provide %O in the command
+ specification, this will be done automatically.
+
+ An example of the use of the -pdfxelatex option:
+
+ latexmk -pdfxe -pdfxelatex="xelatex --shell-escape %O %S"
+ foo.tex
+
+
+
+ -pretex=CODE
+
+ Given that CODE is some TeX code, this options sets that code to
+ be executed before inputting source file. This only works if
+ the command for invoking the relevant *latex is suitably config-
+ ured. See the documentation of the variable $pre_tex_code, and
+ the substitution strings %P and %U for more details. This op-
+ tion works by setting the variable $pre_tex_code.
+
+ See also the -usepretex option.
+
+ An example:
+
+ latexmk -pretex='\AtBeginDocument{Message\par}' -usepretex
+ foo.tex
+
+ But this is better written
+
+ latexmk -usepretex='\AtBeginDocument{Message\par}' foo.tex
+
+
+
+
+ 18 June 2019 15
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ If you already have a suitable command configured, you only need
+
+ latexmk -pretex='\AtBeginDocument{Message\par}' foo.tex
+
+
+ -print=dvi, -print=ps, -print=pdf, -print=auto,
+ Define which kind of file is printed. This option also ensures
+ that the requisite file is made, and turns on printing.
+
+ The (default) case -print=auto determines the kind of print file
+ automatically from the set of files that is being made. The
+ first in the list postscript, pdf, dvi that is among the files
+ to be made is the one used for print out.
+
+
+ -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
+ 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
+ extension ".psF". All extra processing (e.g. preview, printing)
+ will then be performed on this filtered postscript file.
+
+ Example of usage: Use psnup to print two pages on the one page:
+
+ latexmk -ps -pF 'psnup -2' foo.tex
+
+ or
+
+ latexmk -ps -pF "psnup -2" foo.tex
+
+ Whether to use single or double quotes round the "psnup -2" will
+ depend on your command interpreter, as used by the particular
+ version of perl and the operating system on your computer.
+
+
+ -pv Run file previewer. If the -view option is used, this will se-
+ lect 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
+ previewer will be used. This option is incompatible with the -p
+ and -pvc options, so it turns them off.
+
+
+ -pv- Turn off -pv.
+
+
+
+
+
+ 18 June 2019 16
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ -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 in-
+ compatible with the -p and -pv options, so it turns these op-
+ tions off.
+
+ The -pvc option also turns off force mode (-f), as is normally
+ best for continuous preview mode. If you really want force
+ mode, use the options in the order -pvc -f.
+
+ With a good previewer the display will be automatically updated.
+ (Under some but not all versions of UNIX/Linux "gv -watch" does
+ this for postscript files; this can be set by a configuration
+ variable. This would also work for pdf files except for an ap-
+ parent bug in gv that causes an error when the newly updated pdf
+ file is read.) Many other previewers will need a manual update.
+
+ Important note: the acroread program on MS-Windows locks the pdf
+ file, and prevents new versions being written, so it is a bad
+ idea to use acroread to view pdf files in preview-continuous
+ mode. It is better to use a different viewer: SumatraPDF and
+ gsview are good possibilities.
+
+ There are some other methods for arranging an update, notably
+ useful for many versions of xdvi and xpdf. These are best set
+ in latexmk's configuration; see below.
+
+ 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-
+ ning.)
+
+
+ -pvc- Turn off -pvc.
+
+
+ -pvctimeout
+ Do timeout in pvc mode after period of inactivity, which is 30
+ min. by default. Inactivity means a period when latexmk has de-
+ tected no file changes and hence has not taken any actions like
+ compiling the document.
+
+
+ -pvctimeout-
+ Don't do timeout in pvc mode after inactivity.
+
+
+
+
+
+ 18 June 2019 17
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ -pvctimeoutmins=<time>
+ Set period of inactivity in minutes for pvc timeout.
+
+
+ -quiet Same as -silent
+
+
+ -r <rcfile>
+ 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
+ with the -r option can override both the standard initialization
+ files and previously specified options. But all of these can be
+ overridden by later options.
+
+ The contents of the RC file just comprise a piece of code in the
+ Perl programming language (typically a sequence of assignment
+ statements); they are executed when the -r option is encountered
+ during latexmk's parsing of its command line. See the -e option
+ for a way of giving initialization code directly on latexmk's
+ command line. An error results in latexmk stopping. Multiple
+ instances of the -r and -e options can be used, and they are ex-
+ ecuted in the order they appear on the command line.
+
+
+ -recorder
+ Give the -recorder option with latex and pdflatex. In (most)
+ modern versions of these programs, this results in a file of ex-
+ tension .fls containing a list of the files that these programs
+ have read and written. Latexmk will then use this file to im-
+ prove its detection of source files and generated files after a
+ run of latex or pdflatex. This is the default setting of la-
+ texmk, unless overridden in an initialization file.
+
+ For further information, see the documentation for the $recorder
+ configuration variable.
+
+
+ -recorder-
+ Do not supply 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.)
+
+
+
+ 18 June 2019 18
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ -showextraoptions
+ Show the list of extra latex and pdflatex options that latexmk
+ recognizes, but that it simply passes through to the programs
+ latex, pdflatex, etc when they are run. These options are
+ (currently) a combination of those allowed by the TeXLive and
+ MiKTeX implementations. (If a particular option is given to la-
+ texmk but is not handled by the particular implementation of la-
+ tex or pdflatex that is being used, that program will probably
+ give an error message.) These options are very numerous, but
+ are not listed in this documentation because they have no effect
+ on latexmk's actions.
+
+ There are a few options (-includedirectory=dir, -initialize,
+ -ini) that are not recognized, either because they don't fit
+ with latexmk's intended operations, or because they need special
+ processing by latexmk that isn't implemented (at least, not
+ yet).
+
+ There are also options that are accepted by latex etc, but in-
+ stead trigger actions by latexmk: -help, -version.
+
+ Finally, there are certain options for latex and pdflatex (e.g.,
+ -recorder) that trigger special actions or behavior by latexmk
+ itself as well as being passed in some form to the called latex
+ and pdflatex program, or that affect other programs as well.
+ These options do have entries in this documentation. These op-
+ tions are: -jobname=STRING, -aux-directory=dir, -output-direc-
+ tory=DIR, -quiet, and -recorder.
+
+
+ -silent
+ Run commands silently, i.e., with options that reduce the amount
+ of diagnostics generated. For example, with the default set-
+ tings, the command "latex -interaction=batchmode" is used for
+ latex, and similarly for its friends.
+
+ See also the -logfilewarninglist and -logfilewarninglist- op-
+ tions.
+
+ Also reduce the number of informational messages that latexmk
+ itself generates.
+
+ To change the options used to make the commands run silently,
+ you need to configure latexmk with changed values of its config-
+ uration variables, the relevant ones being $bib-
+ tex_silent_switch, $biber_silent_switch, $dvipdf_silent_switch,
+ $dvips_silent_switch, $latex_silent_switch, $luala-
+ tex_silent_switch $makeindex_silent_switch, $pdfla-
+ tex_silent_switch, and $xelatex_silent_switch
+
+
+ -stdtexcmds
+ Sets the commands for latex, etc, so that they are the standard
+ ones. This is useful to override special configurations.
+
+
+
+ 18 June 2019 19
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ The result is that $latex = 'latex %O %S', and similarly for
+ $pdflatex, $lualatex, and $xelatex. (The option -no-pdf needed
+ for $xelatex is provided automatically, given that %O appears in
+ the definition.)
+
+
+ -time Show CPU time used. See also the configuration variable
+ $show_time.
+
+
+ -time- Do not show CPU time used. See also the configuration variable
+ $show_time.
+
+
+ -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 commands), latexmk tries to make them by a
+ custom dependency. If no relevant custom dependency with an ap-
+ propriate source file is found, and if the -use-make option is
+ set, then as a last resort latexmk will try to use the make pro-
+ gram 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
+ 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. (De-
+ fault.)
+
+
+ -usepretex
+ Sets the command lines for latex, etc, so that they use the code
+ that is defined by the variable $pre_tex_code or that is set by
+ the option -pretex=CODE to execute the specified TeX code before
+ the source file is read. This option overrides any previous
+ definition of the command lines.
+
+ The result is that $latex = 'latex %O %P', and similarly for
+ $pdflatex, $lualatex, and $xelatex. (The option -no-pdf needed
+ for $xelatex is provided automatically, given that %O appears in
+ the definition.)
+
+
+ -usepretex=CODE
+ Equivalent to -pretex=CODE -usepretex. Example
+
+
+
+
+ 18 June 2019 20
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ latexmk -usepretex='\AtBeginDocument{Message\par}' foo.tex
+
+
+ -v, -version
+ Print version number of latexmk.
+
+
+ -verbose
+ Opposite of -silent. This is the default setting.
+
+
+ -view=default, -view=dvi, -view=ps, -view=pdf, -view=none
+ Set the kind of file used when previewing is requested (e.g., by
+ the -pv or -pvc switches). The default is to view the "highest"
+ kind of requested file (in the low-to-high order .dvi, .ps,
+ .pdf).
+
+ Note the possibility -view=none where no viewer is opened at
+ all. One example of is use is in conjunction with the -pvc op-
+ tion, when you want latexmk to do a compilation automatically
+ whenever source file(s) change, but do not want a previewer to
+ be opened.
+
+
+ -Werror
+ This causes latexmk to return a non-zero status code if any of
+ the files processed gives a warning about problems with cita-
+ tions or references (i.e., undefined citations or references or
+ about multiply defined references). This is after latexmk has
+ completed all the runs it needs to try and resolve references
+ and citations. Thus -Werror causes latexmk to treat such warn-
+ ings as errors, but only when they occur on the last run of
+ (pdf)latex and only after processing is complete. Also can be
+ set by the configuration variable $warnings_as_errors.
+
+
+ -xelatex
+ Use xelatex. That is, use xelatex to process the source file(s)
+ to pdf. The generation of dvi and postscript files is turned
+ off.
+
+ This option is equivalent to using the following set of options
+
+ -pdfxe -dvi- -ps-
+
+ [Note: Note that the method of implementation of this option,
+ but not its intended primary effect, differ from some earlier
+ versions of latexmk. Latexmk first uses xelatex to make an .xdv
+ file, and does all the extra runs needed (including those of
+ bibtex, etc). Only after that does it make the pdf file from
+ the .xdv file, using xdvipdfmx. This procedure can result in
+ considerable savings in run time, since the xdv-to-pdf conver-
+ sion is quite time-consuming when large graphics files are used
+ in the document.]
+
+
+
+ 18 June 2019 21
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ Compatibility between options
+
+ 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 op-
+ tions turns the others off.
+
+
+EXAMPLES
+ % latexmk thesis # run latex enough times to resolve
+ cross-references
+
+ % latexmk -pvc -ps thesis# run latex enough times to resolve
+ cross-references, make a postscript
+ file, start a previewer. Then
+ watch for changes in the source
+ file thesis.tex and any files it
+ uses. After any changes rerun latex
+ the appropriate number of times and
+ remake the postscript file. If latex
+ encounters an error, latexmk will
+ keep running, watching for
+ source file changes.
+
+ % latexmk -c # remove .aux, .log, .bbl, .blg, .dvi,
+ .pdf, .ps & .bbl files
+
+
+
+DEALING WITH ERRORS, PROBLEMS, ETC
+ Some possibilities:
+
+ a. If you get a strange error, do look carefully at the output that is
+ on the screen and in log files. While there is much that is notori-
+ ously verbose in the output of latex (and that is added to by latexmk),
+ the verbosity is there for a reason: to enable the user to diagnose
+ problems. Latexmk does repeat some messages at the end of a run that
+ it thinks would otherwise be easy to miss in the middle of other out-
+ put.
+
+ b. Generally, remember that latexmk does its work by running other pro-
+ grams. Your first priority in dealing with errors should be to examine
+ what went wrong with the individual programs. Then you need to correct
+ the causes of errors in the runs of these programs. (Often these come
+ from errors in the source document, but they could also be about miss-
+ ing LaTeX packages, etc.)
+
+ c. If latexmk doesn't run the programs the way you would like, then you
+ need to look in this documentation at the list of command line options
+ and then at the sections on configuration/initialization files. A lot
+ of latexmk's behavior is configurable to deal with particular situa-
+ tions. (But there is a lot of reading!)
+
+
+
+ 18 June 2019 22
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ The remainder of these notes consists of ideas for dealing with more
+ difficult situations.
+
+ d. Further tricks can involve replacing the standard commands that la-
+ texmk runs by other commands or scripts.
+
+ e. For possible examples of code for use in an RC file, see the direc-
+ tory example_rcfiles in the distribution of latexmk (e.g., at
+ http://mirror.ctan.org/support/latexmk/example_rcfiles). Even if these
+ examples don't do what you want, they may provide suitable inspiration.
+
+ f. There's a useful trick that can be used when you use lualatex in-
+ stead of pdflatex (and in some related situations). The problem is
+ that latexmk won't notice a dependency on a file, bar.baz say, that is
+ input by the lua code in your document instead of by the LaTeX part.
+ (Thus if you change bar.baz and rerun latexmk, then latexmk will think
+ no files have changed and not rerun lualatex, whereas if you had '\in-
+ put{bar.baz}' in the LaTeX part of the document, latexmk would notice
+ the change.) One solution is just to put the following somewhere in
+ the LaTeX part of the document:
+
+ \typeout{(bar.baz)}
+
+ This puts a line in the log file that latexmk will treat as implying
+ that the file bar.baz was read. (At present I don't know a way of do-
+ ing this automatically.) Of course, if the file has a different name,
+ change bar.baz to the name of your file.
+
+ g. See also the section "Advanced Configuration: Some extra resources".
+
+ h. Look on tex.stackexchange, i.e., at http://tex.stackex-
+ change.com/questions/tagged/latexmk Someone may have already solved
+ your problem.
+
+ i. Ask a question at tex.stackexchange.com.
+
+ j. Or ask me (the author of latexmk). My e-mail is at the end of this
+ documentation.
+
+
+
+ALLOWING FOR CHANGE OF OUTPUT FILE TYPE
+ When one of the latex engines is run, the usual situation is that latex
+ produces a .dvi file, while pdflatex and lualatex produce a .pdf file.
+ For xelatex the default is to produce a .pdf file, but to optimize pro-
+ cessing time latexmk runs xelatex its -no-pdf option so that it pro-
+ duces an .xdv file. Further processing by latexmk takes this as a
+ starting point.
+
+ However, the actual output file may differ from the normal expectation;
+ and then latexmk can adjust its processing to accommodate this situa-
+ tion. The difference in output file type can happen for two reasons:
+ One is that for latex, pdflatex and lualatex the document itself can
+ override the defaults. The other is that there may be a configuration,
+
+
+
+ 18 June 2019 23
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ or misconfiguration, such that the program that latexmk invokes to com-
+ pile the document is not the expected one, or is given options incom-
+ patible with what latexmk initially expects. (E.g., the -output-for-
+ mat=... option could be used with lualatex, or xelatex gets invoked
+ without the -no-pdf option.)
+
+ Under latex and pdflatex, control of the output format by the document
+ is done by setting the \pdfoutput macro. Under lualatex, the \output-
+ mode macro is used instead.
+
+ One example of an important use-case for document control of the output
+ format is a document that uses the psfrag package to insert graphical
+ elements in the output file. The psfrag package achieves its effects by
+ inserting postscript code in the output of the compilation of the docu-
+ ment. This entails the use of compilation to a .dvi file, followed by
+ the use of conversion to a postscript file (either directly, as by
+ dvips or implicitly, as an intermediate step by dvipdf). Then it is
+ useful to force output to be of the .dvi format by inserting \pdfout-
+ put=0 in the preamble of the document.
+
+ Another example is where the document uses graphics file of the .pdf,
+ .jpg, and png types. With the default setting for the graphicx pack-
+ age, these can be processed in compilation to .pdf but not with compi-
+ lation to .dvi. In this case, it is useful to insert \pdfoutput=1 in
+ the preamble of the document to force compilation to .pdf output for-
+ mat.
+
+ In all of these cases, it is needed that latexmk has to adjust its pro-
+ cessing to deal with a mismatch between the actual output format (out
+ of .pdf, .dvi, .xdv) and the initially expected output, if possible.
+ Latexmk does this provided the following conditions are met.
+
+ The first is that latexmk's $allow_switch configuration variable is set
+ to a non-zero value as it is by default. If this variable is zero, a
+ mismatch of filetypes in the compilation results in an erro.
+
+ The second condition for latexmk to be able to handle a change of out-
+ put type is that no explicit requests for .dvi or .ps output files are
+ made. Explicit requests are by the -dvi and -ps, -print=dvi,
+ -print=ps, -view=dvi, and -view=ps options, and by corresponding set-
+ tings of the $dvi_mode, $postscript_mode, $print_type, and $view con-
+ figuration variables. The print-type and view-type restrictions only
+ apply when printing and viewing are explicitly requested, respectively.
+ For this purpose, the use of the -pdfdvi and -pdfps options (and the
+ corresponding setting of the $pdf_mode variable) does not count as an
+ explicit request for the .dvi and .ps files; they are merely regarded
+ as a request for making a .pdf file together with an initial proposal
+ for the processing route to make it.
+
+ Note that when accommodating a change in output file type, there is in-
+ volved a substantial change in the network of rules that latexmk uses
+ in its actions. The second condition applied to accommodate a change
+ is to avoid situations where the change in the rule network is too rad-
+ ical to be readily handled automatically.
+
+
+
+ 18 June 2019 24
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+CONFIGURATION/INITIALIZATION (RC) FILES
+ In this section is explained which configuration files are read by la-
+ texmk. Subsequent sections "How to Set Variables in Initialization
+ Files", "Format of Command Specifications", "List of Configuration
+ Variables Usable in Initialization Files", "Custom Dependencies", and
+ "Advanced Configuration" give details on what can be configured and
+ how.
+
+ Latexmk can be customized using initialization files, which are read at
+ startup in the following order:
+
+ 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 the first it finds of
+ "/cygdrive/c/latexmk/LatexMk",
+ "/opt/local/share/latexmk/LatexMk",
+ "/usr/local/share/latexmk/LatexMk",
+ "/usr/local/lib/latexmk/LatexMk".
+
+ In addition, it then tries the same set of locations, but with the file
+ name replaced "LatexMk" replaced by "latexmkrc".
+
+ If the environment variable LATEXMKRCSYS is set, its value is used as
+ the name of the system RC file, instead of any of the above.
+
+ 2) The user's RC file, if it exists. This can be in one of two places.
+ The traditional one is ".latexmkrc" in the user's home directory. The
+ other possibility is "latexmk/latexmkrc" in the user's XDG configura-
+ tion home directory. The actual file read is the first of "$XDG_CON-
+ FIG_HOME/latexmk/latexmkrc" or "$HOME/.latexmkrc" which exists. (See
+ https://specifications.freedesktop.org/basedir-spec/basedir-spec-lat-
+ est.html for details on the XDG Base Directory Specification.)
+
+ Here $HOME is the user's home directory. [Latexmk determines the
+ user's home directory as follows: It is the value of the environment
+ variable HOME, if this variable exists, which normally is the case on
+ UNIX-like systems (including Linux and OS-X). Otherwise the environ-
+ ment variable USERPROFILE is used, if it exists, which normally is the
+ case on MS-Windows systems. Otherwise a blank string is used instead of
+ $HOME, in which case latexmk does not look for an RC file in it.]
+
+ $XDG_CONFIG_HOME is the value of the environment variable XDG_CON-
+ FIG_HOME if it exists. If this environment variable does not exist,
+ but $HOME is non-blank, then $XDG_CONFIG_HOME is set to the default
+ value of $HOME/.config. Otherwise $XDG_CONFIG_HOME is blank, and la-
+ texmk does not look for an RC file under it.
+
+
+
+
+
+ 18 June 2019 25
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ 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 se-
+ quence of assignment statements that override some of the built-in set-
+ tings of Latexmk. Straightforward cases can be handled without knowl-
+ edge of the Perl language by using the examples in this document as
+ templates. Comment lines are introduced by the "#" character.
+
+ Note that command line options are obeyed in the order in which they
+ are written; thus any RC file specified on the command line with the -r
+ option can override previous options but can be itself overridden by
+ later options on the command line. There is also the -e option, which
+ allows initialization code to be specified in latexmk's command line.
+
+ For possible examples of code for in an RC file, see the directory ex-
+ ample_rcfiles in the distribution of latexmk (e.g., at http://mir-
+ ror.ctan.org/support/latexmk/example_rcfiles).
+
+
+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
+ files". (See the earlier section "Configuration/Initialization (rc)
+ Files" for the files where the configurations are done.) Syntax for
+ setting these variables is of the following forms:
+
+ $bibtex = 'bibtex %O %B';
+
+ for the setting of a string variable,
+
+ $preview_mode = 1;
+
+ for the setting of a numeric variable, and
+
+ @default_files = ('paper', 'paper1');
+
+ for the setting of an array of strings. It is possible to append an
+ item to an array variable as follows:
+
+ 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
+
+
+
+ 18 June 2019 26
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ these complications.)
+
+ 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 view a postscript file. This section describes some important fea-
+ tures of how the commands are specified. (Note that some of the possi-
+ bilities listed here do not apply to the $kpsewhich variable; see its
+ documentation.)
+
+ 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
+ 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 in the invoca-
+ tion of latexmk, it results in the replacement of %O by "-interac-
+ tion=batchmode".)
+
+ The available placeholders are:
+
+ %A basename of the main tex file. Unlike %R, this is unaffected by
+ the setting of a jobname by the -jobname option or the $jobname
+ configuration value.
+
+ %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
+ converting a dvi file to postscript).
+
+ %O options
+
+ %P If the variable $pre_tex_code is non-empty, then %P is substi-
+ tuted by the contents of $pre_tex_code followed by \in-
+ put{SOURCE}, where SOURCE stands for the name of the source
+ file. Appropriate quoting is done. This enables TeX code to be
+ passed to one of the *latex engines to be executed before the
+ source file is read.
+
+ If the variable $pre_tex_code is the empty string, then %P is
+
+
+
+ 18 June 2019 27
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ equivalent to %S.
+
+ %R root filename. This is the base name for the main tex file.
+
+ By default this is the basename of the main tex file. However
+ the value can be changed by the use of the -jobname option or
+ the $jobname configuration variable.
+
+ %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.
+
+ %U If the variable $pre_tex_code is non-empty, then its value is
+ substituted for %U (appropriately quoted). Otherwise it is re-
+ placed by a null string.
+
+ %Y Name of directory for auxiliary output files (see the configura-
+ tion variable $aux_dir). A directory separation character ('/')
+ is appended if $aux_dir is non-empty and does not end in a suit-
+ able character, with suitable characters being those appropriate
+ to UNIX and MS-Windows, i.e., ':', '/' and '\'. Note that if
+ after initialization, $out_dir is set, but $aux_dir is not set
+ (i.e., it is blank), then latexmk sets $aux_dir to the same
+ value $out_dir.
+
+ %Z Name of directory for output files (see the configuration vari-
+ able $out_dir). A directory separation character ('/') is ap-
+ pended if $out_dir is non-empty and does not end in a suitable
+ character, with suitable characters being those appropriate to
+ UNIX and MS-Windows, i.e., ':', '/' and '\'.
+
+ If for some reason you need a literal % character in your string not
+ subject to the above rules, use "%%".
+
+ Appropriate quoting will be applied to the filename substitutions, so
+ you mustn't supply them yourself even if the names of your files have
+ spaces in them. (But if your TeX filenames have spaces in them, beware
+ that some older 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
+ basename of a bibtex run is the same as for the texfile. But in a doc-
+ ument with several bibliographies, the bibliography files will have a
+ variety of names. Since bibtex is invoked with the basename of the
+ bibliography file, the setting for the bibtex command should therefore
+ be
+
+ $bibtex = 'bibtex %O %B';
+
+ Generally, you should use %B rather than %R. Similarly for most
+
+
+
+ 18 June 2019 28
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ purposes, the name %T of the primary texfile is not a useful place-
+ holder.
+
+ See the default values in the section "List of configuration variables
+ usable in initialization files" for what is normally the most appropri-
+ 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
+ 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
+ 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 re-
+ turns to its next task (or exits if there is nothing else to do). To
+ achieve this effect of detaching a command, you need to precede the
+ command name with "start ", as in
+
+ $dvi_previewer = 'start xdvi %O %S';
+
+ This will be translated to whatever is appropriate for your operating
+ system.
+
+ Notes: (1) In some circumstances, latexmk will always run a command de-
+ tached. 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.
+
+ 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 en-
+ closed in double quotes, as in
+
+ $lpr_pdf = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p
+ %S';
+ $pdf_previewer = 'start "c:/Program Files/SumatraPDF/Suma-
+ traPDF.exe" %O %S';
+ $pdf_previewer = 'start "c:/Program Files/SumatraPDF (x86)/Suma-
+ traPDF.exe" %O %S';
+
+
+ (Note about the above example: Under MS-Windows forward slashes are
+ equivalent to backslashes in a filename under almost all circumstances,
+ 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 language.)
+
+
+
+ 18 June 2019 29
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ Command names under Cygwin: If latexmk is executed by Cygwin's Perl,
+ be particularly certain that pathnames in commands have forward slashes
+ not the usual backslashes for the separator of pathname components.
+ See the above examples. Backslashes often get misinterpreted by the
+ Unix shell used by Cygwin's Perl to execute external commands. Forward
+ slashes don't suffer from this problem, and (when quoted, as above) are
+ equally acceptable to MS-Windows.
+
+ 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 MS-Windows, this will cause to be run whatever program the system
+ has associated with dvi files. (The same applies for a postscript
+ viewer and a pdf viewer.) But note that this trick is not always suit-
+ able for the pdf previwer, if your system has acroread for the default
+ pdf viewer. As explained elsewhere, acroread under MS-Windows does not
+ work well with latex and latexmk, because acroread locks the pdf file.
+
+ Not using a certain command: If a command is not to be run, the command
+ name NONE is used, as in
+
+ $lpr = 'NONE lpr';
+
+ 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
+ file:
+
+ $latex = 'latex --src-specials %O %S';
+
+ Running a subroutine instead of an external command: Use a specifica-
+ tion starting with "internal", as in
+
+ $latex = 'internal mylatex %O %S';
+ sub mylatex {
+ my @args = @_;
+ # Possible preprocessing here
+ return system 'latex', @args;
+ }
+
+ For some of the more exotic possibilities that then become available,
+ see the section "ADVANCED CONFIGURATION: Some extra resources and ad-
+ vanced tricks". Also see some of the examples in the directory exam-
+ ple_rcfiles in the latexmk distribution.
+
+ Advanced tricks: Normally one specifies a single command for the com-
+ mands invoked by latexmk. Naturally, if there is some complicated
+
+
+
+ 18 June 2019 30
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ 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.
+
+ You can also use a Perl subroutine instead of a script -- see above.
+ This is generally the most flexible and portable solution.
+
+ 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 ex-
+ tra processing, you could do something like:
+
+ $pdflatex = 'pdflatex --shell-escape %O %S; pst2pdf_for_latexmk
+ %B';
+
+ This definition assumes you are using a UNIX-like system (which in-
+ cludes Linux and OS-X), so that the two commands to be run are sepa-
+ rated by the semicolon in the middle of the string.
+
+ If you are using MS-Windows, you would replace the above line by
+
+ $pdflatex = 'cmd /c pdflatex --shell-escape %O %S'
+ . '&& pst2pdf_for_latexmk %B';
+
+ Here, the UNIX command separator ; is replaced by &&. In addition,
+ there is a problem that some versions of Perl on MS-Windows do not obey
+ the command separator; this problem is overcome by explicitly invoking
+ the MS-Windows command-line processor cmd.exe.
+
+
+LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES
+ In this section are specified the variables whose values can be ad-
+ justed to configure latexmk. (See the earlier section "Configura-
+ tion/Initialization (rc) Files" for the files where the configurations
+ are done.)
+
+ Default values are indicated in brackets. Note that for variables that
+ are boolean in character, concerning whether latexmk does or does not
+ behave in a certain way, a non-zero value, normally 1, indicates true,
+ i.e., the behavior occurs, while a zero value indicates a false value,
+ i.e., the behavior does not occur.
+
+
+ $allow_switch [1]
+
+ This controls what happens when the output extension of latex,
+ pdflatex, lualatex or xelatex differs from what is expected.
+ (The possible extensions are .dvi, .pdf, .xdv.) This can happen
+ with the use of the \pdfoutput macro in a document compiled un-
+ der latex or pdflatex, or with the use of the \outputmode macro
+ under lualatex. It can also happen with certain kinds of incor-
+ rect configuration.
+
+ In such a case, latexmk can appropriately adjust its network of
+
+
+
+ 18 June 2019 31
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ rules. The adjustment is made if $allow_switch is on, and if no
+ request for a dvi or ps file has been made.
+
+ See the section ALLOWING FOR CHANGE OF OUTPUT EXTENSION.
+
+
+ $always_view_file_via_temporary [0]
+ Whether .ps and .pdf files are initially to be made in a tempo-
+ rary directory and then moved to the final location. (This ap-
+ plies to dvips, dvipdf, and ps2pdf operations, and the filtering
+ operators on .dvi and .ps files. It does not apply to pdflatex,
+ unfortunately, since pdflatex provides no way of specifying a
+ chosen name for the output file.)
+
+ This use of a temporary file solves a problem that the making of
+ these files can occupy a substantial time. If a viewer (notably
+ gv) sees that the file has changed, it may read the new file be-
+ fore the program writing the file has not yet finished its work,
+ which can cause havoc.
+
+ See the $pvc_view_file_via_temporary variable for a setting that
+ applies only if preview-continuous mode (-pvc option) is used.
+ See $tmpdir for the setting of the directory where the temporary
+ file is created.
+
+
+ $analyze_input_log_always [1]
+
+ After a run of latex (etc), always analyze .log for input files
+ in the <...> and (...) constructions. Otherwise, only do the
+ analysis when fls file doesn't exist or is out of date.
+
+ Under normal circumstances, the data in the fls file is reli-
+ able, and the test of the log file gets lots of false positives;
+ usually $analyze_input_log_always is best set to zero. But the
+ test of the log file is needed at least in the following situa-
+ tion: When a user needs to persuade latexmk that a certain file
+ is a source file, and latexmk doesn't otherwise find it. Then
+ the user can write code that causes a line with (...) to be
+ written to log file. One important case is for lualatex, which
+ doesn't always generate lines in the .fls file for input lua
+ files. (The situation with lualatex is HIGHLY version depen-
+ dent, e.g., there was a big change between TeXLive 2016 and
+ TeXLive 2017.)
+
+ To keep backward compatibility with older versions of latexmk,
+ the default is to set $analyze_input_log_always to 1.
+
+
+ $auto_rc_use [1]
+ Whether to automatically read the standard initialization (rc)
+ files, which are the system RC file, the user's RC file, and the
+ RC file in the current directory. The command line option -norc
+ can be used to turn this setting off. Each RC file could also
+
+
+
+ 18 June 2019 32
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ turn this setting off, i.e., it could set $auto_rc_use to zero
+ to prevent automatic reading of the later RC files.
+
+ This variable does not affect the reading of RC files specified
+ on the command line by the -r option.
+
+ $aux_dir [""]
+ The directory in which auxiliary files (aux, log, etc) are to be
+ written by a run of (pdf)latex. If this variable is not set,
+ but $out_dir is set, then $aux_dir is set to $out_dir, which is
+ the directory to which general output files are to be written.
+
+ Important note: The effect of $aux_dir, if different from
+ $out_dir, is achieved by giving (pdf)latex the -aux-directory.
+ Currently (Dec. 2011 and later) this only works on the MiKTeX
+ version of (pdf)latex.
+
+ See also the documentation of $out_dir for some complications on
+ what directory names are suitable.
+
+ If you also use the -cd option, and $out_dir (or $aux_dir) con-
+ tains a relative path, then the path is interpreted relative to
+ the document directory.
+
+ $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
+ -d option.
+
+ Note that if $banner is nonzero, the $postscript_mode is assumed
+ and the postscript file is always generated, even if it is newer
+ than the dvi file.
+
+ $banner_intensity [0.95]
+ Equivalent to the -bi option, this is a decimal number between 0
+ and 1 that specifies how dark to print the banner message. 0 is
+ black, 1 is white. The default is just right if your toner car-
+ tridge isn't running too low.
+
+ $banner_message ["DRAFT"]
+ The banner message to print across each page when converting the
+ dvi file to postscript. This is equivalent to the -bm option.
+
+ $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
+
+
+
+ 18 June 2019 33
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ directories where latexmk should look for .bib files. By de-
+ fault 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:
+
+ @BIBINPUTS = ( ".", "C:\\bibfiles" );
+ @BIBINPUTS = ( ".", "\\server\bibfiles" );
+ @BIBINPUTS = ( ".", "C:/bibfiles" );
+ @BIBINPUTS = ( ".", "//server/bibfiles" );
+ @BIBINPUTS = ( ".", "/usr/local/texmf/bibtex/bib" );
+
+ Note that under MS Windows, either a forward slash "/" or a
+ backward slash "\" 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 cur-
+ rent version of latexmk, since it has a better method of search-
+ ing 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 @BIBINPUTS.
+
+ $biber ["biber %O %S"]
+ The biber processing program.
+
+ $biber_silent_switch ["--onlylog"]
+ Switch(es) for the biber processing program when silent mode is
+ on.
+
+ $bibtex ["bibtex %O %S"]
+ The BibTeX processing program.
+
+ $bibtex_fudge [1]
+ When using bibtex, whether to take special action to allow bib-
+ tex to work when $out_dir or $aux_dir is specified. In May
+ 2018, there was planned an update to bibtex to correct a bug,
+ after that update, the special action will no longer be re-
+ quired.
+
+ $bibtex_silent_switch ["-terse"]
+ Switch(es) for the BibTeX processing program when silent mode is
+ on.
+
+ $bibtex_use [1]
+ Under what conditions to run bibtex or biber. When latexmk dis-
+ 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
+
+
+
+ 18 June 2019 34
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ use of bibtex or biber will result in incorrect overwriting of
+ the precious bbl files. The variable $bibtex_use controls
+ whether this happens, and also controls whether or not .bbl
+ files are deleted in a cleanup operation.
+
+ The possible values of $bibtex_use are:
+ 0: never use BibTeX or biber; never delete .bbl files in a
+ cleanup.
+ 1: only use bibtex or biber if the bib files exist; never
+ delete .bbl files in a cleanup.
+ 1.5: only use bibtex or biber if the bib files exist; condi-
+ tionally delete .bbl files in a cleanup (i.e., delete them only
+ when the bib files all exist).
+ 2: run bibtex or biber whenever it appears necessary to update
+ the bbl files, without testing for the existence of the bib
+ files; always delete .bbl files in a cleanup.
+
+ Note that the value 1.5 does not work properly if the document
+ uses biber instead of bibtex. (There's a long story why not.)
+
+
+ $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 the fls file (or failing that, in log file) as being
+ generated. It will also include files made from these first
+ generation generated files.
+
+ This operation is somewhat dangerous, and can have unintended
+ consequences, since the files to be deleted are determined from
+ a file created by (pdf)latex, which can contain erroneous infor-
+ mation. Therefore this variable is turned off by default, and
+ then files to be deleted are restricted to those explictly spec-
+ ified by patterns configured in the variables clean_ext,
+ clean_full_ext, and @generated_exts, together with those very
+ standard cases that are hardwired into latexmk (e.g., .log
+ 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 ex-
+ cept for dep and aux files. (There is also extra cleaning as
+ specified by the $clean_ext, $clean_full_ext and @generated_exts
+ variables.)
+
+ 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.
+
+
+
+
+ 18 June 2019 35
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ $clean_ext [""]
+ Extra extensions of files for latexmk to remove when any of the
+ clean-up options (-c or -C) is selected. The value of this
+ variable is a string containing the extensions separated by spa-
+ ces.
+
+ It is also possible to specify a more general pattern of file to
+ be deleted, by using the place holder %R, as in commands, and it
+ is also possible to use wildcards. Thus setting
+
+ $clean_ext = "out %R-blx.bib %R-figures*.log pythontex-
+ files-%R/*";
+
+ in an initialization file will imply that when a clean-up opera-
+ tion is specified, not only is the standard set of files
+ deleted, but also files of the form FOO.out, FOO-blx.bib, %R-
+ figures*.log, and pythontex-files-FOO/*, where FOO stands for
+ the basename of the file being processed (as in FOO.tex).
+
+ The files to be deleted are relative to the directory specified
+ by $aux_dir. (Note that if $out_dir but not $aux_dir is set,
+ then in its initialization, latexmk sets $aux_dir equal to
+ $out_dir. A normal situation is therefore that $aux_dir equals
+ $out_dir, which is the only case supported by TeXLive, unlike
+ MiKTeX.)
+
+ The filenames specfied for a clean-up operation can refer not
+ only to regular files but also to directories. Directories are
+ only deleted if they are empty. An example of an application is
+ to pythontex, which creates files in a particular directory.
+ You can arrange to remove both the files and the directory by
+ setting
+
+ $clean_ext = "pythontex-files-%R pythontex-files-%R";
+
+ See also the variable @generated_exts.
+
+ $clean_full_ext [""]
+ Extra extensions of files for latexmk to remove when the -C op-
+ tion is selected, i.e., extensions of files to remove when the
+ .dvi, etc files are to be cleaned-up.
+
+ More general patterns are allowed, as for $clean_ext.
+
+ The files specified by $clean_full_ext to be deleted are rela-
+ tive to the directory specified by $out_dir.
+
+
+ $compiling_cmd [""], $failure_cmd [""], $warning_cmd [""], $success_cmd
+ [""]
+
+ These variables specify commands that are executed at certain
+ points of compilations during preview-continuous mode. One mo-
+ tivation for their existance is to allow very useful convenient
+
+
+
+ 18 June 2019 36
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ visual indications of compilation status even when the window
+ receiving the screen output of the compilation is hidden.
+
+ The commands are executed at the following points: $compil-
+ ing_cmd at the start of compilation, $success_cmd at the end of
+ a completely successful compilation, $failure_cmd at the end of
+ an unsuccessful compilation, $warning_cmd at the of an otherwise
+ successful compilation that gives warnings about undefined cita-
+ tions or references or about multiply defined references. If any
+ of above variables is undefined or blank (the default situa-
+ tion), then the corresponding command is not executed.
+
+ However, when $warning_cmd is not set, then in the case of a
+ compilation with warnings about references or citations, but
+ with no other error, one or other of $success_cmd or $fail-
+ ure_cmd is used (if it is set) according to the setting of
+ $warnings_as_errors.
+
+ An example of a simple setting of these variables is as follows
+
+ $compiling_cmd = "xdotool search --name \"%D\" set_window
+ --name \"%D compiling\"";
+ $success_cmd = "xdotool search --name \"%D\" set_window
+ --name \"%D OK\"";
+ $warning_cmd = "xdotool search --name \"%D\" ".
+ "set_window --name \"%D CITE/REF ISSUE\"";
+ $failure_cmd = "xdotool search --name \"%D\" set_window
+ --name \"%D FAILURE\"";
+
+ These assume that the program xdotool is installed, that the
+ previewer is using an X-Window system for display, and that the
+ title of the window contains the name of the displayed file, as
+ it normally does. When the commands are executed, the place-
+ holder string %D is replaced by the name of the destination
+ file, which is the previewed file. The above commands result in
+ an appropriate string being appended to the filename in the win-
+ dow title: " compiling", " OK", or " FAILURE".
+
+ Other placeholders that can be used are %S, %T, and %R, with %S
+ and %T normally being identical. These can be useful for a com-
+ mand changing the title of the edit window. The visual indica-
+ tion in a window title can useful, since the user does not have
+ to keep shifting attention to the (possibly hidden) compilation
+ window to know the status of the compilation.
+
+ More complicated situations can best be handled by defining a
+ Perl subroutine to invoke the necessary commands, and using the
+ "internal" keyword in the definitions to get the subroutine to
+ be invoked. (See the section "Format of Command Specifications"
+ for how to do this.)
+
+ Naturally, the above settings that invoke the xdotool program
+ are only applicable when the X-Window system is used for the
+ relevant window(s). For other cases, you will have to find what
+
+
+
+ 18 June 2019 37
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ software solutions are available.
+
+
+ @cus_dep_list [()]
+ Custom dependency list -- see section on "Custom Dependencies".
+
+ @default_excluded_files [()]
+ When latexmk is invoked with no files specified on the command
+ line, then, by default, it will process all files in the current
+ directory with the extension .tex. (In general, it will process
+ the files specified in the @default_files variable.)
+
+ But sometimes you want to exclude particular files from this de-
+ fault list. In that case you can specify the excluded files in
+ the array @default_excluded_files. For example if you wanted to
+ process all .tex files with the exception of common.tex, which
+ is a not a standard alone LaTeX file but a file input by some or
+ all of the others, you could do
+
+ @default_files = ("*.tex");
+
+ @default_excluded_files = ("common.tex");
+
+ If you have a variable or large number of files to be processed,
+ this method saves you from having to list them in detail in @de-
+ fault_files and having to update the list every time you change
+ the set of files to be processed.
+
+ Notes: 1. This variable has no effect except when no files are
+ specified on the latexmk command line. 2. Wildcards are allowed
+ in @default_excluded_files.
+
+ @default_files [("*.tex")]
+ Default list of files to be processed.
+
+ If no filenames are specified on the command line, latexmk pro-
+ cesses all tex files specified in the @default_files variable,
+ which by default is set to all tex files ("*.tex") in the cur-
+ rent 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
+ can list the files to be processed by setting @default_files in
+ an initialization file (e.g., the file "latexmkrc" in the cur-
+ rent directory). Then if no files are specified on the command
+ line then the files you specify by setting @default_files are
+ processed.
+
+ Three examples:
+
+ @default_files = ("paper_current");
+
+ @default_files = ("paper1", "paper2.tex");
+
+ @default_files = ("*.tex", "*.dtx");
+
+
+
+ 18 June 2019 38
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ Note that more than file may be given, and that the default ex-
+ tension 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.
+
+ If you want latexmk to process all .tex files with a few excep-
+ tions, see the @default_excluded_files array variable.
+
+ $dependents_phony [0]
+ If a list of dependencies is output, this variable determines
+ whether to include a phony target for each source file. If you
+ use the dependents list in a Makefile, the dummy rules work
+ around errors make gives if you remove header files without up-
+ dating the Makefile to match.
+
+ $dependents_list [0]
+ Whether to display a list(s) of dependencies at the end of a
+ run.
+
+ $deps_file ["-"]
+ Name of file to receive list(s) of dependencies at the end of a
+ run, to be used if $dependesnt_list is set. If the filename is
+ "-", then the dependency list is set to stdout (i.e., normally
+ the screen).
+
+ $do_cd [0]
+ Whether to change working directory to the directory specified
+ for the main source file before processing it. The default be-
+ havior is not to do this, which is the same as the behavior of
+ latex and pdflatex programs. This variable is set by the -cd
+ and -cd- options on latexmk's command line.
+
+ $dvi_filter [empty]
+ The dvi file filter to be run on the newly produced dvi file be-
+ fore other processing. Equivalent to specifying the -dF option.
+
+ $dvi_mode [See below for default]
+ If nonzero, generate a dvi version of the document. Equivalent
+ to the -dvi option.
+
+ The variable $dvi_mode defaults to 0, but if no explicit re-
+ quests are made for other types of file (postscript, pdf), then
+ $dvi_mode will be set to 1. In addition, if a request for a
+ file for which a .dvi file is a prerequisite, then $dvi_mode
+ will be set to 1.
+
+ $dvi_previewer ["start xdvi %O %S" under UNIX]
+ The command to invoke a dvi-previewer. [Under MS-Windows the
+ default is "start"; then latexmk arranges to use the MS-Windows
+ start program, which will cause to be run whatever command the
+ system has associated with .dvi files.]
+
+ Important note: Normally you will want to have a previewer run
+ detached, so that latexmk doesn't wait for the previewer to
+
+
+
+ 18 June 2019 39
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ terminate before continuing its work. So normally you should
+ prefix the command by "start ", which flags to latexmk that it
+ should do the detaching of the previewer itself (by whatever
+ method is appropriate to the operating system). But sometimes
+ letting latexmk do the detaching is not appropriate (for a vari-
+ ety of non-trivial reasons), so you should put the "start " bit
+ in yourself, whenever it is needed.
+
+ $dvi_previewer_landscape ["start xdvi %O %S"]
+ The command to invoke a dvi-previewer in landscape mode. [Under
+ MS-Windows the default is "start"; then latexmk arranges to use
+ the MS-Windows start program, which will cause to be run what-
+ ever command the system has associated with .dvi files.]
+
+ $dvipdf ["dvipdf %O %S %D"]
+ Command to convert .dvi to .pdf file. A common reconfiguration
+ is to use the dvipdfm command, which needs its arguments in a
+ different order:
+
+ $dvipdf = "dvipdfm %O -o %D %S";
+
+ WARNING: The default dvipdf script generates pdf files with
+ bitmapped fonts, which do not look good when viewed by acroread.
+ That script should be modified to give dvips the options "-P
+ pdf" to ensure that type 1 fonts are used in the pdf file.
+
+ $dvipdf_silent_switch ["-q"]
+ Switch(es) for dvipdf program when silent mode is on.
+
+ N.B. The standard dvipdf program runs silently, so adding the
+ silent switch has no effect, but is actually innocuous. But if
+ an alternative program is used, e.g., dvipdfmx, then the silent
+ switch has an effect. The default setting is correct for
+ dvipdfm and dvipdfmx.
+
+ $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 variable -- see below -- will be in-
+ cluded in the options substituted for "%O".
+
+ $dvips_landscape ["dvips -tlandscape %O -o %D %S"]
+ The program to used as a filter to convert a .dvi file to a .ps
+ file in landscape mode.
+
+ $dvips_pdf_switch ["-P pdf"]
+ Switch(es) for dvips program when pdf file is to be generated
+ from .ps file.
+
+ $dvips_silent_switch ["-q"]
+ Switch(es) for dvips program when silent mode is on.
+
+ $dvi_update_command [""]
+ When the dvi previewer is set to be updated by running a
+
+
+
+ 18 June 2019 40
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ command, this is the command that is run. See the information
+ for the variable $dvi_update_method for further information, and
+ see information on the variable $pdf_update_method for an exam-
+ ple for the analogous case of a pdf previewer.
+
+ $dvi_update_method [2 under UNIX, 1 under MS-Windows]
+ How the dvi viewer updates its display when the dvi file has
+ changed. The values here apply equally to the $pdf_up-
+ date_method and to the $ps_update_method variables.
+ 0 => update is automatic,
+ 1=> manual update by user, which may only mean a mouse click
+ on the viewer's window or may mean a more serious action.
+ 2 => Send the signal, whose number is in the variable
+ $dvi_update_signal. The default value under UNIX is suitable
+ for xdvi.
+ 3 => Viewer cannot do an update, because it locks the file.
+ (As with acroread under MS-Windows.)
+ 4 => run a command to do the update. The command is speci-
+ fied by the variable $dvi_update_command.
+
+ See information on the variable $pdf_update_method for an exam-
+ ple of updating by command.
+
+ $dvi_update_signal [Under UNIX: SIGUSR1, which is a system-dependent
+ value]
+ The number of the signal that is sent to the dvi viewer when it
+ is updated by sending a signal -- see the information on the
+ variable $dvi_update_method. The default value is the one ap-
+ propriate for xdvi on a UNIX system.
+
+ $failure_cmd [undefined]
+ See the documentation for $compiling_cmd.
+
+ $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
+ need to change this.
+
+ $filetime_causality_threshold [5]; $filetime_offset_report_threshold
+ [30]. (Units of seconds.)
+
+ These variables control how latexmk deals with the following is-
+ sue, which can affect the use of files that are on a remote
+ filesystem (network share) instead of being on a file system lo-
+ cal to the computer running latexmk. Almost users will not have
+ to worry about these settings, and can ignore the following ex-
+ planation.
+
+ In almost all situations, latexmk does not need to use the time
+ stamps of the files it works with. However, there are a couple
+ of situations when it needs to know whether a certain file was
+ created in the current run of a program (e.g., (pdf)latex) or is
+ a leftover file from a previous run. It does this by comparing
+ the modification time of the file with the system time just
+
+
+
+ 18 June 2019 41
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ before the program was started. If the modification time is ear-
+ lier than when the program was started, the file is a leftover
+ file, which latexmk treats as if it were not created. If the
+ filetime is at least the program start time, then it can be as-
+ sumed that the file was created in the current run.
+
+ Unfortunately, this test can fail if the file is on a remote
+ system, since its system time is not necessarily synchronized
+ with that of the local system; the timestamps on the remote
+ files are set by the remote system, not the local system. Gen-
+ erally, modern operating systems regularly synchronize their
+ time with a server, so the non-synchronization is mostly small
+ (a second or so, or a few seconds). But even a small difference
+ can mess up latexmk's test.
+
+ Latexmk measures the time difference between the time on the two
+ systems and compensates for this. But the measurement (in a
+ system-independent way) is only accurate to a second or two. So
+ latexmk allows for a threshold on the difference between file
+ and system time before it concludes that a file is a leftover
+ file from a previous run. The configuration variable $file-
+ time_causality_theshhold, which in units of seconds, specifies
+ this threshold. Luckily high precision is not needed. The pre-
+ vious run is normally the previous run in a human run-edit-run
+ cycle, and is at least many seconds back. A few seconds is
+ therefore appropriate for the threshold, $filetime_causal-
+ ity_theshhold; it should be non-negative always, and should be
+ bigger than 2 if a remote filesystem or network share is used.
+
+ If the difference in system times on the two systems is large,
+ it normally indicates that at least one of the systems is mis-
+ configured. The variable $filetime_offset_report_threshold
+ specifies the smallest size of the difference (or offset) in
+ seconds between the times of the local and remote system beyond
+ which the offset is reported. This is reported at the point in
+ the latexmk's progress that it measures the offset. The report
+ is made if silent mode is used and diagnostic mode is not on.
+
+
+ $force_mode [0]
+ If nonzero, continue processing past minor latex errors includ-
+ ing unrecognized cross references. Equivalent to specifying the
+ -f option.
+
+ @generated_exts [( aux , bbl , idx , ind , lof , lot , out , toc ,
+ $fdb_ext )]
+ This contains a list of extensions for files that are generated
+ during a LaTeX run and that are read in by LaTeX in later runs,
+ either directly or indirectly.
+
+ This list specifies files known to be generated by latex (and
+ pdflatex, etc). It is used in two ways: (a) The specified files
+ are deleted in a cleanup operation (with the -c, -C, -CA, -g and
+ -gg options), and (b) It affects the determination of whether a
+
+
+
+ 18 June 2019 42
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ rerun of (pdf)LaTeX is needed after a run that gives an error.
+
+ (Concerning item (b): Normally, a change of a source file during
+ a run should provoke a rerun. This includes a file generated by
+ LaTeX, e.g., an aux file, that is read in on subsequent runs.
+ But after a run that results in an error, a new run should not
+ occur until the user has made a change in the files. But the
+ user may have corrected an error in a source .tex file during
+ the run. So latexmk needs to distinguish user-generated and au-
+ tomatically generated files; it determines the automatically
+ generated files as those with extensions in the list in @gener-
+ ated_exts.)
+
+ A convenient way to add an extra extension to the list, without
+ losing the already defined ones is to use a push command in the
+ line in an RC file. E.g.,
+
+ push @generated_exts, "end";
+
+ adds the extension "end" to the list of predefined generated ex-
+ tensions. (This extension is used by the RevTeX package, for
+ example.)
+
+ $go_mode [0]
+ If nonzero, process files regardless of timestamps, and is then
+ equivalent to the -g option.
+
+ %hash_calc_ignore_pattern
+ !!!This variable is for experts only!!!
+
+ The general rule latexmk uses for determining when an extra run
+ of some program is needed is that one of the source files has
+ changed. But consider for example a latex package that causes
+ an encapsulated postscript file (an "eps" file) to be made that
+ is to be read in on the next run. The file contains a comment
+ line giving its creation date and time. On the next run the
+ time changes, latex sees that the eps file has changed, and
+ therefore reruns latex. This causes an infinite loop, that is
+ only terminated because latexmk has a limit on the number of
+ runs to guard against pathological situations.
+
+ But the changing line has no real effect, since it is a comment.
+ You can instruct latex to ignore the offending line as follows:
+
+ $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: ';
+
+ This creates a rule for files with extension .eps about lines to
+ ignore. The left-hand side is a Perl idiom for setting an item
+ in a hash. Note that the file extension is specified without a
+ period. The value, on the right-hand side, is a string contain-
+ ing a regular expresssion. (See documentation on Perl for how
+ they are to be specified in general.) This particular regular
+ expression specifies that lines beginning with "%%CreationDate:
+ " are to be ignored in deciding whether a file of the given
+
+
+
+ 18 June 2019 43
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ extension .eps has changed.
+
+ There is only one regular expression available for each exten-
+ sion. If you need more one pattern to specify lines to ignore,
+ then you need to combine the patterns into a single regular ex-
+ pression. The simplest method is separate the different simple
+ patterns by a vertical bar character (indicating "alternation"
+ in the jargon of regular expressions). For example,
+
+ $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: |^%%Ti-
+ tle: ';
+
+ causes lines starting with either "^%%CreationDate: " or "^%%Ti-
+ tle: " to be ignored.
+
+ It may happen that a pattern to be ignored is specified in, for
+ example, in a system or user initialization file, and you wish
+ to remove this in a file that is read later. To do this, you
+ use Perl's delete function, e.g.,
+
+ delete $hash_calc_ignore_pattern{'eps'};
+
+
+ $jobname [""]
+
+ This specifies the jobname, i.e., the basename that is used for
+ generated files (.aux, .log, .dvi, .ps, .pdf, etc). If this
+ variable is a null string, then the basename is the basename of
+ the main tex file. (At present, the string in $jobname should
+ not contain spaces.)
+
+ The placeholder '%A' is permitted. This will be substituted by
+ the basename of the TeX file. The primary purpose is when a va-
+ riety of tex files are to be processed, and you want to use a
+ different jobname for each but one that is distinct for each.
+ Thus if you wanted to compare compilations of a set of files on
+ different operating systems, with distinct filenames for all the
+ cases, you could set
+
+ $jobname = "%A-$^O";
+
+ in an initialization file. (Here $^O is a variable provided by
+ perl that contains perl's name for the operating system.)
+
+ Suppose you had .tex files test1.tex and test2.tex. Then when
+ you run
+
+ latexmk -pdf *.tex
+
+ both files will be compiled. The .aux, .log, and .pdf files
+ will have basenames test1-MSWin32 ante test2-MSWin32 on a MS-
+ Windows system, test1-darwin and test2-darwin on an OS-X system,
+ and a variety of similar cases on linux systems.
+
+
+
+
+ 18 June 2019 44
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ $kpsewhich ["kpsewhich %S"]
+ The program called to locate a source file when the name alone
+ is not sufficient. Most filenames used by latexmk have suffi-
+ cient path information to be found directly. But sometimes, no-
+ tably when a .bib or a .bst file is found from the log file of a
+ bibtex or biber run, only the base name of the file is known,
+ but not its path. The program specified by $kpsewhich is used to
+ find it.
+
+ (For advanced users: Because of the different way in which la-
+ texmk uses the command specified in $kpsewhich, some of the pos-
+ sibilities listed in the FORMAT OF COMMAND SPECIFICATIONS do not
+ apply. The internal and start keywords are not available. A
+ simple command specification with possible options and then "%S"
+ is all that is guaranteed to work. Note that for other com-
+ mands, "%S" is substituted by a single source file. In contrast,
+ for $kpsewhich, "%S" may be substituted by a long list of space-
+ separated filenames, each of which is quoted. The result on
+ STDOUT of running the command is then piped to latexmk.)
+
+ See also the @BIBINPUTS variable for another way that latexmk
+ also uses to try to locate files; it applies only in the case of
+ .bib files.
+
+ $kpsewhich_show [0]
+ Whether to show diagnostics about invocations of kpsewhich: the
+ command line use to invoke it and the results. These diagnos-
+ tics are shown if $kpsewhich_show is non-zero or if diagnostics
+ mode is on. (But in the second case, lots of other diagnostics
+ are also shown.) Without these diagnostics there is nothing
+ visible in latexmk's screen output about invocations of kpse-
+ which.
+
+ $landscape_mode [0]
+ If nonzero, run in landscape mode, using the landscape mode pre-
+ viewers and dvi to postscript converters. Equivalent to the -l
+ option. Normally not needed with current previewers.
+
+ $latex ["latex %O %S"]
+ Specifies the command line for the LaTeX processing program.
+ Note that as with other programs, you can use this variable not
+ just to change the name of the program used, but also specify
+ options to the program. E.g.,
+
+ $latex = "latex --src-specials %O %S";
+
+ To do a coordinated setting of all of $latex, $pdflatex, $luala-
+ tex, and $xelatex, see the section "Advanced Configuration".
+
+
+ %latex_input_extensions
+ This variable specifies the extensions tried by latexmk when it
+ finds that a LaTeX run resulted in an error that a file has not
+ been found, and the file is given without an extension. This
+
+
+
+ 18 June 2019 45
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ typically happens when LaTeX commands of the form \input{file}
+ or \includegraphics{figure}, when the relevant source file does
+ not exist.
+
+ In this situation, latexmk searches for custom dependencies to
+ make the missing file(s), but restricts it to the extensions
+ specified by the variable %latex_input_extensions. The default
+ extensions are 'tex' and 'eps'.
+
+ (For Perl experts: %latex_input_extensions is a hash whose keys
+ are the extensions. The values are irrelevant.) Two subrou-
+ tines are provided for manipulating this and the related vari-
+ able %pdflatex_input_extensions, add_input_ext and remove_in-
+ put_ext. They are used as in the following examples are possi-
+ ble lines in an initialization file:
+
+ remove_input_ext( 'latex', 'tex' );
+
+ removes the extension 'tex' from latex_input_extensions
+
+ add_input_ext( 'latex', 'asdf' );
+
+ add the extension 'asdf to latex_input_extensions. (Naturally
+ with such an extension, you should have made an appropriate cus-
+ tom dependency for latexmk, and should also have done the appro-
+ priate programming in the LaTeX source file to enable the file
+ to be read. The standard extensions are handled by LaTeX and
+ its graphics/graphicx packages.)
+
+ $latex_silent_switch ["-interaction=batchmode"]
+ Switch(es) for the LaTeX processing program when silent mode is
+ on.
+
+ If you use MikTeX, you may prefer the results if you configure
+ the options to include -c-style-errors, e.g., by the following
+ line in an initialization file
+
+ $latex_silent_switch = "-interaction=batchmode -c-style-er-
+ rors";
+
+
+ $lpr ["lpr %O %S" under UNIX/Linux, "NONE lpr" under MS-Windows]
+ The command to print postscript files.
+
+ Under MS-Windows (unlike UNIX/Linux), there is no standard pro-
+ gram for printing files. But there are ways you can do it. For
+ example, if you have gsview installed, you could use it with the
+ option "/p":
+
+ $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
+
+ If gsview is installed in a different directory, you will need
+ to make the appropriate change. Note the combination of single
+ and double quotes around the name. The single quotes specify
+
+
+
+ 18 June 2019 46
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ that this is a string to be assigned to the configuration vari-
+ able $lpr. The double quotes are part of the string passed to
+ the operating system to get the command obeyed; this is neces-
+ sary because one part of the command name ("Program Files") con-
+ tains a space which would otherwise be misinterpreted.
+
+ $lpr_dvi ["NONE lpr_dvi"]
+ The printing program to print dvi files.
+
+ $lpr_pdf ["NONE lpr_pdf"]
+ The printing program to print pdf files.
+
+ Under MS-Windows you could set this to use gsview, if it is in-
+ stalled, e.g.,
+
+ $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
+
+ If gsview is installed in a different directory, you will need
+ to make the appropriate change. Note the double quotes around
+ the name: this is necessary because one part of the command name
+ ("Program Files") contains a space which would otherwise be mis-
+ interpreted.
+
+ $lualatex ["lualatex %O %S"]
+ Specifies the command line for the LaTeX processing program that
+ is to be used when the lualatex program is called for (e.g., by
+ the option -lualatex.
+
+ To do a coordinated setting of all of $latex, $pdflatex, $luala-
+ tex, and $xelatex, see the section "Advanced Configuration".
+
+
+ %lualatex_input_extensions
+ This variable specifies the extensions tried by latexmk when it
+ finds that a lualatex run resulted in an error that a file has
+ not been found, and the file is given without an extension.
+ This typically happens when LaTeX commands of the form \in-
+ put{file} or \includegraphics{figure}, when the relevant source
+ file does not exist.
+
+ In this situation, latexmk searches for custom dependencies to
+ make the missing file(s), but restricts it to the extensions
+ specified by the variable %pdflatex_input_extensions. The de-
+ fault extensions are 'tex', 'pdf', 'jpg, and 'png'.
+
+ See details of the %latex_input_extensions for other information
+ that equally applies to %lualatex_input_extensions.
+
+ $lualatex_silent_switch ["-interaction=batchmode"]
+ Switch(es) for the lualatex program (specified in the variable
+ $lualatex) when silent mode is on.
+
+ See details of the $latex_silent_switch for other information
+ that equally applies to $lualatex_silent_switch.
+
+
+
+ 18 June 2019 47
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ $make ["make"]
+ The make processing program.
+
+ $makeindex ["makeindex %O -o %D %S"]
+ The index processing program.
+
+ $makeindex_silent_switch ["-q"]
+ Switch(es) for the index processing program when silent mode is
+ on.
+
+ $max_repeat [5]
+ The maximum number of times latexmk will run latex/pdflatex be-
+ fore deciding that there may be an infinite loop and that it
+ needs to bail out, rather than rerunning latex/pdflatex again to
+ resolve cross-references, etc. The default value covers all
+ normal cases.
+
+ (Note that the "etc" covers a lot of cases where one run of la-
+ tex/pdflatex generates files to be read in on a later run.)
+
+ $MSWin_back_slash [1]
+ This configuration variable only has an effect when latexmk is
+ running under MS-Windows. It determines whether, when a command
+ is executed under MS-Windows, there should be substituted "\"
+ for the separator character between components of a directory
+ name. Internally, latexmk uses "/" for the directory separator
+ character, which is the character used by Unix-like systems.
+
+ For many programs under MS-Windows, both "\" and "/" are accept-
+ able as the directory separator character. But some programs
+ only accept "\" on the command line. So for safety latexmk
+ makes a translation, by default. It is conceivable that under
+ certain situations this is undesirable, so the configuration can
+ be changed. (A possible example might be when some of the soft-
+ ware is implemented using Cygwin, which provides a Unix-like en-
+ vironment inside MS-Windows.)
+
+ $new_viewer_always [0]
+ This variable applies to latexmk only in continuous-preview
+ mode. If $new_viewer_always is 0, latexmk will check for a pre-
+ viously running previewer on the same file, and if one is run-
+ ning will not start a new one. If $new_viewer_always is non-
+ zero, this check will be skipped, and latexmk will behave as if
+ no viewer is running.
+
+ $out_dir [""]
+ If non-blank, this variable specifies the directory in which
+ output files are to be written by a run of (pdf)latex. See also
+ the variable $aux_dir.
+
+ The effect of this variable (when non-blank) is achieved by us-
+ ing the -output-directory option of (pdf)latex. This exists in
+ the usual current (Dec. 2011 and later) implementations of TeX,
+ i.e., MiKTeX and TeXLive. But it may not be present in other
+
+
+
+ 18 June 2019 48
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ versions.
+
+ If you also use the -cd option, and $out_dir (or $aux_dir) con-
+ tains a relative path, then the path is interpreted relative to
+ the document directory.
+
+ Commonly, the directory specified for output files is a subdi-
+ rectory of the current working directory. However, if you spec-
+ ify some other directory, e.g., "/tmp/foo" or "../output", be
+ aware that this could cause problems, e.g., with makeindex or
+ bibtex. This is because modern versions of these programs, by
+ default, will refuse to work when they find that they are asked
+ to write to a file in a directory that appears not to be the
+ current working directory or one of its subdirectories. This is
+ part of security measures by the whole TeX system that try to
+ prevent malicious or errant TeX documents from incorrectly mess-
+ ing with a user's files. If for $out_dir or $aux_dir you really
+ do need to specify an absolute pathname (e.g., "/tmp/foo") or a
+ path (e.g., "../output") that includes a higher-level directory,
+ and you need to use makeindex or bibtex, then you need to dis-
+ able the security measures (and assume any risks). One way of
+ doing this is to temporarily set an operating system environment
+ variable openout_any to "a" (as in "all"), to override the de-
+ fault "paranoid" setting.
+
+ $pdf_mode [0]
+ If zero, do NOT generate a pdf version of the document. If
+ equal to 1, generate a pdf version of the document using pdfla-
+ tex, using the command specified by the $pdflatex variable. If
+ equal to 2, generate a pdf version of the document from the ps
+ file, by using the command specified by the $ps2pdf variable.
+ If equal to 3, generate a pdf version of the document from the
+ dvi file, by using the command specified by the $dvipdf vari-
+ able. If equal to 4, generate a pdf version of the document us-
+ ing lualatex, using the command specified by the $lualatex vari-
+ able. If equal to 5, generate a pdf version (and an xdv ver-
+ sion) of the document using xelatex, using the commands speci-
+ fied by the $xelatex and xdvipdfmx variables.
+
+ In $pdf_mode=2, it is ensured that .dvi and .ps files are also
+ made. In $pdf_mode=3, it is ensured that a .dvi file is also
+ made. But this may be overridden by the document.
+
+ $pdflatex ["pdflatex %O %S"]
+ Specifies the command line for the LaTeX processing program in a
+ version that makes a pdf file instead of a dvi file.
+
+ An example use of this variable is to add certain options to the
+ command line for the program, e.g.,
+
+ $pdflatex = "pdflatex --shell-escape %O %S";
+
+ (In some earlier versions of latexmk, you needed to use an as-
+ signment to $pdflatex to allow the use of lualatex or xelatex
+
+
+
+ 18 June 2019 49
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ instead of pdflatex. There are now separate configuration vari-
+ ables for the use of lualatex or xelatex. See $lualatex and
+ $xelatex.)
+
+ To do a coordinated setting of all of $latex, $pdflatex, $luala-
+ tex, and $xelatex, see the section "Advanced Configuration".
+
+ %pdflatex_input_extensions
+ This variable specifies the extensions tried by latexmk when it
+ finds that a pdflatex run resulted in an error that a file has
+ not been found, and the file is given without an extension.
+ This typically happens when LaTeX commands of the form \in-
+ put{file} or \includegraphics{figure}, when the relevant source
+ file does not exist.
+
+ In this situation, latexmk searches for custom dependencies to
+ make the missing file(s), but restricts it to the extensions
+ specified by the variable %pdflatex_input_extensions. The de-
+ fault extensions are 'tex', 'pdf', 'jpg, and 'png'.
+
+ See details of the %latex_input_extensions for other information
+ that equally applies to %pdflatex_input_extensions.
+
+ $pdflatex_silent_switch ["-interaction=batchmode"]
+ Switch(es) for the pdflatex program (specified in the variable
+ $pdflatex) when silent mode is on.
+
+ See details of the $latex_silent_switch for other information
+ that equally applies to $pdflatex_silent_switch.
+
+ $pdf_previewer ["start acroread %O %S"]
+ The command to invoke a pdf-previewer.
+
+ On MS-Windows, the default is changed to "cmd /c start """; un-
+ der more recent versions of Windows, this will cause to be run
+ whatever command the system has associated with .pdf files. But
+ this may be undesirable if this association is to acroread --
+ see the notes in the explanation of the -pvc option.]
+
+ On OS-X the default is changed to "open %S", which results in
+ OS-X starting up (and detaching) the viewer associated with the
+ file. By default, for pdf files this association is to OS-X's
+ preview, which is quite satisfactory.
+
+ WARNING: Problem under MS-Windows: if acroread is used as the
+ pdf previewer, and it is actually viewing a pdf file, the pdf
+ file cannot be updated. Thus makes acroread a bad choice of
+ previewer if you use latexmk's previous-continuous mode (option
+ -pvc) under MS-windows. This problem does not occur if, for ex-
+ ample, SumatraPDF or gsview is used to view pdf files.
+
+ Important note: Normally you will want to have a previewer run
+ detached, so that latexmk doesn't wait for the previewer to ter-
+ minate before continuing its work. So normally you should
+
+
+
+ 18 June 2019 50
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ prefix the command by "start ", which flags to latexmk that it
+ should do the detaching of the previewer itself (by whatever
+ method is appropriate to the operating system). But sometimes
+ letting latexmk do the detaching is not appropriate (for a vari-
+ ety of non-trivial reasons), so you should put the "start " bit
+ in yourself, whenever it is needed.
+
+ $pdf_update_command [""]
+ When the pdf previewer is set to be updated by running a com-
+ mand, this is the command that is run. See the information for
+ the variable $pdf_update_method.
+
+ $pdf_update_method [1 under UNIX, 3 under MS-Windows]
+ How the pdf viewer updates its display when the pdf file has
+ changed. See the information on the variable $dvi_update_method
+ for the codes. (Note that information needs be changed slightly
+ so that for the value 4, to run a command to do the update, the
+ command is specified by the variable $pdf_update_command, and
+ for the value 2, to specify update by signal, the signal is
+ specified by $pdf_update_signal.)
+
+ Note that acroread under MS-Windows (but not UNIX) locks the pdf
+ file, so the default value is then 3.
+
+ Arranging to use a command to get a previewer explicitly updated
+ requires three variables to be set. For example:
+
+ $pdf_previewer = "start xpdf -remote %R %O %S";
+ $pdf_update_method = 4;
+ $pdf_update_command = "xpdf -remote %R -reload";
+
+ The first setting arranges for the xpdf program to be used in
+ its "remote server mode", with the server name specified as the
+ rootname of the TeX file. The second setting arranges for up-
+ dating to be done in response to a command, and the third set-
+ ting sets the update command.
+
+ $pdf_update_signal [Under UNIX: SIGHUP, which is a system-dependent
+ value]
+ The number of the signal that is sent to the pdf viewer when it
+ is updated by sending a signal -- see the information on the
+ variable $pdf_update_method. The default value is the one ap-
+ propriate for gv on a UNIX system.
+
+ $pid_position[1 under UNIX, -1 under MS-Windows]
+ The variable $pid_position is used to specify which word in
+ lines of the output from $pscmd corresponds to the process ID.
+ The first word in the line is numbered 0. The default value of
+ 1 (2nd word in line) is correct for Solaris 2.6, Linux, and OS-X
+ with their default settings of $pscmd.
+
+ Setting the variable to -1 is used to indicate that $pscmd is
+ not to be used.
+
+
+
+
+ 18 June 2019 51
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ $postscript_mode [0]
+ If nonzero, generate a postscript version of the document.
+ Equivalent to the -ps option.
+
+ If some other request is made for which a postscript file is
+ needed, then $postscript_mode will be set to 1.
+
+ $pre_tex_code ['']
+
+ Sets TeX code to be executed before inputting the source file.
+ This works if the relevant one of $latex, etc contains a suit-
+ able command line with a %P or %U substitution. For example you
+ could do
+
+ $latex = 'latex %O %P';
+ $pre_tex_code = '\AtBeginDocument{An initial message\par}';
+
+ To set all of $latex, $pdflatex, $lualatex, and $xelatex you
+ could use the subroutine alt_tex_cmds:
+
+ &alt_tex_cmds;
+ $pre_tex_code = '\AtBeginDocument{An initial message\par}';
+
+
+
+ $preview_continuous_mode [0]
+ If nonzero, run a previewer to view the document, and continue
+ running latexmk to keep .dvi up-to-date. Equivalent to the -pvc
+ option. Which previewer is run depends on the other settings,
+ see the command line options -view=, and the variable $view.
+
+ $preview_mode [0]
+ If nonzero, run a previewer to preview the document. Equivalent
+ to the -pv option. Which previewer is run depends on the other
+ settings, see the command line options -view=, and the variable
+ $view.
+
+ $printout_mode [0]
+ If nonzero, print the document using the command specified in
+ the $lpr variable. Equivalent to the -p option. This is recom-
+ mended not to be set from an RC file, otherwise you could waste
+ lots of paper.
+
+ $print_type = ["auto"]
+ Type of file to printout: possibilities are "auto", "dvi",
+ "none", "pdf", or "ps". See the option -print= for the meaning
+ of the "auto" value.
+
+ $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,
+ and to find the process ID (needed if latexmk needs to signal
+ the previewer about file changes).
+
+
+
+
+ 18 June 2019 52
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ Each line of the output of this command is assumed to correspond
+ to one process. See the $pid_position variable for how the
+ process number is determined.
+
+ The default for pscmd is "NONE" under MS-Windows and cygwin
+ (i.e., the command is not used), "ps -ww -u $ENV{USER}" under
+ OS-X, and "ps -f -u $ENV{USER}" under other operating systems
+ (including Linux). In these specifications "$ENV{USER}" is sub-
+ stituted by the username.
+
+ $ps2pdf ["ps2pdf %O %S %D"]
+ Command to convert .ps to .pdf file.
+
+ $ps_filter [empty]
+ The postscript file filter to be run on the newly produced post-
+ script file before other processing. Equivalent to specifying
+ the -pF option.
+
+ $ps_previewer ["start gv %O %S", but start %O %S under MS-Windows]
+ The command to invoke a ps-previewer. (The default under MS-
+ Windows will cause to be run whatever command the system has as-
+ sociated with .ps files.)
+
+ Note that gv could be used with the -watch option updates its
+ display whenever the postscript file changes, whereas ghostview
+ does not. However, different versions of gv have slightly dif-
+ ferent ways of writing this option. You can configure this
+ variable appropriately.
+
+ WARNING: Linux systems may have installed one (or more) versions
+ of gv under different names, e.g., ggv, kghostview, etc, but
+ perhaps not one actually called gv.
+
+ Important note: Normally you will want to have a previewer run
+ detached, so that latexmk doesn't wait for the previewer to ter-
+ minate before continuing its work. So normally you should pre-
+ fix the command by "start ", which flags to latexmk that it
+ should do the detaching of the previewer itself (by whatever
+ method is appropriate to the operating system). But sometimes
+ letting latexmk do the detaching is not appropriate (for a vari-
+ ety of non-trivial reasons), so you should put the "start " bit
+ in yourself, whenever it is needed.
+
+
+ $ps_previewer_landscape ["start gv -swap %O %S", but start %O %S under
+ MS-Windows]
+ The command to invoke a ps-previewer in landscape mode.
+
+ $ps_update_command [""]
+ When the postscript previewer is set to be updated by running a
+ command, this is the command that is run. See the information
+ for the variable $ps_update_method.
+
+
+
+
+
+ 18 June 2019 53
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ $ps_update_method [0 under UNIX, 1 under MS-Windows]
+ How the postscript viewer updates its display when the .ps file
+ has changed. See the information on the variable $dvi_up-
+ date_method for the codes. (Note that information needs be
+ changed slightly so that for the value 4, to run a command to do
+ the update, the command is specified by the variable $ps_up-
+ date_command, and for the value 2, to specify update by signal,
+ the signal is specified by $ps_update_signal.)
+
+ $ps_update_signal [Under UNIX: SIGHUP, which is a system-dependent
+ value]
+ The number of the signal that is sent to the pdf viewer when it
+ is updated by sending a signal -- see $ps_update_method. The
+ default value is the one appropriate for gv on a UNIX system.
+
+ $pvc_timeout [0]
+ If this variable is nonzero, there will be a timeout in pvc
+ mode after a period of inactivity. Inactivity means a period
+ when latexmk has detected no file changes and hence has not
+ taken any actions like compiling the document. The period of in-
+ activity is in the variable $pvc_timeout_mins.
+
+
+ $pvc_timeout_mins [30]
+ The period of inactivity, in minutes, after which pvc mode times
+ out. This is used if $pvc_timeout is nonzero.
+
+ $pvc_view_file_via_temporary [1]
+ The same as $always_view_file_via_temporary, except that it only
+ applies in preview-continuous mode (-pvc option).
+
+ $quote_filenames [1]
+ This specifies whether substitutions for placeholders in command
+ specifications (as in $pdflatex) are surrounded by double
+ quotes. If this variable is 1 (or any other value Perl regards
+ as true), then quoting is done. Otherwise quoting is omitted.
+
+ The quoting method used by latexmk is tested to work correctly
+ under UNIX systems (including Linux and Mac OS-X) and under MS-
+ Windows. It allows the use of filenames containing special
+ characters, notably spaces. (But note that many versions of la-
+ tex and pdflatex cannot correctly deal with TeX files whose
+ names contain spaces. Latexmk's quoting only ensures that such
+ filenames are correctly treated by the operating system in pass-
+ ing arguments to programs.)
+
+ $recorder [1]
+ 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.
+
+
+
+
+ 18 June 2019 54
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ It is generally recommended to use this option (or to configure
+ the $recorder variable to be on.) But it only works if (pdf)la-
+ tex supports the -recorder option, which is true for most cur-
+ rent 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.
+
+ $search_path_separator [See below for default]
+ The character separating paths in the environment variables TEX-
+ INPUTS, BIBINPUTS, and BSTINPUTS. This variable is mainly used
+ by latexmk when the -outdir, -output-directory, -auxdir, and/or
+ -aux-directory options are used. In that case latexmk needs to
+ communicate appropriately modified search paths to bibtex,
+ dvipdf, dvips, and (pdf)latex.
+
+ [Comment to technically savvy readers: (pdf)latex doesn't actu-
+ ally need the modified search path. But, surprisingly, dvipdf
+ and dvips do, because sometimes graphics files get generated in
+ the output or aux directories.]
+
+ The default under MSWin and Cygwin is ';' and under UNIX-like
+ operating systems (including Linux and OS-X) is ':'. Normally
+ the defaults give correct behavior. But there can be difficul-
+ ties if your operating system is of one kind, but some of your
+ software is running under an emulator for the other kind of op-
+ erating system; in that case you'll need to find out what is
+ needed, and set $search_path_separator explicitly. (The same
+ goes, of course, for unusual operating systems that are not in
+ the MSWin, Linux, OS-X, Unix collection.)
+
+ $show_time [0]
+ Whether to show CPU time used.
+
+ $silence_logfile_warnings [0]
+ Whether after a run of (pdf)latex to summarize warnings in the
+ log file about undefined citations and references. Setting $si-
+ lence_logfile_warnings=0 gives the summary of warnings (provided
+ silent mode isn't also set), and this is useful to locate unde-
+ fined citations and references without searching through the
+ much more verbose log file or the screen output of (pdf)latex.
+ But the summary can also be excessively annoying. The default
+ is not to give these warnings. The command line options -si-
+ lence_logfile_warning_list and -silence_logfile_warning_list-
+ also set this variable.
+
+ Note that multiple occurrences for the same undefined object on
+ the same page and same line will be compressed to a single
+
+
+
+ 18 June 2019 55
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ warning.
+
+ $silent [0]
+ Whether to run silently. Setting $silent to 1 has the same ef-
+ fect as the -quiet of -silent options on the command line.
+
+ $sleep_time [2]
+ 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 al-
+ lowed.
+
+ 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
+ variable.
+
+ 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".
+
+ $success_cmd [undefined]
+ See the documentation for $compiling_cmd.
+
+ $tmpdir [See below for default]
+ Directory to store temporary files that latexmk may generate
+ while running.
+
+ The default under MSWindows (including cygwin), is to set $tm-
+ pdir to the value of the first of whichever of the system envi-
+ ronment variables TMPDIR or TEMP exists, otherwise to the cur-
+ rent 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.
+
+
+
+
+
+ 18 June 2019 56
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ $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).
+
+
+ $warnings_as_errors [0]
+ Normally latexmk copies the behavior of latex in treating unde-
+ fined references and citations and multiply defined references
+ as conditions that give a warning but not an error. The vari-
+ able $warnings_as_errors controls whether this behavior is modi-
+ fied.
+
+ When the variable is non-zero, latexmk at the end of its run
+ will return a non-zero status code to the operating system if
+ any of the files processed gives a warning about problems with
+ citations or references (i.e., undefined citations or references
+ or multiply defined references). This is after latexmk has com-
+ pleted all the runs it needs to try and resolve references and
+ citations. Thus $warnings_as_errors being nonzero causes la-
+ texmk to treat such warnings as errors, but only when they occur
+ on the last run of (pdf)latex and only after processing is com-
+ plete. A non-zero value $warnings_as_errors can be set by the
+ command-line option -Werror.
+
+ The default behavior is normally satisfactory in the usual edit-
+ compile-edit cycle. But, for example, latexmk can also be used
+ as part of a build process for some bigger project, e.g., for
+ creating documentation in the build of a software application.
+ Then it is often sensible to treat citation and reference warn-
+ ings as errors that require the overall build process to be
+ aborted. Of course, since multiple runs of (pdf)latex are gen-
+ erally needed to resolve references and citations, what matters
+ is not the warnings on the first run, but the warnings on the
+ last run; latexmk takes this into account appropriately.
+
+ In addition, when preview-continuous mode is used, a non-zero
+ value for $warnings_as_errors changes the use of the commands
+ $failure_cmd, $warning_cmd, and $success_cmd after a complia-
+ tion. If there are citation or reference warnings, but no other
+ errors, the behavior is as follows. If $warning_cmd is set, it
+ is used. If it is not set, then then if $warnings_as_errors is
+ non-zero and $failure_cmd is set, then $failure_cmd. Otherwise
+ $success_cmd is used, if it is set. (The foregoing explanation
+ is rather complicated, because latexmk has to deal with the case
+ that one or more of the commands isn't set.)
+
+
+ $xdvipdfmx ["xdvipdfmx -o %D %O %S"]
+
+ The program to make a pdf file from an xdv file (used in con-
+ junction with xelatex when $pdf_mode=5).
+
+
+
+
+ 18 June 2019 57
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ $xdvipdfmx_silent_switch ["-q"]
+ Switch(es) for the xdvipdfmx program when silent mode is on.
+
+ $xelatex ["xelatex %O %S"]
+ Specifies the command line for the LaTeX processing program of
+ when the xelatex program is called for. See the documentation
+ of the -xelatex option for some special properties of latexmk's
+ use of xelatex.
+
+ Note about xelatex: Now latexmk uses xelatex to make an .xdv
+ rather than .pdf file, with the .pdf file being created in a
+ separate step. This is enforced by the use of the -no-pdf op-
+ tion. If %O is part of the command for invoking xelatex, then
+ latexmk will insert the -no-pdf option automatically, otherwise
+ you must provide the option yourself
+
+ To do a coordinated setting of all of $latex, $pdflatex, $luala-
+ tex, and $xelatex, see the section "Advanced Configuration".
+
+
+ %xelatex_input_extensions
+ This variable specifies the extensions tried by latexmk when it
+ finds that an xelatex run resulted in an error that a file has
+ not been found, and the file is given without an extension.
+ This typically happens when LaTeX commands of the form \in-
+ put{file} or \includegraphics{figure}, when the relevant source
+ file does not exist.
+
+ In this situation, latexmk searches for custom dependencies to
+ make the missing file(s), but restricts it to the extensions
+ specified by the variable %xelatex_input_extensions. The de-
+ fault extensions are 'tex', 'pdf', 'jpg, and 'png'.
+
+ See details of the %latex_input_extensions for other information
+ that equally applies to %xelatex_input_extensions.
+
+ $xelatex_silent_switch ["-interaction=batchmode"]
+ Switch(es) for the xelatex program (specified in the variable
+ $xelatex) when silent mode is on.
+
+ See details of the $latex_silent_switch for other information
+ that equally applies to $xelatex_silent_switch.
+
+
+
+
+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
+ would be to allow latexmk to convert a .fig file to .eps to be included
+ in the .tex file.
+
+
+
+
+
+
+ 18 June 2019 58
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ Defining a custom dependency:
+ The old method of configuring latexmk to use a custom dependency was to
+ directly manipulate the @cus_dep_list array that contains information
+ defining the custom dependencies. (See the section "Old Method of
+ Defining Custom Dependencies" for details.) This method still works,
+ but is no longer preferred.
+
+ A better method is to use the subroutines that allow convenient manipu-
+ lations of the custom dependency list. These are
+
+ add_cus_dep( fromextension, toextension, must, subroutine )
+ remove_cus_dep( fromextension, toextension )
+ show_cus_dep()
+
+ The arguments are as follows:
+
+ from extension:
+ The extension of the file we are converting from (e.g. "fig").
+ It is specified without a period.
+
+ to extension:
+ The extension of the file we are converting to (e.g. "eps"). It
+ is specified without a period.
+
+ must: If non-zero, the file from which we are converting must exist,
+ if it doesn't exist latexmk will give an error message and exit
+ unless the -f option is specified. If must is zero and the file
+ we are converting from doesn't exist, then no action is taken.
+ Generally, the appropriate value of must is zero.
+
+ function:
+ The name of the subroutine that latexmk should call to perform
+ the file conversion. The first argument to the subroutine is
+ the base name of the file to be converted without any extension.
+ The subroutines are declared in the syntax of Perl. The func-
+ tion should return 0 if it was successful and a nonzero number
+ if it failed.
+
+
+ Naturally add_cus_dep adds a custom dependency with the specified from
+ and to extensions. If a custom dependency has been previously defined
+ (e.g., in an rcfile that was read earlier), then it is replaced by the
+ new one.
+
+ The subroutine remove_cus_dep removes the specified custom dependency.
+ The subroutine show_cus_dep causes a list of the currently defined cus-
+ tom dependencies to be sent to the screen output.
+
+
+ How custom dependencies are used:
+ An instance of a custom dependency rule is created whenever latexmk de-
+ tects that a run of latex/pdflatex needs to read a file, like a graph-
+ ics file, whose extension is the to-extension of a custom dependency.
+ Then latexmk examines whether a file exists with the same name, but
+
+
+
+ 18 June 2019 59
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ with the corresponding from-extension, as specified in the custom-de-
+ pendency. If it does, then a corresponding instance of the custom de-
+ pendency is created, after which the rule is invoked whenever the des-
+ tination file (the one with the to-extension) is out-of-date with re-
+ spect to the corresponding source file.
+
+ To make the new destination file, the Perl subroutine specified in the
+ rule is invoked, with an argument that is the base name of the files in
+ question. Simple cases just involve a subroutine invoking an external
+ program; this can be done by following the templates below, even by
+ those without knowledge of the Perl programming language. Of course,
+ experts could do something much more elaborate.
+
+ One item in the specification of each custom-dependency rule, labeled
+ "must" above, specifies how the rule should be applied when the source
+ file fails to exist.
+
+ When latex reports that an input file (e.g., a graphics file) does not
+ exist, latexmk tries to find a source file and a custom dependency that
+ can be used to make it. If it succeeds, then it creates an instance of
+ the custom dependency and invokes it to make the missing file, after
+ which the next pass of latex etc will be able to read the newly created
+ file.
+
+ Note for advanced usage: The operating system's environment variable
+ TEXINPUTS can be used to specify a search path for finding files by la-
+ tex etc. Correspondingly, when a missing file is reported, latexmk
+ looks in the directories specified in TEXINPUTS as well as in the cur-
+ rent directory, to find a source file from which an instance of a cus-
+ tom dependency can be used to make the missing file.
+
+
+ Function to implement custom dependency, traditional method:
+ The function that implements a custom dependency gets the information
+ on the files to be processed in two ways. The first is through its one
+ argument; the argument contains the base name of the source and desti-
+ nation files. The second way is described later.
+
+ A simple and typical example of code in an initialization rcfile using
+ the first method is:
+
+ add_cus_dep( 'fig', 'eps', 0, 'fig2eps' );
+ sub fig2eps {
+ system( "fig2dev -Leps \"$_[0].fig\" \"$_[0].eps\"" );
+ }
+
+ The first line adds a custom dependency that converts a file with ex-
+ tension "fig", as created by the xfig program, to an encapsulated post-
+ script file, with extension "eps". The remaining lines define a sub-
+ routine that carries out the conversion. If a rule for converting
+ "fig" to "eps" files already exists (e.g., from a previously read-in
+ initialization file), the latexmk will delete this rule before making
+ the new one.
+
+
+
+
+ 18 June 2019 60
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ Suppose latexmk is using this rule to convert a file "figure.fig" to
+ "figure.eps". Then it will invoke the fig2eps subroutine defined in
+ the above code with a single argument "figure", which is the basename
+ of each of the files (possibly with a path component). This argument
+ is referred to by Perl as $_[0]. In the example above, the subroutine
+ uses the Perl command system to invoke the program fig2dev. The double
+ quotes around the string are a Perl idiom that signify that each string
+ of the form of a variable name, $_[0] in this case, is to be substi-
+ tuted by its value.
+
+ If the return value of the subroutine is non-zero, then latexmk will
+ assume an error occurred during the execution of the subroutine. In
+ the above example, no explicit return value is given, and instead the
+ return value is the value returned by the last (and only) statement,
+ i.e., the invocation of system, which returns the value 0 on success.
+
+ If you use pdflatex instead of latex, then you will probably prefer to
+ convert your graphics files to pdf format, in which case you would re-
+ place the above code in an initialization file by
+
+ add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' );
+ sub fig2pdf {
+ system( "fig2dev -Lpdf \"$_[0].fig\" \"$_[0].pdf\"" );
+ }
+
+ Note 1: In the command lines given in the system commands in the above
+ examples, double quotes have been inserted around the file names (im-
+ plemented by '\"' in the Perl language). They immunize the running of
+ the program against special characters in filenames. Very often these
+ quotes are not necessary, i.e., they can be omitted. But it is nor-
+ mally safer to keep them in. Even though the rules for quoting vary
+ between operating systems, command shells and individual pieces of
+ software, the quotes in the above examples do not cause problems in the
+ cases I have tested.
+
+ Note 2: One case in which the quotes are important is when the files
+ are in a subdirectory and your operating system is Microsoft Windows.
+ Then the separator character for directory components can be either a
+ forward slash '/' or Microsoft's more usual backward slash '\'. For-
+ ward slashes are generated by latexmk, to maintain its sanity from
+ software like MiKTeX that mixes both directory separators; but their
+ correct use normally requires quoted filenames. (See a log file from a
+ run of MiKTeX (at least in v. 2.9) for an example of the use of both
+ directory separators.)
+
+ Note 3: The subroutines implementing custom dependencies in the exam-
+ ples given just have a single line invoking an external program.
+ That's the usual situation. But since the subroutines are in the Perl
+ language, you can implement much more complicated processing if you
+ need it.
+
+
+ Removing custom dependencies, and when you might need to do this:
+ If you have some general custom dependencies defined in the system or
+
+
+
+ 18 June 2019 61
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ user initialization file, you may find that for a particular project
+ they are undesirable. So you might want to delete the unneeded ones.
+ A situation where this would be desirable is where there are multiple
+ custom dependencies with the same from-extension or the same to-exten-
+ sion. In that case, latexmk might choose a different one from the one
+ you want for a specific project. As an example, to remove any "fig" to
+ "eps" rule you would use:
+
+ remove_cus_dep( 'fig', 'eps' );
+
+ If you have complicated sets of custom dependencies, you may want to
+ get a listing of the custom dependencies. This is done by using the
+ line
+
+ show_cus_dep();
+
+ in an initialization file.
+
+
+ Function implementing custom dependency, alternative methods:
+ So far the examples for functions to implement custom dependencies have
+ used the argument of the function to specify the base name of converted
+ file. This method has been available since very old versions of la-
+ texmk, and many examples can be found, e.g., on the web.
+
+ However in later versions of latexmk the internal structure of the im-
+ plementation of its "rules" for the steps of processing, including cus-
+ tom dependencies, became much more powerful. The function implementing
+ a custom dependency is executed within a special context where a number
+ of extra variables and subroutines are defined. Publicly documented
+ ones, intended to be long-term stable, are listed below, under the
+ heading "Variables and subroutines for processing a rule".
+
+ Examples of their use is given in the following examples, concerning
+ multiple index files and glossaries.
+
+ The only index-file conversion built-in to latexmk is from an ".idx"
+ file written on one run of latex/pdflatex to an ".ind" file to be read
+ in on a subsequent run. But with the index.sty package, for example,
+ you can create extra indexes with extensions that you configure. La-
+ texmk does not know how to deduce the extensions from the information
+ it has. But you can easily write a custom dependency. For example if
+ your latex file uses the command "\newindex{special}{ndx}{nnd}{Special
+ index}" you will need to get latexmk to convert files with the exten-
+ sion .ndx to .nnd. The most elementary method is to define a custom
+ dependency as follows:
+
+ add_cus_dep( 'ndx', 'nnd', 0, 'ndx2nnd' );
+ sub ndx2nnd {
+ return system( "makeindex -o \"$_[0].nnd\" \"$_[0].ndx\"" );
+ }
+ push @generated_exts, 'ndx', 'nnd';
+
+ Notice the added line compared with earlier examples. The extra line
+
+
+
+ 18 June 2019 62
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ gets the extensions "ndx" and "nnd" added to the list of extensions for
+ generated files; then the extra index files will be deleted by clean-up
+ operations
+
+ But if you have yet more indexes with yet different extensions, e.g.,
+ "adx" and "and", then you will need a separate function for each pair
+ of extensions. This is quite annoying. You can use the Run_subst
+ function to simplify the definitions to use a single function:
+
+ add_cus_dep( 'ndx', 'nnd', 0, 'dx2nd' );
+ add_cus_dep( 'adx', 'and', 0, 'dx2nd' );
+ sub dx2nd {
+ return Run_subst( "makeindex -o %D %S" );
+ }
+ push @generated_exts, 'ndx', 'nnd', 'adx', 'and';
+
+ You could also instead use
+
+ add_cus_dep( 'ndx', 'nnd', 0, 'dx2nd' );
+ add_cus_dep( 'adx', 'and', 0, 'dx2nd' );
+ sub dx2nd {
+ return Run_subst( $makeindex );
+ }
+ push @generated_exts, 'ndx', 'nnd', 'adx', 'and';
+
+ This last example uses the command specification in $makeindex, and so
+ any customization you have made for the standard index also applies to
+ your extra indexes.
+
+ Similar techniques can be applied for glossaries.
+
+ Those of you with experience with Makefiles, may get concerned that the
+ .ndx file is written during a run of latex/pdflatex and is always later
+ than the .nnd last read in. Thus the .nnd appears to be perpetually
+ out-of-date. This situation, of circular dependencies, is endemic to
+ latex, and is one of the issues that latexmk is programmed to overcome.
+ It examines the contents of the files (by use of a checksum), and only
+ does a remake when the file contents have actually changed.
+
+ Of course if you choose to write random data to the .nnd (or the .aux
+ file, etc) that changes on each new run, then you will have a problem.
+ For real experts: See the %hash_cal_ignore_pattern if you have to deal
+ with such problems.
+
+
+ Old Method of Defining Custom Dependencies:
+ In much older versions of latexmk, the only method of defining custom
+ dependencies was to directly manipulate the table of custom dependen-
+ cies. This is contained in the @cus_dep_list array. It is an array of
+ strings, and each string in the array has four items in it, each sepa-
+ rated by a space, the from-extension, the to-extension, the "must"
+ item, and the name of the subroutine for the custom dependency. These
+ were all defined above.
+
+
+
+
+ 18 June 2019 63
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ 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 {
+ return system( "fig2dev -Lps \"$_[0].fig\" \"$_[0].eps\"" );
+ }
+
+ This method still works, and is almost equivalent to the code given
+ earlier that used the add_cus_dep subroutine. However, the old method
+ doesn't delete any previous custom-dependency for the same conversion.
+ So the new method is preferable.
+
+
+
+ADVANCED CONFIGURATION: Some extra resources and advanced tricks
+ For most purposes, simple configuration for latexmk along the lines of
+ the examples given is sufficient. But sometimes you need something
+ harder. In this section, I indicate some extra possibilities. Gener-
+ ally to use these, you need to be fluent in the Perl language, since
+ this is what is used in the rc files.
+
+ See also the section DEALING WITH ERRORS, PROBLEMS, ETC. See also the
+ examples in the directory example_rcfiles in the latexmk distributions.
+ Even if none of the examples apply to your case, they may give you use-
+ ful ideas
+
+
+ Utility subroutines
+ ensure_path( var, values ...)
+
+ The first parameter is the name of one of the system's environ-
+ ment variables for search paths. The remaining parameters are
+ values that should be in the variable. For each of the value
+ parameters, if it isn't already in the variable, then it is
+ prepended to the variable; in that case the environment variable
+ is created if it doesn't already exist. For separating values,
+ the character appropriate the the operating system is used --
+ see the configuration variable $search_path_separator.
+
+ Example:
+
+ ensure_path( 'TEXINPUTS', './custom_cls_sty_files//' );
+
+ (In this example, the trailing '//' is documented by TeX systems
+ to mean that latex, pdflatex, etc search for files in the speci-
+ fied directory and in all subdirectories.)
+
+ Technically ensure_path works by setting Perl's variable
+ $ENV{var}, where var is the name of the target variable. The
+ changed value is then passed as an environment variable to any
+ invoked programs.
+
+
+
+
+ 18 June 2019 64
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ Variables and subroutines for processing a rule
+ A step in the processing is called a rule. One possibility to implement
+ the processing of a rule is by a Perl subroutine. This is always the
+ case for custom dependencies. Also, for any other rule, you can use a
+ subroutine by prefixing the command specification by the word "inter-
+ nal" -- see the section FORMAT OF COMMAND SPECIFICATIONS.
+
+ When you use a subroutine for processing a rule, all the possibilities
+ of Perl programming are available, of course. In addition, some of la-
+ texmk's internal variables and subroutines are available. The ones
+ listed below are intended to be available to (advanced) users, and
+ their specifications will generally have stability under upgrades. Gen-
+ erally, the variables should be treated as read-only: Changing their
+ values can have bad consequences, since it is liable to mess up the
+ consistency of what latexmk is doing.
+
+ $rule This variable has the name of the rule, as known to latexmk.
+ Note that the exact contents of this variable for a given rule
+ may be dependent on the version of latexmk
+
+ $$Psource
+ This gives the name of the primary source file. Note the double
+ dollar signs.
+
+ $$Pdest
+ This gives the name of the main output file if any. Note the
+ double dollar signs.
+
+ rdb_ensure_file( $rule, file )
+ This a subroutine that ensures that the given file is among the
+ source files for the specified rule. It is typically used when,
+ during the processing of a rule, it is known that a particular
+ extra file is among the dependencies that latexmk should know,
+ but its default methods don't find the dependency. Almost always
+ the first argument is the name of the rule currently being pro-
+ cessed, so it is then appropriate to specify it by $rule.
+
+ For examples of its use, see some of the files in the directory
+ example_rcfiles of latexmk's distribution. Currently the cases
+ that use this subroutine are bib2gls-latexmkrc, exceltex_la-
+ texmkrc and texinfo-latexmkrc. These illustrate typical cases
+ where latexmk's normal processing fails to detect certain extra
+ source files.
+
+ rdb_remove_files( $rule, file, ... )
+ This subroutine removes one or more files from the dependency
+ list for the given rule.
+
+ rdb_list_source( $rule )
+ This subroutine returns the list of source files (i.e., the de-
+ pendency list) for the given rule.
+
+ rdb_set_source( $rule, file, ... )
+
+
+
+
+ 18 June 2019 65
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ rdb_set_source( $rule, @files )
+ This subroutine sets the dependency list for the given rule to
+ be the specified files. Files that are already in the list have
+ unchanged information. Files that were not in the list are
+ added to it. Files in the previous dependency list that are not
+ in the newly specified list of files are removed from the depen-
+ dency list.
+
+ Run_subst( command_spec )
+ This subroutine runs the command specified by command_spec. The
+ specification is a string in the format listed in the section
+ "Format of Command Specifications". An important action of the
+ Run_subst is to make substitutions of placeholders, e.g., %S and
+ %D for source and destination files; these get substituted be-
+ fore the command is run. In addition, the command after substi-
+ tution is printed to the screen unless latexmk is running in
+ silent mode.
+
+
+ Coordinated Setting of Commands for *latex
+ To set all of $latex, $pdflatex, $lualatex, and $xelatex to a common
+ pattern, you can use one of the following subroutines, std_tex_cmds,
+ alt_tex_cmds, and set_tex_cmds.
+
+ They work as follows
+
+ &std_tex_cmds;
+
+ This results in $latex = 'latex %O %S', and similarly for $pdflatex,
+ $lualatex, and $xelatex. Note the ampersand in the invocation; this
+ indicates to Perl that a subroutine is being called.
+
+ &alt_tex_cmds;
+
+ This results in $latex = 'latex %O %P', and similarly for $pdflatex,
+ $lualatex, and $xelatex. Note the ampersand in the invocation; this
+ indicates to Perl that a subroutine is being called.
+
+ set_tex_cmds( CMD_SPEC );
+
+ Here CMD_SPEC is the command line without the program name. This re-
+ sults in $latex = 'CMD_SPEC', and similarly for $pdflatex, $lualatex,
+ and $xelatex. An example would be
+
+ set_tex_cmds( '--interaction=batchmode %O %S' );
+
+
+ Advanced configuration: 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
+
+
+
+ 18 June 2019 66
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ 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 er-
+ ror-prone, especially when the dependencies can be determined automati-
+ cally. 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. Po-
+ tentially 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 la-
+ texmk, as is suitable for a straightforward LaTeX document. For this a
+ suitable Makefile is like
+
+ .PHONY : FORCE_MAKE
+ all : try.pdf
+ %.pdf : %.tex FORCE_MAKE
+ latexmk -pdf -dvi- -ps- $<
+
+ (Note: the last line must be introduced by a tab for the Makefile to
+ function correctly!) Naturally, if making try.pdf from its associated
+ LaTeX file try.tex were the only task to be performed, a direct use of
+ latexmk without a Makefile would normally be better. The benefit of
+ using a Makefile for a LaTeX document would be in a larger project,
+ 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
+
+
+
+ 18 June 2019 67
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ 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 ex-
+ ample, 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 follow-
+ ing:
+
+ TARGETS = document1.pdf document2.pdf
+ DEPS_DIR = .deps
+ LATEXMK = latexmk -recorder -use-make -deps \
+ -e 'warn qq(In Makefile, turn off custom dependencies\n);' \
+ -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 op-
+ tion, which improves its detection of files generated during a run of
+ pdflatex; such files should not be in the dependency list. The -e op-
+ tions 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
+
+
+
+ 18 June 2019 68
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+ "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), lualatex(1), pdflatex(1), xelatex(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:
+ manually refresh (or reopen) display. Or use one of the other preview-
+ ers and update methods.
+
+ (The following isn't really a bug, but concerns features of preview-
+ ers.) Preview continuous mode only works perfectly with certain pre-
+ viewers: Xdvi on UNIX/Linux works for dvi files. Gv on UNIX/Linux
+ works for both postscript and pdf. Ghostview on UNIX/Linux needs a
+ manual update (reopen); it views postscript and pdf. Gsview under MS-
+ Windows works for both postscript and pdf, but only reads the updated
+ file when its screen is refreshed. Acroread under UNIX/Linux views
+ pdf, but the file needs to be closed and reopened to view an updated
+ version. Under MS-Windows, acroread locks its input file and so the
+ pdf file cannot be updated. (Remedy: configure latexmk to use suma-
+ trapdf instead.)
+
+THANKS TO
+ Authors of previous versions. Many users with their feedback, and es-
+ pecially 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 stan-
+ dard form to avoid being harvested too easily.)
+
+AUTHOR
+ Current version, by John Collins (username jcc8 at node psu.edu).
+ (Version 4.65).
+
+ Released version can be obtained from CTAN:
+ <http://www.ctan.org/pkg/latexmk/>, and from the author's website
+ <http://www.personal.psu.edu/jcc8/latexmk/>.
+ Modifications and enhancements by Evan McLean (Version 2.0)
+ Original script called "go" by David J. Musliner (RCS Version 3.2)
+
+
+
+
+
+
+
+
+
+
+
+
+ 18 June 2019 69
+
+
+
+
+
+LATEXMK(1) General Commands Manual LATEXMK(1)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 18 June 2019 70
+
+