diff options
Diffstat (limited to 'support/latexmk/latexmk.1')
-rw-r--r-- | support/latexmk/latexmk.1 | 3821 |
1 files changed, 3821 insertions, 0 deletions
diff --git a/support/latexmk/latexmk.1 b/support/latexmk/latexmk.1 new file mode 100644 index 0000000000..5c00bafa43 --- /dev/null +++ b/support/latexmk/latexmk.1 @@ -0,0 +1,3821 @@ +.TH LATEXMK 1 "18 June 2019" "" +.SH NAME +latexmk \- generate LaTeX document +.SH SYNOPSIS +.B latexmk [options] [file ...] +.SH DESCRIPTION +.I Latexmk +completely automates the process of compiling a LaTeX document. +Essentially, it is like a specialized relative of the general +\fImake\fR utility, but one which determines dependencies +automatically and has some other very useful features. In its basic +mode of operation \fIlatexmk\fR 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. +.PP +By default \fIlatexmk\fR will run the commands necessary to generate +a .dvi file. +.PP +\fILatexmk\fR can also be set to run continuously with a suitable +previewer. In that case the \fIlatex\fR program (or one of its +relatives), etc, are rerun whenever +one of the source files is modified, and the previewer automatically +updates the on-screen view of the compiled document. +.PP +\fILatexmk\fR 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 \fB-recorder\fR option of modern versions of +\fIlatex\fR (and \fIpdflatex\fR, \fIxelatex\fR, \fIlualatex\fR, etc). +See the documentation for the \fB-recorder\fR option of \fIlatexmk\fR +below.) When \fIlatexmk\fR is run, it examines properties of the +source files, and if any have been changed since the last document +generation, \fIlatexmk\fR will run the various LaTeX processing +programs as necessary. In particular, it will repeat the run of +\fIlatex\fR (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, \fIlatexmk\fR will also run \fIbibtex\fR, +\fIbiber\fR, and/or \fImakeindex\fR. In addition, \fIlatexmk\fR can +be configured to generate other necessary files. For example, from an +updated figure file it can automatically generate a file in +encapsulated postscript or another suitable format for reading by +LaTeX. +.PP +\fILatexmk\fR has two different previewing options. With the simple +\fB-pv\fR option, a dvi, postscript or pdf previewer is automatically +run after generating the dvi, postscript or pdf version of the +document. The type of file to view is selected according to +configuration settings and command line options. +.PP +The second previewing option is the powerful \fB-pvc\fR option +(mnemonic: "preview continuously"). In this case, \fIlatexmk\fR runs +continuously, regularly monitoring all the source files to see if any +have changed. Every time a change is detected, \fIlatexmk\fR 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, \fIlatexmk\fR completely automates the cycle of +updating the .dvi (and/or the .ps and .pdf) file, and refreshing +the previewer's display. It's not quite WYSIWYG, but usefully close. +.PP +For other previewers, the user may have to manually make the previewer +update its display, which can be (e.g., with some versions of \fIxdvi\fR and +\fIgsview\fR) as simple as forcing a redraw of its display. +.PP +\fILatexmk\fR 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 \fB-dF\fR and +\fB-pF\fR, and the documentation for the \fI$dvi_filter\fR and +\fI$ps_filter\fR configuration variables.) These capabilities are +leftover from older versions of \fIlatexmk\fR, but \fBare currently +non-functional\fR. +More flexibility can +be obtained in current versions, since the command strings for running +\fIlatex\fR, \fIpdflatex\fR, etc can now be configured to run multiple +commands. +This also extends the possibility of postprocessing generated files. +.PP +\fILatexmk\fR is highly configurable, both from the command line and +in configuration 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 \fIlatexmk\fR often works +without special configuration 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 Configuration" +.PP +A very annoying complication handled very reliably by \fIlatexmk\fR, +is that LaTeX is a multiple pass system. On each run, LaTeX reads in +information generated on a previous run, for things like cross +referencing and indexing. In the simplest cases, a second run of +LaTeX suffices, and often the log file contains a message about the +need for another pass. However, there is a wide variety of add-on +macro packages to LaTeX, with a variety of behaviors. The result is +to break simple-minded determinations of how many runs are needed and +of which programs. \fILatexmk\fR 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 \fIlatexmk\fR generates an extra file (with extension +\fI.fdb_latexmk\fR, by default) that contains the source file +information. + +.SH LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE +In general the command line to invoke \fIlatexmk\fR has the form + + latexmk [options] [file] + +All options can be introduced by single or double "-" characters, +e.g., "latexmk -help" or "latexmk --help". + +\fBNote 1\fR: \fBIn addition to the options in the list below, +\fIlatexmk\fR recognizes almost all the options recognized by the +\fIlatex\fR, \fIpdflatex\fR programs (and their relatives) in their +current TeXLive and MiKTeX implementations. Some of the options for +these programs also trigger special action or behavior by +\fIlatexmk\fR, in which case they have specific explanations in this +document. Otherwise, they +are just passed through to a called \fIlatex\fR or \fIpdflatex\fR +program. Run \fIlatexmk\fR with the \fB-showextraoptions\fR to get a +list of the options that \fIlatexmk\fR accepts and that are simply +passed through to \fIlatex\fR or \fIpdflatex\fR (etc). See also the +explanation of the \fB-showextraoptions\fR option for more +information. + +\fBNote 2\fR: In this documentation, the program \fIpdflatex\fR is often +referred to. Users of programs like \fIlualatex\fR and \fIxelatex\fR +should know that from \fIlatexmk\fR's point of view, these other +programs behave very like \fIpdflatex\fR, i.e., they make a pdf file from a +tex file, etc. So whenever \fIpdflatex\fR is mentioned without +mention of the other programs, the statements apply equally to +\fIlualatex\fR, \fIxelatex\fR, and any other similar programs. +\fILatexmk\fR can be easily configured to use whichever of these +programs is needed. See the documentation for the following options: +\fB-pdflua\fR, \fB-pdfxe\fR, \fB-lualatex\fR, and \fB-xelatex\fR, +and also see the documentation for the +\fI$pdflatex\fR, \fI$lualatex\fR, and \fI$xelatex\fR configuration variables. +At present \fIlatexmk\fR does not do automatic detection of which +program is to be used. + + +\fBDefinitions of options and arguments\fR + +.TP +.B file +One or more files can be specified. If no files are specified, +\fIlatexmk\fR will, by default, run on all files in the current working directory +with a ".tex" extension. This behavior can be changed: see the +description concerning the \fI@default_files\fR variable in the +section "List of configuration variables usable in initialization +files". + +If a file is specified without an extension, then the ".tex" extension +is automatically added, just as LaTeX does. Thus, if you specify: + + latexmk foo + +then \fIlatexmk\fR 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 problematic for +the \fIlatex\fR etc programs. These characters are: "$", "%", "\\", +"~", the double quote character, and the control characters null, tab, +form feed, carriage return, line feed, and delete. In addition "&" is +prohibited when it is the first character of a filename. + +\fILatexmk\fR gives a fatal error when it detects any of the above +characters in the TeX filename(s) specified on the command line. +\fIHowever\fR before testing for illegal characters, \fIlatexmk\fR +removes matching pairs of double quotes from a filename. This matches +the behavior of \fIlatex\fR etc, and deals with problems that occasionally +result from filenames that have been incorrectly quoted on the command +line. \fIIn addition\fR, under Microsoft Windows, the forward slash +character "\\" is a directory separator, so \fIlatexmk\fR replaces it +by a backward slash "/", which is also a legal directory separator in +Windows, and is accepted by \fIlatex\fR etc. + +.TP +.B -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 \fB-aux-directory\fR option of (pdf)latex, +which currently is only implemented on the MiKTeX version of +(pdf)latex. + +See also the \fB-outdir\fR/\fB-output-directory\fR options, and the +\fI$aux_dir\fR, \fI$out_dir\fR, and \fI$search_path_separator\fR +configuration variables of \fIlatexmk\fR. In particular, see the +documentation of \fI$out_dir\fR for some complications on what +directory names are suitable. + +If you also use the \fB-cd\fR option, and the specified auxiliary output +directory is a relative path, then the path is interpreted relative to +the document directory. + +.TP +.B -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 \fI$bibtex_use\fR +variable to 2 in a configuration file. + +.TP +.B -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 +\fB-bibtex-\fR option will prevent \fIlatexmk\fR from trying to run +\fIbibtex\fR or \fIbiber\fR, which would result in overwriting of the +bbl files. + +This property can also be configured by setting the \fI$bibtex_use\fR +variable to 0 in a configuration file. + +.TP +.B -bibtex-cond +When the source file uses bbl file(s) for the bibliography, run +\fIbibtex\fR or \fIbiber\fR as needed to regenerate the bbl files, but +only if the +relevant bib file(s) exist. Thus when the bib files are not +available, \fIbibtex\fR or \fIbiber\fR is not run, thereby avoiding +overwriting of +the bbl file(s). +Also, always treat .bbl files as precious, +i.e., do not delete them in a cleanup operation. + +This is the default setting. +It can also be configured by setting the \fI$bibtex_use\fR +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 scientific journal +where authors submit .tex and .bbl files, but not the original .bib +file. In that case, running \fIbibtex\fR or \fIbiber\fR 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 demand. + +(Note that it is possible for \fIlatexmk\fR to decide that the bib +file does not exist, even though the bib file does exist and +\fIbibtex\fR or \fIbiber\fR finds it. The problem is that the bib +file may not be in +the current directory but in some search path; the places +\fIlatexmk\fR and \fIbibtex\fR or \fIbiber\fR cause to be searched need not be +identical. On modern installations of TeX and related programs this +problem should not arise, since \fIlatexmk\fR uses the \fIkpsewhich\fR +program to do the search, and \fIkpsewhich\fR should use the same +search path as \fIbibtex\fR and \fIbiber\fR. If this problem arises, use the +\fB-bibtex\fR option when invoking \fIlatexmk\fR.) + +Note that this value does \fInot\fR work properly if the document uses +\fIbiber\fR instead of \fIbibtex\fR. (There's a long story why not.) + +.TP +.B -bibtex-cond1 +The same as \fB-bibtex-cond1\fR except that .bbl files are only +treated as precious if one or more bibfiles fails to exist. + +Thus if all the bib files exist, \fIbibtex\fR or \fIbiber\fR is run to +generate .bbl files as needed, and then it is appropriate to delete +the bbl files in a cleanup operation since they can be re-generated. + +This property can also be configured by setting the \fI$bibtex_use\fR +variable to 1.5 in a configuration file. + +.TP +.B -bm <message> +A banner message to print diagonally across each page when converting +the dvi file to postscript. The message must be a single argument on +the command line so be careful with quoting spaces and such. + +Note that if the \fB-bm\fR option is specified, the \fB-ps\fR option is +assumed. + +.TP +.B -bi <intensity> +How dark to print the banner message. A decimal number between 0 and 1. +0 is black and 1 is white. The default is 0.95, which is OK unless your +toner cartridge is getting low. + +.TP +.B -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 character messages. + +.TP +.B -commands +List the commands used by \fIlatexmk\fR for processing files, and then +exit. + +.TP +.B -c +Clean up (remove) all regeneratable files generated by \fIlatex\fR and +\fIbibtex\fR or \fIbiber\fR except dvi, postscript and pdf. These files are a +combination of log files, aux files, \fIlatexmk\fR's database file of +source file information, +and those with extensions +specified in the \fI@generated_exts\fR configuration variable. In addition, +files specified by the \fI$clean_ext\fR and \fI@generated_exts\fR +configuration variables are removed. + +This cleanup is instead of a regular make. See the \fB-gg\fR option +if you want to do a cleanup then a make. + +\fITreatment of .bbl files: \fR If \fI$bibtex_use\fR is set to 0 or 1, +bbl files are always treated as non-regeneratable. If +\fI$bibtex_use\fR is set to 1.5, bbl files are counted as +non-regeneratable conditionally: If the bib file exists, then bbl +files are regeneratable, and are deleted in a clean up. But if +\fI$bibtex_use\fR 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 \fI$bibtex_use\fR is set to 2, bbl files are always +treated as regeneratable, and are deleted in a cleanup. + +\fITreatment of files generated by custom dependencies:\fR If +\fI$cleanup_includes_cusdep_generated\fR is nonzero, regeneratable +files are considered as including those generated by custom +dependencies and are also deleted. Otherwise these files are not +deleted. + +.TP +.B -C +Clean up (remove) all regeneratable files generated by \fIlatex\fR and +\fIbibtex\fR or \fIbiber\fR. This is the same as the \fB-c\fR option with the +addition of dvi, postscript and pdf files, and those specified +in the \fI$clean_full_ext\fR configuration variable. + +This cleanup is instead of a regular make. See the \fB-gg\fR option +if you want to do a cleanup than a make. + +See the \fB-c\fR option for the specification of whether or not .bbl +files are treated as non-regeneratable or regeneratable. + +If \fI$cleanup_includes_cusdep_generated\fR is nonzero, regeneratable +files are considered as including those generated by custom +dependencies and are also deleted. Otherwise these files are not deleted. + +.TP +.B -CA +(Obsolete). Now equivalent to the \fB-C\fR option. See that option +for details. + +.TP +.B -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 \fIlatexmk\fR is invoked from +a GUI configured to invoke \fIlatexmk\fR with a full pathname for the +source file. + +This option works by setting the \fB$do_cd\fR configuration variable +to one; you can set that variable if you want to configure +\fIlatexmk\fR to have the effect of the \fB-cd\fR option without +specifying it on the command line. See the documentation for that +variable. + +.TP +.B -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 +\fIlatex\fR and \fIpdflatex\fR programs. However, it is not desirable +behavior when \fIlatexmk\fR is invoked by a GUI configured to invoke +\fIlatexmk\fR with a full pathname for the source file. See the +\fB-cd\fR option. + +This option works by setting the \fB$do_cd\fR configuration variable +to zero. See the documentation for that variable for more +information. + +.TP +.B -CF +Remove the file containing the database of source file information, +before doing the other actions requested. + +.TP +.B -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 \fB-bs\fR and \fB-bi\fR options. The \fB-bm\fR +option will override this option as this is really just a short way of +specifying: + + latexmk -bm DRAFT + +Note that if the \fB-d\fR option is specified, the \fB-ps\fR option is +assumed. + +.TP +.B -deps +Show a list of dependent files after processing. This is in the form +of a dependency list of the form used by the \fImake\fR 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 +\fIlatexmk\fR can determine them. + +By default the list of dependent files is sent to stdout (i.e., +normally to the screen unless you've redirected \fIlatexmk\fR's +output). But you can set the filename where the list is sent by the +\fB-deps-out=\fR option. + +See the section "USING \fIlatexmk\fR WITH \fImake\fR" for +an example of how to use a dependency list with \fImake\fR. + +Users familiar with GNU \fIautomake\fR and \fIgcc\fR will find that +the \fB-deps\fR option is very similar in its purpose and results to +the \fB-M\fR option to \fIgcc\fR. (In fact, \fIlatexmk\fR also has +options \fB-M\fR, \fB-MF\fR, and \fB-MP\fR options that behave like +those of \fIgcc\fR.) + +.TP +.B -dependents +Equivalent to \fB-deps\fR. + +.TP +.B -deps- +Do not show a list of dependent files after processing. (This is the +default.) + +.TP +.B -dependents- +Equivalent to \fB-deps-\fR. + +.TP +.B -deps-out=FILENAME +Set the filename to which the list of dependent files is written. If +the FILENAME argument is omitted or set to "-", then the output is +sent to stdout. + +Use of this option also turns on the output of the list of dependent +files after processing. + +.TP +.B -dF +Dvi file filtering. The argument to this option is a filter which will +generate a filtered dvi file with the extension ".dviF". All extra +processing (e.g. conversion to postscript, preview, printing) will then +be performed on this filtered dvi file. + +Example usage: To use dviselect to select only the even pages of the dvi file: + + latexmk -dF "dviselect even" foo.tex + +.TP +.B -diagnostics +Print detailed diagnostics during a run. This may help for debugging +problems or to understand \fIlatexmk\fR's behavior in difficult +situations. + +.TP +.B -dvi +Generate dvi version of document. + +.TP +.B -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.) + +.TP +.B -e <code> +Execute the specified initialization code before processing. The code +is \fIPerl\fR code of the same form as is used in \fIlatexmk\fR's +initialization files. For more details, +see the information on the +\fB-r\fR option, and the section about "Configuration/initialization +(RC) files". The code is typically a sequence of assignment +statements separated by semicolons. + +The code is executed when the \fB-e\fR option is encountered during +\fIlatexmk\fR's parsing of its command line. See the \fB-r\fR option +for a way of executing initialization code from a file. An error +results in \fIlatexmk\fR stopping. Multiple instances of the \fB-r\fR +and \fB-e\fR options can be used, and they are executed in the order +they appear on the command line. + +Some care is needed to deal with proper quoting of special characters +in the code on the command line. For example, suppose you want +to set the latex command to use its -shell-escape option, then under +UNIX/Linux you could use the line + + latexmk -e '$latex=q/latex %O -shell-escape %S/' file.tex + +Note that the single quotes block normal UNIX/Linux command shells +from treating the characters inside the quotes as special. +(In this example, the q/.../ construct is a +\fIPerl\fR idiom equivalent to using +single quotes. This avoids the complications of getting a quote +character inside an already quoted string in a way that is independent +of both the shell and the operating-system.) + +The above command line will NOT work under MS-Windows with cmd.exe or +command.com or 4nt.exe. For MS-Windows with these command shells you +could use + + latexmk -e "$latex=q/latex %O -shell-escape %S/" file.tex + +or + + latexmk -e "$latex='latex %O -shell-escape %S'" file.tex + +The last two examples will NOT work with UNIX/Linux command shells. + +(\fINote\fR: the above examples show are to show how to use the +\fB-e\fR to specify initialization code to be executed. But the +particular effect can be achieved also by the use of the \fB-latex\fR +option with less problems in dealing with quoting.) + +.TP +.B -f +Force \fIlatexmk\fR to continue document processing despite errors. +Normally, when \fIlatexmk\fR 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 \fIlatex\fR (etc) that would be done if no errors had +occurred. If instead, or additionally, you want the \fIlatex\fR (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 +\fIlatexmk\fR's option \fB-interaction=nonstopmode\fR. + +.TP +.B -f- +Turn off the forced processing-past-errors such as is set by the +\fB-f\fR option. This could be used to override a setting in a +configuration file. + +.TP +.B -g +Force \fIlatexmk\fR to process document fully, even under situations +where \fIlatexmk\fR 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. + +.TP +.B -g- +Turn off \fB-g\fR. + +.TP +.B -gg +"Super go mode" or "clean make": clean out generated files as if +\fB-C\fR had been given, and then do a regular make. + +.TP +.B -h, -help +Print help information. + +.TP +.B -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.) + +This is like the same option for current implementations of the +\fIlatex\fR, \fIpdflatex\fR, etc, and the passing of this option to +these programs is part of \fIlatexmk\fR's implementation of +\fB-jobname\fR. + +There is one enhancement, that the STRING may contain the +placeholder '%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 \fIlatexmk\fR, and you wish to use a jobname with a +different file-dependent value for each file. For example, suppose +you had .tex files test1.tex and test2.tex, and you wished to compare +the results of compilation by \fIpdflatex\fR and those with +\fIxelatex\fR. 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 \fIpdflatex\fR +would have basenames test1-pdflatex and test2-pdflatex, while from +\fIxelatex\fR, the basenames would be test1-xelatex and test2-xelatex. + +Under MS-Windows with cmd.exe, you would need to double the percent +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 + +.TP +.B -l +Run in landscape mode, using the landscape mode for the previewers and +the dvi to postscript converters. This option is not normally needed +nowadays, since current previewers normally determine this information +automatically. + +.TP +.B -l- +Turn off \fB-l\fR. + +.TP +.B -latex="COMMAND" +This sets the string specifying the command to run latex, and is +typically used to add desired options. Since the string normally +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 \fI$latex\fR configuration variable. Depending on your +operating system and the command-line shell you are using, you may +need to change the single quotes to double quotes (or something +else). + +To set the command for running \fIpdflatex\fR (rather than the command for +\fIlatex\fR) see the \fB-pdflatex\fR option. + +.TP +.B -logfilewarninglist +.B -logfilewarnings +After a run of \fI(pdf)latex\fR, give a list of warnings about +undefined citations and references (unless silent mode is on). + +See also the \fI$silence_logfile_warnings\fR configuration variable. + +.TP +.B -logfilewarninglist- +.B -logfilewarnings- +After a run of \fI(pdf)latex\fR, do not give a list of warnings about +undefined citations and references. (Default) + +See also the \fI$silence_logfile_warnings\fR configuration variable. + +.TP +.B -lualatex +Use \fIlualatex\fR. That is, use \fIlualatex\fR 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- + +(\fINote\fR: Note that the method of implementation of this option, +but not its intended effect, differ from some earlier versions of +\fIlatexmk\fR.) + +.TP +.B -M +Show list of dependent files after processing. This is equivalent to +the \fB-deps\fR option. + +.TP +.B -MF file +If a list of dependents is made, the \fB-MF\fR specifies the file to +write it to. + +.TP +.B -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 \fImake\fR gives if you remove header +files without updating the Makefile to match. + +.TP +.B -new-viewer +When in continuous-preview mode, always start a new viewer to view the +generated file. By default, \fIlatexmk\fR will, in continuous-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. + +.TP +.B -new-viewer- +The inverse of the \fB-new-viewer\fR option. It puts \fIlatexmk\fR +in its normal behavior that in preview-continuous mode it checks for +an already-running previewer. + +.TP +.B -nobibtex +Never run bibtex or biber. Equivalent to the \fB-bibtex-\fR option. + +.TP +.B -norc +Turn off the automatic reading of initialization (rc) files. + +N.B. Normally the initialization files are read and obeyed, and then +command line options are obeyed in the order they are encountered. +But \fB-norc\fR is an exception to this rule: it is acted on first, +no matter where it occurs on the command line. + +.TP +.B -outdir=FOO or -output-directory=FOO + +Sets the directory for the output files of (pdf)latex. This achieves +its effect by the \fB-output-directory\fR option of (pdf)latex, 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 \fB-auxdir\fR/\fB-aux-directory\fR options, and the +\fI$aux_dir\fR, \fI$out_dir\fR, and \fI$search_path_separator\fR +configuration variables of \fIlatexmk\fR. In particular, see the +documentation of \fI$out_dir\fR for some complications on what +directory names are suitable. + +If you also use the \fB-cd\fR option, and the specified output +directory is a relative path, then the path is interpreted relative to +the document directory. + +.TP +.B -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 +\fB-print=...\fR option to change the type of file to be printed, and you +can configure this in a start up file (by setting the +\fI$print_type\fR 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, under MS-Windows you must have suitable program(s) +available, and you must have configured the print commands used by +\fIlatexmk\fR. This can be non-trivial. See the documentation on the +\fI$lpr\fR, \fI$lpr_dvi\fR, and \fI$lpr_pdf\fR configuration variables +to see how to set the commands for printing. + +This option is incompatible with the \fB-pv\fR and \fB-pvc\fR options, +so it turns them off. + +.TP +.B -pdf +Generate pdf version of document using \fIpdflatex\fR. (If you wish +to use \fIlualatex\fR or \fIxelatex\fR, you can use whichever of the +options \fB-pdflua\fR, \fB-pdfxe\fR, \fB-lualatex\fR or \fB-xelatex\fR +applies.) To configure +\fIlatexmk\fR to have such behavior by default, see the section on +"Configuration/initialization (rc) files". + +.TP +.B -pdfdvi +Generate pdf version of document from the dvi file, by default using dvipdf. + +.TP +.B -pdflua +Generate pdf version of document using \fIlualatex\fR. + +.TP +.B -pdfps +Generate pdf version of document from the .ps file, by default using +\fIps2pdf\fR. + +.TP +.B -pdfxe +Generate pdf version of document using \fIxelatex\fR. Note that to +optimize processing time, \fIlatexmk\fR uses \fIxelatex\fR 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 \fIlatexmk\fR +then call \fIxdvipdfmx\fR to generate the final .pdf file. + +(\fINote:\fR When the document includes large graphics files, +especially .png files, the last step can be quite time consuming, even +when the creation of the .xdv file by \fIxelatex\fR 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 \fIxelatex\fR. See the documentation on the \fB-pdfxe\fR +option for why an .xdv file is used. + +.TP +.B -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 \fIlatex\fR (or, more +precisely, whatever program is configured to be used in the +\fI$latex\fR configuration variable). + +.TP +.B -pdflatex="COMMAND" +This sets the string specifying the command to run \fIpdflatex\fR, and is +typically used to add desired options. Since the string normally +contains spaces, it should be quoted, e.g., + + latexmk -pdf -pdflatex="pdflatex --shell-escape %O %S" foo.tex + +The specification of the contents of the string are the same as for +the \fI$pdflatex\fR configuration variable. (The option +\fB-pdflatex\fR in fact sets the variable \fI$pdflatex\fR.) +Depending on your +operating system and the command-line shell you are using, you may +need to change the single quotes to double quotes (or something +else). + +To set the command for running \fIlatex\fR (rather than the command +for \fIpdflatex\fR) see the \fB-latex\fR option. + +.TP +.B -pdflualatex="COMMAND" +This sets the string specifying the command to run \fIlualatex\fR. It +behaves like the \fB-pdflatex\fR option, but sets the variable +\fI$lualatex\fR. + +.TP +.B -pdfxelatex="COMMAND" +This sets the string specifying the command to run \fIxelatex\fR. It +behaves like the \fB-pdflatex\fR option, but sets the variable +\fI$xelatex\fR. + +\fIWarning\fR: It is important to ensure that the -no-pdf is used when +\fIxelatex\fR is invoked; see the explanation for the variable +\fI$xelatex\fR 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 \fB-pdfxelatex\fR option: + + latexmk -pdfxe -pdfxelatex="xelatex --shell-escape %O %S" foo.tex + + +.TP +.B -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 \fI*latex\fR is suitably configured. See +the documentation of the variable \fI$pre_tex_code\fR, and the +substitution strings %P and %U for more details. This option works by +setting the variable \fI$pre_tex_code\fR. + +See also the \fB-usepretex\fR option. + +An example: + + latexmk -pretex='\\AtBeginDocument{Message\\par}' -usepretex foo.tex + +But this is better written + + latexmk -usepretex='\\AtBeginDocument{Message\\par}' foo.tex + +If you already have a suitable command configured, you only need + + latexmk -pretex='\\AtBeginDocument{Message\\par}' foo.tex + +.TP +.B -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 +\fB-print=auto\fR 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. + +.TP +.B -ps +Generate postscript version of document. + +.TP +.B -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.) + +.TP +.B -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. + +.TP +.B -pv +Run file previewer. If the \fB-view\fR option is used, this will select +the kind of file to be previewed (.dvi, .ps or .pdf). +Otherwise the viewer views the "highest" kind of file selected, by the +\fB-dvi\fR, \fB-ps\fR, \fB-pdf\fR, \fB-pdfps\fR 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 \fB-p\fR and \fB-pvc\fR options, +so it turns them off. + +.TP +.B -pv- +Turn off \fB-pv\fR. + +.TP +.B -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 \fB-pv\fR +option. +The preview-continuous option \fB-pvc\fR can only work with one file. +So in this case you will normally only specify one filename on +the command line. It is also incompatible with the +\fB-p\fR and \fB-pv\fR options, so it turns these options off. + +The \fB-pvc\fR option also turns off force mode (\fB-f\fR), as is +normally best for continuous preview mode. If you really want force +mode, use the options in the order \fB-pvc -f\fR. + +With a good previewer the display will be automatically updated. +(Under \fIsome but not all\fR versions of UNIX/Linux "gv -watch" does +this for postscript files; this can be set by a configuration +variable. This would also work for pdf files except for an apparent +bug in gv that causes an error when the newly updated pdf file is +read.) Many other previewers will need a manual update. + +\fBImportant note\fR: 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: \fISumatraPDF\fR and +\fIgsview\fR are good possibilities. + +There are some other methods for arranging an update, notably useful +for many versions of \fIxdvi\fR and \fIxpdf\fR. These are best set in +\fIlatexmk\fR's configuration; see below. + +Note that if \fIlatexmk\fR dies or is stopped by the user, the +"forked" previewer will continue to run. Successive invocations with +the \fB-pvc\fR option will not fork new previewers, but \fIlatexmk\fR +will normally use the existing previewer. (At least this will happen +when \fIlatexmk\fR is running under an operating system where it knows +how to determine whether an existing previewer is running.) + +.TP +.B -pvc- +Turn off \fB-pvc\fR. + +.TP +.B -pvctimeout +Do timeout in pvc mode after period of inactivity, which is 30 min. by +default. Inactivity means a period when \fIlatexmk\fR has detected no +file changes and hence has not taken any actions like compiling the +document. + +.TP +.B -pvctimeout- +Don't do timeout in pvc mode after inactivity. + +.TP +.B -pvctimeoutmins=<time> +Set period of inactivity in \fIminutes\fR for pvc timeout. + +.TP +.B -quiet +Same as -silent + +.TP +.B -r <rcfile> +Read the specified initialization file ("RC file") before processing. + +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 \fB-r\fR option, it is read during this second step. +Thus an initialization file specified with the \fB-r\fR option can +override both the standard initialization files and \fIpreviously\fR +specified options. But all of these can be overridden by \fIlater\fR +options. + +The contents of the RC file just comprise a piece of code in the +\fIPerl\fR programming language +(typically a sequence of assignment statements); they are executed +when the \fB-r\fR option is encountered during \fIlatexmk\fR's parsing +of its command line. See the \fB-e\fR option for a way of giving +initialization code directly on \fIlatexmk\fR's command line. An +error results in \fIlatexmk\fR stopping. Multiple instances of the +\fB-r\fR and \fB-e\fR options can be used, and they are executed in +the order they appear on the command line. + +.TP +.B -recorder +Give the -recorder option with \fIlatex\fR and \fIpdflatex\fR. In +(most) modern versions of these programs, this results in a file of +extension \fI.fls\fR containing a list of the files that these +programs have read and written. \fILatexmk\fR will then use this file +to improve its detection of source files and generated files after a +run of \fIlatex\fR or \fIpdflatex\fR. This is the default setting of +\fIlatexmk\fR, unless overridden in an initialization file. + +For further information, see the documentation for the \fI$recorder\fR +configuration variable. + +.TP +.B -recorder- +Do not supply the -recorder option with \fIlatex\fR and \fIpdflatex\fR. + +.TP +.B -rules +Show a list of \fIlatemk\fR's rules and dependencies after processing. + +.TP +.B -rules- +Do not show a list of \fIlatexmk\fR's rules and dependencies after +processing. (This is the default.) + +.TP +.B -showextraoptions +Show the list of extra \fIlatex\fR and \fIpdflatex\fR options that +\fIlatexmk\fR recognizes, but that it simply passes +through to the programs \fIlatex\fR, \fIpdflatex\fR, 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 \fIlatexmk\fR +but is not handled by the particular implementation of \fIlatex\fR or +\fIpdflatex\fR 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 \fIlatexmk\fR's +actions. + +There are a few options (\fB-includedirectory=dir\fR, +\fB-initialize\fR, \fB-ini\fR) that are not recognized, either because +they don't fit with \fIlatexmk\fR's intended operations, or because +they need special processing by \fIlatexmk\fR that isn't implemented +(at least, not yet). + +There are also options that are accepted by \fIlatex\fR etc, but +instead trigger actions by \fIlatexmk\fR: \fB-help\fR, +\fB-version\fR. + +Finally, there are certain options for \fIlatex\fR and \fIpdflatex\fR +(e.g., \fB-recorder\fR) that trigger special actions or behavior by +\fIlatexmk\fR itself as well as being passed in some form to the +called \fIlatex\fR and \fIpdflatex\fR program, or that affect other +programs as well. These options do have entries in this +documentation. These options are: +\fB-jobname=STRING\fR, \fB-aux-directory=dir\fR, +\fB-output-directory=DIR\fR, \fB-quiet\fR, and \fB-recorder\fR. + +.TP +.B -silent +Run commands silently, i.e., with options that reduce the amount of +diagnostics generated. For example, with the default settings, the +command "latex -interaction=batchmode" is used for \fIlatex\fR, +and similarly for its friends. + +See also the \fB-logfilewarninglist\fR and \fB-logfilewarninglist-\fR +options. + +Also reduce the number of informational messages that \fIlatexmk\fR +itself generates. + +To change the options used to make the commands run silently, you need +to configure \fIlatexmk\fR with changed values of its configuration +variables, the relevant ones being \fI$bibtex_silent_switch\fR, +\fI$biber_silent_switch\fR, \fI$dvipdf_silent_switch\fR, +\fI$dvips_silent_switch\fR, \fI$latex_silent_switch\fR, +\fI$lualatex_silent_switch\fR +\fI$makeindex_silent_switch\fR, \fI$pdflatex_silent_switch\fR, +and \fI$xelatex_silent_switch\fR + +.TP +.B -stdtexcmds +Sets the commands for \fIlatex\fR, etc, so that they are the standard +ones. This is useful to override special configurations. + +The result is that \fI$latex = 'latex %O %S'\fR, and similarly for +\fI$pdflatex\fR, \fI$lualatex\fR, and \fI$xelatex\fR. (The option +\fB-no-pdf\fR needed for \fI$xelatex\fR is provided automatically, +given that %O appears in the definition.) + +.TP +.B -time +Show CPU time used. +See also the configuration variable \fI$show_time\fR. + +.TP +.B -time- +Do not show CPU time used. +See also the configuration variable \fI$show_time\fR. + +.TP +.B -use-make +When after a run of \fIlatex\fR or \fIpdflatex\fR, there are warnings +about missing files (e.g., as requested by the LaTeX \\input, \\include, +and \\includgraphics commands), \fIlatexmk\fR tries to make them by a custom +dependency. If no relevant custom dependency with an appropriate +source file is found, and if the \fB-use-make\fR option is set, then +as a last resort \fIlatexmk\fR will try to use the \fImake\fR program +to try to make the missing files. + +Note that the filename may be specified without an extension, e.g., +by \\includegraphics{drawing} in a LaTeX file. In that case, +\fIlatexmk\fR will try making drawing.ext with ext set in turn to the +possible extensions that are relevant for \fIlatex\fR (or as +appropriate \fIpdflatex\fR). + +See also the documentation for the \fI$use_make_for_missing_files\fR +configuration variable. + +.TP +.B -use-make- +Do not use the make program to try to make missing files. (Default.) + +.TP +.B -usepretex +Sets the command lines for \fIlatex\fR, etc, so that they use the code +that is defined by the variable \fI$pre_tex_code\fR or that is set by +the option \fB-pretex=CODE\fR 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 \fI$latex = 'latex %O %P'\fR, and similarly for +\fI$pdflatex\fR, \fI$lualatex\fR, and \fI$xelatex\fR. (The option +\fB-no-pdf\fR needed for \fI$xelatex\fR is provided automatically, +given that %O appears in the definition.) + +.TP +.B -usepretex=CODE +Equivalent to \fB-pretex=CODE -usepretex\fR. Example + + latexmk -usepretex='\\AtBeginDocument{Message\\par}' foo.tex + +.TP +.B -v, -version +Print version number of \fIlatexmk\fR. + +.TP +.B -verbose +Opposite of \fB-silent\fR. This is the default setting. + +.TP +.B -view=default, -view=dvi, -view=ps, -view=pdf, -view=none +Set the kind of file used when previewing is requested (e.g., by the +\fB-pv\fR or \fB-pvc\fR switches). The default is to view the "highest" +kind of requested file (in the low-to-high order .dvi, .ps, .pdf). + +Note the possibility \fB-view=none\fR where no viewer is opened at +all. One example of is use is in conjunction with the \fB-pvc\fR +option, when you want \fIlatexmk\fR to do a compilation automatically +whenever source file(s) change, but do not want a previewer to be opened. + +.TP +.B -Werror +This causes \fIlatexmk\fR to return a non-zero status code if any of +the files processed gives a warning about problems with citations or +references (i.e., undefined citations or references or about multiply +defined references). This is \fBafter\fR \fIlatexmk\fR has completed +all the runs it needs to try and resolve references and citations. +Thus \fB-Werror\fR causes \fIlatexmk\fR to treat such warnings 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 \fI$warnings_as_errors\fR. + +.TP +.B -xelatex +Use \fIxelatex\fR. That is, use \fIxelatex\fR 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- + +[\fINote\fR: Note that the method of implementation of this option, +but not its intended primary effect, differ from some earlier versions +of \fIlatexmk\fR. \fILatexmk\fR first uses \fIxelatex\fR to make +an .xdv file, and does all the extra runs needed (including those of +\fIbibtex\fR, etc). Only after that does it make the pdf file from +the .xdv file, using \fIxdvipdfmx\fR. This procedure can result in +considerable savings in run time, since the xdv-to-pdf conversion is +quite time-consuming when large graphics files are used in the +document.] + + +.PP +\fBCompatibility between options\fR + +The preview-continuous option \fB-pvc\fR can only work with one file. +So in this case you will normally only specify one filename on +the command line. +.PP +Options \fB-p\fR, \fB-pv\fR and \fB-pvc\fR are mutually exclusive. So +each of these options turns the others off. + +.SH EXAMPLES +.nf +.ta 2i +% \fBlatexmk thesis\fR \fI# run latex enough times to resolve + cross-references\fR + +% \fBlatexmk -pvc -ps thesis\fR \fI# 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, \fIlatexmk\fR will + keep running, watching for + source file changes. + +% \fBlatexmk -c\fR \fI# remove .aux, .log, .bbl, .blg, .dvi, + .pdf, .ps & .bbl files\fR + + +.SH DEALING WITH ERRORS, PROBLEMS, ETC + +.PP +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 +notoriously verbose in the output of \fIlatex\fR (and that is added to +by \fIlatexmk\fR), the verbosity is there for a reason: to enable the +user to diagnose problems. \fILatexmk\fR does repeat some messages at +the end of a run that it thinks would otherwise be easy to miss in the +middle of other output. + +b. Generally, remember that \fIlatexmk\fR does its work by running +other programs. 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 missing LaTeX packages, etc.) + +c. If \fIlatexmk\fR 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 \fIlatexmk\fR's behavior is configurable to deal with +particular situations. (But there is a lot of reading!) + +\fIThe remainder of these notes consists of ideas for dealing with more +difficult situations.\fR + +d. Further tricks can involve replacing the standard commands that +\fIlatexmk\fR runs by other commands or scripts. + +e. For possible examples of code for use in an RC file, see the +directory example_rcfiles in the distribution of \fIlatexmk\fR (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 \fIlualatex\fR +instead of \fIpdflatex\fR (and in some related situations). The +problem is that \fIlatexmk\fR 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 +\fIlatexmk\fR, then \fIlatexmk\fR will think no files have changed and +not rerun \fIlualatex\fR, whereas if you had '\\input{bar.baz}' in the +LaTeX part of the document, \fIlatexmk\fR 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 \fIlatexmk\fR will treat as +implying that the file bar.baz was read. (At present I don't know a +way of doing this automatically.) Of course, if the file has a +different name, change bar.baz to the name of your file. + +g. See also the section "Advanced Configuration: Some extra resources". + +h. Look on tex.stackexchange, i.e., at +http://tex.stackexchange.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 \fIlatexmk\fR). My e-mail is at the end +of this documentation. + + +.SH ALLOWING FOR CHANGE OF OUTPUT FILE TYPE + +When one of the latex engines is run, the usual situation is that +\fIlatex\fR produces a .dvi file, while \fIpdflatex\fR and +\fIlualatex\fR produce a .pdf file. For \fIxelatex\fR the default is +to produce a .pdf file, but to optimize processing time \fIlatexmk\fR +runs \fIxelatex\fR its \fB-no-pdf\fR option so that it produces +an .xdv file. Further processing by \fIlatexmk\fR takes this as a +starting point. + +However, the actual output file may differ from the normal +expectation; and then \fIlatexmk\fR can adjust its processing to +accommodate this situation. The difference in output file type can +happen for two reasons: One is that for \fIlatex\fR, \fIpdflatex\fR +and \fIlualatex\fR the document itself can override the defaults. The +other is that there may be a configuration, or misconfiguration, such +that the program that \fIlatexmk\fR invokes to compile the document is +not the expected one, or is given options incompatible with what +\fIlatexmk\fR initially expects. (E.g., the \fB-output-format=...\fR +option could be used with \fIlualatex\fR, or \fIxelatex\fR gets +invoked without the \fB-no-pdf\fR option.) + +Under \fIlatex\fR and \fIpdflatex\fR, control of the output format by +the document is done by setting the \\pdfoutput macro. Under +\fIlualatex\fR, the \\outputmode 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 document. This entails the use of compilation to a .dvi file, +followed by the use of conversion to a postscript file (either +directly, as by \fIdvips\fR or implicitly, as an intermediate step by +\fIdvipdf\fR). Then it is useful to force output to be of the .dvi +format by inserting \\pdfoutput=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 package, these can be processed in compilation to .pdf but +not with compilation to .dvi. In this case, it is useful to insert +\\pdfoutput=1 in the preamble of the document to force compilation +to .pdf output format. + +In all of these cases, it is needed that \fIlatexmk\fR has to adjust +its processing to deal with a mismatch between the actual output +format (out of .pdf, .dvi, .xdv) and the initially expected output, if +possible. \fILatexmk\fR does this provided the following conditions +are met. + +The first is that \fIlatexmk\fR's \fI$allow_switch\fR 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 \fIlatexmk\fR to be able to handle a change +of output type is that no explicit requests for .dvi or .ps output +files are made. Explicit requests are by the \fB-dvi\fR and +\fB-ps\fR, \fB-print=dvi\fR, \fB-print=ps\fR, \fB-view=dvi\fR, and +\fB-view=ps\fR options, and by corresponding settings of the +\fI$dvi_mode\fR, \fI$postscript_mode\fR, \fI$print_type\fR, and +\fI$view\fR configuration 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 +\fB-pdfdvi\fR and \fB-pdfps\fR options (and the corresponding setting +of the \fI$pdf_mode\fR 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 +involved a substantial change in the network of rules that +\fIlatexmk\fR 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 radical to be readily handled automatically. + + +.SH CONFIGURATION/INITIALIZATION (RC) FILES +.PP +In this section is explained which configuration files are read by +\fIlatexmk\fR. 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. + +\fILatexmk\fR can be customized using initialization files, which are +read at startup in the following order: +.PP +1) The system RC file, if it exists. + On a UNIX system, \fIlatexmk\fR searches for following places for its +system 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), \fIlatexmk\fR 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. +.PP +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 configuration home directory. The actual file read is the first +of "$XDG_CONFIG_HOME/latexmk/latexmkrc" or "$HOME/.latexmkrc" which +exists. (See +https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html +for details on the XDG Base Directory Specification.) + +Here $HOME +is the user's home directory. [\fILatexmk\fR 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 environment +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 \fIlatexmk\fR does not look for an RC file in +it.] + +$XDG_CONFIG_HOME is the value of the environment variable +XDG_CONFIG_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 \fIlatexmk\fR does not look for an RC file under it. + +.PP +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. +.PP +4) Any RC file(s) specified on the command line with the \fB-r\fR +option. +.PP +Each RC file is a sequence of \fIPerl\fR commands. Naturally, a user can use +this in creative ways. But for most purposes, one simply uses a +sequence of assignment statements that override some of the built-in +settings of \fILatexmk\fR. Straightforward cases can be handled +without knowledge of the \fIPerl\fR 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 \fB-r\fR option can override previous options but can be itself +overridden by later options on the command line. There is also the +\fB-e\fR option, which allows initialization code to be specified in +\fIlatexmk\fR's command line. + +\fI +For possible examples of code for in an RC file, see the directory +example_rcfiles in the distribution of \fIlatexmk\fR (e.g., at +http://mirror.ctan.org/support/latexmk/example_rcfiles). +\fR + +.SH HOW TO SET VARIABLES IN INITIALIZATION FILES +.PP +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: +.PP + $bibtex = 'bibtex %O %B'; +.PP +for the setting of a string variable, +.PP + $preview_mode = 1; +.PP +for the setting of a numeric variable, and +.PP + @default_files = ('paper', 'paper1'); +.PP +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 \fIPerl\fR +programming language brings into play some special rules for +interpolating variables into strings. People not fluent in \fIPerl\fR +will want to avoid these complications.) + +You can do much more complicated things, but for this you will need to +consult a manual for the \fIPerl\fR programming language. + + + +.SH FORMAT OF COMMAND SPECIFICATIONS + +Some of the variables set the commands that \fIlatexmk\fR uses for +carrying out its work, for example to generate a .dvi file from a .tex +file or to view a postscript file. This section describes some +important features of how the commands are specified. +(Note\ that some of the possibilities listed here do not apply to +the \fI$kpsewhich\fR variable; see its documentation.) + +\fBPlaceholders\fR: Supposed you wanted \fIlatexmk\fR 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: +.PP + $latex = 'elatex --shell-escape %O %S'; +.PP +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 \fIlatexmk\fR has decided +to use for this command. (E.g., if you used the \fB-silent\fR option in the +invocation of \fIlatexmk\fR, it results in the replacement of %O by +"-interaction=batchmode".) + +The available placeholders are: +.TP +.B %A +basename of the main tex file. Unlike %R, this is unaffected by the +setting of a jobname by the \fI-jobname\fR option or the +\fI$jobname\fR configuration value. +.TP +.B %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. +.TP +.B %D +destination file (e.g., the name of the postscript file when +converting a dvi file to postscript). +.TP +.B %O +options +.TP +.B %P +If the variable \fI$pre_tex_code\fR is non-empty, then %P is +substituted by the contents of \fI$pre_tex_code\fR followed by +\fI\\input{SOURCE}\fR, 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 \fI*latex\fR engines to be executed before the +source file is read. + +If the variable \fI$pre_tex_code\fR is the empty string, then %P is +equivalent to %S. +.TP +.B %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 \fI-jobname\fR option or the +\fI$jobname\fR configuration variable. +.TP +.B %S +source file (e.g., the name of the dvi file when converting a .dvi file +to ps). +.TP +.B %T +The name of the primary tex file. +.TP +.B %U +If the variable \fI$pre_tex_code\fR is non-empty, then its value is +substituted for %U (appropriately quoted). Otherwise it is replaced +by a null string. +.TP +.B %Y +Name of directory for auxiliary output files (see the configuration +variable \fI$aux_dir\fR). A directory separation character ('/') is +appended if \fI$aux_dir\fR 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 '\\'. Note that if after +initialization, \fI$out_dir\fR is set, but \fI$aux_dir\fR is not set +(i.e., it is blank), then \fIlatexmk\fR sets \fI$aux_dir\fR to the +same value \fI$out_dir\fR. +.TP +.B %Z +Name of directory for output files (see the configuration +variable \fI$out_dir\fR). A directory separation character ('/') is +appended if \fI$out_dir\fR 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 '\\'. +.PP +If for some reason you need a literal % character in your string not +subject to the above rules, use "%%". +.PP +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 \fIlatexmk\fR's quoting does not work +correctly on your system, you can turn it off -- see the documentation +for the variable \fI$quote_filenames\fR. +.PP +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 +document 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 +.PP + $bibtex = 'bibtex %O %B'; +.PP +Generally, you should use %B rather than %R. Similarly for most +purposes, the name %T of the primary texfile is not a useful +placeholder. + +See the default values in the section "List of configuration variables +usable in initialization files" for what is normally the most +appropriate usage. + +If you omit to supply any placeholders whatever in the specification +of a command, \fIlatexmk\fR will supply what its author thinks are +appropriate defaults. This gives compatibility with configuration +files for previous versions of \fIlatexmk\fR, which didn't use +placeholders. + +\fB"Detaching" a command\fR: Normally when \fIlatexmk\fR 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 \fIlatexmk\fR gets +the previewer running and then returns to its next task (or exits if +there is nothing else to do). To achieve this effect of detaching a +command, you need to precede the command name with "start ", as in +.PP + $dvi_previewer = 'start xdvi %O %S'; +.PP +This will be translated to whatever is appropriate for your operating +system. + +Notes: (1) In some circumstances, \fIlatexmk\fR will always run a +command detached. This is the case for a previewer in preview +continuous mode, since otherwise previewing continuously makes no +sense. (2) This precludes 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. + +\fBCommand names containing spaces\fR: Under MS-Windows it is common +that the name of a command includes spaces, since software is often +installed in a subdirectory of "C:\\Program Files". Such command names +should be enclosed in double quotes, as in +.PP + $lpr_pdf = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p %S'; + $pdf_previewer = 'start "c:/Program Files/SumatraPDF/SumatraPDF.exe" %O %S'; + $pdf_previewer = 'start "c:/Program Files/SumatraPDF (x86)/SumatraPDF.exe" %O %S'; + +.PP +(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.) + +\fBCommand names under Cygwin\fR: If \fIlatexmk\fR is executed by Cygwin's +Perl, \fI be particularly certain that pathnames in commands have +\fBforward\fI slashes\fR 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. + +\fBUsing MS-Windows file associations\fR: A useful trick under modern +versions of MS-Windows (e.g., WinXP) is to use just the +command 'start' by itself: +.PP + $dvi_previewer = 'start %S'; +.PP +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 suitable 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 \fIlatex\fR and +\fIlatexmk\fR, because acroread locks the pdf file. + +\fBNot using a certain command\fR: If a command is not to be run, the +command name NONE is used, as in +.PP + $lpr = 'NONE lpr'; +.PP +This typically is used when an appropriate command does not exist on +your system. The string after the "NONE" is effectively a comment. + +\fBOptions to commands\fR: +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 \fIlatexmk\fR to use latex with source specials +enabled. Then you might use the following line in an initialization +file: +.PP + $latex = 'latex --src-specials %O %S'; +.PP + +\fBRunning a subroutine instead of an external command\fR: Use a +specification starting with "internal", as in +.PP + $latex = 'internal mylatex %O %S'; + sub mylatex { + my @args = @_; + # Possible preprocessing here + return system 'latex', @args; + } +.PP +For some of the more exotic possibilities that then become available, +see the section "ADVANCED CONFIGURATION: Some extra resources and +advanced tricks". Also see some of the examples in the directory +\fIexample_rcfiles\fR in the \fIlatexmk\fR distribution. + +\fBAdvanced tricks\fR: Normally one specifies a single command for the +commands invoked by \fIlatexmk\fR. Naturally, if there is some +complicated additional processing you need to do in your special +situation, you can write a script (or batch file) to do the +processing, and then configure \fIlatexmk\fR 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 \fIlatexmk\fR to run multiple +commands. For example, if when running \fIpdflatex\fR to generate a pdf +file from a tex file you need to run another program after \fIpdflatex\fR to +perform some extra 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 +includes Linux and OS-X), so that the +two commands to be run are separated 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 \fIPerl\fR on MS-Windows do +not obey the command separator; this problem is overcome by explicitly +invoking the MS-Windows command-line processor \fIcmd.exe\fR. + +.SH LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES +.PP +In this section are specified the variables whose values can be +adjusted to configure \fIlatexmk\fR. (See the earlier section +"Configuration/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 \fIlatexmk\fR 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. + +.TP +.B $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 under \fIlatex\fR +or \fIpdflatex\fR, or with the use of the \\outputmode macro under +\fIlualatex\fR. It can also happen with certain kinds of incorrect +configuration. + +In such a case, \fIlatexmk\fR can appropriately adjust its network of +rules. The adjustment is made if \fI$allow_switch\fR is on, and if no +request for a dvi or ps file has been made. + +See the section ALLOWING FOR CHANGE OF OUTPUT EXTENSION. + +.TP +.B $always_view_file_via_temporary [0] +Whether .ps and .pdf files are initially to be made in a temporary +directory and then moved to the final location. (This applies to +\fIdvips\fR, \fIdvipdf\fR, and \fIps2pdf\fR operations, and the +filtering operators on .dvi and .ps files. It does not apply to +\fIpdflatex\fR, unfortunately, since \fIpdflatex\fR 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 \fIgv\fR) +sees that the file has changed, it may read the new file before +the program writing the file has not yet finished its work, which can +cause havoc. + +See the \fI$pvc_view_file_via_temporary\fR variable for a setting that +applies only if preview-continuous mode (-pvc option) is used. See +\fI$tmpdir\fR for the setting of the directory where the temporary +file is created. + +.TP +.B $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 reliable, 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 situation: 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 dependent, 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. + +.TP +.B $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 \fB-norc\fR can be +used to turn this setting off. Each RC file could also turn this +setting off, i.e., it could set \fI$auto_rc_use\fR 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 \fB-r\fR option. +.TP +.B $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 +\fI$out_dir\fR is set, then \fI$aux_dir\fR is set to \fI$out_dir\fR, +which is the directory to which general output files are to be +written. + +\fBImportant note\fR: The effect of \fI$aux_dir\fR, if different from +\fI$out_dir\fR, is achieved by giving \fI(pdf)latex\fR the +\fB-aux-directory\fR. Currently (Dec. 2011 and later) this only works on the +MiKTeX version of \fI(pdf)latex\fR. + +See also the documentation of \fI$out_dir\fR for some complications on +what directory names are suitable. + +If you also use the \fB-cd\fR option, and \fI$out_dir\fR (or \fI$aux_dir\fR) contains a +relative path, then the path is interpreted relative to the document +directory. +.TP +.B $banner [0] +If nonzero, the banner message is printed across each page when +converting the dvi file to postscript. Without modifying the variable +\fI$banner_message\fR, this is equivalent to specifying the \fB-d\fR +option. + +Note that if \fI$banner\fR is nonzero, the \fI$postscript_mode\fR is +assumed and the postscript file is always generated, even if it is newer +than the dvi file. +.TP +.B $banner_intensity [0.95] +Equivalent to the \fB-bi\fR 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 cartridge isn't +running too low. +.TP +.B $banner_message ["DRAFT"] +The banner message to print across each page when converting the dvi +file to postscript. This is equivalent to the \fB-bm\fR option. +.TP +.B $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 +\fB-bs\fR option. +.TP +.B @BIBINPUTS +This is an array variable, now mostly obsolete, that specifies +directories where +\fIlatexmk\fR should look for .bib files. By default it is set from +the BIBINPUTS environment variable of the operating system. If that +environment variable is not set, a single element list consisting of +the current directory is set. The format of the directory names +depends on your operating system, 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 "\(rs" 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 \fIPerl\fR's rules for writing +strings. + +\fIImportant note:\fR This variable is now mostly obsolete in the +current version of \fIlatexmk\fR, +since it has a better method of searching for files using the +kpsewhich command. However, if your system is an unusual one without +the kpsewhich command, you may need to set the variable \fI@BIBINPUTS\fR. +.TP +.B $biber ["biber %O %S"] +The biber processing program. +.TP +.B $biber_silent_switch ["--onlylog"] +Switch(es) for the biber processing program when silent mode is on. +.TP +.B $bibtex ["bibtex %O %S"] +The BibTeX processing program. +.TP +.B $bibtex_fudge [1] +When using bibtex, whether to take special action to allow bibtex 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 required. +.TP +.B $bibtex_silent_switch ["-terse"] +Switch(es) for the BibTeX processing program when silent mode is on. +.TP +.B $bibtex_use [1] +Under what conditions to run \fIbibtex\fR or \fIbiber\fR. When +\fIlatexmk\fR discovers +from the log file that one (or more) +\fIbibtex\fR/\fIbiber\fR-generated bibliographies +are used, it can run \fIbibtex\fR or \fIbiber\fR whenever it appears +necessary to regenerate the bbl file(s) from their source bib database +file(s). +But sometimes, the bib file(s) are not available (e.g., for a document +obtained from an external archive), but the bbl files are provided. +In that case use of \fIbibtex\fR or \fIbiber\fR will result in +incorrect overwriting of the precious bbl files. The variable +\fI$bibtex_use\fR controls whether this happens, and also controls +whether or not .bbl files are deleted in a cleanup operation. + +The possible values of \fI$bibtex_use\fR are: + 0: never use BibTeX or biber; +never delete .bbl files in a cleanup. + 1: only use \fIbibtex\fR or \fIbiber\fR if the bib files exist; +never delete .bbl files in a cleanup. + 1.5: only use \fIbibtex\fR or \fIbiber\fR if the bib files exist; +conditionally delete .bbl files in a cleanup (i.e., delete them only +when the bib files all exist). + 2: run \fIbibtex\fR or \fIbiber\fR 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 \fInot\fR work properly if the document +uses \fIbiber\fR instead of \fIbibtex\fR. (There's a long story why +not.) + +.TP +.B $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 \fB-C\fR option, custom +dependencies are those listed in the \fI.fdb_latexmk\fR file from a +previous run.) +.TP +.B $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 +information. Therefore this variable is turned off by default, and +then files to be deleted are restricted to those explictly specified +by patterns configured in the variables \fIclean_ext\fR, +\fIclean_full_ext\fR, and \fI@generated_exts\fR, together with those +very standard cases that are hardwired into \fIlatexmk\fR (e.g., .log +files). +.TP +.B $cleanup_mode [0] +If nonzero, specifies cleanup mode: 1 for full cleanup, 2 for cleanup +except for .dvi, .ps and .pdf files, 3 for cleanup except for dep and aux +files. (There is also extra cleaning as specified by the +\fI$clean_ext\fR, \fI$clean_full_ext\fR and \fI@generated_exts\fR +variables.) + +This variable is equivalent to specifying one of +the \fB-c\fR or \fB-C\fR options. But there should be no need +to set this variable from an RC file. +.TP +.B $clean_ext [""] +Extra extensions of files for \fIlatexmk\fR to remove when any of the +clean-up options (\fB-c\fR or \fB-C\fR) is selected. +The value of this variable is a string containing the extensions +separated by spaces. + +It is also possible to specify a more general pattern of file to be +deleted, by using the place holder %R, as in commands, 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 operation 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 +\fI$aux_dir\fR. (Note that if \fI$out_dir\fR but not \fI$aux_dir\fR +is set, then in its initialization, \fIlatexmk\fR sets \fI$aux_dir\fR +equal to \fI$out_dir\fR. A normal situation is therefore that \fI$aux_dir\fR +equals \fI$out_dir\fR, 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 \fI@generated_exts\fR. +.TP +.B $clean_full_ext [""] +Extra extensions of files for \fIlatexmk\fR to remove when the \fB-C\fR +option 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 \fI$clean_ext\fR. + +The files specified by \fI$clean_full_ext\fR to be deleted are +relative to the directory specified by \fI$out_dir\fR. + +.TP +.B $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 motivation for +their existance is to allow very useful convenient 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: +\fI$compiling_cmd\fR at the start of compilation, \fI$success_cmd\fR +at the end of a completely successful compilation, \fI$failure_cmd\fR +at the end of an unsuccessful compilation, \fI$warning_cmd\fR at the +of an otherwise successful compilation that gives warnings about +undefined citations or references or about multiply defined +references. If any of above variables is undefined or blank (the +default situation), then the corresponding command is not executed. + +However, when \fI$warning_cmd\fR 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 \fI$success_cmd\fR or \fI$failure_cmd\fR +is used (if it is set) according to the setting of +\fI$warnings_as_errors\fR. + +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 \fIxdotool\fR 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 placeholder 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 window 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 command changing +the title of the edit window. The visual indication 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 \fIxdotool\fR 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 software +solutions are available. + +.TP +.B @cus_dep_list [()] +Custom dependency list -- see section on "Custom Dependencies". +.TP +.B @default_excluded_files [()] +When \fIlatexmk\fR 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 \fI@default_files\fR variable.) + +But sometimes you want to exclude particular files from this default +list. In that case you can specify the excluded files in the array +\fI@default_excluded_files\fR. 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 +\fI@default_files\fR 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 \fIlatexmk\fR command line. 2. Wildcards are allowed +in \fI@default_excluded_files\fR. +.TP +.B @default_files [("*.tex")] +Default list of files to be processed. + +If no filenames are specified on the command line, +\fIlatexmk\fR processes all tex files specified in the \fI@default_files\fR +variable, which by default is set to all tex files ("*.tex") in the +current directory. This is a convenience: just run \fIlatexmk\fR 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 +\fI@default_files\fR in an initialization file +(e.g., the file "latexmkrc" in the current directory). Then if no +files are specified on the command line then the files you specify by +setting \fI@default_files\fR are processed. + +Three examples: + + @default_files = ("paper_current"); + + @default_files = ("paper1", "paper2.tex"); + + @default_files = ("*.tex", "*.dtx"); + +Note that more than file may be given, and that the default extension +is ".tex". Wild cards are allowed. The parentheses are because +\fI@default_files\fR is an array variable, i.e., a sequence of +filename specifications is possible. + +If you want \fIlatexmk\fR to process all .tex files with a few +exceptions, see the \fI@default_excluded_files\fR array variable. +.TP +.B $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 updating the Makefile to +match. +.TP +.B $dependents_list [0] +Whether to display a list(s) of dependencies at the end of a run. +.TP +.B $deps_file ["-"] +Name of file to receive list(s) of dependencies at the end of a run, +to be used if \fI$dependesnt_list\fR is set. If the filename is "-", +then the dependency list is set to stdout (i.e., normally the screen). +.TP +.B $do_cd [0] +Whether to change working directory to the directory specified for the +main source file before processing it. The default behavior is not to +do this, which is the same as the behavior of \fIlatex\fR and +\fIpdflatex\fR programs. This variable is set by the \fB-cd\fR and +\fB-cd-\fR options on \fIlatexmk\fR's command line. +.TP +.B $dvi_filter [empty] +The dvi file filter to be run on the newly produced dvi file before +other processing. Equivalent to specifying the \fB-dF\fR option. +.TP +.B $dvi_mode [See below for default] +If nonzero, generate a dvi version of the document. +Equivalent to the \fB-dvi\fR option. + +The variable $dvi_mode defaults to 0, but if no explicit requests are +made for other types of file (postscript, pdf), then $dvi_mode will be +set to 1. In addition, if a request for a file for which a .dvi file +is a prerequisite, then $dvi_mode will be set to 1. +.TP +.B $dvi_previewer ["start xdvi %O %S" under UNIX] +The command to invoke a dvi-previewer. +[Under MS-Windows the default is "start"; then \fIlatexmk\fR arranges to +use the MS-Windows \fIstart\fR program, which will cause to be run +whatever command the system has associated with .dvi files.] + +\fBImportant note\fR: Normally you will want to have a previewer run +detached, so that \fIlatexmk\fR doesn't wait for the previewer to +terminate before continuing its work. So normally you should prefix +the command by "start ", which flags to \fIlatexmk\fR that it should +do the detaching of the previewer itself (by whatever method is +appropriate to the operating system). But sometimes letting +\fIlatexmk\fR do the detaching is not appropriate (for a variety of +non-trivial reasons), so you should put the "start " bit in +yourself, whenever it is needed. +.TP +.B $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 \fIlatexmk\fR arranges to +use the MS-Windows \fIstart\fR program, which will cause to be run +whatever command the system has associated with .dvi files.] +.TP +.B $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. +.TP +.B $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 \fIdvipdfm\fR and +\fIdvipdfmx\fR. +.TP +.B $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 +\fI$dvips_pdf_switch\fR variable -- see below -- will be included in +the options substituted for "%O". +.TP +.B $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. +.TP +.B $dvips_pdf_switch ["-P pdf"] +Switch(es) for \fIdvips\fR program when pdf file is to be generated +from .ps file. +.TP +.B $dvips_silent_switch ["-q"] +Switch(es) for \fIdvips\fR program when silent mode is on. +.TP +.B $dvi_update_command [""] +When the dvi previewer is set to be updated by running a command, this +is the command that is run. See the information for the variable +\fI$dvi_update_method\fR for further information, and see information +on the variable \fI$pdf_update_method\fR for an example for the +analogous case of a pdf previewer. +.TP +.B $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 \fI$pdf_update_method\fR and to +the \fI$ps_update_method\fR 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 +\fI$dvi_update_signal\fR. The default value under UNIX is +suitable for \fIxdvi\fR. + 3 => Viewer cannot do an update, because it locks the file. (As with +\fIacroread\fR under MS-Windows.) + 4 => run a command to do the update. The command is specified by +the variable \fI$dvi_update_command\fR. + +See information on the variable \fI$pdf_update_method\fR for an +example of updating by command. +.TP +.B $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 +\fI$dvi_update_method\fR. The default value is the one appropriate +for \fIxdvi\fR on a UNIX system. +.TP +.B $failure_cmd [undefined] +See the documentation for \fI$compiling_cmd\fR. +.TP +.B $fdb_ext ["fdb_latexmk"] +The extension of the file which \fIlatexmk\fR generates to contain a +database of information on source files. You will not normally need +to change this. +.TP +.B $filetime_causality_threshold [5]; $filetime_offset_report_threshold [30]. \fR(Units of seconds.) + +These variables control how \fIlatexmk\fR deals with the following +issue, which can affect the use of files that are on a remote +filesystem (network share) instead of being on a file system local to +the computer running \fIlatexmk\fR. Almost users will not have to +worry about these settings, and can ignore the following explanation. + +In almost all situations, \fIlatexmk\fR 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., \fI(pdf)latex\fR) 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 before the program was +started. If the modification time is earlier than when the program was +started, the file is a leftover file, which \fIlatexmk\fR treats as if +it were not created. If the filetime is at least the program start +time, then it can be assumed 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. Generally, 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 \fIlatexmk\fR's +test. + +\fILatexmk\fR 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 +\fIlatexmk\fR 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 +\fI$filetime_causality_theshhold\fR, which in units of seconds, +specifies this threshold. Luckily high precision is not needed. The +previous 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, \fI$filetime_causality_theshhold\fR; 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 misconfigured. +The variable \fI$filetime_offset_report_threshold\fR 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 \fIlatexmk\fR's +progress that it measures the offset. The report is made if silent +mode is used and diagnostic mode is not on. + +.TP +.B $force_mode [0] +If nonzero, continue processing past minor \fIlatex\fR errors +including unrecognized cross references. Equivalent to specifying the +\fB-f\fR option. +.TP +.B @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 +\fB-c\fR, \fB-C\fR, \fB-CA\fR, \fB-g\fR and \fB-gg\fR options), and +(b) It affects the determination of whether a 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 \fIlatexmk\fR needs +to distinguish user-generated and automatically generated files; it +determines the automatically generated files as those with extensions +in the list in @generated_exts.) + +A convenient way to add an extra extension to the list, without losing +the already defined ones is to use a push command in the line in an +RC file. E.g., + + push @generated_exts, "end"; + +adds the extension "end" to the list of predefined generated +extensions. (This extension is used by the RevTeX package, for +example.) +.TP +.B $go_mode [0] +If nonzero, process files regardless of timestamps, and is then +equivalent to the \fB-g\fR option. +.TP +.B %hash_calc_ignore_pattern +\fB!!!This variable is for experts only!!!\fR + +The general rule \fIlatexmk\fR 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, \fIlatex\fR sees +that the eps file has changed, and therefore reruns latex. This +causes an infinite loop, that is only terminated because \fIlatexmk\fR +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 \fIlatex\fR to ignore the offending line as follows: + + $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: '; + +This creates a rule for files with extension \fI.eps\fR about lines to +ignore. The left-hand side is a \fIPerl\fR 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 containing a +regular expresssion. (See documentation on \fIPerl\fR for how they +are to be specified in general.) This particular regular expression +specifies that lines beginning with "%%CreationDate: " are to be +ignored in deciding whether a file of the given extension \fI.eps\fR +has changed. + +There is only one regular expression available for each extension. If +you need more one pattern to specify lines to ignore, then you need to +combine the patterns into a single regular expression. 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: |^%%Title: '; + +causes lines starting with either "^%%CreationDate: " or "^%%Title: " +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'}; + +.TP +.B $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 \fI$jobname\fR 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 variety 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 \fI$^O\fR 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. + +.TP +.B $kpsewhich ["kpsewhich %S"] +The program called to locate a source file when the name alone is not +sufficient. Most filenames used by \fIlatexmk\fR have sufficient path +information to be found directly. But sometimes, notably when a .bib +or a .bst file is found from the log file of a \fIbibtex\fR or +\fIbiber\fR run, only the base name of the file is known, but not its +path. The program specified by \fI$kpsewhich\fR is used to find it. + +(\fIFor advanced users:\fR Because of the different way in which +\fIlatexmk\fR uses the command specified in \fI$kpsewhich\fR, some of +the possibilities listed in the FORMAT OF COMMAND SPECIFICATIONS do +not apply. The \fIinternal\fR and \fIstart\fR 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 +commands, "%S" is substituted by a single source file. In contrast, +for \fI$kpsewhich\fR, "%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 \fIlatexmk\fR.) + +See also the \fI@BIBINPUTS\fR variable for another way that \fIlatexmk\fR +also uses to try to locate files; it applies only in the case of .bib +files. +.TP +.B $kpsewhich_show [0] +Whether to show diagnostics about invocations of \fIkpsewhich\fR: the +command line use to invoke it and the results. These diagnostics are +shown if \fI$kpsewhich_show\fR 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 +\fIlatexmk\fR's screen output about invocations of \fIkpsewhich\fR. +.TP +.B $landscape_mode [0] +If nonzero, run in landscape mode, using the landscape mode previewers and +dvi to postscript converters. Equivalent to the \fB-l\fR option. +Normally not needed with current previewers. +.TP +.B $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 \fI$latex\fR, \fI$pdflatex\fR, +\fI$lualatex\fR, and \fI$xelatex\fR, see the section "Advanced +Configuration". + +.TP +.B %latex_input_extensions +This variable specifies the extensions tried by \fIlatexmk\fR when it finds +that a LaTeX run resulted in an error that a file has not been found, +and the file is given without an extension. This typically happens when +LaTeX commands of the form \\input{file} or \\includegraphics{figure}, +when the relevant source file does not exist. + +In this situation, \fIlatexmk\fR searches for custom dependencies to make +the missing file(s), but restricts it to the extensions specified by +the variable %latex_input_extensions. The default extensions +are 'tex' and 'eps'. + +(For Perl experts: %latex_input_extensions is a hash whose keys are +the extensions. The values are irrelevant.) Two subroutines are +provided for manipulating this and the related variable +%pdflatex_input_extensions, add_input_ext and remove_input_ext. They +are used as in the following examples are possible lines in an +initialization file: + + remove_input_ext( 'latex', 'tex' ); + +removes the extension 'tex' from latex_input_extensions + + add_input_ext( 'latex', 'asdf' ); + +add the extension 'asdf to latex_input_extensions. (Naturally with +such an extension, you should have made an appropriate custom +dependency for \fIlatexmk\fR, and should also have done the appropriate +programming in the LaTeX source file to enable the file to be read. +The standard extensions are handled by LaTeX and its graphics/graphicx +packages.) +.TP +.B $latex_silent_switch ["-interaction=batchmode"] +Switch(es) for the LaTeX processing program when silent mode is on. + +If you use MikTeX, you may prefer the results if you configure the +options to include -c-style-errors, e.g., by the following line in an +initialization file + + $latex_silent_switch = "-interaction=batchmode -c-style-errors"; + +.TP +.B $lpr ["lpr %O %S" under UNIX/Linux, \(dqNONE lpr\(dq under MS-Windows] +The command to print postscript files. + +Under MS-Windows (unlike UNIX/Linux), there is no standard program for +printing files. But there are ways you can do it. For example, if +you have \fIgsview\fR installed, you could use it with the option "/p": + + $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p'; + +If \fIgsview\fR is installed in a different directory, you will need to make +the appropriate change. Note the combination of single and double +quotes around the name. The single quotes specify that this is a +string to be assigned to the configuration variable \fI$lpr\fR. The double +quotes are part of the string passed to the operating system to get +the command obeyed; this is necessary because one part of the command +name ("Program Files") contains a space which would otherwise be +misinterpreted. +.TP +.B $lpr_dvi ["NONE lpr_dvi"] +The printing program to print dvi files. +.TP +.B $lpr_pdf ["NONE lpr_pdf"] +The printing program to print pdf files. + +Under MS-Windows you could set this to use \fIgsview\fR, if it is installed, +e.g., + + $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p'; + +If \fIgsview\fR 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 misinterpreted. +.TP +.B $lualatex ["lualatex %O %S"] +Specifies the command line for +the LaTeX processing program that is to be used when the \fIlualatex\fR +program is called for (e.g., by the option \fB-lualatex\fR. + +To do a coordinated setting of all of \fI$latex\fR, \fI$pdflatex\fR, +\fI$lualatex\fR, and \fI$xelatex\fR, see the section "Advanced +Configuration". + +.TP +.B %lualatex_input_extensions +This variable specifies the extensions tried by \fIlatexmk\fR when it finds +that a \fIlualatex\fR run resulted in an error that a file has not been found, +and the file is given without an extension. This typically happens when +LaTeX commands of the form \\input{file} or \\includegraphics{figure}, +when the relevant source file does not exist. + +In this situation, \fIlatexmk\fR searches for custom dependencies to make +the missing file(s), but restricts it to the extensions specified by +the variable %pdflatex_input_extensions. The default extensions +are 'tex', 'pdf', 'jpg, and 'png'. + +See details of the \fI%latex_input_extensions\fR for other information +that equally applies to \fI%lualatex_input_extensions\fR. +.TP +.B $lualatex_silent_switch ["-interaction=batchmode"] +Switch(es) for the \fIlualatex\fR program (specified in the variable +\fI$lualatex\fR) when silent mode is on. + +See details of the \fI$latex_silent_switch\fR for other information +that equally applies to \fI$lualatex_silent_switch\fR. +.TP +.B $make ["make"] +The make processing program. +.TP +.B $makeindex ["makeindex %O -o %D %S"] +The index processing program. +.TP +.B $makeindex_silent_switch ["-q"] +\fBSwitch(es)\fR for the index processing program when silent mode is on. +.TP +.B $max_repeat [5] +The maximum number of times \fIlatexmk\fR will run latex/pdflatex +before deciding that there may be an infinite loop and that it needs +to bail out, rather than rerunning latex/pdflatex again to resolve +cross-references, etc. The default value covers all normal cases. + +(Note that the "etc" covers a lot of cases where one run of +latex/pdflatex generates files to be read in on a later run.) +.TP +.B $MSWin_back_slash [1] +This configuration variable only has an effect when \fIlatexmk\fR 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, \fIlatexmk\fR uses "/" for the directory separator +character, which is the character used by Unix-like systems. + +For many programs under MS-Windows, both "\\" and "/" are acceptable +as the directory separator character. But some programs only accept +"\\" on the command line. So for safety \fIlatexmk\fR 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 software is implemented using Cygwin, which provides +a Unix-like environment inside MS-Windows.) +.TP +.B $new_viewer_always [0] +This variable applies to \fIlatexmk\fR \fBonly\fR in +continuous-preview mode. If \fI$new_viewer_always\fR is 0, +\fIlatexmk\fR will check for a previously running previewer on the +same file, and if one is running will not start a new one. If +\fI$new_viewer_always\fR is non-zero, this check will be skipped, and +\fIlatexmk\fR will behave as if no viewer is running. +.TP +.B $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 \fI$aux_dir\fR. + +The effect of this variable (when non-blank) is achieved by using the +\fB-output-directory\fR 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 versions. + +If you also use the \fB-cd\fR option, and \fI$out_dir\fR (or \fI$aux_dir\fR) contains a +relative path, then the path is interpreted relative to the document +directory. + +Commonly, the directory specified for output files is a subdirectory +of the current working directory. However, if you specify some other +directory, e.g., "/tmp/foo" or "../output", be aware that this could +cause problems, e.g., with \fImakeindex\fR or \fIbibtex\fR. 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 messing with a user's files. If for \fI$out_dir\fR or +\fI$aux_dir\fR 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 \fImakeindex\fR or +\fIbibtex\fR, then you need to disable 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 default "paranoid" setting. +.TP +.B $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 \fIpdflatex\fR, +using the command specified by the \fI$pdflatex\fR variable. +If equal to 2, generate a pdf version of the document from the ps +file, by using the command specified by the \fI$ps2pdf\fR variable. +If equal to 3, generate a pdf version of the document from the dvi +file, by using the command specified by the \fI$dvipdf\fR variable. +If equal to 4, generate a pdf version of the document using \fIlualatex\fR, +using the command specified by the \fI$lualatex\fR variable. +If equal to 5, generate a pdf version (and an xdv version) of the +document using \fIxelatex\fR, using the commands specified by the +\fI$xelatex\fR and \fIxdvipdfmx\fR variables. + +In \fI$pdf_mode\fR=2, it is ensured that .dvi and .ps files are also made. +In \fI$pdf_mode\fR=3, it is ensured that a .dvi file is also made. +But this may be overridden by the document. +.TP +.B $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 \fIlatexmk\fR, you needed to use an assignment +to \fI$pdflatex\fR to allow the use of \fIlualatex\fR or \fIxelatex\fR +instead of \fIpdflatex\fR. There are now separate configuration +variables for the use of \fIlualatex\fR or \fIxelatex\fR. See +\fI$lualatex\fR and \fI$xelatex\fR.) + +To do a coordinated setting of all of \fI$latex\fR, \fI$pdflatex\fR, +\fI$lualatex\fR, and \fI$xelatex\fR, see the section "Advanced +Configuration". +.TP +.B %pdflatex_input_extensions +This variable specifies the extensions tried by \fIlatexmk\fR when it finds +that a \fIpdflatex\fR run resulted in an error that a file has not been found, +and the file is given without an extension. This typically happens when +LaTeX commands of the form \\input{file} or \\includegraphics{figure}, +when the relevant source file does not exist. + +In this situation, \fIlatexmk\fR searches for custom dependencies to make +the missing file(s), but restricts it to the extensions specified by +the variable %pdflatex_input_extensions. The default extensions +are 'tex', 'pdf', 'jpg, and 'png'. + +See details of the \fI%latex_input_extensions\fR for other information +that equally applies to \fI%pdflatex_input_extensions\fR. +.TP +.B $pdflatex_silent_switch ["-interaction=batchmode"] +Switch(es) for the \fIpdflatex\fR program (specified in the variable +\fI$pdflatex\fR) when silent mode is on. + +See details of the \fI$latex_silent_switch\fR for other information +that equally applies to \fI$pdflatex_silent_switch\fR. +.TP +.B $pdf_previewer ["start acroread %O %S"] +The command to invoke a pdf-previewer. + +On MS-Windows, the default is changed to "cmd /c start """; under 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 \fIacroread\fR -- see the notes in the explanation +of the \fB-pvc\fR 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. + +\fBWARNING\fR: 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 \fIlatexmk\fR's +previous-continuous mode (option \fB-pvc\fR) under MS-windows. +This problem does not occur if, for example, \fISumatraPDF\fR or \fIgsview\fR is +used to view pdf files. + +\fBImportant note\fR: Normally you will want to have a previewer run +detached, so that \fIlatexmk\fR doesn't wait for the previewer to +terminate before continuing its work. So normally you should prefix +the command by "start ", which flags to \fIlatexmk\fR that it should +do the detaching of the previewer itself (by whatever method is +appropriate to the operating system). But sometimes letting +\fIlatexmk\fR do the detaching is not appropriate (for a variety of +non-trivial reasons), so you should put the "start " bit in +yourself, whenever it is needed. +.TP +.B $pdf_update_command [""] +When the pdf previewer is set to be updated by running a command, this +is the command that is run. See the information for the variable +\fI$pdf_update_method\fR. +.TP +.B $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 \fI$dvi_update_method\fR +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 \fI$pdf_update_command\fR, and for the +value 2, to specify update by signal, the signal is specified by +\fI$pdf_update_signal\fR.) + +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 updating to be done +in response to a command, and the third setting sets the update command. +.TP +.B $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 +\fI$pdf_update_method\fR. The default value is the one appropriate +for \fIgv\fR on a UNIX system. +.TP +.B $pid_position[1 under UNIX, -1 under MS-Windows] +The variable \fI$pid_position\fR is used to +specify which word in lines of the output from \fI$pscmd\fR +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 \fI$pscmd\fR. + +Setting the variable to -1 is used to indicate that +\fI$pscmd\fR is not to be used. +.TP +.B $postscript_mode [0] +If nonzero, generate a postscript version of the document. +Equivalent to the \fB-ps\fR option. + +If some other request is made for which a postscript file is needed, +then $postscript_mode will be set to 1. +.TP +.B $pre_tex_code [''] + +Sets TeX code to be executed before inputting the source file. This +works if the relevant one of \fI$latex\fR, etc contains a suitable +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 \fI$latex\fR, \fI$pdflatex\fR, \fI$lualatex\fR, and +\fI$xelatex\fR you could use the subroutine \fIalt_tex_cmds\fR: + + &alt_tex_cmds; + $pre_tex_code = '\\AtBeginDocument{An initial message\\par}'; + + +.TP +.B $preview_continuous_mode [0] +If nonzero, run a previewer to view the document, and +continue running \fIlatexmk\fR to keep .dvi up-to-date. Equivalent to +the \fB-pvc\fR option. +Which previewer is run depends on the other settings, see the command +line options \fB-view=\fR, and the variable \fI$view\fR. +.TP +.B $preview_mode [0] +If nonzero, run a previewer to preview the document. +Equivalent to the \fB-pv\fR option. +Which previewer is run depends on the other settings, see the command +line options \fB-view=\fR, and the variable \fI$view\fR. +.TP +.B $printout_mode [0] +If nonzero, print the document using the command specified in the +\fI$lpr\fR variable. Equivalent to the +\fB-p\fR option. This is recommended \fBnot\fR to be set from an RC +file, otherwise you could waste lots of paper. +.TP +.B $print_type = ["auto"] +Type of file to printout: possibilities are "auto", "dvi", "none", +"pdf", or "ps". See the option \fB-print=\fR for the meaning of the +"auto" value. +.TP +.B $pscmd +Command used to get all the processes currently run by the user. The +-pvc option uses the command specified by the variable \fI$pscmd\fR to +determine if there is an already running previewer, and to find the +process ID (needed if \fIlatexmk\fR needs to signal the previewer +about file changes). + +Each line of the output of this command is assumed to correspond to +one process. See the \fI$pid_position\fR variable for how the process +number is determined. + +The default for \fIpscmd\fR 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 substituted by the username. +.TP +.B $ps2pdf ["ps2pdf %O %S %D"] +Command to convert .ps to .pdf file. +.TP +.B $ps_filter [empty] +The postscript file filter to be run on the newly produced postscript +file before other processing. Equivalent to specifying the \fB-pF\fR +option. +.TP +.B $ps_previewer ["start gv %O %S", but "start %O %S" under MS-Windows] +The command to invoke a ps-previewer. (The default under MS-Windows +will cause to be run whatever command the system has associated +with .ps files.) + +Note that \fIgv\fR could be used with the -watch option updates its display +whenever the postscript file changes, whereas ghostview does not. +However, different versions of \fIgv\fR have slightly different ways of +writing this option. You can configure this variable appropriately. + +\fBWARNING\fR: Linux systems may have installed one (or more) versions +of \fIgv\fR under different names, e.g., \fIggv\fR, \fIkghostview\fR, +etc, but perhaps not one actually called \fIgv\fR. + +\fBImportant note\fR: Normally you will want to have a previewer run +detached, so that \fIlatexmk\fR doesn't wait for the previewer to +terminate before continuing its work. So normally you should prefix +the command by "start ", which flags to \fIlatexmk\fR that it should +do the detaching of the previewer itself (by whatever method is +appropriate to the operating system). But sometimes letting +\fIlatexmk\fR do the detaching is not appropriate (for a variety of +non-trivial reasons), so you should put the "start " bit in +yourself, whenever it is needed. + +.TP +.B $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. +.TP +.B $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 +\fI$ps_update_method\fR. +.TP +.B $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 \fI$dvi_update_method\fR +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 \fI$ps_update_command\fR, and for the +value 2, to specify update by signal, the signal is specified by +\fI$ps_update_signal\fR.) +.TP +.B $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 \fI$ps_update_method\fR. The +default value is the one appropriate for gv on a UNIX system. +.TP +.B $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 +\fIlatexmk\fR has detected no file changes and hence has not taken any +actions like compiling the document. The period of inactivity is in +the variable $pvc_timeout_mins. + +.TP +.B $pvc_timeout_mins [30] +The period of inactivity, in minutes, after which pvc mode times out. +This is used if \fI$pvc_timeout\fR is nonzero. +.TP +.B $pvc_view_file_via_temporary [1] +The same as \fI$always_view_file_via_temporary\fR, except that it only +applies in preview-continuous mode (-pvc option). +.TP +.B $quote_filenames [1] +This specifies whether substitutions for placeholders in command +specifications (as in \fI$pdflatex\fR) 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 \fIlatexmk\fR 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 \fIlatex\fR and \fIpdflatex\fR cannot +correctly deal with TeX files whose names contain spaces. \fILatexmk\fR's +quoting only ensures that such filenames are correctly treated by the +operating system in passing arguments to programs.) +.TP +.B $recorder [1] +Whether to use the \fB-recorder\fR option to \fIlatex\fR and +\fIpdflatex\fR. Use of this option results in a file of extension +\fI.fls\fR containing a list of the files that these programs have +read and written. \fILatexmk\fR will then use this file to improve +its detection of source files and generated files after a run of +\fIlatex\fR or \fIpdflatex\fR. + +It is generally recommended to use this option (or to configure the +\fI$recorder\fR variable to be on.) But it only works if +\fI(pdf)latex\fR supports the -recorder option, which is true for most +current implementations + +\fINote about the name of the .fls file:\fR Most implementations of +\fI(pdf)latex\fR 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, \fIlatexmk\fR copies the latex.fls or pdflatex.fls to a +file with the basename of the main LaTeX document, e.g., Document.fls. +.TP +.B $search_path_separator [See below for default] +The character separating paths in the environment variables TEXINPUTS, +BIBINPUTS, and BSTINPUTS. This variable is mainly used by +\fIlatexmk\fR when the \fB-outdir\fR, \fB-output-directory\fR, +\fB-auxdir\fR, and/or \fB-aux-directory\fR options are used. In that +case \fIlatexmk\fR needs to communicate appropriately modified search +paths to \fIbibtex\fR, \fIdvipdf\fR, \fIdvips\fR, and +\fI(pdf)latex\fR. + +[Comment to technically savvy readers: \fI(pdf)latex\fR doesn't +actually need the modified search path. But, surprisingly, +\fIdvipdf\fR and \fIdvips\fR 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 difficulties if your +operating system is of one kind, but some of your software is running +under an emulator for the other kind of operating system; in that case +you'll need to find out what is needed, and set +\fI$search_path_separator\fR explicitly. (The same goes, of course, +for unusual operating systems that are not in the MSWin, Linux, OS-X, +Unix collection.) +.TP +.B $show_time [0] +Whether to show CPU time used. +.TP +.B $silence_logfile_warnings [0] +Whether after a run of (pdf)latex to summarize warnings in the log +file about undefined citations and references. Setting +$silence_logfile_warnings=0 gives the summary of warnings (provided +silent mode isn't also set), and this is useful to locate undefined +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 +\fB-silence_logfile_warning_list\fR and +\fB-silence_logfile_warning_list-\fR 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 warning. +.TP +.B $silent [0] +Whether to run silently. Setting $silent to 1 has the same effect as +the \fB-quiet\fR of \fB-silent\fR options on the command line. +.TP +.B $sleep_time [2] +The time to sleep (in seconds) between checking for source file +changes when running with the \fB-pvc\fR option. This is subject to a +minimum of one second delay, except that zero delay is also allowed. + +A value of exactly 0 gives no delay, and typically results in 100% CPU +usage, which may not be desirable. +.TP +.B $texfile_search [""] +This is an obsolete variable, replaced by the \fI@default_files\fR +variable. + +For backward compatibility, if you choose to set +\fI$texfile_search\fR, it is a string of space-separated filenames, and +then \fIlatexmk\fR replaces \fI@default_files\fR with the filenames in +\fI$texfile_search\fR to which is added "*.tex". +.TP +.B $success_cmd [undefined] +See the documentation for $compiling_cmd. +.TP +.B $tmpdir [See below for default] +Directory to store temporary files that \fIlatexmk\fR may generate while +running. + +The default under MSWindows (including cygwin), is to set +\fI$tmpdir\fR to the value of the first of whichever of the system +environment variables TMPDIR or TEMP exists, otherwise to the current +directory. Under other operating systems (expected to be UNIX/Linux, +including OS-X), the default is the value of the system environment +variable TMPDIR if it exists, otherwise "/tmp". +.TP +.B $use_make_for_missing_files [0] +Whether to use \fImake\fR to try and make files that are missing after +a run of \fIlatex\fR or \fIpdflatex\fR, and for which a custom +dependency has not been found. This is generally useful only when +\fIlatexmk\fR is used as part of a bigger project which is built by +using the \fImake\fR program. + +Note that once a missing file has been made, no further calls to +\fImake\fR will be made on a subsequent run of \fIlatexmk\fR to update +the file. Handling this problem is the job of a suitably defined +Makefile. See the section "USING \fIlatexmk\fR WITH \fImake\fR" for +how to do this. The intent of calling \fImake\fR from \fIlatexmk\fR +is merely to detect dependencies. +.TP +.B $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). + +.TP +.B $warnings_as_errors [0] +Normally \fIlatexmk\fR copies the behavior of \fIlatex\fR in treating +undefined references and citations and multiply defined references as +conditions that give a warning but not an error. The variable +\fI$warnings_as_errors\fR controls whether this behavior is modified. + +When the variable is non-zero, \fIlatexmk\fR 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 \fBafter\fR \fIlatexmk\fR has completed +all the runs it needs to try and resolve references and citations. +Thus \fI$warnings_as_errors\fR being nonzero causes \fIlatexmk\fR to +treat such warnings as errors, but only when they occur on the last +run of (pdf)latex and only after processing is complete. A non-zero +value \fI$warnings_as_errors\fR can be set by the command-line option +\fB-Werror\fR. + +The default behavior is normally satisfactory in the usual +edit-compile-edit cycle. But, for example, \fIlatexmk\fR 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 warnings as +errors that require the overall build process to be aborted. Of +course, since multiple runs of (pdf)latex are generally needed to +resolve references and citations, what matters is \fInot\fR the +warnings on the first run, but the warnings on the \fIlast\fR run; +\fIlatexmk\fR takes this into account appropriately. + +In addition, when preview-continuous mode is used, a non-zero value +for \fI$warnings_as_errors\fR changes the use of the commands +\fI$failure_cmd\fR, \fI$warning_cmd\fR, and \fI$success_cmd\fR after a +compliation. If there are citation or reference warnings, but no +other errors, the behavior is as follows. If \fI$warning_cmd\fR is +set, it is used. If it is not set, then then if +\fI$warnings_as_errors\fR is non-zero and \fI$failure_cmd\fR is set, +then \fI$failure_cmd\fR. Otherwise \fI$success_cmd\fR is used, if it +is set. (The foregoing explanation is rather complicated, because +\fIlatexmk\fR has to deal with the case that one or more of the +commands isn't set.) + +.TP +.B $xdvipdfmx ["xdvipdfmx -o %D %O %S"] + +The program to make a pdf file from an xdv file (used in conjunction +with \fIxelatex\fR when \fI$pdf_mode\fR=5). +.TP +.B $xdvipdfmx_silent_switch ["-q"] +Switch(es) for the \fIxdvipdfmx\fR program when silent mode is on. +.TP +.B $xelatex ["xelatex %O %S"] +Specifies the command line for +the LaTeX processing program of +when the \fIxelatex\fR program is called for. See the +documentation of the \fB-xelatex\fR option for some special properties +of \fIlatexmk\fR's use of \fIxelatex\fR. + +\fINote about xelatex\fR: Now \fIlatexmk\fR uses \fIxelatex\fR 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 \fB-no-pdf\fR +option. If %O is part of the command for invoking \fIxelatex\fR, then +\fIlatexmk\fR will insert the \fB-no-pdf\fR option automatically, +otherwise you must provide the option yourself + +To do a coordinated setting of all of \fI$latex\fR, \fI$pdflatex\fR, +\fI$lualatex\fR, and \fI$xelatex\fR, see the section "Advanced +Configuration". + +.TP +.B %xelatex_input_extensions +This variable specifies the extensions tried by \fIlatexmk\fR when it finds +that an \fIxelatex\fR run resulted in an error that a file has not been found, +and the file is given without an extension. This typically happens when +LaTeX commands of the form \\input{file} or \\includegraphics{figure}, +when the relevant source file does not exist. + +In this situation, \fIlatexmk\fR searches for custom dependencies to make +the missing file(s), but restricts it to the extensions specified by +the variable %xelatex_input_extensions. The default extensions +are 'tex', 'pdf', 'jpg, and 'png'. + +See details of the \fI%latex_input_extensions\fR for other information +that equally applies to \fI%xelatex_input_extensions\fR. +.TP +.B $xelatex_silent_switch ["-interaction=batchmode"] +Switch(es) for the \fIxelatex\fR program (specified in the variable +\fI$xelatex\fR) when silent mode is on. + +See details of the \fI$latex_silent_switch\fR for other information +that equally applies to \fI$xelatex_silent_switch\fR. + + + +.SH CUSTOM DEPENDENCIES +.PP +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 \fIlatexmk\fR to convert a \fI.fig\fR file to +\fI.eps\fR to be included in the \fI.tex\fR file. + +.SS Defining a custom dependency: +The old method of configuring \fIlatexmk\fR to use a custom dependency +was to directly manipulate the \fI@cus_dep_list\fR 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 +manipulations 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: +.TP +.B from extension: +The extension of the file we are converting from (e.g. "fig"). +It is specified without a period. +.TP +.B to extension: +The extension of the file we are converting to (e.g. "eps"). +It is specified without a period. +.TP +.B must: +If non-zero, the file from which we are converting \fBmust\fR exist, if it +doesn't exist \fIlatexmk\fR will give an error message and exit unless +the \fB-f\fR option is specified. If \fImust\fR is zero and the file +we are converting from doesn't exist, then no action is taken. +Generally, the appropriate value of \fImust\fR is zero. +.TP +.B function: +The name of the subroutine that \fIlatexmk\fR 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 \fIPerl\fR. The function should return 0 if +it was successful and a nonzero number if it failed. + +.PP + +Naturally \fIadd_cus_dep\fR 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 \fIremove_cus_dep\fR removes the specified custom +dependency. The subroutine \fIshow_cus_dep\fR causes a list of the +currently defined custom dependencies to be sent to the screen +output. + +.SS How custom dependencies are used: +An instance of a custom dependency rule is created whenever +\fIlatexmk\fR detects that a run of latex/pdflatex needs to read a +file, like a graphics file, whose extension is the to-extension of a +custom dependency. Then \fIlatexmk\fR examines whether a file exists +with the same name, but with the corresponding from-extension, as +specified in the custom-dependency. If it does, then a corresponding +instance of the custom dependency is created, after which the rule is +invoked whenever the destination file (the one with the to-extension) +is out-of-date with respect to the corresponding source file. + +To make the new destination file, the \fIPerl\fR 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 \fIPerl\fR 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 \fIlatex\fR reports that an input file (e.g., a graphics file) +does not exist, \fIlatexmk\fR 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 \fIlatex\fR etc will be +able to read the newly created file. + +\fINote for advanced usage\fR: The operating system's environment +variable TEXINPUTS can be used to specify a search path for finding +files by \fIlatex\fR etc. Correspondingly, when a missing file is +reported, \fIlatexmk\fR looks in the directories specified in +TEXINPUTS as well as in the current directory, to find a source file +from which an instance of a custom dependency can be used to make the +missing file. + +.SS 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 +destination 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 +extension "fig", as created by the \fIxfig\fR program, to an encapsulated +postscript file, with extension "eps". The remaining lines define a +subroutine 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 \fIlatexmk\fR will delete this rule before +making the new one. + +Suppose \fIlatexmk\fR 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 \fIPerl\fR as $_[0]. In +the example above, the subroutine uses the \fIPerl\fR command system +to invoke the program fig2dev. The double quotes around the string +are a \fIPerl\fR idiom that signify that each string of the form of a +variable name, $_[0] in this case, is to be substituted by its value. + +If the return value of the subroutine is non-zero, then \fIlatexmk\fR +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 \fIpdflatex\fR instead of latex, then you will probably prefer to +convert your graphics files to pdf format, in which case you would +replace the above code in an initialization file by + + add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' ); + sub fig2pdf { + system( "fig2dev -Lpdf \\"$_[0].fig\\" \\"$_[0].pdf\\"" ); + } + +\fBNote 1:\fR In the command lines given in the system commands in the +above examples, double quotes have been inserted around the file names +(implemented by '\\"' \" " COMMENT TO FOOL EDITOR INTO MATCHING DOUBLE QUOTES +in the Perl language). They immunize the running +of the program against special characters in filenames. Very often +these quotes are not necessary, i.e., they can be omitted. But it is +normally safer to keep them in. Even though the rules for quoting +vary between operating systems, command shells and individual pieces +of software, the quotes in the above examples do not cause problems in +the cases I have tested. + +\fBNote 2:\fR 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 +\'\\'. Forward slashes are generated by \fIlatexmk\fR, 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.) + +\fBNote 3:\fR The subroutines implementing custom dependencies in the +examples 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. + +.SS Removing custom dependencies, and when you might need to do this: +If you have some general custom dependencies defined in the system or +user initialization file, you may find that for a particular project +they are undesirable. So you might want to delete the unneeded ones. +A situation where this would be desirable is where there are multiple +custom dependencies with the same from-extension or the same +to-extension. In that case, \fIlatexmk\fR 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. + +.SS 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 \fIlatexmk\fR, and many examples can be found, e.g., on +the web. + +However in later versions of \fIlatexmk\fR the internal structure of +the implementation of its "rules" for the steps of processing, +including custom 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 \fIlatexmk\fR 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. \fILatexmk\fR 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 +\fIlatexmk\fR to convert files with the extension \fI.ndx\fR to +\fI.nnd\fR. 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 +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 +\fIRun_subst\fR 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 \fI$makeindex\fR, +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 \fI.ndx\fR file is written during a run of +latex/pdflatex and is always later than the \fI.nnd\fR last read in. +Thus the \fI.nnd\fR appears to be perpetually out-of-date. This +situation, of circular dependencies, is endemic to latex, and is one +of the issues that \fIlatexmk\fR 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 \fI.nnd\fR (or the +\fI.aux\fR file, etc) that changes on each new run, then you will have +a problem. For real experts: See the \fI%hash_cal_ignore_pattern\fR +if you have to deal with such problems. + +.SS Old Method of Defining Custom Dependencies: +In much older versions of \fIlatexmk\fR, the only method of defining +custom dependencies was to directly manipulate the table of custom +dependencies. This is contained in the \fI@cus_dep_list\fR array. It +is an array of strings, and each string in the array has four items in +it, each separated by a space, the from-extension, the to-extension, +the "must" item, and the name of the subroutine for the custom +dependency. These were all defined above. +.PP +An example of the old method of defining custom dependencies is as +follows. It is the code in an RC file to ensure automatic conversion +of \fI.fig\fR files to \fI.eps\fR 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 \fIadd_cus_dep\fR subroutine. However, the old +method doesn't delete any previous custom-dependency for the same +conversion. So the new method is preferable. + + +.SH ADVANCED CONFIGURATION: Some extra resources and advanced tricks + +For most purposes, simple configuration for \fIlatexmk\fR along the +lines of the examples given is sufficient. But sometimes you need +something harder. In this section, I indicate some extra +possibilities. Generally 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 \fIexample_rcfiles\fR in the +\fIlatexmk\fR distributions. Even if none of the examples apply to +your case, they may give you useful ideas + +.SS Utility subroutines + +.TP +.B ensure_path( var, values ...) + +The first parameter is the name of one of the system's environment +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 +\fI$search_path_separator\fR. + +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 specified +directory and in all subdirectories.) + +Technically \fIensure_path\fR works by setting Perl's variable +\fI$ENV{var}\fR, where \fIvar\fR is the name of the target variable. +The changed value is then passed as an environment variable to any +invoked programs. + +.SS 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 "internal" -- 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 +\fIlatexmk\fR'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. Generally, 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 \fIlatexmk\fR is doing. +.TP +.B $rule +This variable has the name of the rule, as known to +\fIlatexmk\fR. Note that the exact contents of this variable for a +given rule may be dependent on the version of \fIlatexmk\fR +.TP +.B $$Psource +This gives the name of the primary source file. Note the double +dollar signs. +.TP +.B $$Pdest +This gives the name of the main output file if any. Note the double +dollar signs. +.TP +.B 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 \fIlatexmk\fR should know, but its default +methods don't find the dependency. Almost always the first argument is +the name of the rule currently being processed, so it is then +appropriate to specify it by \fI$rule\fR. + +For examples of its use, see some of the files in the directory +\fIexample_rcfiles\fR of \fIlatexmk\fR's distribution. Currently the +cases that use this subroutine are \fIbib2gls-latexmkrc\fR, +\fIexceltex_latexmkrc\fR and \fItexinfo-latexmkrc\fR. These +illustrate typical cases where \fIlatexmk\fR's normal processing fails +to detect certain extra source files. +.TP +.B rdb_remove_files( $rule, file, ... ) +This subroutine removes one or more files from the dependency list for +the given rule. +.TP +.B rdb_list_source( $rule ) +This subroutine returns the list of source files (i.e., the dependency +list) for the given rule. +.TP +.B rdb_set_source( $rule, file, ... ) +.TP +.B 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 dependency list. +.TP +.B Run_subst( command_spec ) +This subroutine runs the command specified by \fIcommand_spec\fR. The +specification is a string in the format listed in the section "Format +of Command Specifications". An important action of the +\fIRun_subst\fR is to make substitutions of placeholders, e.g., %S and +%D for source and destination files; these get substituted before the +command is run. In addition, the command after substitution is +printed to the screen unless \fIlatexmk\fR is running in silent mode. + +.PP + + +.SS Coordinated Setting of Commands for *latex + +To set all of \fI$latex\fR, \fI$pdflatex\fR, \fI$lualatex\fR, and +\fI$xelatex\fR 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 \fI$latex = 'latex %O %S'\fR, and similarly for +\fI$pdflatex\fR, \fI$lualatex\fR, and \fI$xelatex\fR. Note the +ampersand in the invocation; this indicates to Perl that a subroutine +is being called. + + &alt_tex_cmds; + +This results in \fI$latex = 'latex %O %P'\fR, and similarly for +\fI$pdflatex\fR, \fI$lualatex\fR, and \fI$xelatex\fR. 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 +results in \fI$latex = 'CMD_SPEC'\fR, and similarly for +\fI$pdflatex\fR, \fI$lualatex\fR, and \fI$xelatex\fR. An example would +be + + set_tex_cmds( '--interaction=batchmode %O %S' ); + +.PP + +.SS Advanced configuration: Using \fIlatexmk\fB with \fImake\fR + +This section is targeted only at advanced users who use the \fImake\fR +program for complex projects, as for software development, with the +dependencies specified by a Makefile. + +Now the basic task of \fIlatexmk\fR is to run the appropriate programs +to make a viewable version of a LaTeX document. However, the usual +\fImake\fR 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 \fImake\fR program. Second is that in a large document +the set of source files can change quite frequently, particularly with +included graphics files; in this situation keeping a Makefile manually +updated is inappropriate and error-prone, especially when the +dependencies can be determined automatically. \fILatexmk\fR solves +both of these problems robustly. + +Thus for many standard LaTeX documents \fIlatexmk\fR can be used by +itself without the \fImake\fR program. In a complex project it simply +needs to be suitably configured. A standard configuration would be to +define custom dependencies to make graphics files from their source +files (e.g., as created by the \fIxfig\fR program). Custom +dependencies are \fIlatexmk\fR'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 \fIlatexmk\fR from a Makefile. A +typical example would be to generate documentation for a software +project. Potentially the interaction with the rest of the rules in +the Makefile could be quite complicated, for example if some of the +source files for a LaTeX document are generated by the project's +software. + +In this section, I give a couple of examples of how \fIlatexmk\fR can +be usefully invoked from a Makefile. The examples use specific +features of current versions of GNU \fImake\fR, which is the default +on both linux and OS-X systems. They may need modifications for other +versions of \fImake\fR. + +The simplest method is simply to delegate all the relevant tasks to +\fIlatexmk\fR, 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 +\fIlatexmk\fR 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 \fIlatexmk\fR in the obvious way. +There is a conventional default target named "all", with a +prerequisite of try.pdf. So when \fImake\fR 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 \fIlatexmk\fR to be +invoked. Instead, the pattern 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 \fIlatexmk\fR is always run. It is +\fIlatexmk\fR that decides whether any action is needed, e.g., a rerun +of \fIpdflatex\fR. Effectively the Makefile delegates all decisions +to \fIlatexmk\fR, while \fImake\fR 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 \fIlatexmk\fR. + +But something better is needed in more complicated situations, for +example, when the making of graphics files needs to be specified by +rules in the Makefile. To do this, one can use a Makefile like the +following: + + TARGETS = document1.pdf document2.pdf + DEPS_DIR = .deps + LATEXMK = latexmk -recorder -use-make -deps \\ + -e 'warn qq(In Makefile, turn off custom 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 +\fIautomake\fR handles automatic dependency tracking of C source +files. + +After each run of \fIlatexmk\fR, dependency information is put in a file +in the .deps subdirectory. The Makefile causes these dependency files +to be read by \fImake\fR, 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 dependency 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 \fIxfig\fR program; +these are commonly used for graphics insertions in LaTeX documents. +\fILatexmk\fR is arranged to output a dependency file after each run. +It is given the \fB-recorder\fR option, which improves its detection +of files generated during a run of \fIpdflatex\fR; such files should +not be in the dependency list. The \fB-e\fR options are used to turn +off all custom dependencies, and to document this. Instead the +\fB-use-make\fR is used to delegate the making of missing files to +\fImake\fR itself. + +Suppose in the LaTeX file there is a command \\includegraphics{graph}, +and an \fIxfig\fR file "graph.fig" exists. On a first run, +\fIpdflatex\fR reports a missing file, named "graph". \fILatexmk\fR +succeeds in making "graph.pdf" by calling "make graph.pdf", and after +completion of its work, it lists "fig.pdf" among the dependents of the +file \fIlatexmk\fR is making. Then let "fig.fig" be updated, and then +let \fImake\fR be run. \fIMake\fR first remakes "fig.pdf", and only +then reruns \fIlatexmk\fR. + +Thus we now have a method by which all the subsidiary processing is +delegated to \fImake\fR. + +.SH SEE ALSO +latex(1), bibtex(1), lualatex(1), pdflatex(1), xelatex(1). +.SH 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 +previewers and update methods. + +(The following isn't really a bug, but concerns features of previewers.) +Preview continuous mode only works perfectly with certain previewers: +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 \fIlatexmk\fR to use +\fIsumatrapdf\fR instead.) +.SH THANKS TO +Authors of previous versions. Many users with their feedback, and +especially +David Coppit (username david at node coppit.org) who made many useful +suggestions that contributed to version 3, and Herbert Schulz. +(Please note that the +e-mail addresses are not written in their standard form to avoid being +harvested too easily.) +.SH 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/>. +.br +Modifications and enhancements by Evan McLean (Version 2.0) +.br +Original script called "go" by David J. Musliner (RCS Version 3.2) + +\" LocalWords: fR fIlatexmk dvi ps fILatexmk pdflatex bibtex makeindex fB pv +\" LocalWords: pvc fIgv xdvi gsview cygwin fdb TP tex bm bs fIlatex fIbibtex +\" LocalWords: gg regeneratable dep exts dF dviF dviselect fI fR's lpr pdfps +\" LocalWords: pdfdvi dvipdf pF psF psnup fIsome gv acroread xpdf rcfile cus +\" LocalWords: batchmode latexmkrc elatex basename texfile WinXP BIBINPUTS +\" LocalWords: kpsewhich BibTeX dtx dvipdfm dvips fpTeX MikTeX fBWARNING pid +\" LocalWords: pscmd fIlpr fBnot ENV OSX SIGHUP tmpdir MSWindows tmp eps dev +\" LocalWords: fImust fIperl Lps fIfig |