diff options
author | Karl Berry <karl@freefriends.org> | 2017-01-17 22:27:02 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2017-01-17 22:27:02 +0000 |
commit | 78ef96dc26db9e148bed61c4120e21ae8b034e4b (patch) | |
tree | 43c2e78fa86c7d94a698d1fd42b5355c01787646 /Master/texmf-dist/doc/man/man1/latexmk.1 | |
parent | c8ec67e7148b3e55dcc223df363e08720fe43a32 (diff) |
latexmk (17jan17)
git-svn-id: svn://tug.org/texlive/trunk@42982 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/man/man1/latexmk.1')
-rw-r--r-- | Master/texmf-dist/doc/man/man1/latexmk.1 | 647 |
1 files changed, 376 insertions, 271 deletions
diff --git a/Master/texmf-dist/doc/man/man1/latexmk.1 b/Master/texmf-dist/doc/man/man1/latexmk.1 index e2af193039b..e5b389b1c5b 100644 --- a/Master/texmf-dist/doc/man/man1/latexmk.1 +++ b/Master/texmf-dist/doc/man/man1/latexmk.1 @@ -1,4 +1,4 @@ -.TH LATEXMK 1L "5 September 2016" "" +.TH LATEXMK 1 "16 January 2017" "" .SH NAME latexmk \- generate LaTeX document .SH SYNOPSIS @@ -42,7 +42,7 @@ 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. In the simple +\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 @@ -53,14 +53,14 @@ The second previewing option is the powerful \fB-pvc\fR option 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 (like \fIgv\fR) will then automatically update its +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 possibly the .ps and .pdf) file, and refreshing +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 (some versions of \fIxdvi\fR and +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 @@ -71,17 +71,16 @@ generated dvi and postscript files. (See the options \fB-dF\fR and \fI$ps_filter\fR configuration variables.) These capabilities are leftover from older versions of \fIlatexmk\fR. More flexibility can be obtained in current versions, since the command strings for running -latex, pdflatex, etc can now be configured to run multiple commands. -This also extends the possibility of postprocessing generated files to -pdf files. -files. +\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 (notably Solaris). +other UNIX systems. .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 @@ -91,7 +90,7 @@ LaTeX suffices, and often the log file contains a message about the need for another pass. However, there is a wide variety of add-on macro packages to LaTeX, with a variety of behaviors. The result is to break simple-minded determinations of how many runs are needed and -of which programs. In its new version, \fIlatexmk\fR has a highly +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 @@ -123,19 +122,17 @@ 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 like \fIpdflatex\fR, i.e., they make a pdf file from a +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-pdflatex="COMMAND"\fR, -\fB-lualatex\fR, and -\fB-xelatex\fR, +\fB-pdflua\fR, \fB-pdfxe\fR, \fB-lualatex\fR, and \fB-xelatex\fR, and also see the documentation for the -\fI$pdflatex\fR configuration variable. -At present \fIlatexmk\fR cannot do automatic detection of which -program is to be used. +\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 @@ -402,7 +399,8 @@ requested.) .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 +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. @@ -417,11 +415,11 @@ 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 +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 +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 @@ -439,7 +437,12 @@ or latexmk -e "$latex='latex %O -shell-escape %S'" file.tex -The last two examples will NOT work with UNIX/LINUX command shells. +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 @@ -517,20 +520,37 @@ 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 pdflatex (rather than the command for -latex) see the \fB-pdflatex\fR option. +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). -Note that the effect of this option can also be achieved by using -the \fB-e\fR option with a suitable line of Perl code to set the -\fI$latex\fR variable. See the explanation of the \fB-e\fR option. +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 lualatex. That is, use lualatex to process the source file(s) to -pdf (in place of pdflatex). This option is exactly equivalent to -specifying the following sequence of options: +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- - -pdflatex="lualatex %O %S" -pdf -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 @@ -544,10 +564,10 @@ write it to. .TP .B -MP -If a list of dependents is made, includes phony target for each source +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 make gives if you remove header files without -updating the Makefile to match. +work around errors the program \fImake\fR gives if you remove header +files without updating the Makefile to match. .TP .B -new-viewer @@ -567,14 +587,7 @@ an already-running previewer. .TP .B -nobibtex -Never run bibtex or biber. - -A common use for this option is when a document comes from an external -source, complete with its bbl file(s), and the user does not have the -corresponding bib files available. In this situation use of the -\fB-nobibtex\fR option will prevent \fIlatexmk\fR from trying to run -\fIbibtex\fR or \fIbiber\fR, which would result in overwriting of the -bbl files. +Never run bibtex or biber. Equivalent to the \fB-bibtex-\fR option. .TP .B -norc @@ -613,7 +626,7 @@ But you can use the 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, +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 @@ -630,7 +643,8 @@ so it turns them off. .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-lualatex\fR or \fB-xelatex\fR applies.) To configure +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". @@ -639,9 +653,28 @@ options \fB-lualatex\fR or \fB-xelatex\fR applies.) To configure 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 -ps2pdf. +\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 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.) .TP .B -pdf- @@ -652,7 +685,7 @@ a pdf file.) .TP .B -pdflatex="COMMAND" -This sets the string specifying the command to run pdflatex, and is +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., @@ -664,24 +697,9 @@ operating system and the command-line shell you are using, you may need to change the single quotes to double quotes (or something else). -This option can also be used to set a program to be used instead of -the standard \fIpdflatex\fR program, e.g., - - latexmk -pdf -pdflatex="lualatex %O %S" foo.tex - -to use \fIlualatex\fR or - - latexmk -pdf -pdflatex="xelatex %O %S" foo.tex - -to use \fIxelatex\fR. - To set the command for running \fIlatex\fR (rather than the command for \fIpdflatex\fR) see the \fB-latex\fR option. -Note that the effect of this option can also be achieved by using -the \fB-e\fR option with a suitable line of Perl code to set the -\fI$pdflatex\fR variable. See the explanation of the \fB-e\fR option. - .TP .B -print=dvi, -print=ps, -print=pdf, -print=auto, Define which kind of file is printed. This option also ensures that @@ -764,11 +782,11 @@ 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: SumatraPDF and gsview are -good possibilities. +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 xdvi and xpdf. These are best set in +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 @@ -812,19 +830,20 @@ the order they appear on the command line. .TP .B -recorder -Use the -recorder option with \fIlatex\fR and \fIpdflatex\fR. In +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. +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 use the -recorder option with \fIlatex\fR and \fIpdflatex\fR. +Do not supply the -recorder option with \fIlatex\fR and \fIpdflatex\fR. .TP .B -rules @@ -838,9 +857,9 @@ processing. (This is the default.) .TP .B -showextraoptions Show the list of extra \fIlatex\fR and \fIpdflatex\fR options that -\fIlatexmk\fR recognizes. These are options for the \fIlatex\fR and -\fIpdflatex\fR that \fIlatexmk\fR recognizes, but simply passes -through to these programs when they are run. These options are +\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 @@ -869,49 +888,46 @@ documentation. These options are: \fB-output-directory=DIR\fR, \fB-quiet\fR, and \fB-recorder\fR. .TP -.B -logfilewarninglist -.B -logfilewarnings -After a run of (pdf)latex, give a list of warnings about -undefined citations and references (unless silent mode is on). - -See also the $silence_logfile_warnings configuration variable. - -.TP -.B -logfilewarninglist- -.B -logfilewarnings- -After a run of (pdf)latex, do not give a list of warnings about -undefined citations and references. (Default) - -See also the $silence_logfile_warnings configuration variable. - -.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 latex. +command "latex -interaction=batchmode" is used for \fI(pdf)latex\fR +and friends. See also the \fB-logfilewarninglist\fR and \fB-logfilewarninglist-\fR options. Also reduce the number of informational messages that \fIlatexmk\fR -generates. +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$makeindex_silent_switch\fR, and \fI$pdflatex_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 -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), \fIlatexmk\fR tries to make them by a custom +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 -use-make option is set, then -\fIlatexmk\fR will try as a resort using the make program to try to -make the missing files. +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, @@ -938,20 +954,32 @@ Opposite of \fB-silent\fR. This is the default setting. .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 order dvi, ps, pdf). +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 want a previewer to be opened. +whenever source file(s) change, but do not want a previewer to be opened. .TP .B -xelatex -Use xelatex. That is, use xelatex to process the source file(s) to -pdf (in place of pdflatex). This option is exactly equivalent to -specifying the following sequence of options: +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.] - -pdflatex="xelatex %O %S" -pdf -dvi- -ps- .PP \fBCompatibility between options\fR @@ -977,7 +1005,7 @@ each of these options turns the others off. uses. After any changes rerun latex the appropriate number of times and remake the postscript file. If latex - encounters an error, latexmk will + encounters an error, \fIlatexmk\fR will keep running, watching for source file changes. @@ -1015,7 +1043,7 @@ particular situations. (But there is a lot of reading!) difficult situations.\fR d. Further tricks can involve replacing the standard commands that -\fIlatexmk\fR by other commands or scripts. +\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., @@ -1043,13 +1071,13 @@ different name, change bar.baz to the name of your file. g. See also the section \fBADVANCED CONFIGURATION: Some extra resources\fR. -g. Look on tex.stackexchange, i.e., at +h. Look on tex.stackexchange, i.e., at http://tex.stackexchange.com/questions/tagged/latexmk Someone may have already solved your problem. -h. Ask a question at tex.stackexchange.com. +i. Ask a question at tex.stackexchange.com. -i. Or ask me (the author of \fIlatexmk\fR). My e-mail is at the end +j. Or ask me (the author of \fIlatexmk\fR). My e-mail is at the end of this documentation. @@ -1064,14 +1092,15 @@ 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 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 for the first it finds of +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 + +In addition, it then tries the same set of locations, but with the file name replaced "LatexMk" replaced by "latexmkrc". .PP 2) The user's RC file, if it exists. This can be in one of two @@ -1087,7 +1116,7 @@ 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 +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 @@ -1104,7 +1133,8 @@ and \fIlatexmk\fR does not look for an RC file under it. 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. +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 @@ -1123,7 +1153,7 @@ overridden by later options on the command line. There is also the \fI For possible examples of code for in an RC file, see the directory -example_rcfiles in the distribution of latexmk (e.g., at +example_rcfiles in the distribution of \fIlatexmk\fR (e.g., at http://mirror.ctan.org/support/latexmk/example_rcfiles). \fR @@ -1169,6 +1199,8 @@ 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 @@ -1181,8 +1213,9 @@ 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 -silent option it -would replace %O by "-interaction=batchmode".) +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 @@ -1213,7 +1246,10 @@ 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 '\\'. +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 @@ -1223,17 +1259,13 @@ 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 a pair of these characters. Thus with -the command specification $ps_previewer = 'latex -ad=%%Sfile.ad %S', -the %%S will become %S when the command is executed, but the %S will -be replaced by the source filename, which in this case would be the -name of a postscript file to be viewed. +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 many versions of the TeX program cannot correctly handle -filenames containing spaces.) In case latexmk's quoting does not work +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 @@ -1294,14 +1326,15 @@ should be enclosed in double quotes, as in $pdf_previewer = 'start "c:/Program Files/SumatraPDF (x86)/SumatraPDF.exe" %O %S'; .PP -(Note about the above example: Forward slashes are equivalent to -backslashes in filenames under MS-Windows, provided that the filename +(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 latexmk is executed by Cygwin's +\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 @@ -1315,7 +1348,7 @@ command 'start' by itself: .PP $dvi_previewer = 'start %S'; .PP -Under recent versions of MS-Windows, this will cause to be run +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 @@ -1367,8 +1400,8 @@ 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 pdflatex to generate a pdf -file from a tex file you need to run another program after pdflatex to +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'; @@ -1395,13 +1428,16 @@ Default values are indicated in brackets. .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 -dvips, dvipdf, and ps2pdf operations, and the filtering operators on -dvi and ps files. It does not apply to pdflatex, unfortunately.) +\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 sees that the file -has changed, it reads the new file, and this can cause havoc if the -program writing the file has not yet finished its work. +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 @@ -1429,9 +1465,9 @@ 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 (pdf)latex the +\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 (pdf)latex. +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. @@ -1501,27 +1537,32 @@ the kpsewhich command, you may need to set the variable \fI@BIBINPUTS\fR. The biber processing program. .TP .B $biber_silent_switch ["--onlylog"] -\fBSwitch(es)\fR for the biber processing program when silent mode is on. +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_silent_switch ["-terse"] -\fBSwitch(es)\fR for the BibTeX processing program when silent mode is on. +Switch(es) for the BibTeX processing program when silent mode is on. .TP .B $bibtex_use [1] -Under what conditions to run BibTeX or biber. When \fIlatexmk\fR discovers -from the log file that one (or more) BibTeX/biber-generated bibliographies -are used, it can run BibTeX or biber whenever it appears necessary to -regenerate the bbl file(s) from their source bib database file(s). +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 BibTeX or biber will result in incorrect +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. Its possible values are: 0: never use -BibTeX or biber. 1: only use BibTeX or biber if the bib files exist. -2: run BibTeX or biber whenever it appears necessary to update the bbl +BibTeX or biber. 1: only use \fIbibtex\fR or \fIbiber\fR if the bib +files 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. .TP .B $cleanup_includes_cusdep_generated [0] @@ -1711,9 +1752,9 @@ 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. -[Default is "start" under MS-WINDOWS; under more recent versions of -Windows, this will cause to be run whatever command the system has -associated with .dvi files.] +[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 @@ -1728,9 +1769,10 @@ yourself, whenever it is needed. .TP .B $dvi_previewer_landscape ["start xdvi %O %S"] The command to invoke a dvi-previewer in landscape mode. -[Default is "start" under MS-WINDOWS; under more recent versions of -Windows, this will cause to be run whatever command the system has -associated with .dvi files.] +[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 @@ -1742,6 +1784,7 @@ 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. @@ -1749,24 +1792,25 @@ Switch(es) for dvipdf program when silent mode is on. N.B. The standard dvipdf program runs silently, so adding the silent switch has no effect, but is actually innocuous. But if an alternative program is used, e.g., dvipdfmx, then the silent switch -has an effect. The default setting is correct for dvipdfm and dvipdfmx. +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 -$dvips_pdf_switch -- see below -- will be included in the options -substituted for "%O". +\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 dvips program when pdf file is to be generated from -ps file. +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 dvips program when silent mode is on. +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 @@ -1784,9 +1828,9 @@ the \fI$ps_update_method\fR variables. 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 xdvi. +suitable for \fIxdvi\fR. 3 => Viewer cannot do an update, because it locks the file. (As with -acroread under MS-Windows.) +\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. @@ -1797,10 +1841,10 @@ example of updating by command. 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 xdvi on a UNIX system. +for \fIxdvi\fR on a UNIX system. .TP .B $failure_cmd [undefined] -See the documentation for $compiling_cmd. +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 @@ -1889,8 +1933,8 @@ 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 read later. To do this, you use Perl's delete -function, e.g., +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'}; @@ -1898,11 +1942,21 @@ function, e.g., .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 .bib files are found from the log file of a bibtex or biber run, -the name of -the file, but not its path is known. The program specified by -$kpsewhich is used to find it. +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 @@ -1921,13 +1975,13 @@ but also specify options to the program. E.g., $latex = "latex --src-specials"; .TP .B %latex_input_extensions -This variable specifies the extensions tried by latexmk when it finds +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, latexmk searches for custom dependencies to make +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'. @@ -1947,7 +2001,7 @@ removes the extension 'tex' from latex_input_extensions add the extension 'asdf to latex_input_extensions. (Naturally with such an extension, you should have made an appropriate custom -dependency for latexmk, and should also have done the appropriate +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. @@ -1963,16 +2017,16 @@ 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] +.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 +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 gsview installed, you could use it with the option "/p": +you have \fIgsview\fR installed, you could use it with the option "/p": $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p'; -If gsview is installed in a different directory, you will need to make +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 @@ -1987,17 +2041,46 @@ The printing program to print dvi files. .B $lpr_pdf ["NONE lpr_pdf"] The printing program to print pdf files. -Under MS-Windows you could set this to use gsview, if it is installed, +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 gsview is installed in a different directory, you will need to make +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"] +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. + +.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. @@ -2027,11 +2110,12 @@ 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 -"\\". So for safety \fIlatexmk\fR makes a translation, by default. +"\\" 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 -an Unix-like environment inside MS-Windows.) +a Unix-like environment inside MS-Windows.) .TP .B $new_viewer_always [0] @@ -2078,93 +2162,67 @@ operating system environment variable openout_any to "a" (as in .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 pdflatex. +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. -Equivalent to the \fB-pdf-\fR, \fB-pdf\fR, \fB-pdfdvi\fR, -\fB-pdfps\fR options. .TP .B $pdflatex ["pdflatex %O %S"] The LaTeX processing program in a version that makes a pdf file instead of a dvi file. -An example of the use of this variable is to arrange for -\fIlualatex\fR, \fIxelatex\fR or some similar program -to be used instead of \fIpdflatex\fR. -Note that \fIlualatex\fR and \fIxelatex\fR only produce .pdf files -(and not .dvi), so to use them you will also need to turn on -production of .pdf files, and to turn off the production of .dvi -(and .ps) files, either by command line options or by suitable -settings in a configuration file. Thus to use \fIlualatex\fR, the -following settings are appropriate: - - $pdflatex = "lualatex %O %S"; - $pdf_mode = 1; $postscript_mode = $dvi_mode = 0; - -To use \fIxelatex\fR, the corresponding settings are: - - $pdflatex = "xelatex %O %S"; - $pdf_mode = 1; $postscript_mode = $dvi_mode = 0; - -Another use of the same variable is to add certain options to the +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.) .TP .B %pdflatex_input_extensions -This variable specifies the extensions tried by latexmk when it finds -that a pdflatex run resulted in an error that a file has not been found, +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, latexmk searches for custom dependencies to make +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'. -(For Perl experts: %pdflatex_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 -%latex_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( 'pdflatex', 'tex' ); - -removes the extension 'tex' from pdflatex_input_extensions - - add_input_ext( 'pdflatex', 'asdf' ); - -add the extension 'asdf to pdflatex_input_extensions. (Naturally with -such an extension, you should have made an appropriate custom -dependency for latexmk, 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 pdflatex and its graphics/graphicx -packages.) +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 pdflatex program (specified in the variable -\fI$pdflatex\fR when silent mode is on. +Switch(es) for the \fIpdflatex\fR program (specified in the variable +\fI$pdflatex\fR) 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"; +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 +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 @@ -2180,7 +2238,7 @@ 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, SumatraPDF or gsview is +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 @@ -2228,14 +2286,16 @@ in response to a command, and the third setting sets the update command. 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 gv on a UNIX system. +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 and Linux. Setting the variable to -1 is used to indicate that +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] @@ -2259,7 +2319,8 @@ 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 \fIlpr\fR. Equivalent to the +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 @@ -2280,11 +2341,10 @@ 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 --width 200 -f -u $ENV{USER}" -under linux, "ps -ww -u $ENV{USER}" under darwin (Macintosh OS-X), and -"ps -f -u $ENV{USER}" under other operating systems (including other -flavors of UNIX). In these specifications "$ENV{USER}" is substituted -by the username. +(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. @@ -2294,19 +2354,19 @@ 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 +.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 gv could be used with the -watch option updates its display +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 gv have slightly different ways of +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 gv under different names, e.g., ggv, kghostview, etc, but perhaps -not one called gv. +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 @@ -2319,7 +2379,7 @@ 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] +.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 [""] @@ -2354,11 +2414,11 @@ 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 latexmk is tested to work correctly under +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 LaTeX and PdfLaTeX cannot -correctly deal with TeX files whose names contain spaces. Latexmk's +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 @@ -2390,12 +2450,12 @@ 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 +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, because it corrects it -internally. But, surprisingly, \fIdvipdf\fR and \fIdvips\fR do, +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.] @@ -2410,6 +2470,10 @@ 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 @@ -2484,6 +2548,49 @@ 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 $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"] +The LaTeX processing program of in a version that makes a pdf file instead +of a dvi file, 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. + +.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 @@ -2525,12 +2632,13 @@ 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 -It is invoked whenever \fIlatexmk\fR detects that a run of +A custom dependency rule is invoked 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 rule. If it does, then whenever the destination +custom-dependency rule. If it does, then the rule whenever the destination file (the one with the to-extension) is out-of-date with respect to the corresponding source file. @@ -2541,7 +2649,7 @@ 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 other item in each custom-dependency rule labeled "must" above +One other item in each custom-dependency rule, labeled "must" above, specifies how the rule should be applied when the source file fails to exist. @@ -2549,11 +2657,11 @@ A simple and typical example of code in an initialization rcfile is add_cus_dep( 'fig', 'eps', 0, 'fig2eps' ); sub fig2eps { - system( "fig2dev -Leps \\"$_[0].fig\\" \\"$_[0].eps\\"" ); + return 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 xfig program, to an encapsulated +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 @@ -2577,13 +2685,13 @@ the return value is the value returned by the last (and only) statement, i.e., the invocation of system, which returns the value 0 on success. -If you use pdflatex instead of latex, then you will probably prefer to +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\\"" ); + return system( "fig2dev -Lpdf \\"$_[0].fig\\" \\"$_[0].pdf\\"" ); } \fBNote 1:\fR In the command lines given in the system commands in the @@ -2600,7 +2708,7 @@ the cases I have tested. 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 latexmk, to maintain its +\'\\'. 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 @@ -2636,12 +2744,9 @@ happen: add_cus_dep('ndx', 'nnd', 0, 'makendx2nnd'); sub makendx2nnd { - system( "makeindex -o \\"$_[0].nnd\\" \\"$_[0].ndx\\"" ); + return system( "makeindex -o \\"$_[0].nnd\\" \\"$_[0].ndx\\"" ); } -(You will need to modify this code if you use filenames -with spaces in them, to provide correct quoting of the filenames.) - Those of you with experience with Makefiles, will undoubtedly be 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. @@ -2652,7 +2757,7 @@ dependencies. It examines the contents of the files (by use of an md5 checksum), and only does a remake when the file contents have actually changed. -Of course if you choose to write random data to the \fI.nnd\fR (or and +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. @@ -2675,7 +2780,7 @@ of \fI.fig\fR files to \fI.eps\fR files: push @cus_dep_list, "fig eps 0 fig2eps"; sub fig2eps { - system( "fig2dev -Lps \\"$_[0].fig\\" \\"$_[0].eps\\"" ); + return system( "fig2dev -Lps \\"$_[0].fig\\" \\"$_[0].eps\\"" ); } This method still works, and is equivalent to the earlier code using @@ -2825,7 +2930,7 @@ project, where lines such as the above would be only be a small part of a larger Makefile. The above example has a pattern rule for making a .pdf file from -a .tex file, and it is defined to use latexmk in the obvious way. +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 @@ -2867,7 +2972,7 @@ started with tabs.) This example was inspired by how GNU \fIautomake\fR handles automatic dependency tracking of C source files. -After each run of latexmk, dependency information is put in a file +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 @@ -2909,13 +3014,13 @@ 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 +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 +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 @@ -2930,7 +3035,7 @@ e-mail addresses are not written in their standard form to avoid being harvested by worms and viruses.) .SH AUTHOR Current version, by John Collins (username jcc8 at node psu.edu). -(Version 4.48). +(Version 4.52). Released version can be obtained from CTAN: <http://www.ctan.org/pkg/latexmk/>, and from the |