1LATEXMK(1)                  General Commands Manual                 LATEXMK(1)
2
3
4

NAME

6       latexmk - generate LaTeX document
7

SYNOPSIS

9       latexmk [options] [file ...]
10

DESCRIPTION

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
20       By  default  latexmk will run the commands necessary to generate a .dvi
21       file.
22
23       Latexmk can also be set to run continuously with a suitable  previewer.
24       In  that  case  the  latex  program (or one of its relatives), etc, are
25       rerun whenever one of the source files is modified, and  the  previewer
26       automatically updates the on-screen view of the compiled document.
27
28       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, xelatex, lualatex,  etc).   See  the  documentation  for  the
32       -recorder  option  of latexmk below.)  When latexmk is run, it examines
33       properties of the source files, and if any have been changed since  the
34       last document generation, latexmk will run the various LaTeX processing
35       programs as necessary.  In particular, it will repeat the run of  latex
36       (or  a  related program)) often enough to resolve all cross references;
37       depending on the macro packages used.  With  some  macro  packages  and
38       document classes, four, or even more, runs may be needed. If necessary,
39       latexmk will also run bibtex, biber, and/or  makeindex.   In  addition,
40       latexmk can be configured to generate other necessary files.  For exam‐
41       ple, from an updated figure file it can automatically generate  a  file
42       in  encapsulated  postscript  or another suitable format for reading by
43       LaTeX.
44
45       Latexmk has two different previewing  options.   With  the  simple  -pv
46       option,  a  dvi, postscript or pdf previewer is automatically run after
47       generating the dvi, postscript or pdf version  of  the  document.   The
48       type  of  file  to view is selected according to configuration settings
49       and command line options.
50
51       The second previewing option is the  powerful  -pvc  option  (mnemonic:
52       "preview continuously").  In this case, latexmk runs continuously, reg‐
53       ularly monitoring all the source files to  see  if  any  have  changed.
54       Every  time  a change is detected, latexmk runs all the programs neces‐
55       sary to generate a new version of the document.  A good previewer  will
56       then automatically update its display.  Thus the user can simply edit a
57       file and, when the changes are  written  to  disk,  latexmk  completely
58       automates  the  cycle  of  updating  the .dvi (and/or the .ps and .pdf)
59       file, and refreshing the previewer's display.  It's not quite  WYSIWYG,
60       but usefully close.
61
62       For  other previewers, the user may have to manually make the previewer
63       update its display, which can be (e.g., with some versions of xdvi  and
64       gsview) as simple as forcing a redraw of its display.
65
66       Latexmk  has  the  ability  to print a banner in gray diagonally across
67       each page when making the postscript file.  It  can  also,  if  needed,
68       call  an  external  program to do other postprocessing on generated dvi
69       and postscript files.  (See the options -dF and -pF, and the documenta‐
70       tion  for  the  $dvi_filter  and  $ps_filter  configuration variables.)
71       These capabilities are leftover from older versions of latexmk, but are
72       currently  non-functional.  More flexibility can be obtained in current
73       versions, since the command strings for running  latex,  pdflatex,  etc
74       can  now be configured to run multiple commands.  This also extends the
75       possibility of postprocessing generated files.
76
77       Latexmk is highly configurable, both from the command line and in  con‐
78       figuration  files,  so  that  it can accommodate a wide variety of user
79       needs and system configurations.  Default values are set  according  to
80       the operating system, so latexmk often works without special configura‐
81       tion on MS-Windows, cygwin, Linux, OS-X, and other UNIX  systems.   See
82       the  section  "Configuration/Initialization  (rc)  Files", and then the
83       later sections "How to Set Variables in Initialization Files",  "Format
84       of  Command Specifications", "List of Configuration Variables Usable in
85       Initialization Files", "Custom Dependencies", and "Advanced  Configura‐
86       tion"
87
88       A  very annoying complication handled very reliably by latexmk, is that
89       LaTeX is a multiple pass system.  On each run, LaTeX reads in  informa‐
90       tion generated on a previous run, for things like cross referencing and
91       indexing.  In the simplest cases, a second run of LaTeX  suffices,  and
92       often  the log file contains a message about the need for another pass.
93       However, there is a wide variety of add-on  macro  packages  to  LaTeX,
94       with  a  variety  of  behaviors.   The result is to break simple-minded
95       determinations of how many runs  are  needed  and  of  which  programs.
96       Latexmk  has  a  highly general and efficient solution to these issues.
97       The solution involves retaining between runs information on the  source
98       files,  and  a  symptom  is  that latexmk generates an extra file (with
99       extension .fdb_latexmk, by  default)  that  contains  the  source  file
100       information.
101
102

LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE

104       In general the command line to invoke latexmk has the form
105
106            latexmk [options] [file]
107
108       All options can be introduced by single or double "-" characters, e.g.,
109       "latexmk -help" or "latexmk --help".
110
111       Note 1: In addition to the options in the list  below,  latexmk  recog‐
112       nizes almost all the options recognized by the latex, pdflatex programs
113       (and their relatives) in their current TeXLive and  MiKTeX  implementa‐
114       tions.   Some  of  the  options for these programs also trigger special
115       action or behavior by latexmk, in which case they have specific  expla‐
116       nations in this document.  Otherwise, they are just passed through to a
117       called latex or pdflatex program. Run latexmk  with  the  -showextraop‐
118       tions  to  get  a list of the options that latexmk accepts and that are
119       simply passed through to latex or pdflatex (etc).  See also the  expla‐
120       nation of the -showextraoptions option for more information.
121
122       Note  2:  In this documentation, the program pdflatex is often referred
123       to.  Users of programs like lualatex and xelatex should know that  from
124       latexmk's  point  of view, these other programs behave very like pdfla‐
125       tex, i.e., they make a pdf file from a  tex  file,  etc.   So  whenever
126       pdflatex is mentioned without mention of the other programs, the state‐
127       ments apply equally to lualatex, xelatex, and any  other  similar  pro‐
128       grams.  Latexmk can be easily configured to use whichever of these pro‐
129       grams is needed.  See the  documentation  for  the  following  options:
130       -pdflua,  -pdfxe,  -lualatex, and -xelatex, and also see the documenta‐
131       tion for the $pdflatex, $lualatex,  and  $xelatex  configuration  vari‐
132       ables.   At  present  latexmk  does not do automatic detection of which
133       program is to be used.
134
135
136       Definitions of options and arguments
137
138
139       file   One or more files can be specified.  If no files are  specified,
140              latexmk  will, by default, run on all files in the current work‐
141              ing directory with a ".tex" extension.   This  behavior  can  be
142              changed: see the description concerning the @default_files vari‐
143              able in the section "List of configuration variables  usable  in
144              initialization files".
145
146              If  a  file  is  specified without an extension, then the ".tex"
147              extension is automatically added, just as LaTeX does.  Thus,  if
148              you specify:
149
150                   latexmk foo
151
152              then latexmk will operate on the file "foo.tex".
153
154              There  are  certain  restrictions on what characters can be in a
155              filename; certain characters are either prohibited  or  problem‐
156              atic  for  the  latex  etc programs.  These characters are: "$",
157              "%", "\", "~", the double quote character, and the control char‐
158              acters  null,  tab,  form  feed, carriage return, line feed, and
159              delete.  In addition "&" is prohibited  when  it  is  the  first
160              character of a filename.
161
162              Latexmk  gives  a  fatal  error when it detects any of the above
163              characters in the TeX filename(s) specified on the command line.
164              However  before  testing for illegal characters, latexmk removes
165              matching pairs of double quotes from a filename.   This  matches
166              the  behavior  of  latex etc, and deals with problems that occa‐
167              sionally result from filenames that have been incorrectly quoted
168              on  the command line.  In addition, under Microsoft Windows, the
169              forward slash character "\" is a directory separator, so latexmk
170              replaces  it  by  a  backward  slash  "/", which is also a legal
171              directory separator in Windows, and is accepted by latex etc.
172
173
174       -auxdir=FOO or -aux-directory=FOO
175              Sets the directory for  auxiliary  output  files  of  (pdf)latex
176              (.aux,  .log  etc).  This achieves its effect by the -aux-direc‐
177              tory option of (pdf)latex, which currently is  only  implemented
178              on the MiKTeX version of (pdf)latex.
179
180              See   also   the   -outdir/-output-directory  options,  and  the
181              $aux_dir,  $out_dir,  and  $search_path_separator  configuration
182              variables  of  latexmk.  In particular, see the documentation of
183              $out_dir for some complications  on  what  directory  names  are
184              suitable.
185
186              If you also use the -cd option, and the specified auxiliary out‐
187              put directory is a relative path, then the path  is  interpreted
188              relative to the document directory.
189
190
191       -bibtex
192              When the source file uses bbl files for bibliography, run bibtex
193              or biber as needed to regenerate the bbl files.
194
195              This property can also be configured by setting the  $bibtex_use
196              variable to 2 in a configuration file.
197
198
199       -bibtex-
200              Never  run  bibtex  or  biber.  Also, always treat .bbl files as
201              precious, i.e., do not delete them in a cleanup operation.
202
203              A common use for this option is when a document  comes  from  an
204              external  source,  complete  with  its bbl file(s), and the user
205              does not have the corresponding bib files  available.   In  this
206              situation  use  of the -bibtex- option will prevent latexmk from
207              trying to run bibtex or biber, which would result in overwriting
208              of the bbl files.
209
210              This  property can also be configured by setting the $bibtex_use
211              variable to 0 in a configuration file.
212
213
214       -bibtex-cond
215              When the source file uses bbl file(s) for the bibliography,  run
216              bibtex  or biber as needed to regenerate the bbl files, but only
217              if the relevant bib file(s) exist.  Thus when the bib files  are
218              not  available,  bibtex  or  biber  is not run, thereby avoiding
219              overwriting of the bbl file(s).  Also, always treat  .bbl  files
220              as precious, i.e., do not delete them in a cleanup operation.
221
222              This  is the default setting.  It can also be configured by set‐
223              ting the $bibtex_use variable to 1 in a configuration file.
224
225              The reason for using this setting is that sometimes a .bbl  file
226              is available containing the bibliography for a document, but the
227              .bib file is not available.  An example would be  for  a  scien‐
228              tific  journal where authors submit .tex and .bbl files, but not
229              the original .bib file.  In that case, running bibtex  or  biber
230              would  not  work,  and the .bbl file should be treated as a user
231              source file, and not as  a  file  that  can  be  regenerated  on
232              demand.
233
234              (Note  that  it  is  possible for latexmk to decide that the bib
235              file does not exist, even though the bib  file  does  exist  and
236              bibtex  or biber finds it.  The problem is that the bib file may
237              not be in the current directory but in  some  search  path;  the
238              places latexmk and bibtex or biber cause to be searched need not
239              be identical.  On modern installations of TeX and  related  pro‐
240              grams  this  problem  should  not  arise, since latexmk uses the
241              kpsewhich program to do the search, and kpsewhich should use the
242              same  search  path as bibtex and biber.  If this problem arises,
243              use the -bibtex option when invoking latexmk.)
244
245              Note that this value does not work properly if the document uses
246              biber instead of bibtex.  (There's a long story why not.)
247
248
249       -bibtex-cond1
250              The  same  as  -bibtex-cond1  except  that  .bbl  files are only
251              treated as precious if one or more bibfiles fails to exist.
252
253              Thus if all the bib files exist, bibtex or biber is run to  gen‐
254              erate .bbl files as needed, and then it is appropriate to delete
255              the bbl files in a cleanup operation since they can be re-gener‐
256              ated.
257
258              This  property can also be configured by setting the $bibtex_use
259              variable to 1.5 in a configuration file.
260
261
262       -bm <message>
263              A banner message to print diagonally across each page when  con‐
264              verting  the dvi file to postscript.  The message must be a sin‐
265              gle argument on the command line so be careful with quoting spa‐
266              ces and such.
267
268              Note  that  if  the  -bm  option is specified, the -ps option is
269              assumed.
270
271
272       -bi <intensity>
273              How dark to print the banner message.  A decimal number  between
274              0 and 1.  0 is black and 1 is white.  The default is 0.95, which
275              is OK unless your toner cartridge is getting low.
276
277
278       -bs <scale>
279              A decimal number that specifies how  large  the  banner  message
280              will  be printed.  Experimentation is necessary to get the right
281              scale for your message, as a rule of thumb the scale  should  be
282              about  equal  to 1100 divided by the number of characters in the
283              message.  The default is 220.0 which is just right for 5 charac‐
284              ter messages.
285
286
287       -commands
288              List the commands used by latexmk for processing files, and then
289              exit.
290
291
292       -c     Clean up (remove) all regeneratable files generated by latex and
293              bibtex or biber except dvi, postscript and pdf.  These files are
294              a combination of log files, aux files, latexmk's  database  file
295              of  source file information, and those with extensions specified
296              in the @generated_exts  configuration  variable.   In  addition,
297              files specified by the $clean_ext and @generated_exts configura‐
298              tion variables are removed.
299
300              This cleanup is instead of a regular make.  See the  -gg  option
301              if you want to do a cleanup then a make.
302
303              Treatment  of  .bbl files:  If $bibtex_use is set to 0 or 1, bbl
304              files are always treated as non-regeneratable.   If  $bibtex_use
305              is set to 1.5, bbl files are counted as non-regeneratable condi‐
306              tionally: If the bib file exists, then bbl files are  regenerat‐
307              able,  and are deleted in a clean up.  But if $bibtex_use is 1.5
308              and a bib file doesn't exist, then the bbl files are treated  as
309              non-regeneratable and hence are not deleted.
310
311              In  contrast,  if  $bibtex_use is set to 2, bbl files are always
312              treated as regeneratable, and are deleted in a cleanup.
313
314              Treatment  of  files  generated  by  custom   dependencies:   If
315              $cleanup_includes_cusdep_generated   is  nonzero,  regeneratable
316              files are considered as  including  those  generated  by  custom
317              dependencies  and  are  also deleted.  Otherwise these files are
318              not deleted.
319
320
321       -C     Clean up (remove) all regeneratable files generated by latex and
322              bibtex  or  biber.   This  is the same as the -c option with the
323              addition of dvi, postscript and pdf files, and  those  specified
324              in the $clean_full_ext configuration variable.
325
326              This  cleanup  is instead of a regular make.  See the -gg option
327              if you want to do a cleanup than a make.
328
329              See the -c option for the specification of whether or  not  .bbl
330              files are treated as non-regeneratable or regeneratable.
331
332              If  $cleanup_includes_cusdep_generated is nonzero, regeneratable
333              files are considered as  including  those  generated  by  custom
334              dependencies  and  are  also deleted.  Otherwise these files are
335              not deleted.
336
337
338       -CA    (Obsolete).  Now equivalent to the -C option.  See  that  option
339              for details.
340
341
342       -cd    Change  to  the directory containing the main source file before
343              processing it.  Then all the generated files (.aux, .log,  .dvi,
344              .pdf, etc) will be relative to the source file.
345
346              This  option is particularly useful when latexmk is invoked from
347              a GUI configured to invoke latexmk with a full pathname for  the
348              source file.
349
350              This  option  works by setting the $do_cd configuration variable
351              to one; you can set that  variable  if  you  want  to  configure
352              latexmk  to have the effect of the -cd option without specifying
353              it on the command line.  See the documentation  for  that  vari‐
354              able.
355
356
357       -cd-   Do  NOT  change to the directory containing the main source file
358              before processing it.  Then all the generated files (.aux, .log,
359              .dvi,  .pdf,  etc)  will  be  relative  to the current directory
360              rather than the source file.
361
362              This is the default behavior and corresponds to the behavior  of
363              the  latex  and pdflatex programs.  However, it is not desirable
364              behavior when latexmk is invoked by a GUI configured  to  invoke
365              latexmk  with  a full pathname for the source file.  See the -cd
366              option.
367
368              This option works by setting the $do_cd  configuration  variable
369              to  zero.   See  the  documentation  for  that variable for more
370              information.
371
372
373       -CF    Remove the file containing the database of source file  informa‐
374              tion, before doing the other actions requested.
375
376
377       -d     Set  draft  mode.  This prints the banner message "DRAFT" across
378              your page when converting the dvi file to postscript.  Size  and
379              intensity can be modified with the -bs and -bi options.  The -bm
380              option will override this option as this is really just a  short
381              way of specifying:
382
383                   latexmk -bm DRAFT
384
385              Note  that  if  the  -d  option  is specified, the -ps option is
386              assumed.
387
388
389       -deps  Show a list of dependent files after processing.  This is in the
390              form  of a dependency list of the form used by the make program,
391              and it is therefore suitable for use in a Makefile.  It gives an
392              overall view of the files without listing intermediate files, as
393              well as latexmk can determine them.
394
395              By default the list of dependent files is sent to stdout  (i.e.,
396              normally  to  the screen unless you've redirected latexmk's out‐
397              put). But you can set the filename where the list is sent by the
398              -deps-out= option.
399
400              See  the section "USING latexmk WITH make" for an example of how
401              to use a dependency list with make.
402
403              Users familiar with GNU automake and  gcc  will  find  that  the
404              -deps  option  is very similar in its purpose and results to the
405              -M option to gcc.  (In fact, latexmk also has options  -M,  -MF,
406              and -MP options that behave like those of gcc.)
407
408
409       -dependents
410              Equivalent to -deps.
411
412
413       -deps- Do  not  show a list of dependent files after processing.  (This
414              is the default.)
415
416
417       -dependents-
418              Equivalent to -deps-.
419
420
421       -deps-out=FILENAME
422              Set the filename to which the list of dependent files  is  writ‐
423              ten.   If  the  FILENAME argument is omitted or set to "-", then
424              the output is sent to stdout.
425
426              Use of this option also turns on  the  output  of  the  list  of
427              dependent files after processing.
428
429
430       -dF    Dvi  file  filtering.   The  argument to this option is a filter
431              which will generate a  filtered  dvi  file  with  the  extension
432              ".dviF".   All  extra processing (e.g. conversion to postscript,
433              preview, printing) will then be performed on this  filtered  dvi
434              file.
435
436              Example usage: To use dviselect to select only the even pages of
437              the dvi file:
438
439                   latexmk -dF "dviselect even" foo.tex
440
441
442       -diagnostics
443              Print detailed diagnostics during a  run.   This  may  help  for
444              debugging problems or to understand latexmk's behavior in diffi‐
445              cult situations.
446
447
448       -dvi   Generate dvi version of document.
449
450
451       -dvi-  Turn off generation of dvi version of document.  (This  may  get
452              overridden,  if  some other file is made (e.g., a .ps file) that
453              is generated from the dvi file, or if no generated file  at  all
454              is requested.)
455
456
457       -e <code>
458              Execute  the  specified  initialization  code before processing.
459              The code is Perl code of the same form as is used  in  latexmk's
460              initialization  files.  For more details, see the information on
461              the -r option, and the section about  "Configuration/initializa‐
462              tion  (RC)  files".  The code is typically a sequence of assign‐
463              ment statements separated by semicolons.
464
465              The code is executed when the -e option  is  encountered  during
466              latexmk's  parsing of its command line.  See the -r option for a
467              way of executing initialization code  from  a  file.   An  error
468              results  in  latexmk stopping.  Multiple instances of the -r and
469              -e options can be used, and they are executed in the order  they
470              appear on the command line.
471
472              Some care is needed to deal with proper quoting of special char‐
473              acters in the code on the command line.   For  example,  suppose
474              you  want  to  set  the  latex  command to use its -shell-escape
475              option, then under UNIX/Linux you could use the line
476
477                   latexmk -e '$latex=q/latex %O -shell-escape %S/' file.tex
478
479              Note that the single  quotes  block  normal  UNIX/Linux  command
480              shells  from  treating  the characters inside the quotes as spe‐
481              cial.  (In this example, the q/.../ construct is  a  Perl  idiom
482              equivalent  to  using  single quotes.  This avoids the complica‐
483              tions of getting a quote  character  inside  an  already  quoted
484              string  in  a  way that is independent of both the shell and the
485              operating-system.)
486
487              The above command line  will  NOT  work  under  MS-Windows  with
488              cmd.exe  or  command.com  or 4nt.exe.  For MS-Windows with these
489              command shells you could use
490
491                   latexmk -e "$latex=q/latex %O -shell-escape %S/" file.tex
492
493              or
494
495                   latexmk -e "$latex='latex %O -shell-escape %S'" file.tex
496
497              The last two examples will  NOT  work  with  UNIX/Linux  command
498              shells.
499
500              (Note:  the above examples show are to show how to use the -e to
501              specify initialization code to be executed.  But the  particular
502              effect can be achieved also by the use of the -latex option with
503              less problems in dealing with quoting.)
504
505
506       -f     Force latexmk to continue document  processing  despite  errors.
507              Normally, when latexmk detects that LaTeX or another program has
508              found an error which will not be resolved by further processing,
509              no further processing is carried out.
510
511              Note:  "Further  processing" means the running of other programs
512              or the rerunning of latex (etc) that would be done if no  errors
513              had  occurred.   If instead, or additionally, you want the latex
514              (etc) program not to pause for user input after  an  error,  you
515              should  arrange this by an option that is passed to the program,
516              e.g., by latexmk's option -interaction=nonstopmode.
517
518
519       -f-    Turn off the forced processing-past-errors such as is set by the
520              -f  option.   This could be used to override a setting in a con‐
521              figuration file.
522
523
524       -g     Force latexmk to process document fully, even  under  situations
525              where  latexmk  would  normally  decide  that  no changes in the
526              source files have occurred since the previous run.  This  option
527              is  useful,  for example, if you change some options and wish to
528              reprocess the files.
529
530
531       -g-    Turn off -g.
532
533
534       -gg    "Super go mode" or "clean make": clean out generated files as if
535              -C had been given, and then do a regular make.
536
537
538       -h, -help
539              Print help information.
540
541
542       -jobname=STRING
543              Set  the  basename  of output files(s) to STRING, instead of the
544              default, which is the basename of the specified TeX  file.   (At
545              present, STRING should not contain spaces.)
546
547              This  is like the same option for current implementations of the
548              latex, pdflatex, etc, and the passing of this  option  to  these
549              programs is part of latexmk's implementation of -jobname.
550
551              There is one enhancement, that the STRING may contain the place‐
552              holder '%A'. This will be substituted by the basename of the TeX
553              file.   The primary purpose is when multiple files are specified
554              on the command line to latexmk, and you wish to  use  a  jobname
555              with  a different file-dependent value for each file.  For exam‐
556              ple, suppose you had .tex files test1.tex and test2.tex, and you
557              wished  to  compare  the  results of compilation by pdflatex and
558              those with xelatex.  Then under a unix-type operating system you
559              could use the command line
560
561                  latexmk -pdf -jobname=%A-pdflatex *.tex
562                  latexmk -pdfxe -jobname=%A-xelatex *.tex
563
564              Then  the  .aux,  .log,  and .pdf files from the use of pdflatex
565              would have basenames test1-pdflatex  and  test2-pdflatex,  while
566              from   xelatex,   the   basenames  would  be  test1-xelatex  and
567              test2-xelatex.
568
569              Under MS-Windows with cmd.exe, you would need to double the per‐
570              cent  sign,  so  that the percent character is passed to latexmk
571              rather than being used to substitute an environment variable:
572
573                  latexmk -pdf -jobname=%%A-pdflatex *.tex
574                  latexmk -pdfxe -jobname=%%A-xelatex *.tex
575
576
577       -l     Run in landscape mode, using the landscape mode for the preview‐
578              ers  and  the  dvi to postscript converters.  This option is not
579              normally needed  nowadays,  since  current  previewers  normally
580              determine this information automatically.
581
582
583       -l-    Turn off -l.
584
585
586       -latex="COMMAND"
587              This sets the string specifying the command to run latex, and is
588              typically used to add desired options.  Since  the  string  nor‐
589              mally contains spaces, it should be quoted, e.g.,
590
591                   latexmk -latex="latex --shell-escape %O %S"  foo.tex
592
593              The  specification of the contents of the string are the same as
594              for the $latex configuration variable.  Depending on your  oper‐
595              ating  system  and the command-line shell you are using, you may
596              need to change the single quotes to double quotes (or  something
597              else).
598
599              To set the command for running pdflatex (rather than the command
600              for latex) see the -pdflatex option.
601
602
603       -logfilewarninglist
604              -logfilewarnings After a run of (pdf)latex, give a list of warn‐
605              ings  about  undefined  citations  and references (unless silent
606              mode is on).
607
608              See also the $silence_logfile_warnings configuration variable.
609
610
611       -logfilewarninglist-
612              -logfilewarnings- After a run of (pdf)latex, do not give a  list
613              of warnings about undefined citations and references.  (Default)
614
615              See also the $silence_logfile_warnings configuration variable.
616
617
618       -lualatex
619              Use  lualatex.   That  is,  use  lualatex  to process the source
620              file(s) to pdf.  The generation of dvi and postscript  files  is
621              turned off.
622
623              This option is equivalent to using the following set of options
624
625                   -pdflua -dvi- -ps-
626
627              (Note:  Note  that  the method of implementation of this option,
628              but not its intended effect, differ from some  earlier  versions
629              of latexmk.)
630
631
632       -M     Show  list of dependent files after processing.  This is equiva‐
633              lent to the -deps option.
634
635
636       -MF file
637              If a list of dependents is made, the -MF specifies the  file  to
638              write it to.
639
640
641       -MP    If a list of dependents is made, include a phony target for each
642              source file.  If you use the dependents list in a Makefile,  the
643              dummy  rules  work  around  errors the program make gives if you
644              remove header files without updating the Makefile to match.
645
646
647       -new-viewer
648              When in continuous-preview mode, always start a  new  viewer  to
649              view  the generated file.  By default, latexmk will, in continu‐
650              ous-preview mode, test for a previously  running  previewer  for
651              the same file and not start a new one if a previous previewer is
652              running.  However, its test sometimes fails (notably if there is
653              an  already-running previewer that is viewing a file of the same
654              name as the current file, but in a different  directory).   This
655              option turns off the default behavior.
656
657
658       -new-viewer-
659              The  inverse  of the -new-viewer option.  It puts latexmk in its
660              normal behavior that in preview-continuous mode it checks for an
661              already-running previewer.
662
663
664       -nobibtex
665              Never run bibtex or biber.  Equivalent to the -bibtex- option.
666
667
668       -norc  Turn off the automatic reading of initialization (rc) files.
669
670              N.B.  Normally the initialization files are read and obeyed, and
671              then command line options are  obeyed  in  the  order  they  are
672              encountered.   But  -norc  is  an  exception to this rule: it is
673              acted on first, no matter where it occurs on the command line.
674
675
676       -outdir=FOO or -output-directory=FOO
677
678              Sets the directory for the output  files  of  (pdf)latex.   This
679              achieves   its   effect   by  the  -output-directory  option  of
680              (pdf)latex, which currently (Dec. 2011 and later) is implemented
681              on  the common versions of (pdf)latex, i.e., MiKTeX and TeXLive.
682              It may not be present in other versions.
683
684              See also the -auxdir/-aux-directory options, and  the  $aux_dir,
685              $out_dir,  and $search_path_separator configuration variables of
686              latexmk.  In particular, see the documentation of  $out_dir  for
687              some complications on what directory names are suitable.
688
689              If  you also use the -cd option, and the specified output direc‐
690              tory is a relative path, then the path is  interpreted  relative
691              to the document directory.
692
693
694       -p     Print  out  the  document.  By default the file to be printed is
695              the first in the list postscript, pdf, dvi that is  being  made.
696              But you can use the -print=... option to change the type of file
697              to be printed, and you can configure this in a start up file (by
698              setting the $print_type variable).
699
700              However,  printing  is  enabled by default only under UNIX/Linux
701              systems, where the default is to use the lpr command and only on
702              postscript files.  In general, the correct behavior for printing
703              very much depends on your  system's  software.   In  particular,
704              under  MS-Windows  you  must have suitable program(s) available,
705              and you must have configured the print commands used by latexmk.
706              This  can  be  non-trivial.   See the documentation on the $lpr,
707              $lpr_dvi, and $lpr_pdf configuration variables to see how to set
708              the commands for printing.
709
710              This option is incompatible with the -pv and -pvc options, so it
711              turns them off.
712
713
714       -pdf   Generate pdf version of document using pdflatex.  (If  you  wish
715              to use lualatex or xelatex, you can use whichever of the options
716              -pdflua, -pdfxe, -lualatex or -xelatex applies.)   To  configure
717              latexmk  to  have  such  behavior by default, see the section on
718              "Configuration/initialization (rc) files".
719
720
721       -pdfdvi
722              Generate pdf version of document from the dvi file,  by  default
723              using dvipdf.
724
725
726       -pdflua
727              Generate pdf version of document using lualatex.
728
729
730       -pdfps Generate  pdf  version of document from the .ps file, by default
731              using ps2pdf.
732
733
734       -pdfxe Generate pdf version of document using xelatex.   Note  that  to
735              optimize  processing  time,  latexmk uses xelatex to generate an
736              .xdv file rather than a pdf file directly.  Only after  possibly
737              multiple  runs  to  generate  a  fully up-to-date .xdv file does
738              latexmk then call xdvipdfmx to generate the final .pdf file.
739
740              (Note: When the document includes large  graphics  files,  espe‐
741              cially  .png  files,  the last step can be quite time consuming,
742              even when the creation of the .xdv file by xelatex is fast.   So
743              the  use of the intermediate .xdv file can result in substantial
744              gains in procesing time, since the .pdf file  is  produced  once
745              rather  than  on  every run of xelatex. See the documentation on
746              the -pdfxe option for why an .xdv file is used.
747
748
749       -pdf-  Turn off generation of pdf version of document.   (This  can  be
750              used  to override a setting in a configuration file.  It may get
751              overridden if some other option requires the generation of a pdf
752              file.)
753
754              If  after  all  options  have  been processed, pdf generation is
755              still turned off, then generation of a dvi file will  be  turned
756              on,  and  then  the  program used to compiled a document will be
757              latex (or, more precisely, whatever program is configured to  be
758              used in the $latex configuration variable).
759
760
761       -pdflatex="COMMAND"
762              This sets the string specifying the command to run pdflatex, and
763              is typically used to add desired options.  Since the string nor‐
764              mally contains spaces, it should be quoted, e.g.,
765
766                   latexmk  -pdf  -pdflatex="pdflatex  --shell-escape  %O  %S"
767              foo.tex
768
769              The specification of the contents of the string are the same  as
770              for the $pdflatex configuration variable.  (The option -pdflatex
771              in fact sets the variable $pdflatex.)  Depending on your operat‐
772              ing  system  and  the  command-line shell you are using, you may
773              need to change the single quotes to double quotes (or  something
774              else).
775
776              To  set  the  command for running latex (rather than the command
777              for pdflatex) see the -latex option.
778
779
780       -pdflualatex="COMMAND"
781              This sets the string specifying the command to run lualatex.  It
782              behaves like the -pdflatex option, but sets the variable $luala‐
783              tex.
784
785
786       -pdfxelatex="COMMAND"
787              This sets the string specifying the command to run xelatex.   It
788              behaves  like the -pdflatex option, but sets the variable $xela‐
789              tex.
790
791              Warning: It is important to ensure that the -no-pdf is used when
792              xelatex  is invoked; see the explanation for the variable $xela‐
793              tex for why this is necessary.  If you provide %O in the command
794              specification, this will be done automatically.
795
796              An example of the use of the -pdfxelatex option:
797
798                   latexmk  -pdfxe  -pdfxelatex="xelatex --shell-escape %O %S"
799              foo.tex
800
801
802
803       -pretex=CODE
804
805              Given that CODE is some TeX code, this options sets that code to
806              be  executed  before  inputting source file.  This only works if
807              the command for invoking the relevant *latex is suitably config‐
808              ured.   See the documentation of the variable $pre_tex_code, and
809              the substitution strings %P  and  %U  for  more  details.   This
810              option works by setting the variable $pre_tex_code.
811
812              See also the -usepretex option.
813
814              An example:
815
816                  latexmk  -pretex='\AtBeginDocument{Message\par}'  -usepretex
817              foo.tex
818
819              But this is better written
820
821                  latexmk -usepretex='\AtBeginDocument{Message\par}' foo.tex
822
823              If you already have a suitable command configured, you only need
824
825                  latexmk -pretex='\AtBeginDocument{Message\par}' foo.tex
826
827
828       -print=dvi, -print=ps, -print=pdf, -print=auto,
829              Define which kind of file is printed.  This option also  ensures
830              that the requisite file is made, and turns on printing.
831
832              The (default) case -print=auto determines the kind of print file
833              automatically from the set of files that  is  being  made.   The
834              first  in  the list postscript, pdf, dvi that is among the files
835              to be made is the one used for print out.
836
837
838       -ps    Generate postscript version of document.
839
840
841       -ps-   Turn off generation of postscript version of document.  This can
842              be  used to override a setting in a configuration file.  (It may
843              get overridden by some other option that requires  a  postscript
844              file, for example a request for printing.)
845
846
847       -pF    Postscript  file  filtering.   The  argument to this option is a
848              filter which will generate a filtered postscript file  with  the
849              extension ".psF".  All extra processing (e.g. preview, printing)
850              will then be performed on this filtered postscript file.
851
852              Example of usage: Use psnup to print two pages on the one page:
853
854                   latexmk -ps -pF 'psnup -2' foo.tex
855
856              or
857
858                   latexmk -ps -pF "psnup -2" foo.tex
859
860              Whether to use single or double quotes round the "psnup -2" will
861              depend  on  your  command interpreter, as used by the particular
862              version of perl and the operating system on your computer.
863
864
865       -pv    Run file previewer.  If the -view  option  is  used,  this  will
866              select  the  kind  of  file to be previewed (.dvi, .ps or .pdf).
867              Otherwise the viewer views the "highest" kind of file  selected,
868              by  the -dvi, -ps, -pdf, -pdfps options, in the order .dvi, .ps,
869              .pdf (low to high).  If no file type has been selected, the  dvi
870              previewer will be used.  This option is incompatible with the -p
871              and -pvc options, so it turns them off.
872
873
874       -pv-   Turn off -pv.
875
876
877       -pvc   Run a file previewer  and  continually  update  the  .dvi,  .ps,
878              and/or .pdf files whenever changes are made to source files (see
879              the Description above).  Which of these files is  generated  and
880              which  is  viewed  is  governed by the other options, and is the
881              same as for the -pv option.  The preview-continuous option  -pvc
882              can  only work with one file.  So in this case you will normally
883              only specify one filename on  the  command  line.   It  is  also
884              incompatible  with  the  -p  and  -pv options, so it turns these
885              options off.
886
887              The -pvc option also turns off force mode (-f), as  is  normally
888              best  for  continuous  preview  mode.   If you really want force
889              mode, use the options in the order -pvc -f.
890
891              With a good previewer the display will be automatically updated.
892              (Under  some but not all versions of UNIX/Linux "gv -watch" does
893              this for postscript files; this can be set  by  a  configuration
894              variable.   This  would  also  work  for pdf files except for an
895              apparent bug in gv that causes an error when the  newly  updated
896              pdf  file  is  read.)   Many other previewers will need a manual
897              update.
898
899              Important note: the acroread program on MS-Windows locks the pdf
900              file,  and  prevents  new versions being written, so it is a bad
901              idea to use acroread to view  pdf  files  in  preview-continuous
902              mode.   It  is  better to use a different viewer: SumatraPDF and
903              gsview are good possibilities.
904
905              There are some other methods for arranging  an  update,  notably
906              useful  for  many versions of xdvi and xpdf.  These are best set
907              in latexmk's configuration; see below.
908
909              Note that if latexmk  dies  or  is  stopped  by  the  user,  the
910              "forked" previewer will continue to run.  Successive invocations
911              with the -pvc option will not fork new previewers,  but  latexmk
912              will  normally  use the existing previewer.  (At least this will
913              happen when latexmk is running under an operating  system  where
914              it  knows how to determine whether an existing previewer is run‐
915              ning.)
916
917
918       -pvc-  Turn off -pvc.
919
920
921       -pvctimeout
922              Do timeout in pvc mode after period of inactivity, which  is  30
923              min.  by  default.   Inactivity  means a period when latexmk has
924              detected no file changes and hence has  not  taken  any  actions
925              like compiling the document.
926
927
928       -pvctimeout-
929              Don't do timeout in pvc mode after inactivity.
930
931
932       -pvctimeoutmins=<time>
933              Set period of inactivity in minutes for pvc timeout.
934
935
936       -quiet Same as -silent
937
938
939       -r <rcfile>
940              Read  the  specified initialization file ("RC file") before pro‐
941              cessing.
942
943              Be careful about the ordering: (1) Standard initialization files
944              --  see  the section below on "Configuration/initialization (RC)
945              files" -- are read first.  (2) Then the options on  the  command
946              line  are acted on in the order they are given.  Therefore if an
947              initialization file is specified by the -r option,  it  is  read
948              during  this second step.  Thus an initialization file specified
949              with the -r option can override both the standard initialization
950              files and previously specified options.  But all of these can be
951              overridden by later options.
952
953              The contents of the RC file just comprise a piece of code in the
954              Perl  programming  language  (typically a sequence of assignment
955              statements); they are executed when the -r option is encountered
956              during latexmk's parsing of its command line.  See the -e option
957              for a way of giving initialization code  directly  on  latexmk's
958              command  line.   An error results in latexmk stopping.  Multiple
959              instances of the -r and -e options can be  used,  and  they  are
960              executed in the order they appear on the command line.
961
962
963       -recorder
964              Give  the  -recorder  option with latex and pdflatex.  In (most)
965              modern versions of these programs, this results  in  a  file  of
966              extension  .fls  containing  a list of the files that these pro‐
967              grams have read and written.  Latexmk will then use this file to
968              improve  its detection of source files and generated files after
969              a run of latex or pdflatex.  This  is  the  default  setting  of
970              latexmk, unless overridden in an initialization file.
971
972              For further information, see the documentation for the $recorder
973              configuration variable.
974
975
976       -recorder-
977              Do not supply the -recorder option with latex and pdflatex.
978
979
980       -rules Show a list of latemk's rules and dependencies after processing.
981
982
983       -rules-
984              Do not show a list of latexmk's  rules  and  dependencies  after
985              processing.  (This is the default.)
986
987
988       -showextraoptions
989              Show  the  list of extra latex and pdflatex options that latexmk
990              recognizes, but that it simply passes through  to  the  programs
991              latex,  pdflatex,  etc   when  they  are run.  These options are
992              (currently) a combination of those allowed by  the  TeXLive  and
993              MiKTeX  implementations.   (If  a  particular option is given to
994              latexmk but is not handled by the particular  implementation  of
995              latex or pdflatex that is being used, that program will probably
996              give an error message.)  These options are  very  numerous,  but
997              are not listed in this documentation because they have no effect
998              on latexmk's actions.
999
1000              There are a  few  options  (-includedirectory=dir,  -initialize,
1001              -ini)  that  are  not  recognized, either because they don't fit
1002              with latexmk's intended operations, or because they need special
1003              processing  by  latexmk  that  isn't  implemented (at least, not
1004              yet).
1005
1006              There are also options that  are  accepted  by  latex  etc,  but
1007              instead trigger actions by latexmk: -help, -version.
1008
1009              Finally, there are certain options for latex and pdflatex (e.g.,
1010              -recorder) that trigger special actions or behavior  by  latexmk
1011              itself  as well as being passed in some form to the called latex
1012              and pdflatex program, or that affect  other  programs  as  well.
1013              These  options  do  have  entries  in this documentation.  These
1014              options are: -jobname=STRING, -aux-directory=dir, -output-direc‐
1015              tory=DIR, -quiet, and -recorder.
1016
1017
1018       -silent
1019              Run commands silently, i.e., with options that reduce the amount
1020              of diagnostics generated.  For example, with  the  default  set‐
1021              tings,  the  command  "latex -interaction=batchmode" is used for
1022              latex, and similarly for its friends.
1023
1024              See  also  the  -logfilewarninglist   and   -logfilewarninglist-
1025              options.
1026
1027              Also  reduce  the  number of informational messages that latexmk
1028              itself generates.
1029
1030              To change the options used to make the  commands  run  silently,
1031              you need to configure latexmk with changed values of its config‐
1032              uration   variables,   the    relevant    ones    being    $bib‐
1033              tex_silent_switch,  $biber_silent_switch, $dvipdf_silent_switch,
1034              $dvips_silent_switch,       $latex_silent_switch,        $luala‐
1035              tex_silent_switch        $makeindex_silent_switch,       $pdfla‐
1036              tex_silent_switch, and $xelatex_silent_switch
1037
1038
1039       -stdtexcmds
1040              Sets the commands for latex, etc, so that they are the  standard
1041              ones. This is useful to override special configurations.
1042
1043              The  result  is  that  $latex = 'latex %O %S', and similarly for
1044              $pdflatex, $lualatex, and $xelatex.  (The option -no-pdf  needed
1045              for $xelatex is provided automatically, given that %O appears in
1046              the definition.)
1047
1048
1049       -time  Show  CPU  time  used.   See  also  the  configuration  variable
1050              $show_time.
1051
1052
1053       -time- Do  not show CPU time used.  See also the configuration variable
1054              $show_time.
1055
1056
1057       -use-make
1058              When after a run of latex or pdflatex, there are warnings  about
1059              missing files (e.g., as requested by the LaTeX \input, \include,
1060              and \includgraphics commands), latexmk tries to make them  by  a
1061              custom  dependency.  If  no  relevant  custom dependency with an
1062              appropriate source file is found, and if the -use-make option is
1063              set, then as a last resort latexmk will try to use the make pro‐
1064              gram to try to make the missing files.
1065
1066              Note that the filename may be specified  without  an  extension,
1067              e.g.,  by  \includegraphics{drawing}  in  a LaTeX file.  In that
1068              case, latexmk will try making drawing.ext with ext set  in  turn
1069              to  the  possible  extensions that are relevant for latex (or as
1070              appropriate pdflatex).
1071
1072              See also the documentation for  the  $use_make_for_missing_files
1073              configuration variable.
1074
1075
1076       -use-make-
1077              Do  not  use  the  make  program  to  try to make missing files.
1078              (Default.)
1079
1080
1081       -usepretex
1082              Sets the command lines for latex, etc, so that they use the code
1083              that  is defined by the variable $pre_tex_code or that is set by
1084              the option -pretex=CODE to execute the specified TeX code before
1085              the  source  file  is  read.  This option overrides any previous
1086              definition of the command lines.
1087
1088              The result is that $latex = 'latex %O  %P',  and  similarly  for
1089              $pdflatex,  $lualatex, and $xelatex.  (The option -no-pdf needed
1090              for $xelatex is provided automatically, given that %O appears in
1091              the definition.)
1092
1093
1094       -usepretex=CODE
1095              Equivalent to -pretex=CODE -usepretex.  Example
1096
1097                latexmk -usepretex='\AtBeginDocument{Message\par}' foo.tex
1098
1099
1100       -v, -version
1101              Print version number of latexmk.
1102
1103
1104       -verbose
1105              Opposite of -silent.  This is the default setting.
1106
1107
1108       -view=default, -view=dvi, -view=ps, -view=pdf, -view=none
1109              Set the kind of file used when previewing is requested (e.g., by
1110              the -pv or -pvc switches).  The default is to view the "highest"
1111              kind  of  requested  file  (in  the low-to-high order .dvi, .ps,
1112              .pdf).
1113
1114              Note the possibility -view=none where no  viewer  is  opened  at
1115              all.   One  example  of  is  use is in conjunction with the -pvc
1116              option, when you want latexmk to do a compilation  automatically
1117              whenever  source  file(s) change, but do not want a previewer to
1118              be opened.
1119
1120
1121       -Werror
1122              This causes latexmk to return a non-zero status code if  any  of
1123              the  files  processed  gives a warning about problems with cita‐
1124              tions or references (i.e., undefined citations or references  or
1125              about  multiply  defined references).  This is after latexmk has
1126              completed all the runs it needs to try  and  resolve  references
1127              and  citations.  Thus -Werror causes latexmk to treat such warn‐
1128              ings as errors, but only when they occur  on  the  last  run  of
1129              (pdf)latex  and  only after processing is complete.  Also can be
1130              set by the configuration variable $warnings_as_errors.
1131
1132
1133       -xelatex
1134              Use xelatex.  That is, use xelatex to process the source file(s)
1135              to  pdf.   The  generation of dvi and postscript files is turned
1136              off.
1137
1138              This option is equivalent to using the following set of options
1139
1140                   -pdfxe -dvi- -ps-
1141
1142              [Note: Note that the method of implementation  of  this  option,
1143              but  not  its  intended primary effect, differ from some earlier
1144              versions of latexmk. Latexmk first uses xelatex to make an  .xdv
1145              file,  and  does  all  the extra runs needed (including those of
1146              bibtex, etc).  Only after that does it make the  pdf  file  from
1147              the  .xdv  file,  using xdvipdfmx.  This procedure can result in
1148              considerable savings in run time, since the  xdv-to-pdf  conver‐
1149              sion  is quite time-consuming when large graphics files are used
1150              in the document.]
1151
1152
1153
1154       Compatibility between options
1155
1156       The preview-continuous option -pvc can only work with one file.  So  in
1157       this  case  you  will normally only specify one filename on the command
1158       line.
1159
1160       Options -p, -pv and -pvc are mutually  exclusive.   So  each  of  these
1161       options turns the others off.
1162
1163

EXAMPLES

1165       % latexmk thesis    # run latex enough times to resolve
1166                           cross-references
1167
1168       % latexmk -pvc -ps thesis# run latex enough times to resolve
1169                           cross-references, make a postscript
1170                           file, start a previewer.  Then
1171                           watch for changes in the source
1172                           file thesis.tex and any files it
1173                           uses.  After any changes rerun latex
1174                           the appropriate number of times and
1175                           remake the postscript file.  If latex
1176                           encounters an error, latexmk will
1177                           keep running, watching for
1178                           source file changes.
1179
1180       % latexmk -c        # remove .aux, .log, .bbl, .blg, .dvi,
1181                           .pdf, .ps & .bbl files
1182
1183
1184

DEALING WITH ERRORS, PROBLEMS, ETC

1186       Some possibilities:
1187
1188       a.  If you get a strange error, do look carefully at the output that is
1189       on the screen and in log files.  While there is much  that  is  notori‐
1190       ously verbose in the output of latex (and that is added to by latexmk),
1191       the verbosity is there for a reason: to enable  the  user  to  diagnose
1192       problems.   Latexmk  does repeat some messages at the end of a run that
1193       it thinks would otherwise be easy to miss in the middle of  other  out‐
1194       put.
1195
1196       b. Generally, remember that latexmk does its work by running other pro‐
1197       grams.  Your first priority in dealing with errors should be to examine
1198       what went wrong with the individual programs.  Then you need to correct
1199       the causes of errors in the runs of these programs.  (Often these  come
1200       from  errors in the source document, but they could also be about miss‐
1201       ing LaTeX packages, etc.)
1202
1203       c. If latexmk doesn't run the programs the way you would like, then you
1204       need  to look in this documentation at the list of command line options
1205       and then at the sections on configuration/initialization files.  A  lot
1206       of  latexmk's  behavior  is configurable to deal with particular situa‐
1207       tions.  (But there is a lot of reading!)
1208
1209       The remainder of these notes consists of ideas for  dealing  with  more
1210       difficult situations.
1211
1212       d.  Further  tricks  can  involve  replacing the standard commands that
1213       latexmk runs by other commands or scripts.
1214
1215       e. For possible examples of code for use in an RC file, see the  direc‐
1216       tory   example_rcfiles   in  the  distribution  of  latexmk  (e.g.,  at
1217       http://mirror.ctan.org/support/latexmk/example_rcfiles).  Even if these
1218       examples don't do what you want, they may provide suitable inspiration.
1219
1220       f.  There's  a  useful  trick  that  can  be used when you use lualatex
1221       instead of pdflatex (and in some related situations).  The  problem  is
1222       that  latexmk won't notice a dependency on a file, bar.baz say, that is
1223       input by the lua code in your document instead of by  the  LaTeX  part.
1224       (Thus  if you change bar.baz and rerun latexmk, then latexmk will think
1225       no files have changed and  not  rerun  lualatex,  whereas  if  you  had
1226       '\input{bar.baz}'  in  the  LaTeX  part  of the document, latexmk would
1227       notice the change.)  One solution is just to put  the  following  some‐
1228       where in the LaTeX part of the document:
1229
1230                     \typeout{(bar.baz)}
1231
1232       This  puts  a  line in the log file that latexmk will treat as implying
1233       that the file bar.baz was read.  (At present I  don't  know  a  way  of
1234       doing  this  automatically.)   Of  course,  if the file has a different
1235       name, change bar.baz to the name of your file.
1236
1237       g. See also the section "Advanced Configuration: Some extra resources".
1238
1239       h.   Look   on   tex.stackexchange,   i.e.,   at    http://tex.stackex
1240       change.com/questions/tagged/latexmk   Someone  may  have already solved
1241       your problem.
1242
1243       i. Ask a question at tex.stackexchange.com.
1244
1245       j. Or ask me (the author of latexmk).  My e-mail is at the end of  this
1246       documentation.
1247
1248
1249

ALLOWING FOR CHANGE OF OUTPUT FILE TYPE

1251       When one of the latex engines is run, the usual situation is that latex
1252       produces a .dvi file, while pdflatex and lualatex produce a .pdf  file.
1253       For xelatex the default is to produce a .pdf file, but to optimize pro‐
1254       cessing time latexmk runs xelatex its -no-pdf option so  that  it  pro‐
1255       duces  an  .xdv  file.   Further  processing by latexmk takes this as a
1256       starting point.
1257
1258       However, the actual output file may differ from the normal expectation;
1259       and  then  latexmk can adjust its processing to accommodate this situa‐
1260       tion.  The difference in output file type can happen for  two  reasons:
1261       One  is  that  for latex, pdflatex and lualatex the document itself can
1262       override the defaults. The other is that there may be a  configuration,
1263       or misconfiguration, such that the program that latexmk invokes to com‐
1264       pile the document is not the expected one, or is given  options  incom‐
1265       patible  with  what latexmk initially expects.  (E.g., the -output-for‐
1266       mat=...  option could be used with lualatex, or  xelatex  gets  invoked
1267       without the -no-pdf option.)
1268
1269       Under  latex and pdflatex, control of the output format by the document
1270       is done by setting the \pdfoutput macro.  Under lualatex, the  \output‐
1271       mode macro is used instead.
1272
1273       One example of an important use-case for document control of the output
1274       format is a document that uses the psfrag package to  insert  graphical
1275       elements in the output file. The psfrag package achieves its effects by
1276       inserting postscript code in the output of the compilation of the docu‐
1277       ment.   This entails the use of compilation to a .dvi file, followed by
1278       the use of conversion to a postscript  file  (either  directly,  as  by
1279       dvips  or  implicitly,  as an intermediate step by dvipdf).  Then it is
1280       useful to force output to be of the .dvi format by  inserting  \pdfout‐
1281       put=0 in the preamble of the document.
1282
1283       Another  example  is where the document uses graphics file of the .pdf,
1284       .jpg, and png types.  With the default setting for the  graphicx  pack‐
1285       age,  these can be processed in compilation to .pdf but not with compi‐
1286       lation to .dvi.  In this case, it is useful to insert  \pdfoutput=1  in
1287       the  preamble  of the document to force compilation to .pdf output for‐
1288       mat.
1289
1290       In all of these cases, it is needed that latexmk has to adjust its pro‐
1291       cessing  to  deal with a mismatch between the actual output format (out
1292       of .pdf, .dvi, .xdv) and the initially expected  output,  if  possible.
1293       Latexmk does this provided the following conditions are met.
1294
1295       The first is that latexmk's $allow_switch configuration variable is set
1296       to a non-zero value as it is by default.  If this variable is  zero,  a
1297       mismatch of filetypes in the compilation results in an erro.
1298
1299       The  second condition for latexmk to be able to handle a change of out‐
1300       put type is that no explicit requests for .dvi or .ps output files  are
1301       made.    Explicit  requests  are  by  the  -dvi  and  -ps,  -print=dvi,
1302       -print=ps, -view=dvi, and -view=ps options, and by  corresponding  set‐
1303       tings  of  the $dvi_mode, $postscript_mode, $print_type, and $view con‐
1304       figuration variables.  The print-type and view-type  restrictions  only
1305       apply when printing and viewing are explicitly requested, respectively.
1306       For this purpose, the use of the -pdfdvi and -pdfps  options  (and  the
1307       corresponding  setting  of the $pdf_mode variable) does not count as an
1308       explicit request for the .dvi and .ps files; they are  merely  regarded
1309       as  a  request for making a .pdf file together with an initial proposal
1310       for the processing route to make it.
1311
1312       Note that when accommodating a change in output  file  type,  there  is
1313       involved a substantial change in the network of rules that latexmk uses
1314       in its actions.  The second condition applied to accommodate  a  change
1315       is to avoid situations where the change in the rule network is too rad‐
1316       ical to be readily handled automatically.
1317
1318
1319

CONFIGURATION/INITIALIZATION (RC) FILES

1321       In this section is explained which  configuration  files  are  read  by
1322       latexmk.  Subsequent  sections  "How to Set Variables in Initialization
1323       Files", "Format of  Command  Specifications",  "List  of  Configuration
1324       Variables  Usable  in Initialization Files", "Custom Dependencies", and
1325       "Advanced Configuration" give details on what  can  be  configured  and
1326       how.
1327
1328       Latexmk can be customized using initialization files, which are read at
1329       startup in the following order:
1330
1331       1) The system RC file, if it exists.
1332          On a UNIX system, latexmk searches for following places for its sys‐
1333       tem RC file, in the following order, and reads the first it finds:
1334          "/opt/local/share/latexmk/LatexMk",
1335          "/usr/local/share/latexmk/LatexMk",
1336          "/usr/local/lib/latexmk/LatexMk".
1337          On a Fedora system, it only looks for "/etc/latexmk.conf".
1338          On a MS-Windows system it looks for "C:\latexmk\LatexMk".
1339          On  a cygwin system (i.e., a MS-Windows system in which Perl is that
1340       of cygwin), latexmk reads the first it finds of
1341          "/cygdrive/c/latexmk/LatexMk",
1342          "/opt/local/share/latexmk/LatexMk",
1343          "/usr/local/share/latexmk/LatexMk",
1344          "/usr/local/lib/latexmk/LatexMk".
1345
1346       In addition, it then tries the same set of locations, but with the file
1347       name replaced "LatexMk" replaced by "latexmkrc".
1348
1349       If  the  environment variable LATEXMKRCSYS is set, its value is used as
1350       the name of the system RC file, instead of any of the above.
1351
1352       2) The user's RC file, if it exists.  This can be in one of two places.
1353       The  traditional one is ".latexmkrc" in the user's home directory.  The
1354       other possibility is "latexmk/latexmkrc" in the user's  XDG  configura‐
1355       tion  home  directory.  The actual file read is the first of "$XDG_CON‐
1356       FIG_HOME/latexmk/latexmkrc" or "$HOME/.latexmkrc" which  exists.   (See
1357       https://specifications.freedesktop.org/basedir-spec/basedir-spec-lat
1358       est.html for details on the XDG Base Directory Specification.)
1359
1360       Here $HOME is the  user's  home  directory.   [Latexmk  determines  the
1361       user's  home  directory as follows:  It is the value of the environment
1362       variable HOME, if this variable exists, which normally is the  case  on
1363       UNIX-like  systems  (including Linux and OS-X).  Otherwise the environ‐
1364       ment variable USERPROFILE is used, if it exists, which normally is  the
1365       case on MS-Windows systems. Otherwise a blank string is used instead of
1366       $HOME, in which case latexmk does not look for an RC file in it.]
1367
1368       $XDG_CONFIG_HOME is the value  of  the  environment  variable  XDG_CON‐
1369       FIG_HOME  if  it  exists.  If this environment variable does not exist,
1370       but $HOME is non-blank, then $XDG_CONFIG_HOME is  set  to  the  default
1371       value  of  $HOME/.config.   Otherwise  $XDG_CONFIG_HOME  is  blank, and
1372       latexmk does not look for an RC file under it.
1373
1374
1375       3) The RC file in the current working  directory.   This  file  can  be
1376       named  either "latexmkrc" or ".latexmkrc", and the first of these to be
1377       found is used, if any.
1378
1379       4) Any RC file(s) specified on the command line with the -r option.
1380
1381       Each RC file is a sequence of Perl commands.  Naturally, a user can use
1382       this  in  creative  ways.   But  for  most  purposes, one simply uses a
1383       sequence of assignment statements that override some  of  the  built-in
1384       settings  of  Latexmk.   Straightforward  cases  can be handled without
1385       knowledge of the Perl language by using the examples in  this  document
1386       as templates.  Comment lines are introduced by the "#" character.
1387
1388       Note  that  command  line options are obeyed in the order in which they
1389       are written; thus any RC file specified on the command line with the -r
1390       option  can  override  previous options but can be itself overridden by
1391       later options on the command line.  There is also the -e option,  which
1392       allows initialization code to be specified in latexmk's command line.
1393
1394         For  possible  examples  of code for in an RC file, see the directory
1395       example_rcfiles in the distribution of latexmk  (e.g.,  at  http://mir
1396       ror.ctan.org/support/latexmk/example_rcfiles).
1397
1398

HOW TO SET VARIABLES IN INITIALIZATION FILES

1400       The  important  variables  that  can be configured are described in the
1401       section "List  of  configuration  variables  usable  in  initialization
1402       files".   (See  the  earlier section "Configuration/Initialization (rc)
1403       Files" for the files where the configurations are  done.)   Syntax  for
1404       setting these variables is of the following forms:
1405
1406                           $bibtex = 'bibtex %O %B';
1407
1408       for the setting of a string variable,
1409
1410                           $preview_mode = 1;
1411
1412       for the setting of a numeric variable, and
1413
1414                           @default_files = ('paper', 'paper1');
1415
1416       for  the  setting  of an array of strings.  It is possible to append an
1417       item to an array variable as follows:
1418
1419                           push @default_files, 'paper2';
1420
1421       Note that simple "scalar" variables have names  that  begin  with  a  $
1422       character and array variables have names that begin with a @ character.
1423       Each statement ends with a semicolon.
1424
1425       Strings should be enclosed in single quotes.   (You  could  use  double
1426       quotes,  as  in many programming languages.  But then the Perl program‐
1427       ming language brings into play some  special  rules  for  interpolating
1428       variables  into  strings.  People not fluent in Perl will want to avoid
1429       these complications.)
1430
1431       You can do much more complicated things, but for this you will need  to
1432       consult a manual for the Perl programming language.
1433
1434
1435
1436

FORMAT OF COMMAND SPECIFICATIONS

1438       Some  of  the variables set the commands that latexmk uses for carrying
1439       out its work, for example to generate a .dvi file from a .tex  file  or
1440       to  view a postscript file.  This section describes some important fea‐
1441       tures of how the commands are specified.  (Note that some of the possi‐
1442       bilities  listed  here do not apply to the $kpsewhich variable; see its
1443       documentation.)
1444
1445       Placeholders:  Supposed you wanted latexmk to use the command elatex in
1446       place  of  the  regular  latex  command,  and suppose moreover that you
1447       wanted to give it the option "--shell-escape".  You could  do  this  by
1448       the following setting:
1449
1450            $latex = 'elatex --shell-escape %O %S';
1451
1452       The  two  items  starting with the % character are placeholders.  These
1453       are substituted by appropriate values before the command is run.   Thus
1454       %S  will be replaced by the source file that elatex will be applied to,
1455       and %O will be replaced by any options that latexmk has decided to  use
1456       for this command.  (E.g., if you used the -silent option in the invoca‐
1457       tion of latexmk,  it results in the replacement  of  %O  by  "-interac‐
1458       tion=batchmode".)
1459
1460       The available placeholders are:
1461
1462       %A     basename of the main tex file.  Unlike %R, this is unaffected by
1463              the setting of a jobname by  the -jobname option or the $jobname
1464              configuration value.
1465
1466       %B     base  of  filename  for  current command.  E.g., if a postscript
1467              file document.ps is being made from the dvi  file  document.dvi,
1468              then the basename is document.
1469
1470       %D     destination  file  (e.g.,  the  name of the postscript file when
1471              converting a dvi file to postscript).
1472
1473       %O     options
1474
1475       %P     If the variable $pre_tex_code is non-empty, then %P  is  substi‐
1476              tuted   by   the   contents   of   $pre_tex_code   followed   by
1477              \input{SOURCE}, where SOURCE stands for the name of  the  source
1478              file.  Appropriate quoting is done.  This enables TeX code to be
1479              passed to one of the *latex engines to be  executed  before  the
1480              source file is read.
1481
1482              If  the  variable  $pre_tex_code is the empty string, then %P is
1483              equivalent to %S.
1484
1485       %R     root filename.  This is the base name for the main tex file.
1486
1487              By default this is the basename of the main tex  file.   However
1488              the  value  can  be changed by the use of the -jobname option or
1489              the $jobname configuration variable.
1490
1491       %S     source file (e.g., the name of the dvi file  when  converting  a
1492              .dvi file to ps).
1493
1494       %T     The name of the primary tex file.
1495
1496       %U     If  the  variable  $pre_tex_code is non-empty, then its value is
1497              substituted for %U  (appropriately  quoted).   Otherwise  it  is
1498              replaced by a null string.
1499
1500       %Y     Name of directory for auxiliary output files (see the configura‐
1501              tion variable $aux_dir).  A directory separation character ('/')
1502              is appended if $aux_dir is non-empty and does not end in a suit‐
1503              able character, with suitable characters being those appropriate
1504              to  UNIX  and MS-Windows, i.e., ':', '/' and '\'.   Note that if
1505              after initialization,  $out_dir is set, but $aux_dir is not  set
1506              (i.e.,  it  is  blank),  then  latexmk sets $aux_dir to the same
1507              value $out_dir.
1508
1509       %Z     Name of directory for output files (see the configuration  vari‐
1510              able  $out_dir).   A  directory  separation  character  ('/') is
1511              appended if $out_dir is non-empty and does not end in a suitable
1512              character,  with  suitable characters being those appropriate to
1513              UNIX and MS-Windows, i.e., ':', '/' and '\'.
1514
1515       If for some reason you need a literal % character in  your  string  not
1516       subject to the above rules, use "%%".
1517
1518       Appropriate  quoting  will be applied to the filename substitutions, so
1519       you mustn't supply them yourself even if the names of your  files  have
1520       spaces in them.  (But if your TeX filenames have spaces in them, beware
1521       that some older versions of the TeX  program  cannot  correctly  handle
1522       filenames  containing spaces.)  In case latexmk's quoting does not work
1523       correctly on your system, you can turn it off -- see the  documentation
1524       for the variable $quote_filenames.
1525
1526       The  distinction  between %B and %R needs a bit of care, since they are
1527       often the same, but not always.  For example on a simple document,  the
1528       basename of a bibtex run is the same as for the texfile.  But in a doc‐
1529       ument with several bibliographies, the bibliography files will  have  a
1530       variety  of  names.   Since  bibtex is invoked with the basename of the
1531       bibliography file, the setting for the bibtex command should  therefore
1532       be
1533
1534            $bibtex = 'bibtex %O %B';
1535
1536       Generally,  you  should use %B rather than %R.  Similarly for most pur‐
1537       poses, the name %T of the primary texfile is not a useful placeholder.
1538
1539       See the default values in the section "List of configuration  variables
1540       usable in initialization files" for what is normally the most appropri‐
1541       ate usage.
1542
1543       If you omit to supply any placeholders whatever in the specification of
1544       a  command,  latexmk will supply what its author thinks are appropriate
1545       defaults.  This gives compatibility with configuration files for previ‐
1546       ous versions of latexmk, which didn't use placeholders.
1547
1548       "Detaching"  a  command: Normally when latexmk runs a command, it waits
1549       for the command to run to completion.  This is appropriate for commands
1550       like latex, of course.  But for previewers, the command should normally
1551       run detached, so that latexmk  gets  the  previewer  running  and  then
1552       returns to its next task (or exits if there is nothing else to do).  To
1553       achieve this effect of detaching a command, you  need  to  precede  the
1554       command name with "start ", as in
1555
1556            $dvi_previewer = 'start xdvi %O %S';
1557
1558       This  will  be translated to whatever is appropriate for your operating
1559       system.
1560
1561       Notes: (1) In some circumstances, latexmk will  always  run  a  command
1562       detached.  This is the case for a previewer in preview continuous mode,
1563       since otherwise previewing continuously makes no sense.  (2) This  pre‐
1564       cludes  the  possibility  of running a command named start.  (3) If the
1565       word start occurs more than  once  at  the  beginning  of  the  command
1566       string,  that is equivalent to having just one.  (4) Under cygwin, some
1567       complications happen, since cygwin amounts to a complicated merging  of
1568       UNIX  and  MS-Windows.   See  the  source code for how I've handled the
1569       problem.
1570
1571       Command names containing spaces: Under MS-Windows it is common that the
1572       name of a command includes spaces, since software is often installed in
1573       a subdirectory of "C:\Program Files".  Such  command  names  should  be
1574       enclosed in double quotes, as in
1575
1576            $lpr_pdf  =  '"c:/Program  Files/Ghostgum/gsview/gsview32.exe"  /p
1577       %S';
1578            $pdf_previewer   =   'start   "c:/Program   Files/SumatraPDF/Suma‐
1579       traPDF.exe" %O %S';
1580            $pdf_previewer  =  'start "c:/Program Files/SumatraPDF (x86)/Suma‐
1581       traPDF.exe" %O %S';
1582
1583
1584       (Note about the above example: Under  MS-Windows  forward  slashes  are
1585       equivalent to backslashes in a filename under almost all circumstances,
1586       provided that the filename is inside double quotes.  It  is  easier  to
1587       use forward slashes in examples like the one above, since then one does
1588       not have to worry about the rules for dealing with forward  slashes  in
1589       strings in the Perl language.)
1590
1591       Command  names  under  Cygwin: If latexmk is executed by Cygwin's Perl,
1592       be particularly certain that pathnames in commands have forward slashes
1593       not  the  usual  backslashes  for the separator of pathname components.
1594       See the above examples.  Backslashes often get  misinterpreted  by  the
1595       Unix shell used by Cygwin's Perl to execute external commands.  Forward
1596       slashes don't suffer from this problem, and (when quoted, as above) are
1597       equally acceptable to MS-Windows.
1598
1599       Using  MS-Windows  file  associations: A useful trick under modern ver‐
1600       sions of MS-Windows (e.g., WinXP) is to use just the command 'start' by
1601       itself:
1602
1603            $dvi_previewer = 'start %S';
1604
1605       Under MS-Windows, this will cause to be run whatever program the system
1606       has associated with dvi files.  (The  same  applies  for  a  postscript
1607       viewer and a pdf viewer.)  But note that this trick is not always suit‐
1608       able for the pdf previwer, if your system has acroread for the  default
1609       pdf viewer.  As explained elsewhere, acroread under MS-Windows does not
1610       work well with latex and latexmk, because acroread locks the pdf file.
1611
1612       Not using a certain command: If a command is not to be run, the command
1613       name NONE is used, as in
1614
1615            $lpr  = 'NONE lpr';
1616
1617       This  typically  is  used when an appropriate command does not exist on
1618       your system.  The string after the "NONE" is effectively a comment.
1619
1620       Options to commands: Setting the name of a command can be used not only
1621       for changing the name of the command called, but also to add options to
1622       command.  Suppose you want latexmk to use latex  with  source  specials
1623       enabled.   Then  you  might use the following line in an initialization
1624       file:
1625
1626            $latex = 'latex --src-specials %O %S';
1627
1628       Running a subroutine instead of an external command: Use  a  specifica‐
1629       tion starting with "internal", as in
1630
1631            $latex = 'internal mylatex %O %S';
1632            sub mylatex {
1633                my @args = @_;
1634                # Possible preprocessing here
1635                return system 'latex', @args;
1636            }
1637
1638       For  some  of the more exotic possibilities that then become available,
1639       see the section  "ADVANCED  CONFIGURATION:  Some  extra  resources  and
1640       advanced  tricks". Also see some of the examples in the directory exam‐
1641       ple_rcfiles in the latexmk distribution.
1642
1643       Advanced tricks: Normally one specifies a single command for  the  com‐
1644       mands  invoked  by  latexmk.   Naturally,  if there is some complicated
1645       additional processing you need to do in your special situation, you can
1646       write a script (or batch file) to do the processing, and then configure
1647       latexmk to use your script in place of the standard program.
1648
1649       You can also use a Perl subroutine instead of a script  --  see  above.
1650       This is generally the most flexible and portable solution.
1651
1652       It is also possible to configure latexmk to run multiple commands.  For
1653       example, if when running pdflatex to generate a pdf  file  from  a  tex
1654       file  you  need  to  run another program after pdflatex to perform some
1655       extra processing, you could do something like:
1656
1657            $pdflatex = 'pdflatex --shell-escape  %O  %S;  pst2pdf_for_latexmk
1658       %B';
1659
1660       This  definition  assumes  you  are  using  a  UNIX-like  system (which
1661       includes Linux and OS-X), so that the two commands to be run are  sepa‐
1662       rated by the semicolon in the middle of the string.
1663
1664       If you are using MS-Windows, you would replace the above line by
1665
1666          $pdflatex = 'cmd /c pdflatex --shell-escape %O %S'
1667                      . '&& pst2pdf_for_latexmk %B';
1668
1669       Here,  the  UNIX  command  separator ; is replaced by &&.  In addition,
1670       there is a problem that some versions of Perl on MS-Windows do not obey
1671       the  command separator; this problem is overcome by explicitly invoking
1672       the MS-Windows command-line processor cmd.exe.
1673
1674

LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES

1676       In this section  are  specified  the  variables  whose  values  can  be
1677       adjusted  to  configure  latexmk.  (See the earlier section "Configura‐
1678       tion/Initialization (rc) Files" for the files where the  configurations
1679       are done.)
1680
1681       Default values are indicated in brackets.  Note that for variables that
1682       are boolean in character, concerning whether latexmk does or  does  not
1683       behave  in a certain way, a non-zero value, normally 1, indicates true,
1684       i.e., the behavior occurs, while a zero value indicates a false  value,
1685       i.e., the behavior does not occur.
1686
1687
1688       $allow_switch [1]
1689
1690              This  controls  what happens when the output extension of latex,
1691              pdflatex, lualatex or xelatex differs  from  what  is  expected.
1692              (The possible extensions are .dvi, .pdf, .xdv.)  This can happen
1693              with the use of the \pdfoutput  macro  in  a  document  compiled
1694              under  latex  or  pdflatex,  or  with the use of the \outputmode
1695              macro under lualatex.  It can also happen with certain kinds  of
1696              incorrect configuration.
1697
1698              In  such a case, latexmk can appropriately adjust its network of
1699              rules.  The adjustment is made if $allow_switch is on, and if no
1700              request for a dvi or ps file has been made.
1701
1702              See the section ALLOWING FOR CHANGE OF OUTPUT EXTENSION.
1703
1704
1705       $always_view_file_via_temporary [0]
1706              Whether  .ps and .pdf files are initially to be made in a tempo‐
1707              rary directory and then moved  to  the  final  location.   (This
1708              applies to dvips, dvipdf, and ps2pdf operations, and the filter‐
1709              ing operators on .dvi and .ps  files.   It  does  not  apply  to
1710              pdflatex, unfortunately, since pdflatex provides no way of spec‐
1711              ifying a chosen name for the output file.)
1712
1713              This use of a temporary file solves a problem that the making of
1714              these files can occupy a substantial time.  If a viewer (notably
1715              gv) sees that the file has changed, it may  read  the  new  file
1716              before  the  program  writing  the file has not yet finished its
1717              work, which  can cause havoc.
1718
1719              See the $pvc_view_file_via_temporary variable for a setting that
1720              applies  only  if preview-continuous mode (-pvc option) is used.
1721              See $tmpdir for the setting of the directory where the temporary
1722              file is created.
1723
1724
1725       $analyze_input_log_always [1]
1726
1727              After  a run of latex (etc), always analyze .log for input files
1728              in the <...> and (...) constructions.  Otherwise,  only  do  the
1729              analysis when fls file doesn't exist or is out of date.
1730
1731              Under  normal  circumstances,  the data in the fls file is reli‐
1732              able, and the test of the log file gets lots of false positives;
1733              usually  $analyze_input_log_always is best set to zero.  But the
1734              test of the log file is needed at least in the following  situa‐
1735              tion:  When a user needs to persuade latexmk that a certain file
1736              is a source file, and latexmk doesn't otherwise find  it.   Then
1737              the  user  can  write  code  that causes a line with (...) to be
1738              written to log file.  One important case is for lualatex,  which
1739              doesn't  always  generate  lines  in the .fls file for input lua
1740              files.  (The situation with lualatex is  HIGHLY  version  depen‐
1741              dent,  e.g.,  there  was  a  big change between TeXLive 2016 and
1742              TeXLive 2017.)
1743
1744              To keep backward compatibility with older versions  of  latexmk,
1745              the default is to set $analyze_input_log_always to 1.
1746
1747
1748       $auto_rc_use [1]
1749              Whether  to  automatically read the standard initialization (rc)
1750              files, which are the system RC file, the user's RC file, and the
1751              RC file in the current directory.  The command line option -norc
1752              can be used to turn this setting off.  Each RC file  could  also
1753              turn  this  setting off, i.e., it could set $auto_rc_use to zero
1754              to prevent automatic reading of the later RC files.
1755
1756              This variable does not affect the reading of RC files  specified
1757              on the command line by the -r option.
1758
1759       $aux_dir [""]
1760              The directory in which auxiliary files (aux, log, etc) are to be
1761              written by a run of (pdf)latex.  If this variable  is  not  set,
1762              but  $out_dir is set, then $aux_dir is set to $out_dir, which is
1763              the directory to which general output files are to be written.
1764
1765              Important note:  The  effect  of  $aux_dir,  if  different  from
1766              $out_dir,  is  achieved by giving (pdf)latex the -aux-directory.
1767              Currently (Dec. 2011 and later) this only works  on  the  MiKTeX
1768              version of (pdf)latex.
1769
1770              See also the documentation of $out_dir for some complications on
1771              what directory names are suitable.
1772
1773              If you also use the -cd option, and $out_dir (or $aux_dir)  con‐
1774              tains  a relative path, then the path is interpreted relative to
1775              the document directory.
1776
1777       $banner [0]
1778              If nonzero, the banner message is printed across each page  when
1779              converting  the  dvi  file to postscript.  Without modifying the
1780              variable $banner_message, this is equivalent to  specifying  the
1781              -d option.
1782
1783              Note that if $banner is nonzero, the $postscript_mode is assumed
1784              and the postscript file is always generated, even if it is newer
1785              than the dvi file.
1786
1787       $banner_intensity [0.95]
1788              Equivalent to the -bi option, this is a decimal number between 0
1789              and 1 that specifies how dark to print the banner message. 0  is
1790              black, 1 is white.  The default is just right if your toner car‐
1791              tridge isn't running too low.
1792
1793       $banner_message ["DRAFT"]
1794              The banner message to print across each page when converting the
1795              dvi file to postscript.  This is equivalent to the -bm option.
1796
1797       $banner_scale [220.0]
1798              A  decimal  number  that  specifies how large the banner message
1799              will be printed.  Experimentation is necessary to get the  right
1800              scale  for  your message, as a rule of thumb the scale should be
1801              about equal to 1100 divided by the number of characters  in  the
1802              message.   The  Default  is just right for 5 character messages.
1803              This is equivalent to the -bs option.
1804
1805       @BIBINPUTS
1806              This is an array variable, now mostly obsolete,  that  specifies
1807              directories  where  latexmk  should  look  for  .bib  files.  By
1808              default it is set from the BIBINPUTS environment variable of the
1809              operating  system.   If  that environment variable is not set, a
1810              single element list consisting of the current directory is  set.
1811              The format of the directory names depends on your operating sys‐
1812              tem, of course.  Examples for setting this variable are:
1813
1814                      @BIBINPUTS = ( ".", "C:\\bibfiles" );
1815                      @BIBINPUTS = ( ".", "\\server\bibfiles" );
1816                      @BIBINPUTS = ( ".", "C:/bibfiles" );
1817                      @BIBINPUTS = ( ".", "//server/bibfiles" );
1818                      @BIBINPUTS = ( ".", "/usr/local/texmf/bibtex/bib" );
1819
1820              Note that under MS Windows, either a  forward  slash  "/"  or  a
1821              backward  slash "\" can be used to separate pathname components,
1822              so the first two and the second  two  examples  are  equivalent.
1823              Each  backward slash should be doubled to avoid running afoul of
1824              Perl's rules for writing strings.
1825
1826              Important note: This variable is now mostly obsolete in the cur‐
1827              rent version of latexmk, since it has a better method of search‐
1828              ing for files using the kpsewhich  command.   However,  if  your
1829              system  is an unusual one without the kpsewhich command, you may
1830              need to set the variable @BIBINPUTS.
1831
1832       $biber ["biber %O %S"]
1833              The biber processing program.
1834
1835       $biber_silent_switch ["--onlylog"]
1836              Switch(es) for the biber processing program when silent mode  is
1837              on.
1838
1839       $bibtex ["bibtex %O %S"]
1840              The BibTeX processing program.
1841
1842       $bibtex_fudge [1]
1843              When  using bibtex, whether to take special action to allow bib‐
1844              tex to work when $out_dir or  $aux_dir  is  specified.   In  May
1845              2018,  there  was  planned an update to bibtex to correct a bug,
1846              after  that  update,  the  special  action  will  no  longer  be
1847              required.
1848
1849       $bibtex_silent_switch ["-terse"]
1850              Switch(es) for the BibTeX processing program when silent mode is
1851              on.
1852
1853       $bibtex_use [1]
1854              Under what conditions to run bibtex or biber.  When latexmk dis‐
1855              covers  from the log file that one (or more) bibtex/biber-gener‐
1856              ated bibliographies are used, it can run bibtex or  biber  when‐
1857              ever  it  appears  necessary  to regenerate the bbl file(s) from
1858              their source bib  database  file(s).   But  sometimes,  the  bib
1859              file(s) are not available (e.g., for a document obtained from an
1860              external archive), but the bbl files are provided.  In that case
1861              use  of  bibtex or biber will result in incorrect overwriting of
1862              the precious  bbl  files.   The  variable  $bibtex_use  controls
1863              whether  this  happens,  and  also  controls whether or not .bbl
1864              files are deleted in a cleanup operation.
1865
1866              The possible values of $bibtex_use are:
1867                0: never use BibTeX or biber; never delete  .bbl  files  in  a
1868              cleanup.
1869                1:  only  use  bibtex  or  biber if the bib files exist; never
1870              delete .bbl files in a cleanup.
1871                1.5: only use bibtex or biber if the bib files  exist;  condi‐
1872              tionally  delete .bbl files in a cleanup (i.e., delete them only
1873              when the bib files all exist).
1874                2: run bibtex or biber whenever it appears necessary to update
1875              the  bbl  files,  without  testing  for the existence of the bib
1876              files; always delete .bbl files in a cleanup.
1877
1878              Note that the value 1.5 does not work properly if  the  document
1879              uses biber instead of bibtex.  (There's a long story why not.)
1880
1881
1882       $cleanup_includes_cusdep_generated [0]
1883              If  nonzero,  specifies that cleanup also deletes files that are
1884              generated by custom dependencies.  (When doing a clean up, e.g.,
1885              by use of the -C option, custom dependencies are those listed in
1886              the .fdb_latexmk file from a previous run.)
1887
1888       $cleanup_includes_generated [0]
1889              If nonzero, specifies that cleanup also deletes files  that  are
1890              detected in the fls file (or failing that, in log file) as being
1891              generated.  It will also include files  made  from  these  first
1892              generation generated files.
1893
1894              This  operation  is  somewhat dangerous, and can have unintended
1895              consequences, since the files to be deleted are determined  from
1896              a file created by (pdf)latex, which can contain erroneous infor‐
1897              mation. Therefore this variable is turned off  by  default,  and
1898              then files to be deleted are restricted to those explictly spec‐
1899              ified  by  patterns  configured  in  the  variables   clean_ext,
1900              clean_full_ext,  and  @generated_exts,  together with those very
1901              standard cases that  are  hardwired  into  latexmk  (e.g.,  .log
1902              files).
1903
1904       $cleanup_mode [0]
1905              If  nonzero,  specifies  cleanup mode: 1 for full cleanup, 2 for
1906              cleanup except for .dvi, .ps  and  .pdf  files,  3  for  cleanup
1907              except  for dep and aux files.  (There is also extra cleaning as
1908              specified by the $clean_ext, $clean_full_ext and @generated_exts
1909              variables.)
1910
1911              This  variable  is  equivalent to specifying one of the -c or -C
1912              options.  But there should be no need to set this variable  from
1913              an RC file.
1914
1915       $clean_ext [""]
1916              Extra  extensions of files for latexmk to remove when any of the
1917              clean-up options (-c or -C) is  selected.   The  value  of  this
1918              variable is a string containing the extensions separated by spa‐
1919              ces.
1920
1921              It is also possible to specify a more general pattern of file to
1922              be deleted, by using the place holder %R, as in commands, and it
1923              is also possible to use wildcards.  Thus setting
1924
1925                  $clean_ext  =  "out  %R-blx.bib  %R-figures*.log  pythontex-
1926              files-%R/*";
1927
1928              in an initialization file will imply that when a clean-up opera‐
1929              tion is specified,  not  only  is  the  standard  set  of  files
1930              deleted,  but  also  files of the form FOO.out, FOO-blx.bib, %R-
1931              figures*.log, and pythontex-files-FOO/*, where  FOO  stands  for
1932              the basename of the file being processed (as in FOO.tex).
1933
1934              The  files to be deleted are relative to the directory specified
1935              by $aux_dir.  (Note that if $out_dir but not  $aux_dir  is  set,
1936              then  in  its  initialization,  latexmk  sets  $aux_dir equal to
1937              $out_dir.  A normal situation is therefore that $aux_dir  equals
1938              $out_dir,  which  is  the only case supported by TeXLive, unlike
1939              MiKTeX.)
1940
1941              The filenames specfied for a clean-up operation  can  refer  not
1942              only  to regular files but also to directories.  Directories are
1943              only deleted if they are empty.  An example of an application is
1944              to  pythontex,  which  creates  files in a particular directory.
1945              You can arrange to remove both the files and  the  directory  by
1946              setting
1947
1948                  $clean_ext = "pythontex-files-%R pythontex-files-%R";
1949
1950              See also the variable @generated_exts.
1951
1952       $clean_full_ext [""]
1953              Extra  extensions  of  files  for  latexmk to remove when the -C
1954              option is selected, i.e., extensions of files to remove when the
1955              .dvi, etc files are to be cleaned-up.
1956
1957              More general patterns are allowed, as for $clean_ext.
1958
1959              The  files  specified by $clean_full_ext to be deleted are rela‐
1960              tive to the directory specified by $out_dir.
1961
1962
1963       $compiling_cmd [""], $failure_cmd [""], $warning_cmd [""], $success_cmd
1964       [""]
1965
1966              These  variables  specify  commands that are executed at certain
1967              points of  compilations  during  preview-continuous  mode.   One
1968              motivation  for  their  existance is to allow very useful conve‐
1969              nient visual indications of compilation  status  even  when  the
1970              window receiving the screen output of the compilation is hidden.
1971
1972              The  commands  are  executed  at  the following points: $compil‐
1973              ing_cmd at the start of compilation, $success_cmd at the end  of
1974              a  completely successful compilation, $failure_cmd at the end of
1975              an unsuccessful compilation, $warning_cmd at the of an otherwise
1976              successful compilation that gives warnings about undefined cita‐
1977              tions or references or about multiply defined references. If any
1978              of  above  variables  is  undefined or blank (the default situa‐
1979              tion), then the corresponding command is not executed.
1980
1981              However, when $warning_cmd is not set, then in  the  case  of  a
1982              compilation  with  warnings  about  references or citations, but
1983              with no other error, one or  other  of  $success_cmd  or  $fail‐
1984              ure_cmd  is  used  (if  it  is  set) according to the setting of
1985              $warnings_as_errors.
1986
1987              An example of a simple setting of these variables is as follows
1988
1989                  $compiling_cmd = "xdotool search  --name  \"%D\"  set_window
1990              --name \"%D compiling\"";
1991                  $success_cmd    =  "xdotool  search --name \"%D\" set_window
1992              --name \"%D OK\"";
1993                  $warning_cmd   = "xdotool search --name \"%D\" ".
1994                                   "set_window --name \"%D CITE/REF ISSUE\"";
1995                  $failure_cmd   = "xdotool search  --name  \"%D\"  set_window
1996              --name \"%D FAILURE\"";
1997
1998              These  assume  that  the  program xdotool is installed, that the
1999              previewer is using an X-Window system for display, and that  the
2000              title  of the window contains the name of the displayed file, as
2001              it normally does.  When the commands are  executed,  the  place‐
2002              holder  string  %D  is  replaced  by the name of the destination
2003              file, which is the previewed file.  The above commands result in
2004              an appropriate string being appended to the filename in the win‐
2005              dow title: " compiling", " OK", or " FAILURE".
2006
2007              Other placeholders that can be used are %S, %T, and %R, with  %S
2008              and  %T normally being identical. These can be useful for a com‐
2009              mand changing the title of the edit window. The  visual  indica‐
2010              tion  in a window title can useful, since the user does not have
2011              to keep shifting attention to the (possibly hidden)  compilation
2012              window to know the status of the compilation.
2013
2014              More  complicated  situations  can best be handled by defining a
2015              Perl subroutine to invoke the necessary commands, and using  the
2016              "internal"  keyword  in the definitions to get the subroutine to
2017              be invoked.  (See the section "Format of Command Specifications"
2018              for how to do this.)
2019
2020              Naturally,  the  above  settings that invoke the xdotool program
2021              are only applicable when the X-Window system  is  used  for  the
2022              relevant window(s).  For other cases, you will have to find what
2023              software solutions are available.
2024
2025
2026       @cus_dep_list [()]
2027              Custom dependency list -- see section on "Custom Dependencies".
2028
2029       @default_excluded_files [()]
2030              When latexmk is invoked with no files specified on  the  command
2031              line, then, by default, it will process all files in the current
2032              directory with the extension .tex.  (In general, it will process
2033              the files specified in the @default_files variable.)
2034
2035              But  sometimes  you  want  to exclude particular files from this
2036              default list.  In that case you can specify the  excluded  files
2037              in the array @default_excluded_files.  For example if you wanted
2038              to process all .tex files  with  the  exception  of  common.tex,
2039              which  is  a not a standard alone LaTeX file but a file input by
2040              some or all of the others, you could do
2041
2042                   @default_files = ("*.tex");
2043
2044                   @default_excluded_files = ("common.tex");
2045
2046              If you have a variable or large number of files to be processed,
2047              this  method  saves  you  from  having to list them in detail in
2048              @default_files and having to update  the  list  every  time  you
2049              change the set of files to be processed.
2050
2051              Notes:  1.  This variable has no effect except when no files are
2052              specified on the latexmk command line.  2. Wildcards are allowed
2053              in @default_excluded_files.
2054
2055       @default_files [("*.tex")]
2056              Default list of files to be processed.
2057
2058              If  no filenames are specified on the command line, latexmk pro‐
2059              cesses all tex files specified in the  @default_files  variable,
2060              which  by  default is set to all tex files ("*.tex") in the cur‐
2061              rent directory.  This is a convenience: just run latexmk and  it
2062              will  process  an  appropriate  set of files.  But sometimes you
2063              want only some of these files to be processed.  In this case you
2064              can  list the files to be processed by setting @default_files in
2065              an initialization file (e.g., the file "latexmkrc" in  the  cur‐
2066              rent  directory).  Then if no files are specified on the command
2067              line then the files you specify by  setting  @default_files  are
2068              processed.
2069
2070              Three examples:
2071
2072                   @default_files = ("paper_current");
2073
2074                   @default_files = ("paper1", "paper2.tex");
2075
2076                   @default_files = ("*.tex", "*.dtx");
2077
2078              Note  that  more  than  file  may be given, and that the default
2079              extension is ".tex".  Wild cards are allowed.   The  parentheses
2080              are  because  @default_files  is  an  array  variable,  i.e.,  a
2081              sequence of filename specifications is possible.
2082
2083              If you want latexmk to process all .tex files with a few  excep‐
2084              tions, see the @default_excluded_files array variable.
2085
2086       $dependents_phony [0]
2087              If  a  list  of dependencies is output, this variable determines
2088              whether to include a phony target for each source file.  If  you
2089              use  the  dependents  list  in  a Makefile, the dummy rules work
2090              around errors make gives if  you  remove  header  files  without
2091              updating the Makefile to match.
2092
2093       $dependents_list [0]
2094              Whether  to  display  a  list(s) of dependencies at the end of a
2095              run.
2096
2097       $deps_file ["-"]
2098              Name of file to receive list(s) of dependencies at the end of  a
2099              run,  to be used if $dependesnt_list is set.  If the filename is
2100              "-", then the dependency list is set to stdout  (i.e.,  normally
2101              the screen).
2102
2103       $do_cd [0]
2104              Whether  to  change working directory to the directory specified
2105              for the main source file  before  processing  it.   The  default
2106              behavior is not to do this, which is the same as the behavior of
2107              latex and pdflatex programs.  This variable is set  by  the  -cd
2108              and -cd- options on latexmk's command line.
2109
2110       $dvi_filter [empty]
2111              The  dvi  file  filter  to be run on the newly produced dvi file
2112              before other  processing.   Equivalent  to  specifying  the  -dF
2113              option.
2114
2115       $dvi_mode [See below for default]
2116              If  nonzero, generate a dvi version of the document.  Equivalent
2117              to the -dvi option.
2118
2119              The variable  $dvi_mode  defaults  to  0,  but  if  no  explicit
2120              requests  are  made  for  other types of file (postscript, pdf),
2121              then $dvi_mode will be set to 1.  In addition, if a request  for
2122              a  file  for which a .dvi file is a prerequisite, then $dvi_mode
2123              will be set to 1.
2124
2125       $dvi_previewer ["start xdvi %O %S" under UNIX]
2126              The command to invoke a dvi-previewer.   [Under  MS-Windows  the
2127              default  is "start"; then latexmk arranges to use the MS-Windows
2128              start program, which will cause to be run whatever  command  the
2129              system has associated with .dvi files.]
2130
2131              Important  note:  Normally you will want to have a previewer run
2132              detached, so that latexmk doesn't wait for the previewer to ter‐
2133              minate  before continuing its work.  So normally you should pre‐
2134              fix the command by "start ", which  flags  to  latexmk  that  it
2135              should  do  the  detaching  of the previewer itself (by whatever
2136              method is appropriate to the operating system).   But  sometimes
2137              letting latexmk do the detaching is not appropriate (for a vari‐
2138              ety of non-trivial reasons), so you should put the "start "  bit
2139              in yourself, whenever it is needed.
2140
2141       $dvi_previewer_landscape ["start xdvi %O %S"]
2142              The command to invoke a dvi-previewer in landscape mode.  [Under
2143              MS-Windows the default is "start"; then latexmk arranges to  use
2144              the  MS-Windows  start program, which will cause to be run what‐
2145              ever command the system has associated with .dvi files.]
2146
2147       $dvipdf ["dvipdf %O %S %D"]
2148              Command to convert .dvi to .pdf file.  A common  reconfiguration
2149              is  to  use  the dvipdfm command, which needs its arguments in a
2150              different order:
2151
2152                   $dvipdf = "dvipdfm %O -o %D %S";
2153
2154              WARNING: The default dvipdf  script  generates  pdf  files  with
2155              bitmapped fonts, which do not look good when viewed by acroread.
2156              That script should be modified to give  dvips  the  options  "-P
2157              pdf" to ensure that type 1 fonts are used in the pdf file.
2158
2159       $dvipdf_silent_switch ["-q"]
2160              Switch(es) for dvipdf program when silent mode is on.
2161
2162              N.B.  The  standard  dvipdf program runs silently, so adding the
2163              silent switch has no effect, but is actually innocuous.  But  if
2164              an  alternative program is used, e.g., dvipdfmx, then the silent
2165              switch has an  effect.   The  default  setting  is  correct  for
2166              dvipdfm and dvipdfmx.
2167
2168       $dvips ["dvips %O -o %D %S"]
2169              The  program to used as a filter to convert a .dvi file to a .ps
2170              file.  If pdf is going to be generated from pdf, then the  value
2171              of  the  $dvips_pdf_switch  variable  --  see  below  -- will be
2172              included in the options substituted for "%O".
2173
2174       $dvips_landscape ["dvips -tlandscape %O -o %D %S"]
2175              The program to used as a filter to convert a .dvi file to a  .ps
2176              file in landscape mode.
2177
2178       $dvips_pdf_switch ["-P pdf"]
2179              Switch(es)  for  dvips  program when pdf file is to be generated
2180              from .ps file.
2181
2182       $dvips_silent_switch ["-q"]
2183              Switch(es) for dvips program when silent mode is on.
2184
2185       $dvi_update_command [""]
2186              When the dvi previewer is set to be updated by  running  a  com‐
2187              mand,  this is the command that is run.  See the information for
2188              the variable $dvi_update_method for further information, and see
2189              information  on  the  variable $pdf_update_method for an example
2190              for the analogous case of a pdf previewer.
2191
2192       $dvi_update_method [2 under UNIX, 1 under MS-Windows]
2193              How the dvi viewer updates its display when  the  dvi  file  has
2194              changed.     The    values    here    apply   equally   to   the
2195              $pdf_update_method and to the $ps_update_method variables.
2196                  0 => update is automatic,
2197                  1=> manual update by user, which may only mean a mouse click
2198              on the viewer's window or may mean a more serious action.
2199                  2  =>  Send  the  signal,  whose  number  is in the variable
2200              $dvi_update_signal.  The default value under  UNIX  is  suitable
2201              for xdvi.
2202                  3  => Viewer cannot do an update, because it locks the file.
2203              (As with acroread under MS-Windows.)
2204                  4 => run a command to do the update.  The command is  speci‐
2205              fied by the variable $dvi_update_command.
2206
2207              See  information on the variable $pdf_update_method for an exam‐
2208              ple of updating by command.
2209
2210       $dvi_update_signal [Under UNIX: SIGUSR1, which  is  a  system-dependent
2211       value]
2212              The  number of the signal that is sent to the dvi viewer when it
2213              is updated by sending a signal -- see  the  information  on  the
2214              variable  $dvi_update_method.   The  default  value  is  the one
2215              appropriate for xdvi on a UNIX system.
2216
2217       $failure_cmd [undefined]
2218              See the documentation for $compiling_cmd.
2219
2220       $fdb_ext ["fdb_latexmk"]
2221              The extension of the file which latexmk generates to  contain  a
2222              database  of information on source files.  You will not normally
2223              need to change this.
2224
2225       $filetime_causality_threshold  [5];   $filetime_offset_report_threshold
2226       [30]. (Units of seconds.)
2227
2228              These  variables  control  how  latexmk deals with the following
2229              issue, which can affect the use of files that are  on  a  remote
2230              filesystem  (network  share)  instead  of being on a file system
2231              local to the computer running latexmk.  Almost  users  will  not
2232              have to worry about these settings, and can ignore the following
2233              explanation.
2234
2235              In almost all situations, latexmk does not need to use the  time
2236              stamps  of the files it works with.  However, there are a couple
2237              of situations when it needs to know whether a certain  file  was
2238              created in the current run of a program (e.g., (pdf)latex) or is
2239              a leftover file from a previous run. It does this  by  comparing
2240              the  modification  time  of  the  file with the system time just
2241              before the program was started. If the modification time is ear‐
2242              lier  than  when the program was started, the file is a leftover
2243              file, which latexmk treats as if it were not  created.   If  the
2244              filetime  is  at  least  the  program start time, then it can be
2245              assumed that the file was created in the current run.
2246
2247              Unfortunately, this test can fail if the file  is  on  a  remote
2248              system,  since  its  system time is not necessarily synchronized
2249              with that of the local system;  the  timestamps  on  the  remote
2250              files  are set by the remote system, not the local system.  Gen‐
2251              erally, modern operating  systems  regularly  synchronize  their
2252              time  with  a server, so the non-synchronization is mostly small
2253              (a second or so, or a few seconds).  But even a small difference
2254              can mess up latexmk's test.
2255
2256              Latexmk measures the time difference between the time on the two
2257              systems and compensates for this.  But  the  measurement  (in  a
2258              system-independent way) is only accurate to a second or two.  So
2259              latexmk allows for a threshold on the  difference  between  file
2260              and  system  time  before it concludes that a file is a leftover
2261              file from a previous  run.  The  configuration  variable  $file‐
2262              time_causality_theshhold,  which  in units of seconds, specifies
2263              this threshold.  Luckily high precision is not needed.  The pre‐
2264              vious  run  is normally the previous run in a human run-edit-run
2265              cycle, and is at least many seconds  back.   A  few  seconds  is
2266              therefore   appropriate  for  the  threshold,  $filetime_causal‐
2267              ity_theshhold; it should be non-negative always, and  should  be
2268              bigger than 2 if a remote filesystem or network share is used.
2269
2270              If  the  difference in system times on the two systems is large,
2271              it normally indicates that at least one of the systems  is  mis‐
2272              configured.    The   variable  $filetime_offset_report_threshold
2273              specifies the smallest size of the  difference  (or  offset)  in
2274              seconds  between the times of the local and remote system beyond
2275              which the offset is reported.  This is reported at the point  in
2276              the  latexmk's  progress that it measures the offset. The report
2277              is made if silent mode is used and diagnostic mode is not on.
2278
2279
2280       $force_mode [0]
2281              If nonzero, continue processing past minor latex errors  includ‐
2282              ing unrecognized cross references.  Equivalent to specifying the
2283              -f option.
2284
2285       @generated_exts [( aux , bbl , idx , ind , lof , lot  ,  out  ,  toc  ,
2286       $fdb_ext )]
2287              This  contains a list of extensions for files that are generated
2288              during a LaTeX run and that are read in by LaTeX in later  runs,
2289              either directly or indirectly.
2290
2291              This  list  specifies  files known to be generated by latex (and
2292              pdflatex, etc).  It is used in two ways: (a) The specified files
2293              are deleted in a cleanup operation (with the -c, -C, -CA, -g and
2294              -gg options), and (b) It affects the determination of whether  a
2295              rerun of (pdf)LaTeX is needed after a run that gives an error.
2296
2297              (Concerning item (b): Normally, a change of a source file during
2298              a run should provoke a rerun.  This includes a file generated by
2299              LaTeX,  e.g.,  an  aux file, that is read in on subsequent runs.
2300              But after a run that results in an error, a new run  should  not
2301              occur  until  the  user has made a change in the files.  But the
2302              user may have corrected an error in a source  .tex  file  during
2303              the  run.   So  latexmk  needs to distinguish user-generated and
2304              automatically generated files; it determines  the  automatically
2305              generated  files as those with extensions in the list in @gener‐
2306              ated_exts.)
2307
2308              A convenient way to add an extra extension to the list,  without
2309              losing  the already defined ones is to use a push command in the
2310              line in an RC file.  E.g.,
2311
2312                              push @generated_exts, "end";
2313
2314              adds the extension "end" to the  list  of  predefined  generated
2315              extensions.   (This extension is used by the RevTeX package, for
2316              example.)
2317
2318       $go_mode [0]
2319              If nonzero, process files regardless of timestamps, and is  then
2320              equivalent to the -g option.
2321
2322       %hash_calc_ignore_pattern
2323              !!!This variable is for experts only!!!
2324
2325              The  general rule latexmk uses for determining when an extra run
2326              of some program is needed is that one of the  source  files  has
2327              changed.   But  consider for example a latex package that causes
2328              an encapsulated postscript file (an "eps" file) to be made  that
2329              is  to  be read in on the next run.  The file contains a comment
2330              line giving its creation date and time.  On  the  next  run  the
2331              time  changes,  latex  sees  that  the eps file has changed, and
2332              therefore reruns latex.  This causes an infinite loop,  that  is
2333              only  terminated  because  latexmk  has a limit on the number of
2334              runs to guard against pathological situations.
2335
2336              But the changing line has no real effect, since it is a comment.
2337              You can instruct latex to ignore the offending line as follows:
2338
2339                 $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: ';
2340
2341              This creates a rule for files with extension .eps about lines to
2342              ignore.  The left-hand side is a Perl idiom for setting an  item
2343              in  a hash.  Note that the file extension is specified without a
2344              period.  The value, on the right-hand side, is a string contain‐
2345              ing  a  regular expresssion.  (See documentation on Perl for how
2346              they are to be specified in general.)  This  particular  regular
2347              expression  specifies that lines beginning with "%%CreationDate:
2348              " are to be ignored in deciding whether  a  file  of  the  given
2349              extension .eps has changed.
2350
2351              There  is  only one regular expression available for each exten‐
2352              sion.  If you need more one pattern to specify lines to  ignore,
2353              then  you  need  to  combine  the patterns into a single regular
2354              expression.  The simplest method is separate the different  sim‐
2355              ple  patterns  by a vertical bar character (indicating "alterna‐
2356              tion" in the jargon of regular expressions).  For example,
2357
2358                 $hash_calc_ignore_pattern{'eps'}     =      '^%%CreationDate:
2359              |^%%Title: ';
2360
2361              causes   lines  starting  with  either  "^%%CreationDate:  "  or
2362              "^%%Title: " to be ignored.
2363
2364              It may happen that a pattern to be ignored is specified in,  for
2365              example,  in  a system or user initialization file, and you wish
2366              to remove this in a file that is read later.  To  do  this,  you
2367              use Perl's delete function, e.g.,
2368
2369                  delete $hash_calc_ignore_pattern{'eps'};
2370
2371
2372       $jobname [""]
2373
2374              This  specifies the jobname, i.e., the basename that is used for
2375              generated files (.aux, .log, .dvi, .ps,  .pdf,  etc).   If  this
2376              variable  is a null string, then the basename is the basename of
2377              the main tex file.  (At present, the string in  $jobname  should
2378              not contain spaces.)
2379
2380              The  placeholder  '%A' is permitted. This will be substituted by
2381              the basename of the TeX file.  The primary  purpose  is  when  a
2382              variety  of tex files are to be processed, and you want to use a
2383              different jobname for each but one that is  distinct  for  each.
2384              Thus  if you wanted to compare compilations of a set of files on
2385              different operating systems, with distinct filenames for all the
2386              cases, you could set
2387
2388                 $jobname = "%A-$^O";
2389
2390              in  an initialization file.  (Here $^O is a variable provided by
2391              perl that contains perl's name for the operating system.)
2392
2393              Suppose you had .tex files test1.tex and test2.tex.   Then  when
2394              you run
2395
2396                 latexmk -pdf *.tex
2397
2398              both  files  will  be  compiled.  The .aux, .log, and .pdf files
2399              will have basenames test1-MSWin32 ante test2-MSWin32  on  a  MS-
2400              Windows system, test1-darwin and test2-darwin on an OS-X system,
2401              and a variety of similar cases on linux systems.
2402
2403
2404       $kpsewhich ["kpsewhich %S"]
2405              The program called to locate a source file when the  name  alone
2406              is  not  sufficient.  Most filenames used by latexmk have suffi‐
2407              cient path information to be  found  directly.   But  sometimes,
2408              notably when a .bib or a .bst file is found from the log file of
2409              a bibtex or biber run, only the base name of the file is  known,
2410              but not its path. The program specified by $kpsewhich is used to
2411              find it.
2412
2413              (For advanced users: Because  of  the  different  way  in  which
2414              latexmk  uses  the  command specified in $kpsewhich, some of the
2415              possibilities listed in the FORMAT OF COMMAND SPECIFICATIONS  do
2416              not apply.  The internal and start keywords are not available. A
2417              simple command specification with possible options and then "%S"
2418              is  all  that  is  guaranteed to work.  Note that for other com‐
2419              mands, "%S" is substituted by a single source file. In contrast,
2420              for $kpsewhich, "%S" may be substituted by a long list of space-
2421              separated filenames, each of which is  quoted.   The  result  on
2422              STDOUT of running the command is then piped to latexmk.)
2423
2424              See  also  the  @BIBINPUTS variable for another way that latexmk
2425              also uses to try to locate files; it applies only in the case of
2426              .bib files.
2427
2428       $kpsewhich_show [0]
2429              Whether  to show diagnostics about invocations of kpsewhich: the
2430              command line use to invoke it and the results.   These  diagnos‐
2431              tics  are shown if $kpsewhich_show is non-zero or if diagnostics
2432              mode is on.  (But in the second case, lots of other  diagnostics
2433              are  also  shown.)   Without  these diagnostics there is nothing
2434              visible in latexmk's screen output about  invocations  of  kpse‐
2435              which.
2436
2437       $landscape_mode [0]
2438              If nonzero, run in landscape mode, using the landscape mode pre‐
2439              viewers and dvi to postscript converters.  Equivalent to the  -l
2440              option.  Normally not needed with current previewers.
2441
2442       $latex ["latex %O %S"]
2443              Specifies  the  command  line  for the LaTeX processing program.
2444              Note that as with other programs, you can use this variable  not
2445              just  to  change  the name of the program used, but also specify
2446              options to the program.  E.g.,
2447
2448                                  $latex = "latex --src-specials %O %S";
2449
2450              To do a coordinated setting of all of $latex, $pdflatex, $luala‐
2451              tex, and $xelatex, see the section "Advanced Configuration".
2452
2453
2454       %latex_input_extensions
2455              This  variable specifies the extensions tried by latexmk when it
2456              finds that a LaTeX run resulted in an error that a file has  not
2457              been  found,  and  the file is given without an extension.  This
2458              typically happens when LaTeX commands of the  form  \input{file}
2459              or  \includegraphics{figure}, when the relevant source file does
2460              not exist.
2461
2462              In this situation, latexmk searches for custom  dependencies  to
2463              make  the  missing  file(s),  but restricts it to the extensions
2464              specified by the variable %latex_input_extensions.  The  default
2465              extensions are 'tex' and 'eps'.
2466
2467              (For  Perl experts: %latex_input_extensions is a hash whose keys
2468              are the extensions.  The values are  irrelevant.)   Two  subrou‐
2469              tines  are  provided for manipulating this and the related vari‐
2470              able     %pdflatex_input_extensions,      add_input_ext      and
2471              remove_input_ext.   They  are  used as in the following examples
2472              are possible lines in an initialization file:
2473
2474                  remove_input_ext( 'latex', 'tex' );
2475
2476              removes the extension 'tex' from latex_input_extensions
2477
2478                  add_input_ext( 'latex', 'asdf' );
2479
2480              add the extension 'asdf to  latex_input_extensions.   (Naturally
2481              with such an extension, you should have made an appropriate cus‐
2482              tom dependency for latexmk, and should also have done the appro‐
2483              priate  programming  in the LaTeX source file to enable the file
2484              to be read.  The standard extensions are handled  by  LaTeX  and
2485              its graphics/graphicx packages.)
2486
2487       $latex_silent_switch ["-interaction=batchmode"]
2488              Switch(es)  for the LaTeX processing program when silent mode is
2489              on.
2490
2491              If you use MikTeX, you may prefer the results if  you  configure
2492              the  options  to include -c-style-errors, e.g., by the following
2493              line in an initialization file
2494
2495                $latex_silent_switch   =   "-interaction=batchmode   -c-style-
2496              errors";
2497
2498
2499       $lpr ["lpr %O %S" under UNIX/Linux, "NONE lpr" under MS-Windows]
2500              The command to print postscript files.
2501
2502              Under  MS-Windows (unlike UNIX/Linux), there is no standard pro‐
2503              gram for printing files.  But there are ways you can do it.  For
2504              example, if you have gsview installed, you could use it with the
2505              option "/p":
2506
2507                  $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
2508
2509              If gsview is installed in a different directory, you  will  need
2510              to  make the appropriate change.  Note the combination of single
2511              and double quotes around the name.  The  single  quotes  specify
2512              that  this is a string to be assigned to the configuration vari‐
2513              able $lpr.  The double quotes are part of the string  passed  to
2514              the  operating  system to get the command obeyed; this is neces‐
2515              sary because one part of the command name ("Program Files") con‐
2516              tains a space which would otherwise be misinterpreted.
2517
2518       $lpr_dvi ["NONE lpr_dvi"]
2519              The printing program to print dvi files.
2520
2521       $lpr_pdf ["NONE lpr_pdf"]
2522              The printing program to print pdf files.
2523
2524              Under  MS-Windows  you  could  set  this to use gsview, if it is
2525              installed, e.g.,
2526
2527                  $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
2528
2529              If gsview is installed in a different directory, you  will  need
2530              to  make  the appropriate change.  Note the double quotes around
2531              the name: this is necessary because one part of the command name
2532              ("Program Files") contains a space which would otherwise be mis‐
2533              interpreted.
2534
2535       $lualatex ["lualatex %O %S"]
2536              Specifies the command line for the LaTeX processing program that
2537              is  to be used when the lualatex program is called for (e.g., by
2538              the option -lualatex.
2539
2540              To do a coordinated setting of all of $latex, $pdflatex, $luala‐
2541              tex, and $xelatex, see the section "Advanced Configuration".
2542
2543
2544       %lualatex_input_extensions
2545              This  variable specifies the extensions tried by latexmk when it
2546              finds that a lualatex run resulted in an error that a  file  has
2547              not  been  found,  and  the  file is given without an extension.
2548              This  typically  happens  when  LaTeX  commands  of   the   form
2549              \input{file}  or  \includegraphics{figure},  when  the  relevant
2550              source file does not exist.
2551
2552              In this situation, latexmk searches for custom  dependencies  to
2553              make  the  missing  file(s),  but restricts it to the extensions
2554              specified  by  the  variable  %pdflatex_input_extensions.    The
2555              default extensions are 'tex', 'pdf', 'jpg, and 'png'.
2556
2557              See details of the %latex_input_extensions for other information
2558              that equally applies to %lualatex_input_extensions.
2559
2560       $lualatex_silent_switch ["-interaction=batchmode"]
2561              Switch(es) for the lualatex program (specified in  the  variable
2562              $lualatex) when silent mode is on.
2563
2564              See  details  of  the $latex_silent_switch for other information
2565              that equally applies to $lualatex_silent_switch.
2566
2567       $make ["make"]
2568              The make processing program.
2569
2570       $makeindex ["makeindex %O -o %D %S"]
2571              The index processing program.
2572
2573       $makeindex_silent_switch ["-q"]
2574              Switch(es) for the index processing program when silent mode  is
2575              on.
2576
2577       $max_repeat [5]
2578              The  maximum  number  of  times  latexmk will run latex/pdflatex
2579              before deciding that there may be an infinite loop and  that  it
2580              needs to bail out, rather than rerunning latex/pdflatex again to
2581              resolve cross-references, etc.  The  default  value  covers  all
2582              normal cases.
2583
2584              (Note  that  the  "etc"  covers  a lot of cases where one run of
2585              latex/pdflatex generates files to be read in on a later run.)
2586
2587       $MSWin_back_slash [1]
2588              This configuration variable only has an effect when  latexmk  is
2589              running under MS-Windows.  It determines whether, when a command
2590              is executed under MS-Windows, there should  be  substituted  "\"
2591              for  the  separator  character between components of a directory
2592              name.  Internally, latexmk uses "/" for the directory  separator
2593              character, which is the character used by Unix-like systems.
2594
2595              For many programs under MS-Windows, both "\" and "/" are accept‐
2596              able as the directory separator character.   But  some  programs
2597              only  accept  "\"  on  the  command line.  So for safety latexmk
2598              makes a translation, by default.  It is conceivable  that  under
2599              certain situations this is undesirable, so the configuration can
2600              be changed.  (A possible example might be when some of the soft‐
2601              ware  is  implemented  using  Cygwin, which provides a Unix-like
2602              environment inside MS-Windows.)
2603
2604       $new_viewer_always [0]
2605              This variable applies  to  latexmk  only  in  continuous-preview
2606              mode.  If $new_viewer_always is 0, latexmk will check for a pre‐
2607              viously running previewer on the same file, and if one  is  run‐
2608              ning  will  not  start a new one.  If $new_viewer_always is non-
2609              zero, this check will be skipped, and latexmk will behave as  if
2610              no viewer is running.
2611
2612       $out_dir [""]
2613              If  non-blank,  this  variable  specifies the directory in which
2614              output files are to be written by a run of (pdf)latex.  See also
2615              the variable $aux_dir.
2616
2617              The  effect  of  this  variable  (when non-blank) is achieved by
2618              using the -output-directory option of (pdf)latex.   This  exists
2619              in  the  usual  current (Dec. 2011 and later) implementations of
2620              TeX, i.e., MiKTeX and TeXLive. But it  may  not  be  present  in
2621              other versions.
2622
2623              If  you also use the -cd option, and $out_dir (or $aux_dir) con‐
2624              tains a relative path, then the path is interpreted relative  to
2625              the document directory.
2626
2627              Commonly,  the  directory specified for output files is a subdi‐
2628              rectory of the current working directory.  However, if you spec‐
2629              ify  some  other  directory, e.g., "/tmp/foo" or "../output", be
2630              aware that this could cause problems, e.g.,  with  makeindex  or
2631              bibtex.   This  is because modern versions of these programs, by
2632              default, will refuse to work when they find that they are  asked
2633              to  write  to  a  file in a directory that appears not to be the
2634              current working directory or one of its subdirectories.  This is
2635              part  of  security  measures by the whole TeX system that try to
2636              prevent malicious or errant TeX documents from incorrectly mess‐
2637              ing with a user's files.  If for $out_dir or $aux_dir you really
2638              do need to specify an absolute pathname (e.g., "/tmp/foo") or  a
2639              path (e.g., "../output") that includes a higher-level directory,
2640              and you need to use makeindex or bibtex, then you need  to  dis‐
2641              able  the  security measures (and assume any risks).  One way of
2642              doing this is to temporarily set an operating system environment
2643              variable  openout_any  to  "a"  (as  in  "all"), to override the
2644              default "paranoid" setting.
2645
2646       $pdf_mode [0]
2647              If zero, do NOT generate a pdf  version  of  the  document.   If
2648              equal  to 1, generate a pdf version of the document using pdfla‐
2649              tex, using the command specified by the $pdflatex variable.   If
2650              equal  to  2, generate a pdf version of the document from the ps
2651              file, by using the command specified by  the  $ps2pdf  variable.
2652              If  equal  to 3, generate a pdf version of the document from the
2653              dvi file, by using the command specified by  the  $dvipdf  vari‐
2654              able.   If  equal  to  4, generate a pdf version of the document
2655              using lualatex, using the command  specified  by  the  $lualatex
2656              variable.   If  equal  to  5, generate a pdf version (and an xdv
2657              version) of the document using xelatex, using the commands spec‐
2658              ified by the $xelatex and xdvipdfmx variables.
2659
2660              In  $pdf_mode=2,  it is ensured that .dvi and .ps files are also
2661              made.  In $pdf_mode=3, it is ensured that a .dvi  file  is  also
2662              made.  But this may be overridden by the document.
2663
2664       $pdflatex ["pdflatex %O %S"]
2665              Specifies the command line for the LaTeX processing program in a
2666              version that makes a pdf file instead of a dvi file.
2667
2668              An example use of this variable is to add certain options to the
2669              command line for the program, e.g.,
2670
2671                   $pdflatex = "pdflatex --shell-escape %O %S";
2672
2673              (In  some  earlier  versions  of  latexmk,  you needed to use an
2674              assignment to $pdflatex to allow the use of lualatex or  xelatex
2675              instead of pdflatex.  There are now separate configuration vari‐
2676              ables for the use of lualatex or  xelatex.   See  $lualatex  and
2677              $xelatex.)
2678
2679              To do a coordinated setting of all of $latex, $pdflatex, $luala‐
2680              tex, and $xelatex, see the section "Advanced Configuration".
2681
2682       %pdflatex_input_extensions
2683              This variable specifies the extensions tried by latexmk when  it
2684              finds  that  a pdflatex run resulted in an error that a file has
2685              not been found, and the file  is  given  without  an  extension.
2686              This   typically   happens  when  LaTeX  commands  of  the  form
2687              \input{file}  or  \includegraphics{figure},  when  the  relevant
2688              source file does not exist.
2689
2690              In  this  situation, latexmk searches for custom dependencies to
2691              make the missing file(s), but restricts  it  to  the  extensions
2692              specified   by  the  variable  %pdflatex_input_extensions.   The
2693              default extensions are 'tex', 'pdf', 'jpg, and 'png'.
2694
2695              See details of the %latex_input_extensions for other information
2696              that equally applies to %pdflatex_input_extensions.
2697
2698       $pdflatex_silent_switch ["-interaction=batchmode"]
2699              Switch(es)  for  the pdflatex program (specified in the variable
2700              $pdflatex) when silent mode is on.
2701
2702              See details of the $latex_silent_switch  for  other  information
2703              that equally applies to $pdflatex_silent_switch.
2704
2705       $pdf_previewer ["start acroread %O %S"]
2706              The command to invoke a pdf-previewer.
2707
2708              On  MS-Windows,  the  default  is  changed to "cmd /c start """;
2709              under more recent versions of Windows, this will cause to be run
2710              whatever command the system has associated with .pdf files.  But
2711              this may be undesirable if this association is  to  acroread  --
2712              see the notes in the explanation of the -pvc option.]
2713
2714              On  OS-X  the  default is changed to "open %S", which results in
2715              OS-X starting up (and detaching) the viewer associated with  the
2716              file.   By  default, for pdf files this association is to OS-X's
2717              preview, which is quite satisfactory.
2718
2719              WARNING:  Problem under MS-Windows: if acroread is used  as  the
2720              pdf  previewer,  and  it is actually viewing a pdf file, the pdf
2721              file cannot be updated.  Thus makes acroread  a  bad  choice  of
2722              previewer  if you use latexmk's previous-continuous mode (option
2723              -pvc) under MS-windows.  This problem does  not  occur  if,  for
2724              example, SumatraPDF or gsview is used to view pdf files.
2725
2726              Important  note:  Normally you will want to have a previewer run
2727              detached, so that latexmk doesn't wait for the previewer to ter‐
2728              minate  before continuing its work.  So normally you should pre‐
2729              fix the command by "start ", which  flags  to  latexmk  that  it
2730              should  do  the  detaching  of the previewer itself (by whatever
2731              method is appropriate to the operating system).   But  sometimes
2732              letting latexmk do the detaching is not appropriate (for a vari‐
2733              ety of non-trivial reasons), so you should put the "start "  bit
2734              in yourself, whenever it is needed.
2735
2736       $pdf_update_command [""]
2737              When  the  pdf  previewer is set to be updated by running a com‐
2738              mand, this is the command that is run.  See the information  for
2739              the variable $pdf_update_method.
2740
2741       $pdf_update_method [1 under UNIX, 3 under MS-Windows]
2742              How  the  pdf  viewer  updates its display when the pdf file has
2743              changed. See the information on the variable  $dvi_update_method
2744              for the codes.  (Note that information needs be changed slightly
2745              so that for the value 4, to run a command to do the update,  the
2746              command  is  specified  by the variable $pdf_update_command, and
2747              for the value 2, to specify update  by  signal,  the  signal  is
2748              specified by $pdf_update_signal.)
2749
2750              Note that acroread under MS-Windows (but not UNIX) locks the pdf
2751              file, so the default value is then 3.
2752
2753              Arranging to use a command to get a previewer explicitly updated
2754              requires three variables to be set.  For example:
2755
2756                  $pdf_previewer = "start xpdf -remote %R %O %S";
2757                  $pdf_update_method = 4;
2758                  $pdf_update_command = "xpdf -remote %R -reload";
2759
2760              The  first  setting  arranges for the xpdf program to be used in
2761              its "remote server mode", with the server name specified as  the
2762              rootname  of  the  TeX  file.   The  second setting arranges for
2763              updating to be done in response to a command, and the third set‐
2764              ting sets the update command.
2765
2766       $pdf_update_signal  [Under  UNIX:  SIGHUP,  which is a system-dependent
2767       value]
2768              The number of the signal that is sent to the pdf viewer when  it
2769              is  updated  by  sending  a signal -- see the information on the
2770              variable $pdf_update_method.   The  default  value  is  the  one
2771              appropriate for gv on a UNIX system.
2772
2773       $pid_position[1 under UNIX, -1 under MS-Windows]
2774              The  variable  $pid_position  is  used  to specify which word in
2775              lines of the output from $pscmd corresponds to the  process  ID.
2776              The  first word in the line is numbered 0.  The default value of
2777              1 (2nd word in line) is correct for Solaris 2.6, Linux, and OS-X
2778              with their default settings of $pscmd.
2779
2780              Setting  the  variable  to -1 is used to indicate that $pscmd is
2781              not to be used.
2782
2783       $postscript_mode [0]
2784              If nonzero, generate  a  postscript  version  of  the  document.
2785              Equivalent to the -ps option.
2786
2787              If  some  other  request  is made for which a postscript file is
2788              needed, then $postscript_mode will be set to 1.
2789
2790       $pre_tex_code ['']
2791
2792              Sets TeX code to be executed before inputting the  source  file.
2793              This  works  if the relevant one of $latex, etc contains a suit‐
2794              able command line with a %P or %U substitution.  For example you
2795              could do
2796
2797                   $latex = 'latex %O %P';
2798                   $pre_tex_code = '\AtBeginDocument{An initial message\par}';
2799
2800              To  set  all  of  $latex, $pdflatex, $lualatex, and $xelatex you
2801              could use the subroutine alt_tex_cmds:
2802
2803                   &alt_tex_cmds;
2804                   $pre_tex_code = '\AtBeginDocument{An initial message\par}';
2805
2806
2807
2808       $preview_continuous_mode [0]
2809              If nonzero, run a previewer to view the document,  and  continue
2810              running latexmk to keep .dvi up-to-date.  Equivalent to the -pvc
2811              option.  Which previewer is run depends on the  other  settings,
2812              see the command line options -view=, and the variable $view.
2813
2814       $preview_mode [0]
2815              If nonzero, run a previewer to preview the document.  Equivalent
2816              to the -pv option.  Which previewer is run depends on the  other
2817              settings,  see the command line options -view=, and the variable
2818              $view.
2819
2820       $printout_mode [0]
2821              If nonzero, print the document using the  command  specified  in
2822              the $lpr variable.  Equivalent to the -p option.  This is recom‐
2823              mended not to be set from an RC file, otherwise you could  waste
2824              lots of paper.
2825
2826       $print_type = ["auto"]
2827              Type  of  file  to  printout:  possibilities  are "auto", "dvi",
2828              "none", "pdf", or "ps".   See the option -print= for the meaning
2829              of the "auto" value.
2830
2831       $pscmd Command used to get all the processes currently run by the user.
2832              The -pvc option uses  the  command  specified  by  the  variable
2833              $pscmd  to  determine  if there is an already running previewer,
2834              and to find the process ID (needed if latexmk  needs  to  signal
2835              the previewer about file changes).
2836
2837              Each line of the output of this command is assumed to correspond
2838              to one process.  See the  $pid_position  variable  for  how  the
2839              process number is determined.
2840
2841              The  default  for  pscmd  is  "NONE" under MS-Windows and cygwin
2842              (i.e., the command is not used), "ps -ww  -u  $ENV{USER}"  under
2843              OS-X,  and  "ps  -f -u $ENV{USER}" under other operating systems
2844              (including Linux).  In these specifications "$ENV{USER}" is sub‐
2845              stituted by the username.
2846
2847       $ps2pdf ["ps2pdf %O %S %D"]
2848              Command to convert .ps to .pdf file.
2849
2850       $ps_filter [empty]
2851              The postscript file filter to be run on the newly produced post‐
2852              script file before other processing.  Equivalent  to  specifying
2853              the -pF option.
2854
2855       $ps_previewer ["start gv %O %S", but start %O %S under MS-Windows]
2856              The  command  to  invoke a ps-previewer.  (The default under MS-
2857              Windows will cause to be run whatever  command  the  system  has
2858              associated with .ps files.)
2859
2860              Note  that  gv  could be used with the -watch option updates its
2861              display whenever the postscript file changes, whereas  ghostview
2862              does  not.  However, different versions of gv have slightly dif‐
2863              ferent ways of writing this  option.   You  can  configure  this
2864              variable appropriately.
2865
2866              WARNING: Linux systems may have installed one (or more) versions
2867              of gv under different names, e.g.,  ggv,  kghostview,  etc,  but
2868              perhaps not one actually called gv.
2869
2870              Important  note:  Normally you will want to have a previewer run
2871              detached, so that latexmk doesn't wait for the previewer to ter‐
2872              minate  before continuing its work.  So normally you should pre‐
2873              fix the command by "start ", which  flags  to  latexmk  that  it
2874              should  do  the  detaching  of the previewer itself (by whatever
2875              method is appropriate to the operating system).   But  sometimes
2876              letting latexmk do the detaching is not appropriate (for a vari‐
2877              ety of non-trivial reasons), so you should put the "start "  bit
2878              in yourself, whenever it is needed.
2879
2880
2881       $ps_previewer_landscape  ["start gv -swap %O %S", but start %O %S under
2882       MS-Windows]
2883              The command to invoke a ps-previewer in landscape mode.
2884
2885       $ps_update_command [""]
2886              When the postscript previewer is set to be updated by running  a
2887              command,  this  is the command that is run.  See the information
2888              for the variable $ps_update_method.
2889
2890       $ps_update_method [0 under UNIX, 1 under MS-Windows]
2891              How the postscript viewer updates its display when the .ps  file
2892              has    changed.    See   the   information   on   the   variable
2893              $dvi_update_method for the codes.  (Note that information  needs
2894              be changed slightly so that for the value 4, to run a command to
2895              do  the  update,  the  command  is  specified  by  the  variable
2896              $ps_update_command,  and  for  the value 2, to specify update by
2897              signal, the signal is specified by $ps_update_signal.)
2898
2899       $ps_update_signal [Under UNIX:  SIGHUP,  which  is  a  system-dependent
2900       value]
2901              The  number of the signal that is sent to the pdf viewer when it
2902              is updated by sending a signal --  see  $ps_update_method.   The
2903              default value is the one appropriate for gv on a UNIX system.
2904
2905       $pvc_timeout [0]
2906              If  this  variable  is  nonzero, there will be a  timeout in pvc
2907              mode after a period of inactivity.  Inactivity  means  a  period
2908              when  latexmk  has  detected  no  file changes and hence has not
2909              taken any actions like compiling the  document.  The  period  of
2910              inactivity is in the variable $pvc_timeout_mins.
2911
2912
2913       $pvc_timeout_mins [30]
2914              The period of inactivity, in minutes, after which pvc mode times
2915              out.  This is used if $pvc_timeout is nonzero.
2916
2917       $pvc_view_file_via_temporary [1]
2918              The same as $always_view_file_via_temporary, except that it only
2919              applies in preview-continuous mode (-pvc option).
2920
2921       $quote_filenames [1]
2922              This specifies whether substitutions for placeholders in command
2923              specifications  (as  in  $pdflatex)  are  surrounded  by  double
2924              quotes.   If this variable is 1 (or any other value Perl regards
2925              as true), then quoting is done.  Otherwise quoting is omitted.
2926
2927              The quoting method used by latexmk is tested to  work  correctly
2928              under  UNIX systems (including Linux and Mac OS-X) and under MS-
2929              Windows.  It allows the  use  of  filenames  containing  special
2930              characters,  notably  spaces.   (But  note that many versions of
2931              latex and pdflatex cannot correctly deal with  TeX  files  whose
2932              names  contain spaces.  Latexmk's quoting only ensures that such
2933              filenames are correctly treated by the operating system in pass‐
2934              ing arguments to programs.)
2935
2936       $recorder [1]
2937              Whether  to  use the -recorder option to latex and pdflatex. Use
2938              of this option results in a file of extension .fls containing  a
2939              list  of  the  files  that these programs have read and written.
2940              Latexmk will then use this file  to  improve  its  detection  of
2941              source  files and generated files after a run of latex or pdfla‐
2942              tex.
2943
2944              It is generally recommended to use this option (or to  configure
2945              the  $recorder  variable  to  be  on.)   But  it  only  works if
2946              (pdf)latex supports the -recorder option, which is true for most
2947              current implementations
2948
2949              Note  about  the  name of the .fls file: Most implementations of
2950              (pdf)latex produce an .fls file with the same  basename  as  the
2951              main  document's LaTeX, e.g., for Document.tex, the .fls file is
2952              Document.fls.  However,  some  implementations  instead  produce
2953              files  named  for  the program, i.e., latex.fls or pdflatex.fls.
2954              In this second case, latexmk  copies  the  latex.fls  or  pdfla‐
2955              tex.fls  to a file with the basename of the main LaTeX document,
2956              e.g., Document.fls.
2957
2958       $search_path_separator [See below for default]
2959              The character separating paths in the environment variables TEX‐
2960              INPUTS,  BIBINPUTS, and BSTINPUTS.  This variable is mainly used
2961              by latexmk when the -outdir, -output-directory, -auxdir,  and/or
2962              -aux-directory  options are used.  In that case latexmk needs to
2963              communicate  appropriately  modified  search  paths  to  bibtex,
2964              dvipdf, dvips, and (pdf)latex.
2965
2966              [Comment  to technically savvy readers: (pdf)latex doesn't actu‐
2967              ally need the modified search path.  But,  surprisingly,  dvipdf
2968              and  dvips do, because sometimes graphics files get generated in
2969              the output or aux directories.]
2970
2971              The default under MSWin and Cygwin is ';'  and  under  UNIX-like
2972              operating  systems  (including Linux and OS-X) is ':'.  Normally
2973              the defaults give correct behavior.  But there can be  difficul‐
2974              ties  if  your operating system is of one kind, but some of your
2975              software is running under an emulator  for  the  other  kind  of
2976              operating  system;  in that case you'll need to find out what is
2977              needed, and set $search_path_separator  explicitly.   (The  same
2978              goes,  of  course, for unusual operating systems that are not in
2979              the MSWin, Linux, OS-X, Unix collection.)
2980
2981       $show_time [0]
2982              Whether to show CPU time used.
2983
2984       $silence_logfile_warnings [0]
2985              Whether after a run of (pdf)latex to summarize warnings  in  the
2986              log  file  about  undefined  citations  and references.  Setting
2987              $silence_logfile_warnings=0 gives the summary of warnings  (pro‐
2988              vided  silent mode isn't also set), and this is useful to locate
2989              undefined citations and references without searching through the
2990              much  more  verbose log file or the screen output of (pdf)latex.
2991              But the summary can also be excessively annoying.   The  default
2992              is  not  to  give  these  warnings.   The  command  line options
2993              -silence_logfile_warning_list and -silence_logfile_warning_list-
2994              also set this variable.
2995
2996              Note  that multiple occurrences for the same undefined object on
2997              the same page and same line will be compressed to a single warn‐
2998              ing.
2999
3000       $silent [0]
3001              Whether  to  run  silently.   Setting  $silent to 1 has the same
3002              effect as the -quiet of -silent options on the command line.
3003
3004       $sleep_time [2]
3005              The time to sleep (in seconds) between checking for source  file
3006              changes when running with the -pvc option.  This is subject to a
3007              minimum of one second delay, except  that  zero  delay  is  also
3008              allowed.
3009
3010              A  value  of  exactly 0 gives no delay, and typically results in
3011              100% CPU usage, which may not be desirable.
3012
3013       $texfile_search [""]
3014              This is an obsolete variable,  replaced  by  the  @default_files
3015              variable.
3016
3017              For   backward   compatibility,  if  you  choose  to  set  $tex‐
3018              file_search, it is a string of  space-separated  filenames,  and
3019              then latexmk replaces @default_files with the filenames in $tex‐
3020              file_search to which is added "*.tex".
3021
3022       $success_cmd [undefined]
3023              See the documentation for $compiling_cmd.
3024
3025       $tmpdir [See below for default]
3026              Directory to store temporary files  that  latexmk  may  generate
3027              while running.
3028
3029              The  default  under  MSWindows  (including  cygwin),  is  to set
3030              $tmpdir to the value of the first of  whichever  of  the  system
3031              environment  variables  TMPDIR  or TEMP exists, otherwise to the
3032              current directory.  Under other operating systems  (expected  to
3033              be  UNIX/Linux, including OS-X), the default is the value of the
3034              system environment  variable  TMPDIR  if  it  exists,  otherwise
3035              "/tmp".
3036
3037       $use_make_for_missing_files [0]
3038              Whether to use make to try and make files that are missing after
3039              a run of latex or pdflatex, and for which  a  custom  dependency
3040              has  not been found.  This is generally useful only when latexmk
3041              is used as part of a bigger project which is built by using  the
3042              make program.
3043
3044              Note that once a missing file has been made, no further calls to
3045              make will be made on a subsequent run of latexmk to  update  the
3046              file.   Handling  this  problem is the job of a suitably defined
3047              Makefile.  See the section "USING latexmk WITH make" for how  to
3048              do  this.   The intent of calling make from latexmk is merely to
3049              detect dependencies.
3050
3051       $view ["default"]
3052              Which kind of file is to be previewed if a  previewer  is  used.
3053              The  possible  values  are  "default",  "dvi", "ps", "pdf".  The
3054              value of "default" means that the "highest" of the kinds of file
3055              generated is to be used (among .dvi, .ps and .pdf).
3056
3057
3058       $warnings_as_errors [0]
3059              Normally  latexmk copies the behavior of latex in treating unde‐
3060              fined references and citations and multiply  defined  references
3061              as  conditions  that give a warning but not an error.  The vari‐
3062              able $warnings_as_errors controls whether this behavior is modi‐
3063              fied.
3064
3065              When  the  variable  is  non-zero, latexmk at the end of its run
3066              will return a non-zero status code to the  operating  system  if
3067              any  of  the files processed gives a warning about problems with
3068              citations or references (i.e., undefined citations or references
3069              or multiply defined references).  This is after latexmk has com‐
3070              pleted all the runs it needs to try and resolve  references  and
3071              citations.    Thus   $warnings_as_errors  being  nonzero  causes
3072              latexmk to treat such warnings as errors,  but  only  when  they
3073              occur on the last run of (pdf)latex and only after processing is
3074              complete.  A non-zero value $warnings_as_errors can  be  set  by
3075              the command-line option -Werror.
3076
3077              The default behavior is normally satisfactory in the usual edit-
3078              compile-edit cycle.  But, for example, latexmk can also be  used
3079              as  part  of  a build process for some bigger project, e.g., for
3080              creating documentation in the build of a  software  application.
3081              Then  it is often sensible to treat citation and reference warn‐
3082              ings as errors that require the  overall  build  process  to  be
3083              aborted.   Of course, since multiple runs of (pdf)latex are gen‐
3084              erally needed to resolve references and citations, what  matters
3085              is  not  the  warnings on the first run, but the warnings on the
3086              last run; latexmk takes this into account appropriately.
3087
3088              In addition, when preview-continuous mode is  used,  a  non-zero
3089              value  for  $warnings_as_errors  changes the use of the commands
3090              $failure_cmd, $warning_cmd, and $success_cmd  after  a  complia‐
3091              tion.  If there are citation or reference warnings, but no other
3092              errors, the behavior is as follows. If $warning_cmd is  set,  it
3093              is  used.  If it is not set, then then if $warnings_as_errors is
3094              non-zero and $failure_cmd is set, then $failure_cmd.   Otherwise
3095              $success_cmd  is used, if it is set.  (The foregoing explanation
3096              is rather complicated, because latexmk has to deal with the case
3097              that one or more of the commands isn't set.)
3098
3099
3100       $xdvipdfmx ["xdvipdfmx -o %D %O %S"]
3101
3102              The  program  to  make a pdf file from an xdv file (used in con‐
3103              junction with xelatex when $pdf_mode=5).
3104
3105       $xdvipdfmx_silent_switch ["-q"]
3106              Switch(es) for the xdvipdfmx program when silent mode is on.
3107
3108       $xelatex ["xelatex %O %S"]
3109              Specifies the command line for the LaTeX processing  program  of
3110              when  the  xelatex program is called for.  See the documentation
3111              of the -xelatex option for some special properties of  latexmk's
3112              use of xelatex.
3113
3114              Note  about  xelatex:  Now  latexmk uses xelatex to make an .xdv
3115              rather than .pdf file, with the .pdf file  being  created  in  a
3116              separate  step.   This  is  enforced  by  the use of the -no-pdf
3117              option.  If %O is part of the command for invoking xelatex, then
3118              latexmk  will insert the -no-pdf option automatically, otherwise
3119              you must provide the option yourself
3120
3121              To do a coordinated setting of all of $latex, $pdflatex, $luala‐
3122              tex, and $xelatex, see the section "Advanced Configuration".
3123
3124
3125       %xelatex_input_extensions
3126              This  variable specifies the extensions tried by latexmk when it
3127              finds that an xelatex run resulted in an error that a  file  has
3128              not  been  found,  and  the  file is given without an extension.
3129              This  typically  happens  when  LaTeX  commands  of   the   form
3130              \input{file}  or  \includegraphics{figure},  when  the  relevant
3131              source file does not exist.
3132
3133              In this situation, latexmk searches for custom  dependencies  to
3134              make  the  missing  file(s),  but restricts it to the extensions
3135              specified  by  the  variable   %xelatex_input_extensions.    The
3136              default extensions are 'tex', 'pdf', 'jpg, and 'png'.
3137
3138              See details of the %latex_input_extensions for other information
3139              that equally applies to %xelatex_input_extensions.
3140
3141       $xelatex_silent_switch ["-interaction=batchmode"]
3142              Switch(es) for the xelatex program (specified  in  the  variable
3143              $xelatex) when silent mode is on.
3144
3145              See  details  of  the $latex_silent_switch for other information
3146              that equally applies to $xelatex_silent_switch.
3147
3148
3149
3150

CUSTOM DEPENDENCIES

3152       In any RC file a set of custom dependencies can be set up to convert  a
3153       file with one extension to a file with another.  An example use of this
3154       would be to allow latexmk to convert a .fig file to .eps to be included
3155       in the .tex file.
3156
3157
3158   Defining a custom dependency:
3159       The old method of configuring latexmk to use a custom dependency was to
3160       directly manipulate the @cus_dep_list array that  contains  information
3161       defining  the  custom  dependencies.   (See  the section "Old Method of
3162       Defining Custom Dependencies" for details.) This  method  still  works,
3163       but is no longer preferred.
3164
3165       A better method is to use the subroutines that allow convenient manipu‐
3166       lations of the custom dependency list.  These are
3167
3168           add_cus_dep( fromextension, toextension, must, subroutine )
3169           remove_cus_dep( fromextension, toextension )
3170           show_cus_dep()
3171
3172       The arguments are as follows:
3173
3174       from extension:
3175              The extension of the file we are converting from  (e.g.  "fig").
3176              It is specified without a period.
3177
3178       to extension:
3179              The extension of the file we are converting to (e.g. "eps").  It
3180              is specified without a period.
3181
3182       must:  If non-zero, the file from which we are converting  must  exist,
3183              if  it doesn't exist latexmk will give an error message and exit
3184              unless the -f option is specified.  If must is zero and the file
3185              we  are  converting from doesn't exist, then no action is taken.
3186              Generally, the appropriate value of must is zero.
3187
3188       function:
3189              The name of the subroutine that latexmk should call  to  perform
3190              the  file  conversion.   The first argument to the subroutine is
3191              the base name of the file to be converted without any extension.
3192              The  subroutines  are declared in the syntax of Perl.  The func‐
3193              tion should return 0 if it was successful and a  nonzero  number
3194              if it failed.
3195
3196
3197       Naturally  add_cus_dep adds a custom dependency with the specified from
3198       and to extensions.  If a custom dependency has been previously  defined
3199       (e.g.,  in an rcfile that was read earlier), then it is replaced by the
3200       new one.
3201
3202       The subroutine remove_cus_dep removes the specified custom  dependency.
3203       The subroutine show_cus_dep causes a list of the currently defined cus‐
3204       tom dependencies to be sent to the screen output.
3205
3206
3207   How custom dependencies are used:
3208       An instance of a custom dependency rule  is  created  whenever  latexmk
3209       detects  that  a  run  of  latex/pdflatex  needs to read a file, like a
3210       graphics file, whose extension is the to-extension of a  custom  depen‐
3211       dency.  Then latexmk examines whether a file exists with the same name,
3212       but with the corresponding from-extension, as specified in the  custom-
3213       dependency.   If  it  does, then a corresponding instance of the custom
3214       dependency is created, after which the rule  is  invoked  whenever  the
3215       destination  file  (the  one with the to-extension) is out-of-date with
3216       respect to the corresponding source file.
3217
3218       To make the new destination file, the Perl subroutine specified in  the
3219       rule is invoked, with an argument that is the base name of the files in
3220       question.  Simple cases just involve a subroutine invoking an  external
3221       program;  this  can  be  done by following the templates below, even by
3222       those without knowledge of the Perl programming language.   Of  course,
3223       experts could do something much more elaborate.
3224
3225       One  item  in the specification of each custom-dependency rule, labeled
3226       "must" above, specifies how the rule should be applied when the  source
3227       file fails to exist.
3228
3229       When  latex reports that an input file (e.g., a graphics file) does not
3230       exist, latexmk tries to find a source file and a custom dependency that
3231       can be used to make it.  If it succeeds, then it creates an instance of
3232       the custom dependency and invokes it to make the  missing  file,  after
3233       which the next pass of latex etc will be able to read the newly created
3234       file.
3235
3236       Note for advanced usage: The operating  system's  environment  variable
3237       TEXINPUTS  can  be  used  to specify a search path for finding files by
3238       latex etc.  Correspondingly, when a missing file is  reported,  latexmk
3239       looks  in the directories specified in TEXINPUTS as well as in the cur‐
3240       rent directory, to find a source file from which an instance of a  cus‐
3241       tom dependency can be used to make the missing file.
3242
3243
3244   Function to implement custom dependency, traditional method:
3245       The  function  that implements a custom dependency gets the information
3246       on the files to be processed in two ways.  The first is through its one
3247       argument;  the argument contains the base name of the source and desti‐
3248       nation files.  The second way is described later.
3249
3250       A simple and typical example of code in an initialization rcfile  using
3251       the first method is:
3252
3253           add_cus_dep( 'fig', 'eps', 0, 'fig2eps' );
3254           sub fig2eps {
3255               system( "fig2dev -Leps \"$_[0].fig\" \"$_[0].eps\"" );
3256           }
3257
3258       The  first  line  adds  a  custom  dependency that converts a file with
3259       extension "fig", as created by the xfig  program,  to  an  encapsulated
3260       postscript  file,  with  extension "eps".  The remaining lines define a
3261       subroutine that carries out the conversion.  If a rule  for  converting
3262       "fig"  to  "eps"  files already exists (e.g., from a previously read-in
3263       initialization file), the latexmk will delete this rule  before  making
3264       the new one.
3265
3266       Suppose  latexmk  is  using this rule to convert a file "figure.fig" to
3267       "figure.eps".  Then it will invoke the fig2eps  subroutine  defined  in
3268       the  above  code with a single argument "figure", which is the basename
3269       of each of the files (possibly with a path component).   This  argument
3270       is  referred to by Perl as $_[0].  In the example above, the subroutine
3271       uses the Perl command system to invoke the program fig2dev.  The double
3272       quotes around the string are a Perl idiom that signify that each string
3273       of the form of a variable name, $_[0] in this case, is  to  be  substi‐
3274       tuted by its value.
3275
3276       If  the  return  value of the subroutine is non-zero, then latexmk will
3277       assume an error occurred during the execution of  the  subroutine.   In
3278       the  above  example, no explicit return value is given, and instead the
3279       return value is the value returned by the last  (and  only)  statement,
3280       i.e., the invocation of system, which returns the value 0 on success.
3281
3282       If  you use pdflatex instead of latex, then you will probably prefer to
3283       convert your graphics files to pdf format,  in  which  case  you  would
3284       replace the above code in an initialization file by
3285
3286           add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' );
3287           sub fig2pdf {
3288               system( "fig2dev -Lpdf \"$_[0].fig\" \"$_[0].pdf\"" );
3289           }
3290
3291       Note  1: In the command lines given in the system commands in the above
3292       examples, double quotes  have  been  inserted  around  the  file  names
3293       (implemented  by '\"' in the Perl language).  They immunize the running
3294       of the program against special characters  in  filenames.   Very  often
3295       these  quotes  are not necessary, i.e., they can be omitted.  But it is
3296       normally safer to keep them in.  Even though the rules for quoting vary
3297       between  operating  systems,  command  shells  and individual pieces of
3298       software, the quotes in the above examples do not cause problems in the
3299       cases I have tested.
3300
3301       Note  2:  One  case in which the quotes are important is when the files
3302       are in a subdirectory and your operating system is  Microsoft  Windows.
3303       Then  the  separator character for directory components can be either a
3304       forward slash '/' or Microsoft's more usual backward slash  ´\'.   For‐
3305       ward  slashes  are  generated  by  latexmk, to maintain its sanity from
3306       software like MiKTeX that mixes both directory  separators;  but  their
3307       correct use normally requires quoted filenames.  (See a log file from a
3308       run of MiKTeX (at least in v. 2.9) for an example of the  use  of  both
3309       directory separators.)
3310
3311       Note  3:  The subroutines implementing custom dependencies in the exam‐
3312       ples given just have  a  single  line  invoking  an  external  program.
3313       That's  the usual situation.  But since the subroutines are in the Perl
3314       language, you can implement much more  complicated  processing  if  you
3315       need it.
3316
3317
3318   Removing custom dependencies, and when you might need to do this:
3319       If  you  have some general custom dependencies defined in the system or
3320       user initialization file, you may find that for  a  particular  project
3321       they  are  undesirable.  So you might want to delete the unneeded ones.
3322       A situation where this would be desirable is where there  are  multiple
3323       custom  dependencies with the same from-extension or the same to-exten‐
3324       sion. In that case, latexmk might choose a different one from  the  one
3325       you want for a specific project.  As an example, to remove any "fig" to
3326       "eps" rule you would use:
3327
3328           remove_cus_dep( 'fig', 'eps' );
3329
3330       If you have complicated sets of custom dependencies, you  may  want  to
3331       get  a  listing  of the custom dependencies.  This is done by using the
3332       line
3333
3334           show_cus_dep();
3335
3336       in an initialization file.
3337
3338
3339   Function implementing custom dependency, alternative methods:
3340       So far the examples for functions to implement custom dependencies have
3341       used the argument of the function to specify the base name of converted
3342       file.  This method has  been  available  since  very  old  versions  of
3343       latexmk, and many examples can be found, e.g., on the web.
3344
3345       However  in  later  versions  of  latexmk the internal structure of the
3346       implementation of its "rules" for the steps  of  processing,  including
3347       custom  dependencies,  became  much more powerful.  The function imple‐
3348       menting a custom dependency is executed within a special context  where
3349       a number of extra variables and subroutines are defined.  Publicly doc‐
3350       umented ones, intended to be long-term stable, are listed below,  under
3351       the heading "Variables and subroutines for processing a rule".
3352
3353       Examples  of  their  use is given in the following examples, concerning
3354       multiple index files and glossaries.
3355
3356       The only index-file conversion built-in to latexmk is  from  an  ".idx"
3357       file  written on one run of latex/pdflatex to an ".ind" file to be read
3358       in on a subsequent run.  But with the index.sty package,  for  example,
3359       you  can  create  extra  indexes  with  extensions  that you configure.
3360       Latexmk does not know how to deduce the extensions from the information
3361       it  has.  But you can easily write a custom dependency.  For example if
3362       your latex file uses the command  "\newindex{special}{ndx}{nnd}{Special
3363       index}"  you  will need to get latexmk to convert files with the exten‐
3364       sion .ndx to .nnd.  The most elementary method is to  define  a  custom
3365       dependency as follows:
3366
3367           add_cus_dep( 'ndx', 'nnd', 0, 'ndx2nnd' );
3368           sub ndx2nnd {
3369               return system( "makeindex -o \"$_[0].nnd\" \"$_[0].ndx\"" );
3370           }
3371           push @generated_exts, 'ndx', 'nnd';
3372
3373       Notice  the  added line compared with earlier examples.  The extra line
3374       gets the extensions "ndx" and "nnd" added to the list of extensions for
3375       generated files; then the extra index files will be deleted by clean-up
3376       operations
3377
3378       But if you have yet more indexes with yet different  extensions,  e.g.,
3379       "adx"  and  "and", then you will need a separate function for each pair
3380       of extensions.  This is quite annoying.   You  can  use  the  Run_subst
3381       function to simplify the definitions to use a single function:
3382
3383           add_cus_dep( 'ndx', 'nnd', 0, 'dx2nd' );
3384           add_cus_dep( 'adx', 'and', 0, 'dx2nd' );
3385           sub dx2nd {
3386               return Run_subst( "makeindex -o %D %S" );
3387           }
3388           push @generated_exts, 'ndx', 'nnd', 'adx', 'and';
3389
3390       You could also instead use
3391
3392           add_cus_dep( 'ndx', 'nnd', 0, 'dx2nd' );
3393           add_cus_dep( 'adx', 'and', 0, 'dx2nd' );
3394           sub dx2nd {
3395               return Run_subst( $makeindex );
3396           }
3397           push @generated_exts, 'ndx', 'nnd', 'adx', 'and';
3398
3399       This  last example uses the command specification in $makeindex, and so
3400       any customization you have made for the standard index also applies  to
3401       your extra indexes.
3402
3403       Similar techniques can be applied for glossaries.
3404
3405       Those of you with experience with Makefiles, may get concerned that the
3406       .ndx file is written during a run of latex/pdflatex and is always later
3407       than  the  .nnd  last read in.  Thus the .nnd appears to be perpetually
3408       out-of-date.  This situation, of circular dependencies, is  endemic  to
3409       latex, and is one of the issues that latexmk is programmed to overcome.
3410       It examines the contents of the files (by use of a checksum), and  only
3411       does a remake when the file contents have actually changed.
3412
3413       Of  course  if you choose to write random data to the .nnd (or the .aux
3414       file, etc) that changes on each new run, then you will have a  problem.
3415       For  real experts: See the %hash_cal_ignore_pattern if you have to deal
3416       with such problems.
3417
3418
3419   Old Method of Defining Custom Dependencies:
3420       In much older versions of latexmk, the only method of  defining  custom
3421       dependencies  was  to directly manipulate the table of custom dependen‐
3422       cies.  This is contained in the @cus_dep_list array.  It is an array of
3423       strings,  and each string in the array has four items in it, each sepa‐
3424       rated by a space, the  from-extension,  the  to-extension,  the  "must"
3425       item,  and the name of the subroutine for the custom dependency.  These
3426       were all defined above.
3427
3428       An example of the old method of defining custom dependencies is as fol‐
3429       lows.  It  is  the code in an RC file to ensure automatic conversion of
3430       .fig files to .eps files:
3431
3432           push @cus_dep_list, "fig eps 0 fig2eps";
3433           sub fig2eps {
3434               return system( "fig2dev -Lps \"$_[0].fig\" \"$_[0].eps\"" );
3435           }
3436
3437       This method still works, and is almost equivalent  to  the  code  given
3438       earlier  that used the add_cus_dep subroutine.  However, the old method
3439       doesn't delete any previous custom-dependency for the same  conversion.
3440       So the new method is preferable.
3441
3442
3443

ADVANCED CONFIGURATION: Some extra resources and advanced tricks

3445       For  most purposes, simple configuration for latexmk along the lines of
3446       the examples given is sufficient.  But  sometimes  you  need  something
3447       harder.   In this section, I indicate some extra possibilities.  Gener‐
3448       ally to use these, you need to be fluent in the  Perl  language,  since
3449       this is what is used in the rc files.
3450
3451       See  also the section DEALING WITH ERRORS, PROBLEMS, ETC.  See also the
3452       examples in the directory example_rcfiles in the latexmk distributions.
3453       Even if none of the examples apply to your case, they may give you use‐
3454       ful ideas
3455
3456
3457   Utility subroutines
3458       ensure_path( var, values ...)
3459
3460              The first parameter is the name of one of the system's  environ‐
3461              ment  variables  for search paths.  The remaining parameters are
3462              values that should be in the variable.  For each  of  the  value
3463              parameters,  if  it  isn't  already  in the variable, then it is
3464              prepended to the variable; in that case the environment variable
3465              is  created  if it doesn't already exist. For separating values,
3466              the character appropriate the the operating system  is  used  --
3467              see the configuration variable $search_path_separator.
3468
3469              Example:
3470
3471                ensure_path( 'TEXINPUTS', './custom_cls_sty_files//' );
3472
3473              (In this example, the trailing '//' is documented by TeX systems
3474              to mean that latex, pdflatex, etc search for files in the speci‐
3475              fied directory and in all subdirectories.)
3476
3477              Technically   ensure_path   works  by  setting  Perl's  variable
3478              $ENV{var}, where var is the name of the  target  variable.   The
3479              changed  value  is then passed as an environment variable to any
3480              invoked programs.
3481
3482
3483   Variables and subroutines for processing a rule
3484       A step in the processing is called a rule. One possibility to implement
3485       the  processing  of a rule is by a Perl subroutine.  This is always the
3486       case for custom dependencies. Also, for any other rule, you can  use  a
3487       subroutine  by  prefixing the command specification by the word "inter‐
3488       nal" -- see the section FORMAT OF COMMAND SPECIFICATIONS.
3489
3490       When you use a subroutine for processing a rule, all the  possibilities
3491       of  Perl  programming  are  available, of course.  In addition, some of
3492       latexmk's internal variables and subroutines are available.   The  ones
3493       listed  below  are  intended  to  be available to (advanced) users, and
3494       their specifications will generally have stability under upgrades. Gen‐
3495       erally,  the  variables  should be treated as read-only: Changing their
3496       values can have bad consequences, since it is liable  to  mess  up  the
3497       consistency of what latexmk is doing.
3498
3499       $rule  This  variable  has  the  name of the rule, as known to latexmk.
3500              Note that the exact contents of this variable for a  given  rule
3501              may be dependent on the version of latexmk
3502
3503       $$Psource
3504              This gives the name of the primary source file.  Note the double
3505              dollar signs.
3506
3507       $$Pdest
3508              This gives the name of the main output file if  any.   Note  the
3509              double dollar signs.
3510
3511       rdb_ensure_file( $rule, file )
3512              This  a subroutine that ensures that the given file is among the
3513              source files for the specified rule.  It is typically used when,
3514              during  the  processing of a rule, it is known that a particular
3515              extra file is among the dependencies that latexmk  should  know,
3516              but its default methods don't find the dependency. Almost always
3517              the first argument is the name of the rule currently being  pro‐
3518              cessed, so it is then appropriate to specify it by $rule.
3519
3520              For  examples of its use, see some of the files in the directory
3521              example_rcfiles of latexmk's distribution.  Currently the  cases
3522              that   use   this   subroutine   are  bib2gls-latexmkrc,  excel‐
3523              tex_latexmkrc and texinfo-latexmkrc.  These  illustrate  typical
3524              cases  where latexmk's normal processing fails to detect certain
3525              extra source files.
3526
3527       rdb_remove_files( $rule, file, ... )
3528              This subroutine removes one or more files  from  the  dependency
3529              list for the given rule.
3530
3531       rdb_list_source( $rule )
3532              This  subroutine  returns  the  list  of source files (i.e., the
3533              dependency list) for the given rule.
3534
3535       rdb_set_source( $rule, file, ... )
3536
3537       rdb_set_source( $rule, @files )
3538              This subroutine sets the dependency list for the given  rule  to
3539              be the specified files.  Files that are already in the list have
3540              unchanged information.  Files that were  not  in  the  list  are
3541              added to it.  Files in the previous dependency list that are not
3542              in the newly specified list of files are removed from the depen‐
3543              dency list.
3544
3545       Run_subst( command_spec )
3546              This subroutine runs the command specified by command_spec.  The
3547              specification is a string in the format listed  in  the  section
3548              "Format  of Command Specifications".  An important action of the
3549              Run_subst is to make substitutions of placeholders, e.g., %S and
3550              %D  for  source  and  destination  files;  these get substituted
3551              before the command is run.  In addition, the command after  sub‐
3552              stitution  is printed to the screen unless latexmk is running in
3553              silent mode.
3554
3555
3556   Coordinated Setting of Commands for *latex
3557       To set all of $latex, $pdflatex, $lualatex, and $xelatex  to  a  common
3558       pattern,  you  can  use one of the following subroutines, std_tex_cmds,
3559       alt_tex_cmds, and set_tex_cmds.
3560
3561       They work as follows
3562
3563          &std_tex_cmds;
3564
3565       This results in $latex = 'latex %O %S', and  similarly  for  $pdflatex,
3566       $lualatex,  and  $xelatex.   Note the ampersand in the invocation; this
3567       indicates to Perl that a subroutine is being called.
3568
3569          &alt_tex_cmds;
3570
3571       This results in $latex = 'latex %O %P', and  similarly  for  $pdflatex,
3572       $lualatex,  and  $xelatex.   Note the ampersand in the invocation; this
3573       indicates to Perl that a subroutine is being called.
3574
3575         set_tex_cmds( CMD_SPEC );
3576
3577       Here CMD_SPEC is the  command  line  without  the  program  name.  This
3578       results in $latex = 'CMD_SPEC', and similarly for $pdflatex, $lualatex,
3579       and $xelatex. An example would be
3580
3581         set_tex_cmds( '--interaction=batchmode %O %S' );
3582
3583
3584   Advanced configuration: Using latexmk with make
3585       This section is targeted only at advanced users who use the  make  pro‐
3586       gram for complex projects, as for software development, with the depen‐
3587       dencies specified by a Makefile.
3588
3589       Now the basic task of latexmk is to run  the  appropriate  programs  to
3590       make  a  viewable version of a LaTeX document.  However, the usual make
3591       program is not suited to this purpose for at least two reasons.   First
3592       is that the use of LaTeX involves circular dependencies (e.g., via .aux
3593       files), and these cannot be handled by the standard make program.  Sec‐
3594       ond  is  that  in  a  large document the set of source files can change
3595       quite frequently, particularly with included graphics  files;  in  this
3596       situation  keeping  a  Makefile  manually  updated is inappropriate and
3597       error-prone, especially when the dependencies can be  determined  auto‐
3598       matically.  Latexmk solves both of these problems robustly.
3599
3600       Thus  for  many  standard LaTeX documents latexmk can be used by itself
3601       without the make program.  In a complex project it simply needs  to  be
3602       suitably  configured.  A standard configuration would be to define cus‐
3603       tom dependencies to make graphics files from their source files  (e.g.,
3604       as  created  by  the  xfig program).  Custom dependencies are latexmk's
3605       equivalent of pattern rules in Makefiles.
3606
3607       Nevertheless there are projects for which a  Makefile  is  appropriate,
3608       and it is useful to know how to use latexmk from a Makefile.  A typical
3609       example would be to generate  documentation  for  a  software  project.
3610       Potentially  the interaction with the rest of the rules in the Makefile
3611       could be quite complicated, for example if some of the source files for
3612       a LaTeX document are generated by the project's software.
3613
3614       In this section, I give a couple of examples of how latexmk can be use‐
3615       fully invoked from a Makefile.  The examples use specific  features  of
3616       current  versions  of  GNU make, which is the default on both linux and
3617       OS-X systems.  They may need modifications for other versions of make.
3618
3619       The simplest method is simply to delegate all  the  relevant  tasks  to
3620       latexmk, as is suitable for a straightforward LaTeX document.  For this
3621       a suitable Makefile is like
3622
3623           .PHONY : FORCE_MAKE
3624           all : try.pdf
3625           %.pdf : %.tex FORCE_MAKE
3626               latexmk -pdf -dvi- -ps- $<
3627
3628       (Note: the last line must be introduced by a tab for  the  Makefile  to
3629       function  correctly!)  Naturally, if making try.pdf from its associated
3630       LaTeX file try.tex were the only task to be performed, a direct use  of
3631       latexmk  without  a  Makefile would normally be better.  The benefit of
3632       using a Makefile for a LaTeX document would be  in  a  larger  project,
3633       where lines such as the above would be only be a small part of a larger
3634       Makefile.
3635
3636       The above example has a pattern rule for making a .pdf file from a .tex
3637       file,  and it is defined to use latexmk in the obvious way.  There is a
3638       conventional  default  target  named  "all",  with  a  prerequisite  of
3639       try.pdf.   So  when  make is invoked, by default it makes try.pdf.  The
3640       only complication is  that  there  may  be  many  source  files  beyond
3641       try.tex, but these aren't specified in the Makefile, so changes in them
3642       will not by themselves cause latexmk to be invoked.  Instead, the  pat‐
3643       tern  rule is equipped with a "phony" prerequisite FORCE_MAKE; this has
3644       the effect of causing the  rule  to  be  always  out-of-date,  so  that
3645       latexmk  is  always run.  It is latexmk that decides whether any action
3646       is needed, e.g., a rerun of pdflatex.  Effectively the  Makefile  dele‐
3647       gates all decisions to latexmk, while make has no knowledge of the list
3648       of source files except for primary LaTeX file for  the   document.   If
3649       there  are,  for example, graphics files to be made, these must be made
3650       by custom dependencies configured in latexmk.
3651
3652       But something better is needed  in  more  complicated  situations,  for
3653       example,  when  the  making  of graphics files needs to be specified by
3654       rules in the Makefile.  To do this, one can use  a  Makefile  like  the
3655       following:
3656
3657            TARGETS = document1.pdf document2.pdf
3658            DEPS_DIR = .deps
3659            LATEXMK = latexmk -recorder -use-make -deps \
3660                  -e 'warn qq(In Makefile, turn off custom dependencies\n);' \
3661                  -e '@cus_dep_list = ();' \
3662                  -e 'show_cus_dep();'
3663            all : $(TARGETS)
3664            $(foreach file,$(TARGETS),$(eval -include $(DEPS_DIR)/$(file)P))
3665            $(DEPS_DIR) :
3666                   mkdir $@
3667            %.pdf : %.tex
3668                   if [ ! -e $(DEPS_DIR) ]; then mkdir $(DEPS_DIR); fi
3669                   $(LATEXMK) -pdf -dvi- -ps- -deps-out=$(DEPS_DIR)/$@P $<
3670            %.pdf : %.fig
3671                   fig2dev -Lpdf $< $@
3672
3673       (Again,  the  lines  containing  the  commands  for the rules should be
3674       started with tabs.)  This example was inspired by how GNU automake han‐
3675       dles automatic dependency tracking of C source files.
3676
3677       After  each  run of latexmk, dependency information is put in a file in
3678       the .deps subdirectory.  The Makefile causes these dependency files  to
3679       be read by make, which now has the full dependency information for each
3680       target .pdf file.  To make things less trivial it  is  specificed  that
3681       two  files document1.pdf and document2.pdf are the targets.  The depen‐
3682       dency files are .deps/document1.pdfP and .deps/document2.pdfP.
3683
3684       There is now no need for the phony prerequisite for the  rule  to  make
3685       .pdf files from .tex files.  But I have added a rule to make .pdf files
3686       from .fig files produced by the xfig program; these are  commonly  used
3687       for  graphics  insertions  in  LaTeX documents.  Latexmk is arranged to
3688       output a dependency file after each run.  It  is  given  the  -recorder
3689       option, which improves its detection of files generated during a run of
3690       pdflatex; such files should not be in  the  dependency  list.   The  -e
3691       options  are  used to turn off all custom dependencies, and to document
3692       this.  Instead the -use-make is used to delegate the making of  missing
3693       files to make itself.
3694
3695       Suppose  in  the LaTeX file there is a command \includegraphics{graph},
3696       and an xfig file "graph.fig" exists.  On a first run, pdflatex  reports
3697       a  missing  file, named "graph". Latexmk succeeds in making "graph.pdf"
3698       by calling "make graph.pdf", and after completion of its work, it lists
3699       "fig.pdf" among the dependents of the file latexmk is making.  Then let
3700       "fig.fig" be updated, and then let make be  run.   Make  first  remakes
3701       "fig.pdf", and only then reruns latexmk.
3702
3703       Thus  we  now  have  a method by which all the subsidiary processing is
3704       delegated to make.
3705
3706

SEE ALSO

3708       latex(1), bibtex(1), lualatex(1), pdflatex(1), xelatex(1).
3709

BUGS

3711       Sometimes a viewer (gv) tries to read an updated .ps or .pdf file after
3712       its  creation is started but before the file is complete.  Work around:
3713       manually refresh (or reopen) display.  Or use one of the other preview‐
3714       ers and update methods.
3715
3716       (The  following  isn't  really a bug, but concerns features of preview‐
3717       ers.)  Preview continuous mode only works perfectly with  certain  pre‐
3718       viewers:  Xdvi  on  UNIX/Linux  works  for dvi files.  Gv on UNIX/Linux
3719       works for both postscript and pdf.  Ghostview  on  UNIX/Linux  needs  a
3720       manual  update (reopen); it views postscript and pdf.  Gsview under MS-
3721       Windows works for both postscript and pdf, but only reads  the  updated
3722       file  when  its  screen  is refreshed.  Acroread under UNIX/Linux views
3723       pdf, but the file needs to be closed and reopened to  view  an  updated
3724       version.   Under  MS-Windows,  acroread locks its input file and so the
3725       pdf file cannot be updated.  (Remedy: configure latexmk  to  use  suma‐
3726       trapdf instead.)
3727

THANKS TO

3729       Authors  of  previous  versions.   Many  users with their feedback, and
3730       especially David Coppit (username david at node  coppit.org)  who  made
3731       many  useful  suggestions  that  contributed  to version 3, and Herbert
3732       Schulz.  (Please note that the e-mail  addresses  are  not  written  in
3733       their standard form to avoid being harvested too easily.)
3734

AUTHOR

3736       Current  version,  by  John  Collins  (username  jcc8 at node psu.edu).
3737       (Version 4.64a).
3738
3739       Released     version     can      be      obtained      from      CTAN:
3740       <http://www.ctan.org/pkg/latexmk/>,   and  from  the  author's  website
3741       <http://www.personal.psu.edu/jcc8/latexmk/>.
3742       Modifications and enhancements by Evan McLean (Version 2.0)
3743       Original script called "go" by David J. Musliner (RCS Version 3.2)
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756                                  21 May 2019                       LATEXMK(1)
Impressum