1LATEXMK(1L) LATEXMK(1L)
2
6 latexmk - generate LaTeX document
7
9 latexmk [options] [file ...]
10
12 Latexmk completely automates the process of compiling a LaTeX document.
13 Essentially, it is like a specialized relative of the general make
14 utility, but one which determines dependencies automatically and has
15 some other very useful features. In its basic mode of operation
16 latexmk is given the name of the primary source file for a document,
17 and it issues the appropriate sequence of commands to generate a .dvi,
18 .ps, .pdf and/or hardcopy version of the document.
19 By default latexmk will run the commands necessary to generate a .dvi
21 file.
22 Latexmk can also be set to run continuously with a suitable previewer.
24 In that case the LaTeX program, etc, are rerun whenever one of the
25 source files is modified, and the previewer automatically updates the
26 on-screen view of the compiled document.
27 Latexmk determines which are the source files by examining the log
29 file. (Optionally, it also examines the list of input and output files
30 generated by the -recorder option of modern versions of latex and
31 pdflatex. See the documentation for the -recorder option of latexmk
32 below.) When latexmk is run, it examines properties of the source
33 files, and if any have been changed since the last document generation,
34 latexmk will run the various LaTeX processing programs as necessary.
35 In particular, it will repeat the run of LaTeX (or pdflatex) often
36 enough to resolve all cross references; depending on the macro packages
37 used. With some macro packages and document classes, four, or even
38 more, runs may be needed. If necessary, latexmk will also run bibtex,
39 biber, and/or makeindex. In addition, latexmk can be configured to
40 generate other necessary files. For example, from an updated figure
41 file it can automatically generate a file in encapsulated postscript or
42 another suitable format for reading by LaTeX.
43 Latexmk has two different previewing options. In the simple -pv
45 option, a dvi, postscript or pdf previewer is automatically run after
46 generating the dvi, postscript or pdf version of the document. The
47 type of file to view is selected according to configuration settings
48 and command line options.
49 The second previewing option is the powerful -pvc option (mnemonic:
51 "preview continuously"). In this case, latexmk runs continuously, reg‐
52 ularly monitoring all the source files to see if any have changed.
53 Every time a change is detected, latexmk runs all the programs neces‐
54 sary to generate a new version of the document. A good previewer (like
55 gv) will then automatically update its display. Thus the user can sim‐
56 ply edit a file and, when the changes are written to disk, latexmk com‐
57 pletely automates the cycle of updating the .dvi (and possibly the .ps
58 and .pdf) file, and refreshing the previewer's display. It's not quite
59 WYSIWYG, but usefully close.
60 For other previewers, the user may have to manually make the previewer
62 update its display, which can be (some versions of xdvi and gsview) as
63 simple as forcing a redraw of its display.
64 Latexmk has the ability to print a banner in gray diagonally across
66 each page when making the postscript file. It can also, if needed,
67 call an external program to do other postprocessing on the generated
68 files.
69 Latexmk is highly configurable, both from the command line and in con‐
71 figuration files, so that it can accommodate a wide variety of user
72 needs and system configurations. Default values are set according to
73 the operating system, so latexmk often works without special configura‐
74 tion on MS-Windows, cygwin, Linux, OS-X, and other UNIX systems
75 (notably Solaris).
76 A very annoying complication handled very reliably by Latexmk, is that
78 LaTeX is a multiple pass system. On each run, LaTeX reads in informa‐
79 tion generated on a previous run, for things like cross referencing and
80 indexing. In the simplest cases, a second run of LaTeX suffices, and
81 often the log file contains a message about the need for another pass.
82 However, there is a wide variety of add-on macro packages to LaTeX,
83 with a variety of behaviors. The result is to break simple-minded
84 determinations of how many runs are needed and of which programs. In
85 its new version, latexmk has a highly general and efficient solution to
86 these issues. The solution involves retaining between runs information
87 on the source files, and a symptom is that latexmk generates an extra
88 file (with extension .fdb_latexmk, by default) that contains the source
89 file information.
90
93 (All options can be introduced by single or double "-" characters,
94 e.g., "latexmk -help" or "latexmk --help".)
95 file One or more files can be specified. If no files are specified,
97 latexmk will, by default, run on all files in the current work‐
98 ing directory with a ".tex" extension. This behavior can be
99 changed: see the description concerning the @default_files vari‐
100 able in the section "List of configuration variables usable in
101 initialization files".
102 If a file is specified without an extension, then the ".tex" extension
104 is automatically added, just as LaTeX does. Thus, if you specify:
105 latexmk foo
107 then latexmk will operate on the file "foo.tex".
109 -bibtex
111 When the source file uses bbl files for bibliography, run bibtex
112 or biber as needed to regenerate the bbl files.
113 This property can also be configured by setting the $bibtex_use
115 variable to 2 in a configuration file
116 -bibtex-
118 Never run bibtex or biber.
119 A common use for this option is when a document comes from an
121 external source, complete with its bbl file(s), and the user
122 does not have the corresponding bib files available. In this
123 situation use of the -bibtex- option will prevent latexmk from
124 trying to run bibtex or biber, which would result in overwriting
125 of the bbl files.
126 -bibtex-cond
128 When the source file uses bbl file(s) for the bibliography, run
129 bibtex or biber as needed to regenerate the bbl files, but only
130 if the relevant bib file(s) exist. Thus when the bib files are
131 not available, bibtex or biber is not run, thereby avoiding
132 overwriting of the bbl file(s). This is the default setting.
133 (Note that it is possible for latexmk to decide that the bib
135 file does not exist, even though the bib file does exist and
136 bibtex or biber finds it. The problem is that the bib file may
137 not be in the current directory but in some search path; the
138 places latexmk and bibtex or biber cause to be searched need not
139 be identical. On modern installations of TeX and related pro‐
140 grams this problem should not arise, since latexmk uses the
141 kpsewhich program to do the search, and kpsewhich should use the
142 same search path as bibtex and biber. If this problem arises,
143 use the -bibtex option when invoking latexmk.)
144 -bm <message>
146 A banner message to print diagonally across each page when con‐
147 verting the dvi file to postscript. The message must be a sin‐
148 gle argument on the command line so be careful with quoting spa‐
149 ces and such.
150 Note that if the -bm option is specified, the -ps option is
152 assumed.
153 -bi <intensity>
155 How dark to print the banner message. A decimal number between
156 0 and 1. 0 is black and 1 is white. The default is 0.95, which
157 is OK unless your toner cartridge is getting low.
158 -bs <scale>
160 A decimal number that specifies how large the banner message
161 will be printed. Experimentation is necessary to get the right
162 scale for your message, as a rule of thumb the scale should be
163 about equal to 1100 divided by the number of characters in the
164 message. The default is 220.0 which is just right for 5 charac‐
165 ter messages.
166 -commands
168 List the commands used by latexmk for processing files, and then
169 exit.
170 -c Clean up (remove) all regeneratable files generated by latex and
172 bibtex or biber except dvi, postscript and pdf. These files are
173 a combination of log files, aux files, latexmk's database file
174 of source file information, and those with extensions specified
175 in the @generated_exts configuration variable. In addition,
176 files with extensions by the $clean_ext configuration variable
177 are removed.
178 This cleanup is instead of a regular make. See the -gg option
180 if you want to do a cleanup then a make.
181 If $bibtex_use is set to 0 or 1, bbl files are counted as non-
183 regeneratable.
184 If $cleanup_includes_cusdep_generated is nonzero, regeneratable
186 files are considered as including those generated by custom
187 dependencies and are also deleted. Otherwise these files are
188 not deleted.
189 -C Clean up (remove) all regeneratable files generated by latex and
191 bibtex or biber. This is the same as the -c option with the
192 addition of dvi, postscript and pdf files, and those with exten‐
193 sions in the $clean_full_ext configuration variable.
194 This cleanup is instead of a regular make. See the -gg option
196 if you want to do a cleanup than a make.
197 If $bibtex_use is set to 0 or 1, bbl files are counted as non-
199 regeneratable.
200 If $cleanup_includes_cusdep_generated is nonzero, regeneratable
202 files are considered as including those generated by custom
203 dependencies and are also deleted. Otherwise these files are
204 not deleted.
205 -CA (Obsolete). Now equivalent to the -C option. See that option
207 for details.
208 -CF Remove the file containing the database of source file informa‐
210 tion, before doing the other actions requested.
211 -d Set draft mode. This prints the banner message "DRAFT" across
213 your page when converting the dvi file to postscript. Size and
214 intensity can be modified with the -bs and -bi options. The -bm
215 option will override this option as this is really just a short
216 way of specifying:
217 latexmk -bm DRAFT
219 Note that if the -d option is specified, the -ps option is
221 assumed.
222 -deps Show a list of dependent files after processing. This is in the
224 form of a dependency list of the form used by the make program,
225 and it is therefore suitable for use in a Makefile. It gives an
226 overall view of the files without listing intermediate files, as
227 well as latexmk can determine them.
228 By default the list of dependent files is sent to stdout (i.e.,
230 normally to the screen unless you've redirected latexmk's out‐
231 put). But you can set the filename where the list is sent by
232 the -deps-out= option.
233 See the section "USING latexmk WITH make" for an example of how
235 to use a dependency list with make.
236 Users familiar with GNU automake and gcc will find that the
238 -deps option is very similar in its purpose and results to the
239 -M option to gcc.
240 -dependents
242 Equivalent to -deps.
243 -deps- Do not show a list of dependent files after processing. (This
245 is the default.)
246 -dependents-
248 Equivalent to -deps-.
249 -deps-out=FILENAME
251 Set the filename to which the list of dependent files is writ‐
252 ten. If the FILENAME argument is omitted or set to '-', then
253 the output is sent to stdout.
254 Use of this option also turns on the output of the list of
256 dependent files after processing.
257 -dF Dvi file filtering. The argument to this option is a filter
259 which will generate a filtered dvi file with the extension
260 ".dviF". All extra processing (e.g. conversion to postscript,
261 preview, printing) will then be performed on this filtered dvi
262 file.
263 Example usage: To use dviselect to select only the even pages of
265 the dvi file:
266 latexmk -dF 'dviselect even' foo.tex
268 -diagnostics
270 Print detailed diagnostics during a run. This may help for
271 debugging problems or to understand latexmk's behavior in diffi‐
272 cult situations.
273 -dvi Generate dvi version of document.
275 -dvi- Turn off generation of dvi version of document. (This may get
277 overridden, if some other file is made (e.g., a .ps file) that
278 is generated from the dvi file, or if no generated file at all
279 is requested.)
280 -e <code>
282 Execute the specified initialization code before processing.
283 The code is Perl code of the same form as is used in latexmk's
284 initialization files -- for more details, see the information on
285 the -r option, and the section about "Configuration/initializa‐
286 tion (RC) files". The code is typically a sequence of assign‐
287 ment statements separated by semicolons.
288 The code is executed when the -e option is encountered during
290 latexmk's parsing of its command line. See the -r option for a
291 way of executing initialization code from a file. An error
292 results in latexmk stopping. Multiple instances of the -r and
293 -e options can be used, and they are executed in the order they
294 appear on the command line.
295 Some care is needed to deal with proper quoting of special char‐
297 acters in the code on the command line. For example, suppose
298 you want to set the latex command to use its -shell-escape
299 option, then under UNIX/LINUX you could use the line
300 latexmk -e '$latex=q/latex %O -shell-escape %S/' file.tex
302 Note that the single quotes block normal UNIX/LINUX command
304 shells from treating the characters inside the quotes as spe‐
305 cial. (In this example, the q/.../ construct is a Perl idiom
306 equivalent to using single quotes. This avoids the complica‐
307 tions of getting a quote character inside an already quoted
308 string in a way that is independent of both the shell and the
309 operating-system.)
310 The above command line will NOT work under MS-Windows with
312 cmd.exe or command.com or 4nt.exe. For MS-Windows with these
313 command shells you could use
314 latexmk -e "$latex=q/latex %O -shell-escape %S/" file.tex
316 or
318 latexmk -e "$latex='latex %O -shell-escape %S'" file.tex
320 The last two examples will NOT work with UNIX/LINUX command
322 shells.
323 -f Force latexmk to continue document processing despite errors.
325 Normally, when latexmk detects that LaTeX or another program has
326 found an error which will not be resolved by further processing,
327 no further processing is carried out.
328 -f- Turn off the forced processing-past-errors such as is set by the
330 -f option. This could be used to override a setting in a con‐
331 figuration file.
332 -g Force latexmk to process document fully, even under situations
334 where latexmk would normally decide that no changes in the
335 source files have occurred since the previous run. This option
336 is useful, for example, if you change some options and wish to
337 reprocess the files.
338 -g- Turn off -g.
340 -gg "Super go mode" or "clean make": clean out generated files as if
342 -C had been given, and then do a regular make.
343 -h, -help
345 Print help information.
346 -l Run in landscape mode, using the landscape mode for the preview‐
348 ers and the dvi to postscript converters. This option is not
349 normally needed nowadays, since current previewers normally
350 determine this information automatically.
351 -l- Turn off -l.
353 -new-viewer
355 When in continuous-preview mode, always start a new viewer to
356 view the generated file. By default, latexmk will, in continu‐
357 ous-preview mode, test for a previously running previewer for
358 the same file and not start a new one if a previous previewer is
359 running. However, its test sometimes fails (notably if there is
360 an already-running previewer that is viewing a file of the same
361 name as the current file, but in a different directory). This
362 option turns off the default behavior.
363 -new-viewer-
365 The inverse of the -new-viewer option. It puts latexmk in its
366 normal behavior that in preview-continuous mode it checks for an
367 already-running previewer.
368 -nobibtex
370 Never run bibtex or biber.
371 A common use for this option is when a document comes from an
373 external source, complete with its bbl file(s), and the user
374 does not have the corresponding bib files available. In this
375 situation use of the -nobibtex option will prevent latexmk from
376 trying to run bibtex or biber, which would result in overwriting
377 of the bbl files.
378 -p Print out the document. By default it is the generated post‐
380 script file that is printed. But you can use the -print=...
381 option to print the dvi or pdf files instead, and you can con‐
382 figure this in a start up file (by setting the $print_type vari‐
383 able).
384 However, printing is enabled by default only under UNIX/LINUX
386 systems, where the default is to use the lpr command. In gen‐
387 eral, the correct behavior for printing very much depends on
388 your system's software. In particular, under MS-Windows you
389 must have suitable program(s) available, and you must have con‐
390 figured the print commands used by latexmk. This can be non-
391 trivial. See the documentation on the $lpr, $lpr_dvi, and
392 $lpr_pdf configuration variables to see how to set the commands
393 for printing.
394 This option is incompatible with the -pv and -pvc options, so it
396 turns them off.
397 -pdf Generate pdf version of document using pdflatex.
399 -pdfdvi
401 Generate pdf version of document from the dvi file, by default
402 using dvipdf.
403 -pdfps Generate pdf version of document from the ps file, by default
405 using ps2pdf.
406 -pdf- Turn off generation of pdf version of document. (This can be
408 used to override a setting in a configuration file. It may get
409 overridden if some other option requires the generation of a pdf
410 file.)
411 -print=dvi, -print=ps, -print=pdf
413 Define which kind of file is printed. This option also ensures
414 that the requisite file is made, and turns on printing. The
415 default is to print a postscript file.
416 -ps Generate postscript version of document.
418 -ps- Turn off generation of postscript version of document. This can
420 be used to override a setting in a configuration file. (It may
421 get overridden by some other option that requires a postscript
422 file, for example a request for printing.)
423 -pF Postscript file filtering. The argument to this option is a
425 filter which will generate a filtered postscript file with the
426 extension ".psF". All extra processing (e.g. preview, printing)
427 will then be performed on this filtered postscript file.
428 Example of usage: Use psnup to print two pages on the one page:
430 latexmk -ps -pF 'psnup -2' foo.tex
432 or
434 latexmk -ps -pF "psnup -2" foo.tex
436 Whether to use single or double quotes round the "psnup -2" will
438 depend on your command interpreter, as used by the particular
439 version of perl and the operating system on your computer.
440 -pv Run file previewer. If the -view option is used, this will
442 select the kind of file to be previewed (dvi, ps or pdf). Oth‐
443 erwise the viewer views the "highest" kind of file selected, by
444 the -dvi, -ps, -pdf, -pdfps options, in the order dvi, ps, pdf
445 (low to high). If no file type has been selected, the dvi pre‐
446 viewer will be used. This option is incompatible with the -p
447 and -pvc options, so it turns them off.
448 -pv- Turn off -pv.
450 -pvc Run a file previewer and continually update the .dvi, .ps,
452 and/or .pdf files whenever changes are made to source files (see
453 the Description above). Which of these files is generated and
454 which is viewed is governed by the other options, and is the
455 same as for the -pv option. The preview-continuous option -pvc
456 can only work with one file. So in this case you will normally
457 only specify one filename on the command line. It is also
458 incompatible with the -p and -pv options, so it turns these
459 options off.
460 The -pvc option also turns off force mode (-f), as is normally
462 best for continuous preview mode. If you really want force
463 mode, use the options in the order -pvc -f.
464 With a good previewer the display will be automatically updated.
466 (Under some but not all versions of UNIX/Linux "gv -watch" does
467 this for postscript files; this can be set by a configuration
468 variable. This would also work for pdf files except for an
469 apparent bug in gv that causes an error when the newly updated
470 pdf file is read.) Many other previewers will need a manual
471 update.
472 Important note: the acroread program on MS-Windows locks the pdf
474 file, and prevents new versions being written, so it is a bad
475 idea to use acroread to view pdf files in preview-continuous
476 mode. It is better to use a dvi or ps viewer, as set by one of
477 the -view=dvi and -view=ps options.
478 There are some other methods for arranging an update, notably
480 useful for many versions of xdvi and xpdf. These are best set
481 in latexmk's configuration; see below.
482 Note that if latexmk dies or is stopped by the user, the
484 "forked" previewer will continue to run. Successive invocations
485 with the -pvc option will not fork new previewers, but latexmk
486 will normally use the existing previewer. (At least this will
487 happen when latexmk is running under an operating system where
488 it knows how to determine whether an existing previewer is run‐
489 ning.)
490 -pvc- Turn off -pvc.
492 -quiet Same as -silent
494 -r <rcfile>
496 Read the specified initialization file ("RC file") before pro‐
497 cessing.
498 Be careful about the ordering: (1) Standard initialization files
500 -- see the section below on "Configuration/initialization (RC)
501 files" -- are read first. (2) Then the options on the command
502 line are acted on in the order they are given. Therefore if an
503 initialization file is specified by the -r option, it is read
504 during this second step. Thus an initialization file specified
505 with the -r option can override both the standard initialization
506 files and previously specified options. But all of these can be
507 overridden by later options.
508 The contents of the RC file just comprise a piece of code in the
510 Perl programming language (typically a sequence of assignment
511 statements); they are executed when the -r option is encountered
512 during latexmk's parsing of its command line. See the -e option
513 for a way of giving initialization code directly on latexmk's
514 command line. An error results in latexmk stopping. Multiple
515 instances of the -r and -e options can be used, and they are
516 executed in the order they appear on the command line.
517 -recorder
519 Use the -recorder option with latex and pdflatex. In (most)
520 modern versions of these programs, this results in a file of
521 extension .fls containing a list of the files that these pro‐
522 grams have read and written. Latexmk will then use this file to
523 improve its detection of source files and generated files after
524 a run of latex or pdflatex.
525 For further information, see the documentation for the $recorder
527 configuration variable.
528 -recorder-
530 Do not use the -recorder option with latex and pdflatex.
531 -rules Show a list of latemk's rules and dependencies after processing.
533 -rules-
535 Do not show a list of latexmk's rules and dependencies after
536 processing. (This is the default.)
537 -silent
539 Run commands silently, i.e., with options that reduce the amount
540 of diagnostics generated. For example, with the default set‐
541 tings, the command "latex -interaction=batchmode" is used for
542 latex.
543 Also reduce the number of informational messages that latexmk
545 generates.
546 To change the options used to make the commands run silently,
548 you need to configure latexmk with changed values of its config‐
549 uration variables, the relevant ones being $bib‐
550 tex_silent_switch, $biber_silent_switch, $dvips_silent_switch,
551 $latex_silent_switch, and $pdflatex_silent_switch.
552 -use-make
554 When after a run of latex or pdflatex, there are warnings about
555 missing files (e.g., as requested by the LaTeX \input, \include,
556 and \includgraphics), latexmk tries to make them by a custom
557 dependency. If no relevant custom dependency with an appropriate
558 source file is found, and if the -use-make option is set, then
559 latexmk will try as a resort using the make program to try to
560 make the missing files.
561 Note that the filename may be specified without an extension,
563 e.g., by \includegraphics{drawing} in a LaTeX file. In that
564 case, latexmk will try making drawing.ext with ext set in turn
565 to the possible extensions that are relevant for latex (or as
566 appropriate pdflatex).
567 See also the documentation for the $use_make_for_missing_files
569 configuration variable.
570 -use-make-
572 Do not use the make program to try to make missing files.
573 (Default.)
574 -v, -version
576 Print version number of latexmk.
577 -verbose
579 Opposite of -silent. This is the default setting.
580 -view=default, -view=dvi, -view=ps, -view=pdf
582 Set the kind of file used when previewing is requested (e.g., by
583 the -pv or -pvc switches). The default is to view the "highest"
584 kind of requested file (in the order dvi, ps, pdf).
585 The preview-continuous option -pvc can only work with one file. So in
587 this case you will normally only specify one filename on the command
588 line.
589 Options -p, -pv and -pvc are mutually exclusive. So each of these
591 options turns the others off.
592
595 % latexmk thesis # run latex enough times to resolve
596 cross-references
597 % latexmk -pvc -ps thesis# run latex enough times to resolve
599 cross-references, make a postscript
600 file, start a previewer. Then
601 watch for changes in the source
602 file thesis.tex and any files it
603 uses. After any changes rerun latex
604 the appropriate number of times and
605 remake the postscript file. If latex
606 encounters an error, latexmk will
607 keep running, watching for
608 source file changes.
609 % latexmk -c # remove .aux, .log, .bbl, .blg, .dvi,
611 .pdf, .ps & .bbl files
612
616 Latexmk can be customized using initialization files, which are read at
617 startup in the following order:
618 1) The system RC file, if it exists.
620 On a UNIX system, latexmk searches for following places for its sys‐
621 tem RC file, in the following order, and reads the first it finds:
622 "/opt/local/share/latexmk/LatexMk",
623 "/usr/local/share/latexmk/LatexMk",
624 "/usr/local/lib/latexmk/LatexMk".
625 On a Fedora system, it only looks for "/etc/latexmk.conf".
626 On a MS-WINDOWS system it looks for "C:\latexmk\LatexMk".
627 On a cygwin system (i.e., a MS-Windows system in which perl is
628 that of cygwin), latexmk reads for the first it finds of
629 "/cygdrive/c/latexmk/LatexMk",
630 "/opt/local/share/latexmk/LatexMk",
631 "/usr/local/share/latexmk/LatexMk",
632 "/usr/local/lib/latexmk/LatexMk".
633 2) The user's RC file, "$HOME/.latexmkrc", if it exists. Here $HOME is
635 the value of the environment variable HOME. On UNIX and clones
636 (including LINUX), this variable is set by the system; on MS-Windows,
637 the user may choose to set it.
638 3) The RC file in the current working directory. This file can be
640 named either "latexmkrc" or ".latexmkrc", and the first of these to be
641 found is used, if any.
642 4) Any RC file(s) specified on the command line with the -r option.
644 Each RC file is a sequence of Perl commands. Naturally, a user can use
646 this in creative ways. But for most purposes, one simply uses a
647 sequence of assignment statements that override some of the built-in
648 settings of Latexmk. Straightforward cases can be handled without
649 knowledge of the Perl language by using the examples in this document
650 as templates. Comment lines are introduced by the "#" character.
651 Note that command line options are obeyed in the order in which they
653 are written; thus any RC file specified on the command line with the -r
654 option can override previous options but can be itself overridden by
655 later options on the command line. There is also the -e option, which
656 allows initialization code to be specified in latexmk's command line.
657
660 The important variables that can be configured are described in the
661 section "List of configuration variables usable in initialization
662 files". Syntax for setting these variables is of the following forms:
663 $bibtex = 'bibtex %O %B';
665 for the setting of a string variable,
667 $preview_mode = 1;
669 for the setting of a numeric variable, and
671 @default_files = ('paper', 'paper1');
673 for the setting of an array of strings. It is possible to append an
675 item to an array variable as follows:
676 push @default_files, 'paper2';
678 Note that simple "scalar" variables have names that begin with a $
680 character and array variables have names that begin with a @ character.
681 Each statement ends with a semicolon.
682 Strings should be enclosed in single quotes. (You could use double
684 quotes, as in many programming languages. But then the Perl program‐
685 ming language brings into play some special rules for interpolating
686 variables into strings. People not fluent in Perl will want to avoid
687 these complications.)
688 You can do much more complicated things, but for this you will need to
690 consult a manual for the Perl programming language.
691
696 Some of the variables set the commands that latexmk uses for carrying
697 out its work, for example to generate a dvi file from a tex file or to
698 view a postscript file. This section describes some important features
699 of how the commands are specified.
700 Placeholders: Supposed you wanted latexmk to use the command elatex in
702 place of the regular latex command, and suppose moreover that you
703 wanted to give it the option "--shell-escape". You could do this by
704 the following setting:
705 $latex = 'elatex --shell-escape %O %S';
707 The two items starting with the % character are placeholders. These
709 are substituted by appropriate values before the command is run. Thus
710 %S will be replaced by the source file that elatex will be applied to,
711 and %O will be replaced by any options that latexmk has decided to use
712 for this command. (E.g., if you used the -silent option it would
713 replace %O by "-interaction=batchmode".)
714 The available placeholders are:
716 %B base of filename for current command. E.g., if a postscript
718 file document.ps is being made from the dvi file document.dvi,
719 then the basename is document.
720 %D destination file (e.g., the name of the postscript file when
722 converting a dvi file to postscript).
723 %O options
725 %R root filename. This is the base name for the main tex file.
727 %S source file (e.g., the name of the dvi file when converting a
729 dvi file to ps).
730 %T The name of the primary tex file.
732 If for some reason you need a literal % character in your string not
734 subject to the above rules, use a pair of these characters. Thus with
735 the command specification $ps_previewer = 'latex -ad=%%Sfile.ad %S',
736 the %%S will become %S when the command is executed, but the %S will be
737 replaced by the source filename, which in this case would be the name
738 of a postscript file to be viewed.
739 Appropriate quoting will be applied to the filename substitutions, so
741 you mustn't supply them yourself even if you the names of your have
742 spaces in them. (But if your TeX filenames have spaces in them, beware
743 that many versions of the TeX program cannot correctly handle filenames
744 containing spaces.) In case latexmk's quoting does not work correctly
745 on your system, you can turn it off -- see the documentation for the
746 variable $quote_filenames.
747 The distinction between %B and %R needs a bit of care, since they are
749 often the same, but not always. For example on a simple document, the
750 basename of a bibtex run is the same as for the texfile. But in a doc‐
751 ument with several bibliographies, the bibliography files will have a
752 variety of names. Since bibtex is invoked with the basename of the
753 bibliography file, the setting for the bibtex command should therefore
754 be
755 $bibtex = 'bibtex %O %B';
757 Generally, you should use %B rather than %R. Similarly for most pur‐
759 poses, the name %T of the primary texfile is not a useful placeholder.
760 See the default values in the section "List of configuration variables
762 usable in initialization files" for what is normally the most appropri‐
763 ate usage.
764 If you omit to supply any placeholders whatever in the specification of
766 a command, latexmk will supply what its author thinks are appropriate
767 defaults. This gives compatibility with configuration files for previ‐
768 ous versions of latexmk, which didn't use placeholders.
769 "Detaching" a command: Normally when latexmk runs a command, it waits
771 for the command to run to completion. This is appropriate for commands
772 like latex, of course. But for previewers, the command should normally
773 run detached, so that latexmk gets the previewer running and then
774 returns to its next task (or exits if there is nothing else to do). To
775 achieve this effect of detaching a command, you need to precede the
776 command name with "start ", as in
777 $dvi_previewer = 'start xdvi %O %S';
779 This will be translated to whatever is appropriate for your operating
781 system.
782 Notes: (1) In some circumstances, latex will always run a command
784 detached. This is the case for a previewer in preview continuous mode,
785 since otherwise previewing continuously makes no sense. (2) This pre‐
786 cludes the possibility of running a command named start. (3) If the
787 word start occurs more than once at the beginning of the command
788 string, that is equivalent to having just one. (4) Under cygwin, some
789 complications happen, since cygwin amounts to a complicated merging of
790 UNIX and MS-Windows. See the source code for how I've handled the
791 problem.
792 Command names containing spaces: Under MS-Windows it is common that the
794 name of a command includes spaces, since software is often installed in
795 a subdirectory of "C:\Program Files". Such command names should be
796 enclosed in double quotes, as in
797 $lpr_pdf = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p
799 %S';
800 $pdf_previewer = 'start "c:/Program Files/SumatraPDF/Suma‐
801 traPDF.exe" %O %S';
802 $pdf_previewer = 'start "c:/Program Files/SumatraPDF (x86)/Suma‐
803 traPDF.exe" %O %S';
804 (Note about the above example: Forward slashes are equivalent to back‐
807 slashes in filenames under MS-Windows, provided that the filename is
808 inside double quotes. It is easier to use forward slashes in examples
809 like the one above, since then one does not have to worry about the
810 rules for dealing with forward slashes in strings in the Perl lan‐
811 guage.)
812 Command names under Cygwin: If latexmk is executed by Cygwin's perl,
814 be particularly certain that pathnames in commands have forward slashes
815 not the usual backslashes for the separator of pathname components.
816 See the above examples. Backslashes often get misinterpreted by the
817 Unix shell used by Cygwin's Perl to execute external commands. Forward
818 slashes don't suffer from this problem, and (when quoted, as above) are
819 equally acceptable to MS-Windows.
820 Using MS-Windows file associations: A useful trick under modern ver‐
822 sions of MS-Windows (e.g., WinXP) is to use just the command 'start' by
823 itself:
824 $dvi_previewer = 'start %S';
826 Under recent versions of MS-Windows, this will cause to be run whatever
828 program the system has associated with dvi files. (The same applies
829 for a postscript viewer and a pdf viewer.) But note that this trick is
830 not always suitable for the pdf previwer, if your system has acroread
831 for the default pdf viewer. As explained elsewhere, acroread under MS-
832 Windows does not work well with latex and latexmk, because acroread
833 locks the pdf file.
834 Not using a certain command: If a command is not to be run, the command
836 name NONE is used, as in
837 $lpr = 'NONE lpr';
839 This typically is used when an appropriate command does not exist on
841 your system. The string after the "NONE" is effectively a comment.
842 Options to commands: Setting the name of a command can be used not only
844 for changing the name of the command called, but also to add options to
845 command. Suppose you want latexmk to use latex with source specials
846 enabled. Then you might use the following line in an initialization
847 file:
848 $latex = 'latex --src-specials %O %S';
850 Advanced tricks: Normally one specifies a single command for the com‐
852 mands invoked by latexmk. Naturally, if there is some complicated
853 additional processing you need to do in your special situation, you can
854 write a script (or batch file) to do the processing, and then configure
855 latexmk to use your script in place of the standard program.
856 It is also possible to configure latexmk to run multiple commands. For
858 example, if when running pdflatex to generate a pdf file from a tex
859 file you need to run another program after pdflatex to perform some
860 extra processing, you could do something like:
861 $pdflatex = 'pdflatex --shell-escape %O %S; pst2pdf_for_latexmk
863 %B';
864 This definition assumes you are using a UNIX-like system, so that the
866 two commands to be run are separated by the semicolon in the middle of
867 the string.
868
872 Default values are indicated in brackets.
873 $always_view_file_via_temporary [0]
875 Whether ps and pdf files are initially to be made in a temporary
876 directory and then moved to the final location. (This applies
877 to dvips, dvipdf, and ps2pdf operations, and the filtering oper‐
878 ators on dvi and ps files. It does not apply to pdflatex,
879 unfortunately.)
880 This use of a temporary file solves a problem that the making of
882 these files can occupy a substantial time. If a viewer sees
883 that the file has changed, it reads the new file, and this can
884 cause havoc if the program writing the file has not yet finished
885 its work.
886 See the $pvc_view_file_via_temporary variable for a setting that
888 applies only if preview-continuous mode (-pvc option) is used.
889 See $tmpdir for the setting of the directory where the temporary
890 file is created.
891 $banner [0]
894 If nonzero, the banner message is printed across each page when
895 converting the dvi file to postscript. Without modifying the
896 variable $banner_message, this is equivalent to specifying the
897 -d option.
898 Note that if $banner is nonzero, the $postscript_mode is assumed
900 and the postscript file is always generated, even if it is newer
901 than the dvi file.
902 $banner_intensity [0.95]
904 Equivalent to the -bi option, this is a decimal number between 0
905 and 1 that specifies how dark to print the banner message. 0 is
906 black, 1 is white. The default is just right if your toner car‐
907 tridge isn't running too low.
908 $banner_message ["DRAFT"]
910 The banner message to print across each page when converting the
911 dvi file to postscript. This is equivalent to the -bm option.
912 $banner_scale [220.0]
914 A decimal number that specifies how large the banner message
915 will be printed. Experimentation is necessary to get the right
916 scale for your message, as a rule of thumb the scale should be
917 about equal to 1100 divided by the number of characters in the
918 message. The Default is just right for 5 character messages.
919 This is equivalent to the -bs option.
920 @BIBINPUTS
922 This is an array variable, now mostly obsolete, that specifies
923 directories where latexmk should look for .bib files. By
924 default it is set from the BIBINPUTS environment variable of the
925 operating system. If that environment variable is not set, a
926 single element list consisting of the current directory is set.
927 The format of the directory names depends on your operating sys‐
928 tem, of course. Examples for setting this variable are:
929 @BIBINPUTS = ( ".", "C:\bibfiles" );
931 @BIBINPUTS = ( ".", "\\server\bibfiles" );
932 @BIBINPUTS = ( ".", "C:/bibfiles" );
933 @BIBINPUTS = ( ".", "//server/bibfiles" );
934 @BIBINPUTS = ( ".", "/usr/local/texmf/bibtex/bib" );
935 Note that under MS Windows, either a forward slash "/" or a
937 backward slash "\" can be used to separate pathname components,
938 so the first two and the second two examples are equivalent.
939 Each backward slash should be doubled to avoid running afoul of
940 Perl's rules for writing strings.
941 Important note: This variable is now mostly obsolete in the current
943 version of latexmk, since it has a better method of searching for files
944 using the kpsewhich command. However, if your system is an unusual one
945 without the kpsewhich command, you may need to set the variable @BIBIN‐
946 PUTS.
947 $biber ["biber %O %S"]
949 The biber processing program.
950 $biber_silent_switch ["--onlylog"]
952 Switch(es) for the biber processing program when silent mode is
953 on.
954 $bibtex ["bibtex %O %S"]
956 The BibTeX processing program.
957 $bibtex_silent_switch ["-terse"]
959 Switch(es) for the BibTeX processing program when silent mode is
960 on.
961 $bibtex_use [1]
963 Under what conditions to run BibTeX or biber. When latexmk dis‐
964 covers from the log file that one (or more) BibTeX/biber-gener‐
965 ated bibliographies are used, it can run BibTeX or biber when‐
966 ever it appears necessary to regenerate the bbl file(s) from
967 their source bib database file(s).
968 But sometimes, the bib file(s) are not available (e.g., for a
970 document obtained from an external archive), but the bbl files
971 are provided. In that case use of BibTeX or biber will result
972 in incorrect overwriting of the precious bbl files. The vari‐
973 able $bibtex_use controls whether this happens. Its possible
974 values are: 0: never use BibTeX or biber. 1: only use BibTeX or
975 biber if the bib files exist. 2: run BibTeX or biber whenever
976 it appears necessary to update the bbl files, without testing
977 for the existence of the bib files.
978 $cleanup_includes_cusdep_generated [0]
980 If nonzero, specifies that cleanup also deletes files that are
981 generated by custom dependencies. (When doing a clean up, e.g.,
982 by use of the -C option, custom dependencies are those listed in
983 the .fdb_latexmk file from a previous run.)
984 $cleanup_includes_generated [0]
986 If nonzero, specifies that cleanup also deletes files that are
987 detected in log file as being generated (see the \openout lines
988 in the log file). It will also include files made from these
989 first generation generated files.
990 $cleanup_mode [0]
992 If nonzero, specifies cleanup mode: 1 for full cleanup, 2 for
993 cleanup except for dvi, ps and pdf files, 3 for cleanup except
994 for dep and aux files. (There is also extra cleaning as speci‐
995 fied by the $clean_ext, $clean_full_ext and @generated_exts
996 variables.)
997 This variable is equivalent to specifying one of the -c or -C options.
999 But there should be no need to set this variable from an RC file.
1000 $clean_ext [""]
1002 Extra extensions of files for latexmk to remove when any of the
1003 clean-up options (-c or -C) is selected. The value of this
1004 variable is a string containing the extensions separated by spa‐
1005 ces.
1006 It is also possible to specify a more general pattern of file to
1008 be deleted, by using the place holder %R, as in commands. Thus
1009 setting
1010 $clean_ext = "out %R-blx.bib";
1012 in an initialization file will imply that when a clean-up opera‐
1014 tion is specified, not only is the standard set of files
1015 deleted, but also files of the form FOO.out and FOO-blx.bib,
1016 where FOO stands for the basename of the file being processed
1017 (as in FOO.tex).
1018 $clean_full_ext [""]
1021 Extra extensions of files for latexmk to remove when the -C
1022 option is selected, i.e., extensions of files to remove when the
1023 .dvi, etc files are to be cleaned-up.
1024 @cus_dep_list [()]
1026 Custom dependency list -- see section on "Custom Dependencies".
1027 @default_files [("*.tex")]
1029 Default list of files to be processed.
1030 Normally, if no filenames are specified on the command line,
1032 latexmk processes all tex files specified in the @default_files
1033 variable, which by default is set to all tex files ("*.tex") in
1034 the current directory. This is a convenience: just run latexmk
1035 and it will process an appropriate set of files. But sometimes
1036 you want only some of these files to be processed. In this case
1037 you set the @default_files in an initialization file (e.g., the
1038 file "latexmkrc" in the current directory). Then if no files
1039 are specified on the command line then the files you specify by
1040 setting @default_files are processed.
1041 Three examples:
1043 @default_files = ("paper_current");
1045 @default_files = ("paper1", "paper2.tex");
1047 @default_files = ("*.tex", "*.dtx");
1049 Note that more than file may be given, and that the default
1051 extension is ".tex". Wild cards are allowed. The parentheses
1052 are because @default_files is an array variable, i.e., a
1053 sequence of filename specifications is possible.
1054 $dependents_list [0]
1056 Whether to display a list(s) of dependencies at the end of a
1057 run.
1058 $dvi_filter [empty]
1060 The dvi file filter to be run on the newly produced dvi file
1061 before other processing. Equivalent to specifying the -dF
1062 option.
1063 $dvi_mode [See below for default]
1065 If nonzero, generate a dvi version of the document. Equivalent
1066 to the -dvi option.
1067 The variable $dvi_mode defaults to 0, but if no explicit requests are
1069 made for other types of file (postscript, pdf), then $dvi_mode will be
1070 set to 1. In addition, if a request for a file for which a .dvi file
1071 is a prerequisite, then $dvi_mode will be set to 1.
1072 $dvi_previewer ["start xdvi %O %S" under UNIX]
1074 The command to invoke a dvi-previewer. [Default is "start"
1075 under MS-WINDOWS; under more recent versions of Windows, this
1076 will cause to be run whatever command the system has associated
1077 with .dvi files.]
1078 $dvi_previewer_landscape ["start xdvi %O %S"]
1080 The command to invoke a dvi-previewer in landscape mode.
1081 [Default is "start" under MS-WINDOWS; under more recent versions
1082 of Windows, this will cause to be run whatever command the sys‐
1083 tem has associated with .dvi files.]
1084 $dvipdf ["dvipdf %O %S %D"]
1086 Command to convert dvi to pdf file. A common reconfiguration is
1087 to use the dvipdfm command, which needs its arguments in a dif‐
1088 ferent order:
1089 $dvipdf = "dvipdfm %O -o %D %S";
1091 WARNING: The default dvipdf script generates pdf files with
1093 bitmapped fonts, which do not look good when viewed by acroread.
1094 That script should be modified to give dvips the options "-P
1095 pdf" to ensure that type 1 fonts are used in the pdf file.
1096 $dvips ["dvips %O -o %D %S"]
1098 The program to used as a filter to convert a .dvi file to a .ps
1099 file. If pdf is going to be generated from pdf, then the value
1100 of the $dvips_pdf_switch -- see below -- will be included in the
1101 options substituted for "%O".
1102 $dvips_landscape ["dvips -tlandscape %O -o %D %S"]
1104 The program to used as a filter to convert a .dvi file to a .ps
1105 file in landscape mode.
1106 $dvips_pdf_switch ["-P pdf"]
1108 Switch(es) for dvips program when pdf file is to be generated
1109 from ps file.
1110 $dvips_silent_switch ["-q"]
1112 Switch(es) for dvips program when silent mode is on.
1113 $dvi_update_command [""]
1115 When the dvi previewer is set to be updated by running a com‐
1116 mand, this is the command that is run. See the information for
1117 the variable $dvi_update_method for further information, and see
1118 information on the variable $pdf_update_method for an example
1119 for the analogous case of a pdf previewer.
1120 $dvi_update_method [2 under UNIX, 1 under MS-Windows]
1122 How the dvi viewer updates its display when the dvi file has
1123 changed. The values here apply equally to the
1124 $pdf_update_method and to the $ps_update_method variables.
1125 0 => update is automatic,
1126 1=> manual update by user, which may only mean a mouse click
1127 on the viewer's window or may mean a more serious action.
1128 2 => Send the signal, whose number is in the variable
1129 $dvi_update_signal. The default value under UNIX is suitable
1130 for xdvi.
1131 3 => Viewer cannot do an update, because it locks the file.
1132 (As with acroread under MS-Windows.)
1133 4 => run a command to do the update. The command is speci‐
1134 fied by the variable $dvi_update_command.
1135 See information on the variable $pdf_update_method for an exam‐
1137 ple of updating by command.
1138 $dvi_update_signal [Under UNIX: SIGUSR1, which is a system-dependent
1140 value]
1141 The number of the signal that is sent to the dvi viewer when it
1142 is updated by sending a signal -- see the information on the
1143 variable $dvi_update_method. The default value is the one
1144 appropriate for xdvi on a UNIX system.
1145 $fdb_ext ["fdb_latexmk"]
1147 The extension of the file which latexmk generates to contain a
1148 database of information on source files. You will not normally
1149 need to change this.
1150 $force_mode [0]
1152 If nonzero, continue processing past minor latex errors includ‐
1153 ing unrecognized cross references. Equivalent to specifying the
1154 -f option.
1155 @generated_exts [( aux , bbl , idx , ind , lof , lot , out , toc ,
1157 $fdb_ext )]
1158 This contains a list of extensions for files that are generated
1159 during a LaTeX run and that are read in by LaTeX in later runs,
1160 either directly or indirectly.
1161 This list has two uses: (a) to set the kinds of file to be
1163 deleted in a cleanup operation (with the -c, -C, -CA, -g and -gg
1164 options), and (b) in the determination of whether a rerun of
1165 (pdf)LaTeX is needed after a run that gives an error.
1166 (Normally, a change of a source file during a run should provoke
1168 a rerun. This includes a file generated by LaTeX, e.g., an aux
1169 file, that is read in on subsequent runs. But after a run that
1170 results in an error, a new run should occur until the user has
1171 made a change in the files. But the user may have corrected an
1172 error in a source .tex file during the run. So latexmk needs to
1173 distinguish user-generated and automatically generated files; it
1174 determines the automatically generated files as those with
1175 extensions in the list in @generated_exts.)
1176 A convenient way to add an extra extension to the list, without
1178 losing the already defined ones is to use a push command in the
1179 line in an RC file. E.g.,
1180 push @generated_exts, "end";
1182 adds the extension "end" to the list of predefined generated
1184 extensions. (This extension is used by the RevTeX package, for
1185 example.)
1186 $go_mode [0]
1188 If nonzero, process files regardless of timestamps, and is then
1189 equivalent to the -g option.
1190 %hash_calc_ignore_pattern
1192 !!!This variable is for experts only!!!
1193 The general rule latexmk uses for determining when an extra run
1195 of some program is needed is that one of the source files has
1196 changed. But consider for example a latex package that causes
1197 an encapsulated postscript file (an "eps" file) to be made that
1198 is to be read in on the next run. The file contains a comment
1199 line giving its creation date and time. On the next run the
1200 time changes, latex sees that the eps file has changed, and
1201 therefore reruns latex. This causes an infinite loop, that is
1202 only terminated becaues latexmk has a limit on the number of
1203 runs to guard against pathological situations.
1204 But the changing line has no real effect, since it is a comment.
1206 You can instruct latex to ignore the offending line as follows:
1207 $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: ';
1209 This creates a rule for files with extension .eps about lines to
1211 ignore. The left-hand side is a Perl idiom for setting an item
1212 in a hash. Note that the file extension is specified without a
1213 period. The value, on the right-hand side, is a string contain‐
1214 ing a regular expresssion. (See documentation on Perl for how
1215 they are to be specified in general.) This particular regular
1216 expression specifies that lines beginning with "%%CreationDate:
1217 " are to be ignored in deciding whether a file of the given
1218 extension .eps has changed.
1219 There is only one regular expression available for each exten‐
1221 sion. If you need more one pattern to specify lines to ignore,
1222 then you need to combine the patterns into a single regular
1223 expression. The simplest method is separate the different sim‐
1224 ple patterns by a vertical bar character (indicating "alterna‐
1225 tion" in the jargon of regular expressions). For example,
1226 $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate:
1228 |^%%Title: ';
1229 causes lines starting with either "^%%CreationDate: " or
1231 "^%%Title: " to be ignored.
1232 It may happen that a pattern to be ignored is specified in, for
1234 example, in a system or user initialization file, and you wish
1235 to remove this in a file read later. To do this, you use perl's
1236 delete function, e.g.,
1237 delete $hash_calc_ignore_pattern{'eps'};
1239 $kpsewhich ["kpsewhich %S"]
1242 The program called to locate a source file when the name alone
1243 is not sufficient. Most filenames used by latexmk have suffi‐
1244 cient path information to be found directly. But sometimes,
1245 notably when .bib files are found from the log file of a bibtex
1246 or biber run, the name of the file, but not its path is known.
1247 The program specified by $kpsewhich is used to find it.
1248 See also the @BIBINPUTS variable for another way that latexmk
1250 also uses to try to locate files; it applies only in the case of
1251 .bib files.
1252 $landscape_mode [0]
1254 If nonzero, run in landscape mode, using the landscape mode pre‐
1255 viewers and dvi to postscript converters. Equivalent to the -l
1256 option. Normally not needed with current previewers.
1257 $latex ["latex %O %S"]
1259 The LaTeX processing program. Note that as with other programs,
1260 you can use this variable not just to change the name of the
1261 program used, but also specify options to the program. E.g.,
1262 $latex = "latex --src-specials";
1264 %latex_input_extensions
1266 This variable specifies the extensions tried by latexmk when it
1267 finds that a LaTeX run resulted in an error that a file has not
1268 been found, and the file is given without an extension. This
1269 typically happens when LaTeX commands of the form \input{file}
1270 or \includegraphics{figure}, when the relevant source file does
1271 not exist.
1272 In this situation, latexmk searches for custom dependencies to
1274 make the missing file(s), but restricts it to the extensions
1275 specified by the variable %latex_input_extensions. The default
1276 extensions are 'tex' and 'eps'.
1277 (For Perl experts: %latex_input_extensions is a hash whose keys
1279 are the extensions. The values are irrelevant.) Two subrou‐
1280 tines are provided for manipulating this and the related vari‐
1281 able %pdflatex_input_extensions, add_input_ext and
1282 remove_input_ext. They are used as in the following examples
1283 are possible lines in an initialization file:
1284 remove_input_ext( 'latex', 'tex' );
1286 removes the extension 'tex' from latex_input_extensions
1288 add_input_ext( 'latex', 'asdf' );
1290 add the extension 'asdf to latex_input_extensions. (Naturally
1292 with such an extension, you should have made an appropriate cus‐
1293 tom dependency for latexmk, and should also have done the appro‐
1294 priate programming in the LaTeX source file to enable the file
1295 to be read. The standard extensions are handled by LaTeX and
1296 its graphics/graphicx packages.
1297 $latex_silent_switch ["-interaction=batchmode"]
1300 Switch(es) for the LaTeX processing program when silent mode is
1301 on.
1302 If you use MikTeX, you may prefer the results if you configure
1304 the options to include -c-style-errors, e.g., by the following
1305 line in an initialization file
1306 $latex_silent_switch = "-interaction=batchmode -c-style-
1308 errors";
1309 $lpr ["lpr %O %S" under UNIX/LINUX, "NONE lpr" under MS-WINDOWS]
1312 The command to print postscript files.
1313 Under MS-Windows (unlike UNIX/LINUX), there is no standard pro‐
1315 gram for printing files. But there are ways you can do it. For
1316 example, if you have gsview installed, you could use it with the
1317 option "/p":
1318 $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
1320 If gsview is installed in a different directory, you will need
1322 to make the appropriate change. Note the combination of single
1323 and double quotes around the name. The single quotes specify
1324 that this is a string to be assigned to the configuration vari‐
1325 able $lpr. The double quotes are part of the string passed to
1326 the operating system to get the command obeyed; this is neces‐
1327 sary because one part of the command name ("Program Files") con‐
1328 tains a space which would otherwise be misinterpreted.
1329 $lpr_dvi ["NONE lpr_dvi"]
1331 The printing program to print dvi files.
1332 $lpr_pdf ["NONE lpr_pdf"]
1334 The printing program to print pdf files.
1335 Under MS-Windows you could set this to use gsview, if it is
1337 installed, e.g.,
1338 $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
1340 If gsview is installed in a different directory, you will need
1342 to make the appropriate change. Note the double quotes around
1343 the name: this is necessary because one part of the command name
1344 ("Program Files") contains a space which would otherwise be mis‐
1345 interpreted.
1346 $make ["make"]
1349 The make processing program.
1350 $makeindex ["makeindex %O -o %D %S"]
1353 The index processing program.
1354 $max_repeat [5]
1356 The maximum number of times latexmk will run latex/pdflatex
1357 before deciding that there may be an infinite loop and that it
1358 needs to bail out, rather than rerunning latex/pdflatex again to
1359 resolve cross-references, etc. The default value covers all
1360 normal cases.
1361 (Note that the "etc" covers a lot of cases where one run of
1363 latex/pdflatex generates files to be read in on a later run.)
1364 $new_viewer_always [0]
1366 This variable applies to latexmk only in continuous-preview
1367 mode. If $new_viewer_always is 0, latexmk will check for a pre‐
1368 viously running previewer on the same file, and if one is run‐
1369 ning will not start a new one. If $new_viewer_always is non-
1370 zero, this check will be skipped, and latexmk will behave as if
1371 no viewer is running.
1372 $pdf_mode [0]
1374 If zero, do NOT generate a pdf version of the document. If
1375 equal to 1, generate a pdf version of the document using pdfla‐
1376 tex. If equal to 2, generate a pdf version of the document from
1377 the ps file, by using the command specified by the $ps2pdf vari‐
1378 able. If equal to 3, generate a pdf version of the document
1379 from the dvi file, by using the command specified by the $dvipdf
1380 variable.
1381 Equivalent to the -pdf-, -pdf, -pdfdvi, -pdfps options.
1383 $pdflatex ["pdflatex %O %S"]
1385 The LaTeX processing program in the version that makes a pdf
1386 file instead of a dvi file.
1387 %pdflatex_input_extensions
1389 This variable specifies the extensions tried by latexmk when it
1390 finds that a pdfLaTeX run resulted in an error that a file has
1391 not been found, and the file is given without an extension.
1392 This typically happens when LaTeX commands of the form
1393 \input{file} or \includegraphics{figure}, when the relevant
1394 source file does not exist.
1395 In this situation, latexmk searches for custom dependencies to
1397 make the missing file(s), but restricts it to the extensions
1398 specified by the variable %pdflatex_input_extensions. The
1399 default extensions are 'tex', 'pdf', 'jpg, and 'png'.
1400 (For Perl experts: %pdflatex_input_extensions is a hash whose
1402 keys are the extensions. The values are irrelevant.) Two sub‐
1403 routines are provided for manipulating this and the related
1404 variable %latex_input_extensions, add_input_ext and
1405 remove_input_ext. They are used as in the following examples
1406 are possible lines in an initialization file:
1407 remove_input_ext( 'pdflatex', 'tex' );
1409 removes the extension 'tex' from pdflatex_input_extensions
1411 add_input_ext( 'pdflatex', 'asdf' );
1413 add the extension 'asdf to pdflatex_input_extensions. (Natu‐
1415 rally with such an extension, you should have made an appropri‐
1416 ate custom dependency for latexmk, and should also have done the
1417 appropriate programming in the LaTeX source file to enable the
1418 file to be read. The standard extensions are handled by pdfla‐
1419 tex and its graphics/graphicx packages.)
1420 $pdflatex_silent_switch ["-interaction=batchmode"]
1423 Switch(es) for the pdflatex program (specified in the variable
1424 $pdflatex when silent mode is on.
1425 If you use MikTeX, you may prefer the results if you configure
1427 the options to include -c-style-errors, e.g., by the following
1428 line in an initialization file
1429 $latex_silent_switch = "-interaction=batchmode -c-style-
1431 errors";
1432 $pdf_previewer ["start acroread %O %S"]
1435 The command to invoke a pdf-previewer. [Default is changed to
1436 "start" on MS-WINDOWS; under more recent versions of Windows,
1437 this will cause to be run whatever command the system has asso‐
1438 ciated with .pdf files.]
1439 WARNING: Potential problem under MS-Windows: if acroread is used
1441 as the pdf previewer, and it is actually viewing a pdf file, the
1442 pdf file cannot be updated. Thus makes acroread a bad choice of
1443 previewer if you use latexmk's previous-continuous mode (option
1444 -pvc) under MS-windows. This problem does not occur if ghost‐
1445 view, gv or gsview is used to view pdf files.
1446 $pdf_update_command [""]
1448 When the pdf previewer is set to be updated by running a com‐
1449 mand, this is the command that is run. See the information for
1450 the variable $pdf_update_method.
1451 $pdf_update_method [1 under UNIX, 3 under MS-Windows]
1453 How the pdf viewer updates its display when the pdf file has
1454 changed. See the information on the variable $dvi_update_method
1455 for the codes. (Note that information needs be changed slightly
1456 so that for the value 4, to run a command to do the update, the
1457 command is specified by the variable $pdf_update_command, and
1458 for the value 2, to specify update by signal, the signal is
1459 specified by $pdf_update_signal.)
1460 Note that acroread under MS-Windows (but not UNIX) locks the pdf
1462 file, so the default value is then 3.
1463 Arranging to use a command to get a previewer explicitly updated
1465 requires three variables to be set. For example:
1466 $pdf_previewer = "start xpdf -remote %R %O %S";
1468 $pdf_update_method = 4;
1469 $pdf_update_command = "xpdf -remote %R -reload";
1470 The first setting arranges for the xpdf program to be used in
1472 its "remote server mode", with the server name specified as the
1473 rootname of the TeX file. The second setting arranges for
1474 updating to be done in response to a command, and the third set‐
1475 ting sets the update command.
1476 $pdf_update_signal [Under UNIX: SIGHUP, which is a system-dependent
1479 value]
1480 The number of the signal that is sent to the pdf viewer when it
1481 is updated by sending a signal -- see the information on the
1482 variable $pdf_update_method. The default value is the one
1483 appropriate for gv on a UNIX system.
1484 $pid_position[1 under UNIX, -1 under MS-Windows]
1486 The variable $pid_position is used to specify which word in
1487 lines of the output from $pscmd corresponds to the process ID.
1488 The first word in the line is numbered 0. The default value of
1489 1 (2nd word in line) is correct for Solaris 2.6 and Linux. Set‐
1490 ting the variable to -1 is used to indicate that $pscmd is not
1491 to be used.
1492 $postscript_mode [0]
1494 If nonzero, generate a postscript version of the document.
1495 Equivalent to the -ps option.
1496 If some other request is made for which a postscript file is needed,
1498 then $postscript_mode will be set to 1.
1499 $preview_continuous_mode [0]
1501 If nonzero, run a previewer to view the document, and continue
1502 running latexmk to keep .dvi up-to-date. Equivalent to the -pvc
1503 option. Which previewer is run depends on the other settings,
1504 see the command line options -view=, and the variable $view.
1505 $preview_mode [0]
1507 If nonzero, run a previewer to preview the document. Equivalent
1508 to the -pv option. Which previewer is run depends on the other
1509 settings, see the command line options -view=, and the variable
1510 $view.
1511 $printout_mode [0]
1513 If nonzero, print the document using lpr. Equivalent to the -p
1514 option. This is recommended not to be set from an RC file, oth‐
1515 erwise you could waste lots of paper.
1516 $print_type = ["ps"]
1518 Type of file to printout: possibilities are "dvi", "none",
1519 "pdf", or "ps".
1520 $pscmd Command used to get all the processes currently run by the user.
1522 The -pvc option uses the command specified by the variable
1523 $pscmd to determine if there is an already running previewer,
1524 and to find the process ID (needed if latexmk needs to signal
1525 the previewer about file changes).
1526 Each line of the output of this command is assumed to correspond
1528 to one process. See the $pid_position variable for how the
1529 process number is determined.
1530 The default for pscmd is "NONE" under MS-Windows and cygwin
1532 (i.e., the command is not used), "ps --width 200 -f -u
1533 $ENV{USER}" under linux, "ps -ww -u $ENV{USER}" under darwin
1534 (Macintosh OS-X), and "ps -f -u $ENV{USER}" under other operat‐
1535 ing systems (including other flavors of UNIX). In these speci‐
1536 fications "$ENV{USER}" is substituted by the username.
1537 $ps2pdf ["ps2pdf %O %S %D"]
1539 Command to convert ps to pdf file.
1540 $ps_filter [empty]
1542 The postscript file filter to be run on the newly produced post‐
1543 script file before other processing. Equivalent to specifying
1544 the -pF option.
1545 $ps_previewer ["start gv %O %S", but "start %O %S" under MS-WINDOWS]
1547 The command to invoke a ps-previewer. (The default under MS-
1548 WINDOWS will cause to be run whatever command the system has
1549 associated with .ps files.)
1550 Note that gv could be used with the -watch option updates its
1552 display whenever the postscript file changes, whereas ghostview
1553 does not. However, different versions of gv have slightly dif‐
1554 ferent ways of writing this option. You can configure this
1555 variable apppropriately.
1556 WARNING: Linux systems may have installed one (or more) versions
1558 of gv under different names, e.g., ggv, kghostview, etc, but
1559 perhaps not one called gv.
1560 $ps_previewer_landscape ["start gv -swap %O %S", but "start %O %S"
1562 under MS-WINDOWS]
1563 The command to invoke a ps-previewer in landscape mode.
1564 $ps_update_command [""]
1566 When the postscript previewer is set to be updated by running a
1567 command, this is the command that is run. See the information
1568 for the variable $ps_update_method.
1569 $ps_update_method [0 under UNIX, 1 under MS-Windows]
1571 How the postscript viewer updates its display when the ps file
1572 has changed. See the information on the variable
1573 $dvi_update_method for the codes. (Note that information needs
1574 be changed slightly so that for the value 4, to run a command to
1575 do the update, the command is specified by the variable
1576 $ps_update_command, and for the value 2, to specify update by
1577 signal, the signal is specified by $ps_update_signal.)
1578 $ps_update_signal [Under UNIX: SIGHUP, which is a system-dependent
1581 value]
1582 The number of the signal that is sent to the pdf viewer when it
1583 is updated by sending a signal -- see $ps_update_method. The
1584 default value is the one appropriate for gv on a UNIX system.
1585 $pvc_view_file_via_temporary [1]
1588 The same as $always_view_file_via_temporary, except that it only
1589 applies in preview-continuous mode (-pvc option).
1590 $quote_filenames [1]
1593 This specifies whether substitutions for placeholders in command
1594 specifications (as in $pdflatex) are surrounded by double
1595 quotes. If this variable is 1 (or any other value Perl regards
1596 as true), then quoting is done. Otherwise quoting is omitted.
1597 The quoting method used by latexmk is tested to work correctly under
1599 UNIX systems (including Linux and Mac OS-X) and under MS-Windows. It
1600 allows the use of filenames containing special characters, notably spa‐
1601 ces. (But note that many versions of LaTeX and PdfLaTeX cannot cor‐
1602 rectly deal with TeX files whose names contain spaces. Latexmk's quot‐
1603 ing only ensures that such filenames are correctly treated by the oper‐
1604 ating system in passing arguments to programs.)
1605 $recorder [0]
1607 Whether to use the -recorder option to latex and pdflatex. Use
1608 of this option results in a file of extension .fls containing a
1609 list of the files that these programs have read and written.
1610 Latexmk will then use this file to improve its detection of
1611 source files and generated files after a run of latex or pdfla‐
1612 tex.
1613 It is generally recommended to use this option (or to configure
1615 the $recorder variable to be on.) But it only works if
1616 (pdf)latex supports the -recorder option, which is true for most
1617 current implementations
1618 Note about the name of the .fls file: Most implementations of
1620 (pdf)latex produce an .fls file with the same basename as the
1621 main document's LaTeX, e.g., for Document.tex, the .fls file is
1622 Document.fls. However, some implementations instead produce
1623 files named for the program, i.e., latex.fls or pdflatex.fls.
1624 In this second case, latexmk copies the latex.fls or pdfla‐
1625 tex.fls to a file with the basename of the main LaTeX document,
1626 e.g., Document.fls.
1627 $sleep_time [2]
1629 The time to sleep (in seconds) between checking for source file
1630 changes when running with the -pvc option. This is subject to a
1631 minimum of one second delay, except that zero delay is also
1632 allowed.
1633 A value of exactly 0 gives no delay, and typically results in
1635 100% CPU usage, which may not be desirable.
1636 $texfile_search [""]
1638 This is an obsolete variable, replaced by the @default_files
1639 variable.
1640 For backward compatibility, if you choose to set $tex‐
1642 file_search, it is a string of space-separated filenames, and
1643 then latexmk replaces @default_files with the filenames in $tex‐
1644 file_search to which is added "*.tex".
1645 $tmpdir [See below for default]
1647 Directory to store temporary files that latexmk may generate
1648 while running.
1649 The default under MSWindows (including cygwin), is to set
1651 $tmpdir to the value of the first of whichever of the system
1652 environment variables TMPDIR or TEMP exists, otherwise to the
1653 current directory. Under other operating systems (expected to
1654 be UNIX/Linux, including OS-X), the default is the value of the
1655 system environment variable TMPDIR if it exists, otherwise
1656 "/tmp".
1657 $use_make_for_missing_files [0]
1659 Whether to use make to try and make files that are missing after
1660 a run of latex or pdflatex, and for which a custom dependency
1661 has not been found. This is generally useful only when latexmk
1662 is used as part of a bigger project which is built by using the
1663 make program.
1664 Note that once a missing file has been made, no further calls to
1666 make will be made on a subsequent run of latexmk to update the
1667 file. Handling this problem is the job of a suitably defined
1668 Makefile. See the section "USING latexmk WITH make" for how to
1669 do this. The intent of calling make from latexmk is merely to
1670 detect dependencies.
1671 $view ["default"]
1673 Which kind of file is to be previewed if a previewer is used.
1674 The possible values are "default", "dvi", "ps", "pdf". The
1675 value of "default" means that the "highest" of the kinds of file
1676 generated is to be used (among dvi, ps and pdf).
1677
1680 In any RC file a set of custom dependencies can be set up to convert a
1681 file with one extension to a file with another. An example use of this
1682 would be to allow latexmk to convert a .fig file to .eps to be included
1683 in the .tex file.
1684 The old method of configuring latexmk was to directly manipulate the
1686 @cus_dep_list array that contains information defining the custom
1687 dependencies. This method still works. But now there are subroutines
1688 that allow convenient manipulations of the custom dependency list.
1689 These are
1690 add_cus_dep( fromextension, toextension, must, subroutine )
1692 remove_cus_dep( fromextension, toextension )
1693 show_cus_dep()
1694 The custom dependency is a list of rules, each of which is specified as
1696 follow:
1697 from extension:
1699 The extension of the file we are converting from (e.g. "fig").
1700 It is specified without a period.
1701 to extension:
1703 The extension of the file we are converting to (e.g. "eps"). It
1704 is specified without a period.
1705 must: If non-zero, the file from which we are converting must exist,
1707 if it doesn't exist latexmk will give an error message and exit
1708 unless the -f option is specified. If must is zero and the file
1709 we are converting from doesn't exist, then no action is taken.
1710 function:
1712 The name of the subroutine that latexmk should call to perform
1713 the file conversion. The first argument to the subroutine is
1714 the base name of the file to be converted without any extension.
1715 The subroutines are declared in the syntax of Perl. The func‐
1716 tion should return 0 if it was successful and a nonzero number
1717 if it failed.
1718 It is invoked whenever latexmk detects that a run of latex/pdflatex
1720 needs to read a file, like a graphics file, whose extension is the to-
1721 extension of a custom dependency. Then latexmk examines whether a file
1722 exists with the same name, but with the corresponding from-extension,
1723 as specified in the custom-dependency rule. If it does, then whenever
1724 the destination file (the one with the to-extension) is out-of-date
1725 with respect to the corresponding source file.
1726 To make the new destination file, the Perl subroutine specified in the
1728 rule is invoked, with an argument that is the base name of the files in
1729 question. Simple cases just involve a subroutine invoking an external
1730 program; this can be done by following the templates below, even by
1731 those without knowledge of the Perl programming language. Of course,
1732 experts could do something much more elaborate.
1733 One other item in each custom-dependency rule labelled "must" above
1735 specifies how the rule should be applied when the source file fails to
1736 exist.
1737 A simple and typical example of code in an initialization rcfile is
1739 add_cus_dep( 'fig', 'eps', 0, 'fig2eps' );
1741 sub fig2eps {
1742 system("fig2dev -Leps $_[0].fig $_[0].eps");
1743 }
1744 The first line adds a custom dependency that converts a file with
1746 extension "fig", as created by the xfig program, to an encapsulated
1747 postscript file, with extension "eps". The remaining lines define a
1748 subroutine that carries out the conversion. If a rule for converting
1749 "fig" to "eps" files already exists (e.g., from a previously read-in
1750 initialization file), the latexmk will delete this rule before making
1751 the new one.
1752 Suppose latexmk is using this rule to convert a file "figure.fig" to
1754 "figure.eps". Then it will invoke the fig2eps subroutine defined in
1755 the above code with a single argument "figure", which is the basename
1756 of each of the files (possibly with a path component). This argument
1757 is referred to by Perl as $_[0]. In the example above, the subroutine
1758 uses the Perl command system to invoke the program fig2dev. The double
1759 quotes around the string are a Perl idiom that signify that each string
1760 of the form of a variable name, $_[0] in this case, is to be substi‐
1761 tuted by its value.
1762 If the return value of the subroutine is non-zero, then latexmk will
1764 assume an error occurred during the execution of the subroutine. In
1765 the above example, no explicit return value is given, and instead the
1766 return value is the value returned by the last (and only) statement,
1767 i.e., the invocation of system, which returns the value 0 on success.
1768 If you use filenames with spaces in them, and if your LaTeX system and
1770 all other relevant software correctly handle such filenames, then you
1771 could put single quotes around filenames in the command line that is
1772 executed:
1773 add_cus_dep( 'fig', 'eps', 0, 'fig2eps' );
1775 sub fig2eps {
1776 system("fig2dev -Lps '$_[0].fig' '$_[0].eps'");
1777 }
1778 This causes the invocation of the fig2dev program to have quoted file‐
1780 names; it should therefore work with filenames containing spaces. How‐
1781 ever, not all software deals correctly with filenames that contain spa‐
1782 ces. Moreover, the rules, if any, for quoting filenames vary between
1783 operating systems, command shells and individual pieces of software, so
1784 this code may not always work.
1785 If you use pdflatex instead of latex, then you will probably prefer to
1787 convert your graphics files to pdf format, in which case you would
1788 replace the above code in an initialization file by
1789 add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' );
1791 sub fig2pdf {
1792 system("fig2dev -Lpdf $_[0].fig $_[0].pdf");
1793 }
1794 If you have some general custom dependencies defined in the system or
1796 user initialization file, you may find that for a particular project
1797 they are undesirable. So you might want to delete the unneeded ones.
1798 For example, you remove any "fig" to "eps" rule by the line
1799 remove_cus_dep( 'fig', 'eps' );
1801 If you have complicated sets of custom dependencies, you may want to
1803 get a listing of the custom dependencies. This is done by using the
1804 line
1805 show_cus_dep();
1807 in an initialization file.
1809 Another example of a custom dependency overcomes a limitation of
1811 latexmk concerning index files. The only index-file conversion built-
1812 in to latexmk is from an ".idx" file written on one run of latex/pdfla‐
1813 tex to an ".ind" file to be read in on a subsequent run. But with the
1814 index.sty package you can create extra indexes with extensions that you
1815 configure. Latexmk does not know how to deduce the extensions from the
1816 information it has. But you can easily write a custom dependency. For
1817 example if your latex file uses the command "\newindex{spe‐
1818 cial}{ndx}{nnd}{Special index}" you will need to convert files with the
1819 extension .ndx to .nnd. The following lines in an initialization RC
1820 file will cause this to happen:
1821 add_cus_dep('ndx', 'nnd', 0, 'makendx2nnd');
1823 sub makendx2nnd {
1824 system("makeindex -o $_[0].nnd $_[0].ndx");
1825 }
1826 (You will need to modify this code if you use filenames with spaces in
1828 them, to provide correct quoting of the filenames.)
1829 Those of you with experience with Makefiles, will undoubtedly be con‐
1831 cerned that the .ndx file is written during a run of latex/pdflatex and
1832 is always later than the .nnd last read in. Thus the .nnd appears to
1833 be perpetually out-of-date. This situation, of circular dependencies,
1834 is endemic to latex, and latexmk in its current version works correctly
1835 with circular dependencies. It examines the contents of the files (by
1836 use of an md5 checksum), and only does a remake when the file contents
1837 have actually changed.
1838 Of course if you choose to write random data to the .nnd (or and .aux
1840 file, etc) that changes on each new run, then you will have a problem.
1841 For real experts: See the %hash_cal_ignore_pattern if you have to deal
1842 with such problems.
1843 Glossaries can be dealt with similarly.
1845
1848 In previous versions of latexmk, the only method of defining custom
1849 dependencies was to directly manipulate the table of custom dependen‐
1850 cies. This is contained in the @cus_dep_list array. It is an array of
1851 strings, and each string in the array has four items in it, each sepa‐
1852 rated by a space, the from-extension, the to-extension, the "must"
1853 item, and the name of the subroutine for the custom dependency. These
1854 were all defined above.
1855 An example of the old method of defining custom dependencies is as fol‐
1857 lows. It is the code in an RC file to ensure automatic conversion of
1858 .fig files to .eps files:
1859 push @cus_dep_list, "fig eps 0 fig2eps";
1861 sub fig2eps {
1862 system("fig2dev -Lps $_[0].fig $_[0].eps");
1863 }
1864 This method still works, and is equivalent to the earlier code using
1866 the add_cus_dep subroutine, except that it doesn't delete any previous
1867 custom-dependency for the same conversion. So the new method is
1868 preferable.
1869
1874 This section is targeted only at advanced users who use the make pro‐
1875 gram for complex projects, as for software development, with the depen‐
1876 dencies specified by a Makefile.
1877 Now the basic task of latexmk is to run the appropriate programs to
1879 make a viewable version of a LaTeX document. However, the usual make
1880 program is not suited to this purpose for at least two reasons. First
1881 is that the use of LaTeX involves circular dependencies (e.g., via .aux
1882 files), and these cannot be handled by the standard make program. Sec‐
1883 ond is that in a large document the set of source files can change
1884 quite frequently, particularly with included graphics files; in this
1885 situation keeping a Makefile manually updated is inappropriate and
1886 error-prone, especially when the depedencies can be determined automat‐
1887 ically. Latexmk solves both of these problems robustly.
1888 Thus for many standard LaTeX documents latexmk can be used by itself
1890 without the make program. In a complex project it simply needs to be
1891 suitably configured. A standard configuration would be to define cus‐
1892 tom dependencies to make graphics files from their source files (e.g.,
1893 as created by the xfig program). Custom dependencies are latexmk's
1894 equivalent of pattern rules in Makefiles.
1895 Nevertheless there are projects for which a Makefile is appropriate,
1897 and it is useful to know how to use latexmk from a Makefile. A typical
1898 example would be to generate documentation for a software project.
1899 Potentially the interaction with the rest of the rules in the Makefile
1900 could be quite complicated, for example if some of the source files for
1901 a LaTeX document are generated by the project's software.
1902 In this section, I give a couple of examples of how latexmk can be use‐
1904 fully invoked from a Makefile. The examples use specific features of
1905 current versions of GNU make, which is the default on both linux and
1906 OS-X systems. They may need modifications for other versions of make.
1907 The simplest method is simply to delegate all the relevant tasks to
1909 latexmk, as is suitable for a straightforward LaTeX document. For this
1910 a suitable Makefile is like
1911 .PHONY : FORCE_MAKE
1913 all : try.pdf
1914 %.pdf : %.tex FORCE_MAKE
1915 latexmk -pdf -dvi- -ps- $<
1916 (Note: the last line must be introduced by a tab for the Makefile to
1918 function correctly!) Naturally, if making try.pdf from its associated
1919 LaTeX file try.tex were the only task to be performed, a direct use of
1920 latexmk without a Makefile would normally be better. The benefit of
1921 using a Makefile for a LaTeX document would be in a larger project,
1922 where lines such as the above would be only be a small part of a larger
1923 Makefile.
1924 The above example has a pattern rule for making a .pdf file from a .tex
1926 file, and it is defined to use latexmk in the obvious way. There is a
1927 conventional default target named "all", with a prerequisite of
1928 try.pdf. So when make is invoked, by default it makes try.pdf. The
1929 only complication is that there may be many source files beyond
1930 try.tex, but these aren't specified in the Makefile, so changes in them
1931 will not by themselves cause latexmk to be invoked. Instead, the pat‐
1932 tern rule is equipped with a "phony" prerequisite FORCE_MAKE; this has
1933 the effect of causing the rule to be always out-of-date, so that
1934 latexmk is always run. It is latexmk that decides whether any action
1935 is needed, e.g., a rerun of pdflatex. Effectively the Makefile dele‐
1936 gates all decisions to latexmk, while make has no knowledge of the list
1937 of source files except for primary LaTeX file for the document. If
1938 there are, for example, graphics files to be made, these must be made
1939 by custom dependencies configured in latexmk.
1940 But something better is needed in more complicated situations, for
1942 example, when the making of graphics files needs to be specified by
1943 rules in the Makefile. To do this, one can use a Makefile like the
1944 following:
1945 TARGETS = document1.pdf document2.pdf
1947 DEPS_DIR = .deps
1948 LATEXMK = latexmk -recorder -use-make -deps \
1949 -e 'warn qq(In Makefile, turn off custom dependencies0;' \
1950 -e '@cus_dep_list = ();' \
1951 -e 'show_cus_dep();'
1952 all : $(TARGETS)
1953 $(foreach file,$(TARGETS),$(eval -include $(DEPS_DIR)/$(file)P))
1954 $(DEPS_DIR) :
1955 mkdir $@
1956 %.pdf : %.tex
1957 if [ ! -e $(DEPS_DIR) ]; then mkdir $(DEPS_DIR); fi
1958 $(LATEXMK) -pdf -dvi- -ps- -deps-out=$(DEPS_DIR)/$@P $<
1959 %.pdf : %.fig
1960 fig2dev -Lpdf $< $@
1961 (Again, the lines containing the commands for the rules should be
1963 started with tabs.) This example was inspired by how GNU automake han‐
1964 dles automatic dependency tracking of C source files.
1965 After each run of latexmk, dependency information is put in a file in
1967 the .deps subdirectory. The Makefile causes these dependency files to
1968 be read by make, which now has the full dependency information for each
1969 target .pdf file. To make things less trivial it is specificed that
1970 two files document1.pdf and document2.pdf are the targets. The depen‐
1971 dency files are .deps/document1.pdfP and .deps/document2.pdfP.
1972 There is now no need for the phony prerequisite for the rule to make
1974 .pdf files from .tex files. But I have added a rule to make .pdf files
1975 from .fig files produced by the xfig program; these are commonly used
1976 for graphics insertions in LaTeX documents. Latexmk is arranged to
1977 output a dependency file after each run. It is given the -recorder
1978 option, which improves its detection of files generated during a run of
1979 pdflatex; such files should not be in the dependency list. The -e
1980 options are used to turn off all custom dependencies, and to document
1981 this. Instead the -use-make is used to delegate the making of missing
1982 files to make itself.
1983 Suppose in the LaTeX file there is a command \includegraphics{graph},
1985 and an xfig file "graph.fig" exists. On a first run, pdflatex reports
1986 a missing file, named "graph". Latexmk succeeds in making "graph.pdf"
1987 by calling "make graph.pdf", and after completion of its work, it lists
1988 "fig.pdf" among the dependents of the file latexmk is making. Then let
1989 "fig.fig" be updated, and then let make be run. Make first remakes
1990 "fig.pdf", and only then reruns latexmk.
1991 Thus we now have a method by which all the subsidiary processing is
1993 delegated to make.
1994
1997 latex(1), bibtex(1).
1998
2000 Sometimes a viewer (gv) tries to read an updated .ps or .pdf file after
2001 its creation is started but before the file is complete. Work around:
2002 manually refresh (or reopen) display. Or use one of the other preview‐
2003 ers and update methods.
2004 (The following isn't really a bug, but concerns features of preview‐
2006 ers.) Preview continuous mode only works perfectly with certain pre‐
2007 viewers: Xdvi on UNIX/LINUX works for dvi files. Gv on UNIX/LINUX
2008 works for both postscript and pdf. Ghostview on UNIX/LINUX needs a
2009 manual update (reopen); it views postscript and pdf. Gsview under MS-
2010 Windows works for both postscript and pdf, but only reads the updated
2011 file when its screen is refreshed. Acroread under UNIX/LINUX views
2012 pdf, but the file needs to be closed and reopened to view an updated
2013 version. Under MS-Windows, acroread locks its input file and so the
2014 pdf file cannot be updated. (Remedy: configure latexmk to use gsview
2015 instead.)
2016
2018 Authors of previous versions. Many users with their feedback, and
2019 especially David Coppit (username david at node coppit.org) who made
2020 many useful suggestions that contributed to version 3, and Herbert
2021 Schulz. (Please note that the e-mail addresses are not written in
2022 their standard form to avoid being harvested by worms and viruses.)
2023
2025 Current version, by John Collins (username collins at node
2026 phys.psu.edu). (Version 4.26).
2027 Released version can be obtained from CTAN: <http://www.tug.org/tex-ar‐
2029 chive/support/latexmk/>, and from the author's website
2030 <http://www.phys.psu.edu/~collins/software/latexmk/>.
2031 Modifications and enhancements by Evan McLean (Version 2.0)
2032 Original script called "go" by David J. Musliner (RCS Version 3.2)
2033 9 August 2011 LATEXMK(1L)