diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/latexmk/latexmk.txt |
Initial commit
Diffstat (limited to 'support/latexmk/latexmk.txt')
-rw-r--r-- | support/latexmk/latexmk.txt | 4620 |
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 + + |