diff options
| author | Karl Berry <karl@freefriends.org> | 2016-02-25 22:37:12 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2016-02-25 22:37:12 +0000 |
| commit | 98a791bcc156df953b64c7ec2e85e7d6b9f1e1ec (patch) | |
| tree | c7ceac5a766c4339d39243abaa5f8885416a1eaa /Master/texmf-dist/doc/support | |
| parent | 5a62edeea6cd2a8c22d5e60881029c8c091885a5 (diff) | |
latexmk (25feb16)
git-svn-id: svn://tug.org/texlive/trunk@39860 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support')
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/CHANGES | 15 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/INSTALL | 146 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/README | 4 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/example_rcfiles/Sweave_latexmkrc (renamed from Master/texmf-dist/doc/support/latexmk/example_rcfiles/sweave_latexmkrc) | 0 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/example_rcfiles/TeX4ht-latexmkrc (renamed from Master/texmf-dist/doc/support/latexmk/example_rcfiles/tex4ht-latexmkrc) | 0 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/example_rcfiles/texinfo-latexmkrc | 76 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/latexmk.pdf | bin | 135604 -> 139873 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/latexmk.txt | 1792 |
8 files changed, 1080 insertions, 953 deletions
diff --git a/Master/texmf-dist/doc/support/latexmk/CHANGES b/Master/texmf-dist/doc/support/latexmk/CHANGES index 1274802f235..6c8893896b4 100644 --- a/Master/texmf-dist/doc/support/latexmk/CHANGES +++ b/Master/texmf-dist/doc/support/latexmk/CHANGES @@ -470,3 +470,18 @@ From v. 4.42 to 4.43a characters. On cleanup, synctex.gz files are deleted only by -C, not by -c. +From v. 4.43a to 4.43c + Correct normalization of filenames, so that initial "./" is always + removed. This prevents custom dependencies being run twice on the + same file. + Documentation correction on use of @BIBINPUTS. + Diagnostic correction. + Example rc file for using texinfo (thanks to Vincent Bela\"iche). + Additions to documentation concerning advanced configuration. + +From v. 4.43c to 4.44 + Correct bug in use of %hash_calc_ignore_pattern + (Previously it only had its documented effect when a targetted + file hadn't changed in size.) + Correct error handling when biber finds a malformed .bcf file. + diff --git a/Master/texmf-dist/doc/support/latexmk/INSTALL b/Master/texmf-dist/doc/support/latexmk/INSTALL index 7de9248944f..c32df3f1d5d 100644 --- a/Master/texmf-dist/doc/support/latexmk/INSTALL +++ b/Master/texmf-dist/doc/support/latexmk/INSTALL @@ -1,6 +1,6 @@ INSTALLING latexmk ================== - (Version 4.43a, 5 February 2015) + (Version 4.44, 24 February 2016) John Collins Physics Department @@ -21,11 +21,11 @@ make postscript or pdf files, print the result or preview it, as requested. It can also be set to run continuously with a previewer; the latex program, etc, are then rerun whenever one of the source files is modified. Latexmk automatically determines file dependencies -from the LaTeX .log file. +from the LaTeX .log and .fls files. Latexmk can be installed and used on UNIX (including LINUX and OS-X), -and MS Windows (tested under WinXP). It can presumably be used on -other systems with suitable customization. +and MS Windows (tested under WinXP and some later versions). It can +presumably be used on other systems with suitable customization. On all systems, the prequisites are @@ -38,25 +38,33 @@ a. A working installation of Perl. (See http://www.cpan.org/ if you b. A working installation of TeX and LaTeX. (See http://www.ctan.org/ if you don't have one.) +c. In addition, the installation of TeX and LaTex should, of course, + contain the packages etc that are needed for your specific + documents to be compiled and processed. + !!!! IMPORTANT NOTE: !!!! =========================== If you have installed a modern distribution of TeX and friends, you -may find that latexmk is already installed on your computer. If not, -you may be able to install it by using your distribution's package -manager. - -This is definitely the case for TeXLive 2009 or later, which is also -an essential component of MacTeX. I have also read that another major -distribution MiKTeX also includes latexmk, but I have not checked this -for myself. - -You can test whether latexmk is already installed by trying the -command "latexmk -v" from the command line. If this succeeds, then -latexmk is already installed. Otherwise, if you are using TeXLive or -MacTeX, then you can simply use its package manager to get latexmk -installed, the same as for any other missing package. +may find that latexmk is already installed on your computer. This is +true for full installations of TeXLive 2009 or later on the operating +systems it supports. (Note that MacTeX on OS-X incorporates TeXLive, +so anything said about TeXLive also applies to MacTeX.) If you have +only installed a subset of packages, e.g., because you installed +BasicTeX, then the subset may not include latexmk; in that case you +should be able to use your distribution's package manager to install +latexmk. This is generally the recommended method; only use the +manual installation method below if you have a special need for it. +However, you should still examine the information on configuration +here and in the main documentation to get latexmk working exactly as +you want it. + +You can test whether latexmk is already properly installed by trying +the command "latexmk -v" from the command line. If this succeeds, +then latexmk is already installed. Otherwise, if you are using +TeXLive or MacTeX, then you can simply use its package manager to get +latexmk installed, the same as for any other missing package. If you are on MS-Windows and you are using TeXLive (2009, or later), this distribution also includes a distribution of Perl sufficient to @@ -65,7 +73,10 @@ includes an executable file latexmk.exe that runs latexmk, so you don't have to use the latexmk.bat that is part of the latexmk distribution. - +In the case of MiKTeX, the other standard distribution for MS-Windows, +the main difference from TeXLive as regards latexmk is that you may +need to install a distribution of Perl. A standard default +installation should enable Installing on UNIX/LINUX/OS-X @@ -74,10 +85,12 @@ Installing on UNIX/LINUX/OS-X (Power users can modify these as appropriate.) NOTE: If you are using TeXLive 2009 or later, you can install latexmk -simply by using the TeXLive package manager. In fact, depending on -how much of TeXLive you have already installed, latexmk may already -have been installed. In that case you don't normally need to bother -with the manual installation explained below. +simply by using the TeXLive package manager (that includes users of +MacTeX on OS-X). In fact, depending on how much of TeXLive you have +already installed, latexmk may already have been installed. In that +case you don't normally need to bother with the manual installation +explained below. Still you may need to examine the configuration +instructions. 1. Make sure you have working installations of Perl and TeX/LaTeX. @@ -97,13 +110,16 @@ with the manual installation explained below. Currently the first line is #!/usr/bin/env perl, which uses the program /usr/bin/env to find perl, provided only that the perl executable can be found in the PATH for executables. - This insulates latexmk from the fact that the perl executable + This insulates latexmk from the fact that the Perl executable has a system-dependent location. The program /usr/bin/env is present on almost all modern UNIX/Linux systems.] 5. (Optional) Copy the file latexmk.1 to an appropriate directory for man pages, e.g., /usr/local/man/man1/. + Alternatively, or in addition, put the file latexmk.pdf in a + suitable place for pdf files for documentation. + 6. Check whether the commands used by latexmk for executing latex etc are correct. The ones you particularly have to worry about are those for previewing files ($pdf_previewer, $ps_previewer, and @@ -120,15 +136,33 @@ with the manual installation explained below. system startup file, which is any one of the files /opt/local/share/latexmk/LatexMk, /usr/local/share/latexmk/LatexMk, - /usr/local/lib/latexmk/LatexMk. + /usr/local/lib/latexmk/LatexMk, + /opt/local/share/latexmk/latexmkrc, + /usr/local/share/latexmk/latexmkrc, + /usr/local/lib/latexmk/latexmkrc. (You get to choose which, but only one. If none of these directories is appropriate you'll need to modify latexmk.pl.) + Those directories apply to Unix-like operating systems + (including linux and OS-X). On MS-Windows, the system + start-up file is one of C:\latexmk\LatexMk + C:\latexmk\latexmkrc (If you happen to use Cygwin, latexmk + combines both the MS-Windows and the Unix possibilities.) + b. If you are installing latexmk as an ordinary user, the startup file is the user startup file, which is the file .latexmkrc in your home directory. - The startup files are written in perl, so possible overrides are like + (Under normal circumstances, latexmk's definition of home + directory under Unix-like operating systems is the usual one, + i.e., the value in the environment variable HOME. Under + MS-Windows, a user's home directory is normally the directory + of the user profile, as given in the environment variable + USERPROFILE. In general, latexmk takes a user's home + directory to be the directory specified in the first of the + environment variables HOME and USERPROFILE that is non-empty.) + + The startup files are written in Perl, so possible overrides are like $latex = 'unusual_program_to_run_instead_of_normal_latex %O %S'; @@ -139,7 +173,7 @@ with the manual installation explained below. for the ps command. Here, $pid_position = 1 indicates that the process ID number is in the first column of the output of the - command ps. See the latexmk.pl file for some examples. + command ps. See the latexmk.pl file for some more examples. To determine what commands latexmk currently uses run the following: @@ -188,15 +222,16 @@ have been installed. In that case you don't normally need to bother with the manual installation explained below. 1. Make sure you have working installations of Perl and TeX/LaTeX, - complete with viewers for dvi and/or postscript files. + complete with viewers for dvi and/or postscript files. You will + also need whatever packages your document needs. -2. If necessary, unpack the distribution. [Note: It is a good idea to - unpack the files so that they have the correct line-end characters for - MS-Windows. For example, if you use unzip on latexmk.zip, the command - unzip -a latexmk.zip should do the job. If you don't do this - conversion, it probably won't matter, since much software, including - perl, MikTeX and emacs, handles MS-Windows and UNIX line ends equally - well.] +2. If necessary, unpack the latexmk distribution. [Note: It is a + good idea to unpack the files so that they have the correct + line-end characters for MS-Windows. For example, if you use unzip + on latexmk.zip, the command unzip -a latexmk.zip should do the + job. If you don't do this conversion, it probably won't matter, + since much software, including Perl, MikTeX and emacs, handles + MS-Windows and UNIX line ends equally well.] 3. Copy the files latexmk.pl and latexmk.bat to a suitable directory (your choice). One possibility is a directory C:\local\bin. You will @@ -206,7 +241,11 @@ with the manual installation explained below. 4. If the directory in the previous step is NOT already in the search path for executable files, arrange for this, by adjusting the environment variable PATH suitably. Suppose the latexmk directory - is C:\local\bin. + is C:\local\bin. (Warning: the exact details of the instructions + below are subject to change as new versions of MS-Windows come out, + so you may need to do some exploration to find the equivalents of + the instructions under other versions; the principles remain + unchanged.) a. In Windows XP, there is an item in the Control Panel to adjust the environment: normally Control Panel -> Performance and @@ -222,9 +261,10 @@ with the manual installation explained below. (ii) If you are an administrator, examine the System variables, and adjust the entry to PATH, as above. - b. ONLY in Windows 95, 98 and ME: you will need to add a line to - the end of the C:\AUTOEXEC.BAT file. Suppose the directory for - latexmk is named C:\local\bin, then the line you add is + b. OBSOLETE: ONLY in Windows 95, 98 and ME: you will need to add a + line to the end of the C:\AUTOEXEC.BAT file. Suppose the + directory for latexmk is named C:\local\bin, then the line you + add is PATH %PATH%;C:\local\bin @@ -320,16 +360,22 @@ Tricky points they make your files non-portable. Do something like two-part.tex or two_part.tex instead. -2. The same goes for filenames and directory names with spaces in them. - Much software interprets spaces as separators between different - filenames or between filenames and other text. This can cause - problems in some of the programs called by latexmk. It can also - cause problems when latexmk parses a .log file to determine - dependency information. Latexmk does try to correctly treat - filenames with spaces, as do current implementations of the TeX - program. - -3. If you need to remake documentation files, e.g., latexmk.pdf or +2. The same goes for filenames and directory names with spaces in + them. Much software tends to interpret spaces as separators + between different filenames or between filenames and other text. + This can cause problems in some of the programs called by latexmk. + It can also cause problems when latexmk parses a .log file to + determine dependency information. Latexmk does try to correctly + treat filenames with spaces, as do current implementations of the + TeX program. + +3. Beware also of files and directories whose names contain non-ASCII + characters. There are some tricky problems because of mismatches + between character codings as used by different software and + operating systems. Latexmk tries to do its best, but problems can + arise. + +4. If you need to remake documentation files, e.g., latexmk.pdf or latexmk.txt, from the man page file latexmk.1, the following commands work (on my linux and OS-X systems at least): @@ -358,7 +404,7 @@ Version 2 was modified by Evan McLean. The current version is by John Collins (username jcc8 at node psu.edu) -- other contact details at the top. It is copyright -1998-2011 by John Collins, and the previous authors; see the copyright +1998-2015 by John Collins, and the previous authors; see the copyright notice in the latexmk.pl file, which gives permission to use, copy, modify, and distribute this software and its documentation under the terms of the GNU Public License. diff --git a/Master/texmf-dist/doc/support/latexmk/README b/Master/texmf-dist/doc/support/latexmk/README index 0f4d7620421..b70b5e5384c 100644 --- a/Master/texmf-dist/doc/support/latexmk/README +++ b/Master/texmf-dist/doc/support/latexmk/README @@ -1,4 +1,4 @@ -Latexmk, version 4.43a, 5 February 2015 +Latexmk, version 4.44, 24 February 2016 --------------------------------------- Latexmk completely automates the process of generating a LaTeX @@ -91,7 +91,7 @@ NOTES:- John Collins ---------------------------- "latexmk -h" ---------------------------- -Latexmk 4.43a: Automatic LaTeX document generation routine +Latexmk 4.44: Automatic LaTeX document generation routine Usage: latexmk [latexmk_options] [filename ...] diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/sweave_latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/Sweave_latexmkrc index 19f046be6be..19f046be6be 100644 --- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/sweave_latexmkrc +++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/Sweave_latexmkrc diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/tex4ht-latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/TeX4ht-latexmkrc index de486d8d8be..de486d8d8be 100644 --- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/tex4ht-latexmkrc +++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/TeX4ht-latexmkrc diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/texinfo-latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/texinfo-latexmkrc new file mode 100644 index 00000000000..3a21a3c15db --- /dev/null +++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/texinfo-latexmkrc @@ -0,0 +1,76 @@ +# Modifications 2015 Sep 9-10, John Collins +# Copyright 2014 Vincent Belaïche <vincent.b.1@hotmail.fr> + +# With the settings here, latexmk can be used to process texinfo files +# (typical extension .texi) to pdf files, including the making of +# indices. This version uses a newly documented internal routine +# of latexmk. + +###!!!!!!!!! NOTE THAT THE NAMES OF THE INDEX FILES ARE POSSIBLY +### SUBJECT TO CHANGE IN FUTURE VERSIONS OF texinfo. +### The configuration provided by this file was valid in +### September 2015. (The file texinfo.tex had version +### 2015-07-01.07.) + +$quote_filenames = 1; +$pdflatex = 'internal mylatex %R %Z pdftex %O %S'; +$latex = 'internal mylatex %R %Z etex %O %S'; + +sub mylatex { + my $root = shift; + my $dir_string = shift; + my $ret = system @_; + for my $ext (split " ",$texinfo_indices){ + my $idx = $dir_string.$root.'.'.$ext; + my $ind = $idx.'s'; + if ( (-e $idx) && (-s $idx) ) { + # Only make dependency on the ind-like file + # if the idx-like file both exists and is of + # non-zero length. The test on the length is + # needed because current versions of texindex + # produce no output file if the input file is + # of zero length. + rdb_ensure_file( $rule, $ind ); + } + } + return $ret; +} + +# Please add needed other extensions if there are other user defined indices +$texinfo_indices = 'ky fn cp vr tp pg'; + +$clean_ext .= ' ' . $texinfo_indices; +$clean_full_ext .= ' pdf toc aux'; + +for my $ext (split " ",$texinfo_indices){ + my $index_ext = $ext . 's'; + add_cus_dep( $ext, $index_ext, 1, $ext . '_texindex'); + add_input_ext('pdflatex', $index_ext); + add_input_ext('latex', $index_ext); + $clean_ext .= " $index_ext"; +} + +sub ky_texindex +{ + system( "texindex \"$_[0].ky\"" ); +} +sub fn_texindex +{ + system( "texindex \"$_[0].fn\"" ); +} +sub cp_texindex +{ + system( "texindex \"$_[0].cp\"" ); +} +sub vr_texindex +{ + system( "texindex \"$_[0].vr\"" ); +} +sub tp_texindex +{ + system( "texindex \"$_[0].tp\"" ); +} +sub pg_texindex +{ + system( "texindex \"$_[0].pg\"" ); +} diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.pdf b/Master/texmf-dist/doc/support/latexmk/latexmk.pdf Binary files differindex fecec0f39b1..799292c53d9 100644 --- a/Master/texmf-dist/doc/support/latexmk/latexmk.pdf +++ b/Master/texmf-dist/doc/support/latexmk/latexmk.pdf diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.txt b/Master/texmf-dist/doc/support/latexmk/latexmk.txt index 18c6c768e39..121011730c6 100644 --- a/Master/texmf-dist/doc/support/latexmk/latexmk.txt +++ b/Master/texmf-dist/doc/support/latexmk/latexmk.txt @@ -1,9 +1,4 @@ - - -LATEXMK(1L) LATEXMK(1L) - - NAME latexmk - generate LaTeX document @@ -58,23 +53,23 @@ DESCRIPTION gv) will then automatically update its display. Thus the user can sim- ply edit a file and, when the changes are written to disk, latexmk com- pletely automates the cycle of updating the .dvi (and possibly the .ps + and .pdf) file, and refreshing the previewer's display. It's not quite + WYSIWYG, but usefully close. + For other previewers, the user may have to manually make the previewer + update its display, which can be (some versions of xdvi and gsview) as - 5 February 2015 1 + 1 -LATEXMK(1L) LATEXMK(1L) +LATEXMK(1L) LATEXMK(1L) - and .pdf) file, and refreshing the previewer's display. It's not quite - WYSIWYG, but usefully close. - For other previewers, the user may have to manually make the previewer - update its display, which can be (some versions of xdvi and gsview) as simple as forcing a redraw of its display. Latexmk has the ability to print a banner in gray diagonally across @@ -124,22 +119,22 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE tions. Some of the options for these programs also trigger special action or behavior by latexmk, in which case they have specific expla- nations in this document. Otherwise, they are just passed through to a + called latex or pdflatex program. Run latexmk with the -showextraop- + tions to get a list of the options that latexmk accepts and that are + simply passed through to latex or pdflatex (etc). See also the expla- + nation of the -showextraoptions option for more information. - 5 February 2015 2 + 24 February 2016 2 -LATEXMK(1L) LATEXMK(1L) +LATEXMK(1L) LATEXMK(1L) - called latex or pdflatex program. Run latexmk with the -showextraop- - tions to get a list of the options that latexmk accepts and that are - simply passed through to latex or pdflatex (etc). See also the expla- - nation of the -showextraoptions option for more information. Note 2: In this documentation, the program pdflatex is often referred to. Users of programs like lualatex and xelatex should know that from @@ -191,22 +186,23 @@ LATEXMK(1L) LATEXMK(1L) When the source file uses bbl files for bibliography, run bibtex or biber as needed to regenerate the bbl files. + This property can also be configured by setting the $bibtex_use + variable to 2 in a configuration file + -bibtex- + Never run bibtex or biber. - 5 February 2015 3 + 24 February 2016 3 -LATEXMK(1L) LATEXMK(1L) - This property can also be configured by setting the $bibtex_use - variable to 2 in a configuration file - -bibtex- - Never run bibtex or biber. +LATEXMK(1L) LATEXMK(1L) + A common use for this option is when a document comes from an external source, complete with its bbl file(s), and the user @@ -236,8 +232,8 @@ LATEXMK(1L) LATEXMK(1L) -bm <message> A banner message to print diagonally across each page when con- verting the dvi file to postscript. The message must be a sin- - gle argument on the command line so be careful with quoting spa- - ces and such. + gle argument on the command line so be careful with quoting + spaces and such. Note that if the -bm option is specified, the -ps option is assumed. @@ -255,11 +251,19 @@ LATEXMK(1L) LATEXMK(1L) message. The default is 220.0 which is just right for 5 charac- ter messages. + -commands + List the commands used by latexmk for processing files, and then + exit. + -c Clean up (remove) all regeneratable files generated by latex and + bibtex or biber except dvi, postscript and pdf. These files are + a combination of log files, aux files, latexmk's database file + of source file information, and those with extensions specified + in the @generated_exts configuration variable. In addition, - 5 February 2015 4 + 24 February 2016 4 @@ -268,15 +272,6 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - -commands - List the commands used by latexmk for processing files, and then - exit. - - -c Clean up (remove) all regeneratable files generated by latex and - bibtex or biber except dvi, postscript and pdf. These files are - a combination of log files, aux files, latexmk's database file - of source file information, and those with extensions specified - in the @generated_exts configuration variable. In addition, files specified by the $clean_ext configuration variable are removed. @@ -323,17 +318,6 @@ LATEXMK(1L) LATEXMK(1L) dvi, pdf, etc) will be relative to the current directory rather than the source file. - - - 5 February 2015 5 - - - - - -LATEXMK(1L) LATEXMK(1L) - - This is the default behavior and corresponds to the behavior of the latex and pdflatex programs. However, it is not desirable behavior when latexmk is invoked by a GUI configured to invoke @@ -345,6 +329,18 @@ LATEXMK(1L) LATEXMK(1L) -d Set draft mode. This prints the banner message "DRAFT" across your page when converting the dvi file to postscript. Size and + + + + 24 February 2016 5 + + + + + +LATEXMK(1L) LATEXMK(1L) + + intensity can be modified with the -bs and -bi options. The -bm option will override this option as this is really just a short way of specifying: @@ -388,18 +384,6 @@ LATEXMK(1L) LATEXMK(1L) the output is sent to stdout. Use of this option also turns on the output of the list of - - - - 5 February 2015 6 - - - - - -LATEXMK(1L) LATEXMK(1L) - - dependent files after processing. -dF Dvi file filtering. The argument to this option is a filter @@ -415,8 +399,20 @@ LATEXMK(1L) LATEXMK(1L) -diagnostics Print detailed diagnostics during a run. This may help for - debugging problems or to understand latexmk's behavior in diffi- - cult situations. + debugging problems or to understand latexmk's behavior in + + + + 24 February 2016 6 + + + + + +LATEXMK(1L) LATEXMK(1L) + + + difficult situations. -dvi Generate dvi version of document. @@ -455,17 +451,6 @@ LATEXMK(1L) LATEXMK(1L) string in a way that is independent of both the shell and the operating-system.) - - - 5 February 2015 7 - - - - - -LATEXMK(1L) LATEXMK(1L) - - The above command line will NOT work under MS-Windows with cmd.exe or command.com or 4nt.exe. For MS-Windows with these command shells you could use @@ -486,6 +471,18 @@ LATEXMK(1L) LATEXMK(1L) Note: "Further processing" means the running of other programs or the rerunning of latex (etc) that would be done if no errors + + + + 24 February 2016 7 + + + + + +LATEXMK(1L) LATEXMK(1L) + + had occurred. If instead, or additionally, you want the latex (etc) program not to pause for user input after an error, you should arrange this by an option that is passed to the program, @@ -519,20 +516,7 @@ LATEXMK(1L) LATEXMK(1L) programs is part of latexmk's implementation of -jobname. - -l - - - - 5 February 2015 8 - - - - - -LATEXMK(1L) LATEXMK(1L) - - - Run in landscape mode, using the landscape mode for the preview- + -l Run in landscape mode, using the landscape mode for the preview- ers and the dvi to postscript converters. This option is not normally needed nowadays, since current previewers normally determine this information automatically. @@ -559,6 +543,17 @@ LATEXMK(1L) LATEXMK(1L) using the -e option with a suitable line of Perl code to set the $latex variable. See the explanation of the -e option. + + + 24 February 2016 8 + + + + + +LATEXMK(1L) LATEXMK(1L) + + -lualatex Use lualatex. That is, use lualatex to process the source file(s) to pdf (in place of pdflatex). This option is exactly @@ -586,18 +581,6 @@ LATEXMK(1L) LATEXMK(1L) the same file and not start a new one if a previous previewer is running. However, its test sometimes fails (notably if there is an already-running previewer that is viewing a file of the same - - - - 5 February 2015 9 - - - - - -LATEXMK(1L) LATEXMK(1L) - - name as the current file, but in a different directory). This option turns off the default behavior. @@ -630,6 +613,18 @@ LATEXMK(1L) LATEXMK(1L) achieves its effect by the -output-directory option of (pdf)latex, which currently (Dec. 2011 and later) is implemented on the common versions of (pdf)latex, i.e., MiKTeX and TeXLive. + + + + 24 February 2016 9 + + + + + +LATEXMK(1L) LATEXMK(1L) + + It may not be present in other versions. See also the -auxdir/-aux-directory options, and the $aux_dir, @@ -652,18 +647,6 @@ LATEXMK(1L) LATEXMK(1L) under MS-Windows you must have suitable program(s) available, and you must have configured the print commands used by latexmk. This can be non-trivial. See the documentation on the $lpr, - - - - 5 February 2015 10 - - - - - -LATEXMK(1L) LATEXMK(1L) - - $lpr_dvi, and $lpr_pdf configuration variables to see how to set the commands for printing. @@ -701,34 +684,34 @@ LATEXMK(1L) LATEXMK(1L) The specification of the contents of the string are the same as for the $pdflatex configuration variable. Depending on your operating system and the command-line shell you are using, you - may need to change the single quotes to double quotes (or some- - thing else). - This option can also be used to set a program to be used instead - of the standard pdflatex program, e.g., - latexmk -pdf -pdflatex="lualatex %O %S" foo.tex - to use lualatex or + 24 February 2016 10 - latexmk -pdf -pdflatex="xelatex %O %S" foo.tex - to use xelatex. - To set the command for running latex (rather than the command - for pdflatex) see the -latex option. +LATEXMK(1L) LATEXMK(1L) - 5 February 2015 11 + may need to change the single quotes to double quotes (or some- + thing else). + This option can also be used to set a program to be used instead + of the standard pdflatex program, e.g., + latexmk -pdf -pdflatex="lualatex %O %S" foo.tex + to use lualatex or + latexmk -pdf -pdflatex="xelatex %O %S" foo.tex -LATEXMK(1L) LATEXMK(1L) + to use xelatex. + To set the command for running latex (rather than the command + for pdflatex) see the -latex option. Note that the effect of this option can also be achieved by using the -e option with a suitable line of Perl code to set the @@ -771,31 +754,31 @@ LATEXMK(1L) LATEXMK(1L) select the kind of file to be previewed (dvi, ps or pdf). Oth- erwise the viewer views the "highest" kind of file selected, by the -dvi, -ps, -pdf, -pdfps options, in the order dvi, ps, pdf - (low to high). If no file type has been selected, the dvi pre- - viewer will be used. This option is incompatible with the -p - and -pvc options, so it turns them off. + (low to high). If no file type has been selected, the dvi - -pv- Turn off -pv. - -pvc Run a file previewer and continually update the .dvi, .ps, - and/or .pdf files whenever changes are made to source files (see - the Description above). Which of these files is generated and - which is viewed is governed by the other options, and is the - same as for the -pv option. The preview-continuous option -pvc - can only work with one file. So in this case you will normally - only specify one filename on the command line. It is also + 24 February 2016 11 - 5 February 2015 12 +LATEXMK(1L) LATEXMK(1L) -LATEXMK(1L) LATEXMK(1L) + previewer will be used. This option is incompatible with the -p + and -pvc options, so it turns them off. + -pv- Turn off -pv. + -pvc Run a file previewer and continually update the .dvi, .ps, + and/or .pdf files whenever changes are made to source files (see + the Description above). Which of these files is generated and + which is viewed is governed by the other options, and is the + same as for the -pv option. The preview-continuous option -pvc + can only work with one file. So in this case you will normally + only specify one filename on the command line. It is also incompatible with the -p and -pv options, so it turns these options off. @@ -843,17 +826,10 @@ LATEXMK(1L) LATEXMK(1L) line are acted on in the order they are given. Therefore if an initialization file is specified by the -r option, it is read during this second step. Thus an initialization file specified - with the -r option can override both the standard initialization - files and previously specified options. But all of these can be - overridden by later options. - - The contents of the RC file just comprise a piece of code in the - Perl programming language (typically a sequence of assignment - statements); they are executed when the -r option is encountered - 5 February 2015 13 + 24 February 2016 12 @@ -862,6 +838,13 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + with the -r option can override both the standard initialization + files and previously specified options. But all of these can be + overridden by later options. + + The contents of the RC file just comprise a piece of code in the + Perl programming language (typically a sequence of assignment + statements); they are executed when the -r option is encountered during latexmk's parsing of its command line. See the -e option for a way of giving initialization code directly on latexmk's command line. An error results in latexmk stopping. Multiple @@ -885,41 +868,39 @@ LATEXMK(1L) LATEXMK(1L) -rules Show a list of latemk's rules and dependencies after processing. -rules- - Do not show a list of latexmk's rules and dependencies after + Do not show a list of latexmk's rules and dependencies after processing. (This is the default.) -showextraoptions - Show the list of extra latex and pdflatex options that latexmk - recognizes. These are options for the latex and pdflatex that - latexmk recognizes, but simply passes through to these programs - when they are run. These options are (currently) a combination + Show the list of extra latex and pdflatex options that latexmk + recognizes. These are options for the latex and pdflatex that + latexmk recognizes, but simply passes through to these programs + when they are run. These options are (currently) a combination of those allowed by the TeXLive and MiKTeX implementations. (If - a particular option is given to latexmk but is not handled by + a particular option is given to latexmk but is not handled by the particular implementation of latex or pdflatex that is being - used, that program will probably give an error message.) These + used, that program will probably give an error message.) These options are very numerous, but are not listed in this documenta- tion because they have no effect on latexmk's actions. - There are a few options (-includedirectory=dir, -initialize, - -ini) that are not recognized, either because they don't fit + There are a few options (-includedirectory=dir, -initialize, + -ini) that are not recognized, either because they don't fit with latexmk's intended operations, or because they need special - processing by latexmk that isn't implemented (at least, not + processing by latexmk that isn't implemented (at least, not yet). - There are also options that are accepted by latex etc, but + There are also options that are accepted by latex etc, but instead trigger actions by latexmk: -help, -version. Finally, there are certain options for latex and pdflatex (e.g., - -recorder) that trigger special actions or behavior by latexmk - itself as well as being passed in some form to the called latex - and pdflatex program, or that affect other programs as well. - These options do have entries in this documentation. These - options are: -jobname=STRING, -aux-directory=dir, -output-direc- - tory=DIR, -quiet, and -recorder. + -recorder) that trigger special actions or behavior by latexmk + itself as well as being passed in some form to the called latex + and pdflatex program, or that affect other programs as well. + These options do have entries in this documentation. These - 5 February 2015 14 + 24 February 2016 13 @@ -928,16 +909,20 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + options are: -jobname=STRING, -aux-directory=dir, -output-direc- + tory=DIR, -quiet, and -recorder. + + -logfilewarninglist -logfilewarnings After a run of (pdf)latex, give a list of warn- - ings about undefined citations and references (unless silent + ings about undefined citations and references (unless silent mode is on). See also the $silence_logfile_warnings configuration variable. -logfilewarninglist- - -logfilewarnings- After a run of (pdf)latex, do not give a list + -logfilewarnings- After a run of (pdf)latex, do not give a list of warnings about undefined citations and references. (Default) See also the $silence_logfile_warnings configuration variable. @@ -982,10 +967,11 @@ LATEXMK(1L) LATEXMK(1L) -use-make- Do not use the make program to try to make missing files. + (Default.) - 5 February 2015 15 + 24 February 2016 14 @@ -994,8 +980,6 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - (Default.) - -v, -version Print version number of latexmk. @@ -1048,25 +1032,25 @@ EXAMPLES keep running, watching for source file changes. + % latexmk -c # remove .aux, .log, .bbl, .blg, .dvi, + .pdf, .ps & .bbl files - 5 February 2015 16 +DEALING WITH ERRORS, PROBLEMS, ETC + Some possibilities: + 24 February 2016 15 -LATEXMK(1L) LATEXMK(1L) - % latexmk -c # remove .aux, .log, .bbl, .blg, .dvi, - .pdf, .ps & .bbl files +LATEXMK(1L) LATEXMK(1L) -HOW TO CHANGE THE WAY LATEXMK BEHAVES, DEALING WITH PROBLEMS, ETC - Some possibilities: a. If you get a strange error, do look carefully at the output that is on the screen and in log files. While there is much that is notori- @@ -1076,22 +1060,32 @@ HOW TO CHANGE THE WAY LATEXMK BEHAVES, DEALING WITH PROBLEMS, ETC it thinks would otherwise be easy to miss in the middle of other out- put. - b. If latexmk doesn't do things the way you would like, the first step - in finding out what to do is to look in this documentation at the list - of command line options and then at the sections on configuration/ini- - tialization files. A lot of latexmk's behavior is configurable to deal - with particular situations. (But there is a lot of reading.) + b. Generally, remember that latexmk does its work by running other pro- + grams. Your first priority in dealing with errors should be to examine + what went wrong with the individual programs. Then you need to correct + the causes of errors in the runs of these programs. (Often these come + from errors in the source document, but they could also be about miss- + ing LaTeX packages, etc.) + + c. If latexmk doesn't run the programs the way you would like, then you + need to look in this documentation at the list of command line options + and then at the sections on configuration/initialization files. A lot + of latexmk's behavior is configurable to deal with particular situa- + tions. (But there is a lot of reading!) + + The remainder of these notes consists of ideas for dealing with more + difficult situations. - c. Further tricks can involve replacing the standard commands that + d. Further tricks can involve replacing the standard commands that latexmk by other commands or scripts. - d. For possible examples of code for use in an RC file, see the direc- + e. For possible examples of code for use in an RC file, see the direc- tory example_rcfiles in the distribution of latexmk (e.g., at http://www.ctan.org/tex-archive/support/latexmk/example_rcfiles). Even if these examples don't do what you want, they may provide suitable inspiration. - e. There's a useful trick that can be used when you are lualatex + f. There's a useful trick that can be used when you use lualatex instead of pdflatex (and in some related situations). The problem is that latexmk won't notice a dependency on a file, bar.baz say, that is input by the lua code in your document instead of by the LaTeX part. @@ -1108,16 +1102,20 @@ HOW TO CHANGE THE WAY LATEXMK BEHAVES, DEALING WITH PROBLEMS, ETC doing this automatically.) Of course, if the file has a different name, change bar.baz to the name of your file. - f. Look on tex.stackexchange, i.e., at http://tex.stackex- + g. See also the section ADVANCED CONFIGURATION: Some extra resources. + + g. Look on tex.stackexchange, i.e., at http://tex.stackex- change.com/questions/tagged/latexmk Someone may have already solved your problem. - g. Ask a question at tex.stackexchange.com. + h. Ask a question at tex.stackexchange.com. + i. Or ask me (the author of latexmk). My e-mail is at the end of this + documentation. - 5 February 2015 17 + 24 February 2016 16 @@ -1126,11 +1124,6 @@ HOW TO CHANGE THE WAY LATEXMK BEHAVES, DEALING WITH PROBLEMS, ETC LATEXMK(1L) LATEXMK(1L) - h. Or ask me (the author of latexmk). My e-mail is at the end of this - documentation. - - - CONFIGURATION/INITIALIZATION (RC) FILES Latexmk can be customized using initialization files, which are read at startup in the following order: @@ -1180,29 +1173,28 @@ CONFIGURATION/INITIALIZATION (RC) FILES For possible examples of code for in an RC file, see the directory example_rcfiles in the distribution of latexmk (e.g., at + http://www.ctan.org/tex-archive/support/latexmk/example_rcfiles). +HOW TO SET VARIABLES IN INITIALIZATION FILES + The important variables that can be configured are described in the + section "List of configuration variables usable in initialization + files". Syntax for setting these variables is of the following forms: - 5 February 2015 18 - + $bibtex = 'bibtex %O %B'; + for the setting of a string variable, -LATEXMK(1L) LATEXMK(1L) + 24 February 2016 17 - http://www.ctan.org/tex-archive/support/latexmk/example_rcfiles). -HOW TO SET VARIABLES IN INITIALIZATION FILES - The important variables that can be configured are described in the - section "List of configuration variables usable in initialization - files". Syntax for setting these variables is of the following forms: - $bibtex = 'bibtex %O %B'; +LATEXMK(1L) LATEXMK(1L) - for the setting of a string variable, $preview_mode = 1; @@ -1246,18 +1238,6 @@ FORMAT OF COMMAND SPECIFICATIONS The two items starting with the % character are placeholders. These are substituted by appropriate values before the command is run. Thus - - - - 5 February 2015 19 - - - - - -LATEXMK(1L) LATEXMK(1L) - - %S will be replaced by the source file that elatex will be applied to, and %O will be replaced by any options that latexmk has decided to use for this command. (E.g., if you used the -silent option it would @@ -1276,6 +1256,18 @@ LATEXMK(1L) LATEXMK(1L) %R root filename. This is the base name for the main tex file. + + + + 24 February 2016 18 + + + + + +LATEXMK(1L) LATEXMK(1L) + + %S source file (e.g., the name of the dvi file when converting a dvi file to ps). @@ -1312,18 +1304,6 @@ LATEXMK(1L) LATEXMK(1L) often the same, but not always. For example on a simple document, the basename of a bibtex run is the same as for the texfile. But in a doc- ument with several bibliographies, the bibliography files will have a - - - - 5 February 2015 20 - - - - - -LATEXMK(1L) LATEXMK(1L) - - variety of names. Since bibtex is invoked with the basename of the bibliography file, the setting for the bibtex command should therefore be @@ -1331,111 +1311,124 @@ LATEXMK(1L) LATEXMK(1L) $bibtex = 'bibtex %O %B'; Generally, you should use %B rather than %R. Similarly for most pur- - poses, the name %T of the primary texfile is not a useful placeholder. + poses, the name %T of the primary texfile is not a useful placeholder. - See the default values in the section "List of configuration variables + See the default values in the section "List of configuration variables usable in initialization files" for what is normally the most appropri- ate usage. If you omit to supply any placeholders whatever in the specification of - a command, latexmk will supply what its author thinks are appropriate + a command, latexmk will supply what its author thinks are appropriate defaults. This gives compatibility with configuration files for previ- ous versions of latexmk, which didn't use placeholders. - "Detaching" a command: Normally when latexmk runs a command, it waits + "Detaching" a command: Normally when latexmk runs a command, it waits for the command to run to completion. This is appropriate for commands like latex, of course. But for previewers, the command should normally - run detached, so that latexmk gets the previewer running and then + run detached, so that latexmk gets the previewer running and then returns to its next task (or exits if there is nothing else to do). To - achieve this effect of detaching a command, you need to precede the + achieve this effect of detaching a command, you need to precede the + + + + 24 February 2016 19 + + + + + +LATEXMK(1L) LATEXMK(1L) + + command name with "start ", as in $dvi_previewer = 'start xdvi %O %S'; - This will be translated to whatever is appropriate for your operating + This will be translated to whatever is appropriate for your operating system. - Notes: (1) In some circumstances, latex will always run a command + Notes: (1) In some circumstances, latexmk will always run a command detached. This is the case for a previewer in preview continuous mode, - since otherwise previewing continuously makes no sense. (2) This pre- - cludes the possibility of running a command named start. (3) If the - word start occurs more than once at the beginning of the command - string, that is equivalent to having just one. (4) Under cygwin, some - complications happen, since cygwin amounts to a complicated merging of - UNIX and MS-Windows. See the source code for how I've handled the + since otherwise previewing continuously makes no sense. (2) This pre- + cludes the possibility of running a command named start. (3) If the + word start occurs more than once at the beginning of the command + string, that is equivalent to having just one. (4) Under cygwin, some + complications happen, since cygwin amounts to a complicated merging of + UNIX and MS-Windows. See the source code for how I've handled the problem. Command names containing spaces: Under MS-Windows it is common that the name of a command includes spaces, since software is often installed in - a subdirectory of "C:\Program Files". Such command names should be + a subdirectory of "C:\Program Files". Such command names should be enclosed in double quotes, as in $lpr_pdf = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p %S'; $pdf_previewer = 'start "c:/Program Files/SumatraPDF/Suma- traPDF.exe" %O %S'; - $pdf_previewer = 'start "c:/Program Files/SumatraPDF (x86)/Suma- + $pdf_previewer = 'start "c:/Program Files/SumatraPDF (x86)/Suma- traPDF.exe" %O %S'; - - - - 5 February 2015 21 - - - - - -LATEXMK(1L) LATEXMK(1L) - - - (Note about the above example: Forward slashes are equivalent to back- - slashes in filenames under MS-Windows, provided that the filename is - inside double quotes. It is easier to use forward slashes in examples - like the one above, since then one does not have to worry about the - rules for dealing with forward slashes in strings in the Perl lan- + (Note about the above example: Forward slashes are equivalent to back- + slashes in filenames under MS-Windows, provided that the filename is + inside double quotes. It is easier to use forward slashes in examples + like the one above, since then one does not have to worry about the + rules for dealing with forward slashes in strings in the Perl lan- guage.) - Command names under Cygwin: If latexmk is executed by Cygwin's Perl, + Command names under Cygwin: If latexmk is executed by Cygwin's Perl, be particularly certain that pathnames in commands have forward slashes - not the usual backslashes for the separator of pathname components. - See the above examples. Backslashes often get misinterpreted by the + not the usual backslashes for the separator of pathname components. + See the above examples. Backslashes often get misinterpreted by the Unix shell used by Cygwin's Perl to execute external commands. Forward slashes don't suffer from this problem, and (when quoted, as above) are equally acceptable to MS-Windows. - Using MS-Windows file associations: A useful trick under modern ver- + Using MS-Windows file associations: A useful trick under modern ver- sions of MS-Windows (e.g., WinXP) is to use just the command 'start' by itself: $dvi_previewer = 'start %S'; Under recent versions of MS-Windows, this will cause to be run whatever - program the system has associated with dvi files. (The same applies + program the system has associated with dvi files. (The same applies for a postscript viewer and a pdf viewer.) But note that this trick is - not always suitable for the pdf previwer, if your system has acroread + not always suitable for the pdf previwer, if your system has acroread for the default pdf viewer. As explained elsewhere, acroread under MS- - Windows does not work well with latex and latexmk, because acroread + Windows does not work well with latex and latexmk, because acroread locks the pdf file. Not using a certain command: If a command is not to be run, the command + + + + 24 February 2016 20 + + + + + +LATEXMK(1L) LATEXMK(1L) + + name NONE is used, as in $lpr = 'NONE lpr'; - This typically is used when an appropriate command does not exist on + This typically is used when an appropriate command does not exist on your system. The string after the "NONE" is effectively a comment. Options to commands: Setting the name of a command can be used not only for changing the name of the command called, but also to add options to - command. Suppose you want latexmk to use latex with source specials - enabled. Then you might use the following line in an initialization + command. Suppose you want latexmk to use latex with source specials + enabled. Then you might use the following line in an initialization file: $latex = 'latex --src-specials %O %S'; - Running a subroutine instead of an external command: Use a specifica- + + Running a subroutine instead of an external command: Use a specifica- tion starting with "internal", as in $latex = 'internal mylatex %O %S'; @@ -1445,16 +1438,10 @@ LATEXMK(1L) LATEXMK(1L) return system 'latex', @args; } - - - 5 February 2015 22 - - - - - -LATEXMK(1L) LATEXMK(1L) - + For some of the more exotic possibilities that then become available, + see the section "ADVANCED CONFIGURATION: Some extra resources and + advanced tricks". Also see some of the examples in the directory exam- + ple_rcfiles in the latexmk distribution. Advanced tricks: Normally one specifies a single command for the com- mands invoked by latexmk. Naturally, if there is some complicated @@ -1462,16 +1449,19 @@ LATEXMK(1L) LATEXMK(1L) write a script (or batch file) to do the processing, and then configure latexmk to use your script in place of the standard program. + You can also use a Perl subroutine instead of a script -- see above. + This is generally the most flexible and portable solution. + It is also possible to configure latexmk to run multiple commands. For - example, if when running pdflatex to generate a pdf file from a tex - file you need to run another program after pdflatex to perform some + example, if when running pdflatex to generate a pdf file from a tex + file you need to run another program after pdflatex to perform some extra processing, you could do something like: - $pdflatex = 'pdflatex --shell-escape %O %S; pst2pdf_for_latexmk + $pdflatex = 'pdflatex --shell-escape %O %S; pst2pdf_for_latexmk %B'; - This definition assumes you are using a UNIX-like system (which - includes Linux and OS-X), so that the two commands to be run are sepa- + This definition assumes you are using a UNIX-like system (which + includes Linux and OS-X), so that the two commands to be run are sepa- rated by the semicolon in the middle of the string. If you are using MS-Windows, you would replace the above line by @@ -1479,9 +1469,21 @@ LATEXMK(1L) LATEXMK(1L) $pdflatex = 'cmd /c pdflatex --shell-escape %O %S' . '&& pst2pdf_for_latexmk %B'; - Here, the UNIX command separator ; is replaced by &&. In addition, + Here, the UNIX command separator ; is replaced by &&. In addition, there is a problem that some versions of Perl on MS-Windows do not obey - the command separator; this problem is overcome by explicitly invoking + the command separator; this problem is overcome by explicitly invoking + + + + 24 February 2016 21 + + + + + +LATEXMK(1L) LATEXMK(1L) + + the MS-Windows command-line processor cmd.exe. @@ -1490,56 +1492,44 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES $always_view_file_via_temporary [0] Whether ps and pdf files are initially to be made in a temporary - directory and then moved to the final location. (This applies + directory and then moved to the final location. (This applies to dvips, dvipdf, and ps2pdf operations, and the filtering oper- - ators on dvi and ps files. It does not apply to pdflatex, + ators on dvi and ps files. It does not apply to pdflatex, unfortunately.) This use of a temporary file solves a problem that the making of - these files can occupy a substantial time. If a viewer sees - that the file has changed, it reads the new file, and this can + these files can occupy a substantial time. If a viewer sees + that the file has changed, it reads the new file, and this can cause havoc if the program writing the file has not yet finished its work. See the $pvc_view_file_via_temporary variable for a setting that - applies only if preview-continuous mode (-pvc option) is used. + applies only if preview-continuous mode (-pvc option) is used. See $tmpdir for the setting of the directory where the temporary file is created. $auto_rc_use [1] - Whether to automatically read the standard initialization (rc) + Whether to automatically read the standard initialization (rc) files, which are the system RC file, the user's RC file, and the - - - - 5 February 2015 23 - - - - - -LATEXMK(1L) LATEXMK(1L) - - RC file in the current directory. The command line option -norc - can be used to turn this setting off. Each RC file could also - turn this setting off, i.e., it could set $auto_rc_use to zero + can be used to turn this setting off. Each RC file could also + turn this setting off, i.e., it could set $auto_rc_use to zero to prevent automatic reading of the later RC files. - This variable does not affect the reading of RC files specified + This variable does not affect the reading of RC files specified on the command line by the -r option. $aux_dir [""] The directory in which auxiliary files (aux, log, etc) are to be - written by a run of (pdf)latex. If this variable is not set, - but $out_dir is set, then $aux_dir is set to $out_dir, which is + written by a run of (pdf)latex. If this variable is not set, + but $out_dir is set, then $aux_dir is set to $out_dir, which is the directory to which general output files are to be written. - Important note: The effect of $aux_dir, if different from - $out_dir, is achieved by giving (pdf)latex the -aux-directory. - Currently (Dec. 2011 and later) this only works on the MiKTeX + Important note: The effect of $aux_dir, if different from + $out_dir, is achieved by giving (pdf)latex the -aux-directory. + Currently (Dec. 2011 and later) this only works on the MiKTeX version of (pdf)latex. See also the documentation of $out_dir for some complications on @@ -1547,18 +1537,30 @@ LATEXMK(1L) LATEXMK(1L) $banner [0] - If nonzero, the banner message is printed across each page when - converting the dvi file to postscript. Without modifying the - variable $banner_message, this is equivalent to specifying the + If nonzero, the banner message is printed across each page when + converting the dvi file to postscript. Without modifying the + variable $banner_message, this is equivalent to specifying the -d option. Note that if $banner is nonzero, the $postscript_mode is assumed and the postscript file is always generated, even if it is newer + + + + 24 February 2016 22 + + + + + +LATEXMK(1L) LATEXMK(1L) + + than the dvi file. $banner_intensity [0.95] Equivalent to the -bi option, this is a decimal number between 0 - and 1 that specifies how dark to print the banner message. 0 is + and 1 that specifies how dark to print the banner message. 0 is black, 1 is white. The default is just right if your toner car- tridge isn't running too low. @@ -1567,57 +1569,45 @@ LATEXMK(1L) LATEXMK(1L) dvi file to postscript. This is equivalent to the -bm option. $banner_scale [220.0] - A decimal number that specifies how large the banner message - will be printed. Experimentation is necessary to get the right - scale for your message, as a rule of thumb the scale should be - about equal to 1100 divided by the number of characters in the - message. The Default is just right for 5 character messages. + A decimal number that specifies how large the banner message + will be printed. Experimentation is necessary to get the right + scale for your message, as a rule of thumb the scale should be + about equal to 1100 divided by the number of characters in the + message. The Default is just right for 5 character messages. This is equivalent to the -bs option. @BIBINPUTS - This is an array variable, now mostly obsolete, that specifies - - - - 5 February 2015 24 - - - - - -LATEXMK(1L) LATEXMK(1L) - - - directories where latexmk should look for .bib files. By + This is an array variable, now mostly obsolete, that specifies + directories where latexmk should look for .bib files. By default it is set from the BIBINPUTS environment variable of the - operating system. If that environment variable is not set, a - single element list consisting of the current directory is set. + operating system. If that environment variable is not set, a + single element list consisting of the current directory is set. The format of the directory names depends on your operating sys- tem, of course. Examples for setting this variable are: - @BIBINPUTS = ( ".", "C:\bibfiles" ); + @BIBINPUTS = ( ".", "C:\\bibfiles" ); @BIBINPUTS = ( ".", "\\server\bibfiles" ); @BIBINPUTS = ( ".", "C:/bibfiles" ); @BIBINPUTS = ( ".", "//server/bibfiles" ); @BIBINPUTS = ( ".", "/usr/local/texmf/bibtex/bib" ); - Note that under MS Windows, either a forward slash "/" or a - backward slash "\" can be used to separate pathname components, - so the first two and the second two examples are equivalent. - Each backward slash should be doubled to avoid running afoul of + Note that under MS Windows, either a forward slash "/" or a + backward slash "\" can be used to separate pathname components, + so the first two and the second two examples are equivalent. + Each backward slash should be doubled to avoid running afoul of Perl's rules for writing strings. Important note: This variable is now mostly obsolete in the cur- rent version of latexmk, since it has a better method of search- - ing for files using the kpsewhich command. However, if your - system is an unusual one without the kpsewhich command, you may + ing for files using the kpsewhich command. However, if your + system is an unusual one without the kpsewhich command, you may need to set the variable @BIBINPUTS. $biber ["biber %O %S"] The biber processing program. $biber_silent_switch ["--onlylog"] - Switch(es) for the biber processing program when silent mode is + Switch(es) for the biber processing program when silent mode is on. $bibtex ["bibtex %O %S"] @@ -1627,25 +1617,9 @@ LATEXMK(1L) LATEXMK(1L) Switch(es) for the BibTeX processing program when silent mode is on. - $bibtex_use [1] - Under what conditions to run BibTeX or biber. When latexmk dis- - covers from the log file that one (or more) BibTeX/biber-gener- - ated bibliographies are used, it can run BibTeX or biber when- - ever it appears necessary to regenerate the bbl file(s) from - their source bib database file(s). - - But sometimes, the bib file(s) are not available (e.g., for a - document obtained from an external archive), but the bbl files - are provided. In that case use of BibTeX or biber will result - in incorrect overwriting of the precious bbl files. The vari- - able $bibtex_use controls whether this happens. Its possible - values are: 0: never use BibTeX or biber. 1: only use BibTeX or - biber if the bib files exist. 2: run BibTeX or biber whenever - it appears necessary to update the bbl files, without testing - - 5 February 2015 25 + 24 February 2016 23 @@ -1654,36 +1628,51 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + $bibtex_use [1] + Under what conditions to run BibTeX or biber. When latexmk dis- + covers from the log file that one (or more) BibTeX/biber-gener- + ated bibliographies are used, it can run BibTeX or biber when- + ever it appears necessary to regenerate the bbl file(s) from + their source bib database file(s). + + But sometimes, the bib file(s) are not available (e.g., for a + document obtained from an external archive), but the bbl files + are provided. In that case use of BibTeX or biber will result + in incorrect overwriting of the precious bbl files. The vari- + able $bibtex_use controls whether this happens. Its possible + values are: 0: never use BibTeX or biber. 1: only use BibTeX or + biber if the bib files exist. 2: run BibTeX or biber whenever + it appears necessary to update the bbl files, without testing for the existence of the bib files. $cleanup_includes_cusdep_generated [0] - If nonzero, specifies that cleanup also deletes files that are + If nonzero, specifies that cleanup also deletes files that are generated by custom dependencies. (When doing a clean up, e.g., by use of the -C option, custom dependencies are those listed in the .fdb_latexmk file from a previous run.) $cleanup_includes_generated [0] - If nonzero, specifies that cleanup also deletes files that are - detected in log file as being generated (see the \openout lines - in the log file). It will also include files made from these + If nonzero, specifies that cleanup also deletes files that are + detected in log file as being generated (see the \openout lines + in the log file). It will also include files made from these first generation generated files. $cleanup_mode [0] - If nonzero, specifies cleanup mode: 1 for full cleanup, 2 for - cleanup except for dvi, ps and pdf files, 3 for cleanup except - for dep and aux files. (There is also extra cleaning as speci- - fied by the $clean_ext, $clean_full_ext and @generated_exts + If nonzero, specifies cleanup mode: 1 for full cleanup, 2 for + cleanup except for dvi, ps and pdf files, 3 for cleanup except + for dep and aux files. (There is also extra cleaning as speci- + fied by the $clean_ext, $clean_full_ext and @generated_exts variables.) - This variable is equivalent to specifying one of the -c or -C - options. But there should be no need to set this variable from + This variable is equivalent to specifying one of the -c or -C + options. But there should be no need to set this variable from an RC file. $clean_ext [""] - Extra extensions of files for latexmk to remove when any of the - clean-up options (-c or -C) is selected. The value of this - variable is a string containing the extensions separated by spa- - ces. + Extra extensions of files for latexmk to remove when any of the + clean-up options (-c or -C) is selected. The value of this + variable is a string containing the extensions separated by + spaces. It is also possible to specify a more general pattern of file to be deleted, by using the place holder %R, as in commands, and it @@ -1692,33 +1681,34 @@ LATEXMK(1L) LATEXMK(1L) $clean_ext = "out %R-blx.bib %R-figures*.log"; in an initialization file will imply that when a clean-up opera- - tion is specified, not only is the standard set of files - deleted, but also files of the form FOO.out, FOO-blx.bib, and - %R-figures*.log, where FOO stands for the basename of the file + tion is specified, not only is the standard set of files + deleted, but also files of the form FOO.out, FOO-blx.bib, and + %R-figures*.log, where FOO stands for the basename of the file being processed (as in FOO.tex). $clean_full_ext [""] - Extra extensions of files for latexmk to remove when the -C + Extra extensions of files for latexmk to remove when the -C option is selected, i.e., extensions of files to remove when the - .dvi, etc files are to be cleaned-up. - More general patterns are allowed, as for $clean_ext. - $compiling_cmd [undefined], $failure_cmd [undefined], $success_cmd - [undefined] + 24 February 2016 24 - 5 February 2015 26 +LATEXMK(1L) LATEXMK(1L) + .dvi, etc files are to be cleaned-up. + + More general patterns are allowed, as for $clean_ext. -LATEXMK(1L) LATEXMK(1L) + $compiling_cmd [undefined], $failure_cmd [undefined], $success_cmd + [undefined] These variables specify commands that are executed at certain points of compilations during preview-continuous mode. One @@ -1735,32 +1725,32 @@ LATEXMK(1L) LATEXMK(1L) An example of a typical setting of these variables is as follows - $compiling_cmd = "xdotool search --name \"%D\" set_window + $compiling_cmd = "xdotool search --name \"%D\" set_window --name \"%D compiling\""; - $success_cmd = "xdotool search --name \"%D\" set_window + $success_cmd = "xdotool search --name \"%D\" set_window --name \"%D OK\""; - $failure_cmd = "xdotool search --name \"%D\" set_window + $failure_cmd = "xdotool search --name \"%D\" set_window --name \"%D FAILURE\""; - These assume that the program xdotool is installed, that the - previewer is using an X-Window system for display, and that the - title of the window contains the name of the displayed file, as - it normally does. When the commands are executed, the place- - holder string %D is replaced by the name of the destination + These assume that the program xdotool is installed, that the + previewer is using an X-Window system for display, and that the + title of the window contains the name of the displayed file, as + it normally does. When the commands are executed, the place- + holder string %D is replaced by the name of the destination file, which is the previewed file. The above commands result in an appropriate string being appended to the filename in the win- dow title: " compiling", " OK", or " FAILURE". - Other placeholders that can be used are %S, %T, and %R, with %S - and %T normally being identical. These can be useful for a com- - mand changing the title of the edit window. The visual indica- - tion in a window title can useful, since the user does not have - to keep shifting attention to the (possibly hidden) compilation + Other placeholders that can be used are %S, %T, and %R, with %S + and %T normally being identical. These can be useful for a com- + mand changing the title of the edit window. The visual indica- + tion in a window title can useful, since the user does not have + to keep shifting attention to the (possibly hidden) compilation window to know the status of the compilation. @cus_dep_list [()] - Custom dependency list -- see section on "Custom Dependencies". + Custom dependency list -- see section on "Custom Dependencies". @default_excluded_files [()] @@ -1777,7 +1767,7 @@ LATEXMK(1L) LATEXMK(1L) - 5 February 2015 27 + 24 February 2016 25 @@ -1841,9 +1831,17 @@ LATEXMK(1L) LATEXMK(1L) around errors make gives if you remove header files without updating the Makefile to match. + $dependents_list [0] + Whether to display a list(s) of dependencies at the end of a + run. + + $deps_file ["-"] + Name of file to receive list(s) of dependencies at the end of a + run, to be used if $dependesnt_list is set. If the filename is + - 5 February 2015 28 + 24 February 2016 26 @@ -1852,13 +1850,6 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - $dependents_list [0] - Whether to display a list(s) of dependencies at the end of a - run. - - $deps_file ["-"] - Name of file to receive list(s) of dependencies at the end of a - run, to be used if $dependesnt_list is set. If the filename is "-", then the dependency list is set to stdout (i.e., normally the screen). @@ -1907,17 +1898,6 @@ LATEXMK(1L) LATEXMK(1L) of Windows, this will cause to be run whatever command the sys- tem has associated with .dvi files.] - - - 5 February 2015 29 - - - - - -LATEXMK(1L) LATEXMK(1L) - - $dvipdf ["dvipdf %O %S %D"] Command to convert dvi to pdf file. A common reconfiguration is to use the dvipdfm command, which needs its arguments in a dif- @@ -1933,6 +1913,18 @@ LATEXMK(1L) LATEXMK(1L) $dvipdf_silent_switch ["-q"] Switch(es) for dvipdf program when silent mode is on. + + + + 24 February 2016 27 + + + + + +LATEXMK(1L) LATEXMK(1L) + + N.B. The standard dvipdf program runs silently, so adding the silent switch has no effect, but is actually innocuous. But if an alternative program is used, e.g., dvipdfmx, then the silent @@ -1972,18 +1964,6 @@ LATEXMK(1L) LATEXMK(1L) on the viewer's window or may mean a more serious action. 2 => Send the signal, whose number is in the variable $dvi_update_signal. The default value under UNIX is suitable - - - - 5 February 2015 30 - - - - - -LATEXMK(1L) LATEXMK(1L) - - for xdvi. 3 => Viewer cannot do an update, because it locks the file. (As with acroread under MS-Windows.) @@ -1995,25 +1975,37 @@ LATEXMK(1L) LATEXMK(1L) $dvi_update_signal [Under UNIX: SIGUSR1, which is a system-dependent value] - The number of the signal that is sent to the dvi viewer when it - is updated by sending a signal -- see the information on the - variable $dvi_update_method. The default value is the one + The number of the signal that is sent to the dvi viewer when it + is updated by sending a signal -- see the information on the + variable $dvi_update_method. The default value is the one appropriate for xdvi on a UNIX system. $failure_cmd [undefined] See the documentation for $compiling_cmd. $fdb_ext ["fdb_latexmk"] - The extension of the file which latexmk generates to contain a - database of information on source files. You will not normally + The extension of the file which latexmk generates to contain a + database of information on source files. You will not normally need to change this. + + + + 24 February 2016 28 + + + + + +LATEXMK(1L) LATEXMK(1L) + + $force_mode [0] - If nonzero, continue processing past minor latex errors includ- + If nonzero, continue processing past minor latex errors includ- ing unrecognized cross references. Equivalent to specifying the -f option. - @generated_exts [( aux , bbl , idx , ind , lof , lot , out , toc , + @generated_exts [( aux , bbl , idx , ind , lof , lot , out , toc , $fdb_ext )] This contains a list of extensions for files that are generated during a LaTeX run and that are read in by LaTeX in later runs, @@ -2038,18 +2030,6 @@ LATEXMK(1L) LATEXMK(1L) losing the already defined ones is to use a push command in the line in an RC file. E.g., - - - - 5 February 2015 31 - - - - - -LATEXMK(1L) LATEXMK(1L) - - push @generated_exts, "end"; adds the extension "end" to the list of predefined generated @@ -2082,12 +2062,24 @@ LATEXMK(1L) LATEXMK(1L) This creates a rule for files with extension .eps about lines to ignore. The left-hand side is a Perl idiom for setting an item in a hash. Note that the file extension is specified without a - period. The value, on the right-hand side, is a string contain- - ing a regular expresssion. (See documentation on Perl for how - they are to be specified in general.) This particular regular - expression specifies that lines beginning with "%%CreationDate: - " are to be ignored in deciding whether a file of the given - extension .eps has changed. + period. The value, on the right-hand side, is a string + + + + 24 February 2016 29 + + + + + +LATEXMK(1L) LATEXMK(1L) + + + containing a regular expresssion. (See documentation on Perl + for how they are to be specified in general.) This particular + regular expression specifies that lines beginning with "%%Cre- + ationDate: " are to be ignored in deciding whether a file of the + given extension .eps has changed. There is only one regular expression available for each exten- sion. If you need more one pattern to specify lines to ignore, @@ -2104,18 +2096,6 @@ LATEXMK(1L) LATEXMK(1L) It may happen that a pattern to be ignored is specified in, for example, in a system or user initialization file, and you wish - - - - 5 February 2015 32 - - - - - -LATEXMK(1L) LATEXMK(1L) - - to remove this in a file read later. To do this, you use Perl's delete function, e.g., @@ -2159,28 +2139,27 @@ LATEXMK(1L) LATEXMK(1L) specified by the variable %latex_input_extensions. The default extensions are 'tex' and 'eps'. - (For Perl experts: %latex_input_extensions is a hash whose keys - are the extensions. The values are irrelevant.) Two subrou- - tines are provided for manipulating this and the related vari- - able %pdflatex_input_extensions, add_input_ext and - remove_input_ext. They are used as in the following examples - are possible lines in an initialization file: - remove_input_ext( 'latex', 'tex' ); - - removes the extension 'tex' from latex_input_extensions + 24 February 2016 30 - 5 February 2015 33 +LATEXMK(1L) LATEXMK(1L) + (For Perl experts: %latex_input_extensions is a hash whose keys + are the extensions. The values are irrelevant.) Two subrou- + tines are provided for manipulating this and the related vari- + able %pdflatex_input_extensions, add_input_ext and + remove_input_ext. They are used as in the following examples + are possible lines in an initialization file: -LATEXMK(1L) LATEXMK(1L) + remove_input_ext( 'latex', 'tex' ); + removes the extension 'tex' from latex_input_extensions add_input_ext( 'latex', 'asdf' ); @@ -2214,12 +2193,12 @@ LATEXMK(1L) LATEXMK(1L) $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p'; - If gsview is installed in a different directory, you will need - to make the appropriate change. Note the combination of single - and double quotes around the name. The single quotes specify - that this is a string to be assigned to the configuration vari- - able $lpr. The double quotes are part of the string passed to - the operating system to get the command obeyed; this is neces- + If gsview is installed in a different directory, you will need + to make the appropriate change. Note the combination of single + and double quotes around the name. The single quotes specify + that this is a string to be assigned to the configuration vari- + able $lpr. The double quotes are part of the string passed to + the operating system to get the command obeyed; this is neces- sary because one part of the command name ("Program Files") con- tains a space which would otherwise be misinterpreted. @@ -2229,17 +2208,15 @@ LATEXMK(1L) LATEXMK(1L) $lpr_pdf ["NONE lpr_pdf"] The printing program to print pdf files. - Under MS-Windows you could set this to use gsview, if it is + Under MS-Windows you could set this to use gsview, if it is installed, e.g., $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p'; - If gsview is installed in a different directory, you will need - to make the appropriate change. Note the double quotes around - 5 February 2015 34 + 24 February 2016 31 @@ -2248,6 +2225,8 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + If gsview is installed in a different directory, you will need + to make the appropriate change. Note the double quotes around the name: this is necessary because one part of the command name ("Program Files") contains a space which would otherwise be mis- interpreted. @@ -2302,10 +2281,17 @@ LATEXMK(1L) LATEXMK(1L) $out_dir [""] + If non-blank, this variable specifies the directory in which + output files are to be written by a run of (pdf)latex. See also + the variable $aux_dir. + The effect of this variable (when non-blank) is achieved by + using the -output-directory option of (pdf)latex. This exists + in the usual current (Dec. 2011 and later) implementations of - 5 February 2015 35 + + 24 February 2016 32 @@ -2314,13 +2300,6 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - If non-blank, this variable specifies the directory in which - output files are to be written by a run of (pdf)latex. See also - the variable $aux_dir. - - The effect of this variable (when non-blank) is achieved by - using the -output-directory option of (pdf)latex. This exists - in the usual current (Dec. 2011 and later) implementations of TeX, i.e., MiKTeX and TeXLive. But it may not be present in other versions. @@ -2368,18 +2347,6 @@ LATEXMK(1L) LATEXMK(1L) tex, xelatex or some similar program to be used instead of pdflatex. Note that lualatex and xelatex only produce .pdf files (and not .dvi), so to use them you will also need to turn - - - - 5 February 2015 36 - - - - - -LATEXMK(1L) LATEXMK(1L) - - on production of .pdf files, and to turn off the production of .dvi (and .ps) files, either by command line options or by suit- able settings in a configuration file. Thus to use lualatex, the @@ -2396,6 +2363,18 @@ LATEXMK(1L) LATEXMK(1L) Another use of the same variable is to add certain options to the command line for the program, e.g., + + + + 24 February 2016 33 + + + + + +LATEXMK(1L) LATEXMK(1L) + + $pdflatex = "pdflatex --shell-escape %O %S"; @@ -2434,18 +2413,6 @@ LATEXMK(1L) LATEXMK(1L) tex and its graphics/graphicx packages.) - - - - 5 February 2015 37 - - - - - -LATEXMK(1L) LATEXMK(1L) - - $pdflatex_silent_switch ["-interaction=batchmode"] Switch(es) for the pdflatex program (specified in the variable $pdflatex when silent mode is on. @@ -2472,6 +2439,17 @@ LATEXMK(1L) LATEXMK(1L) file. By default, for pdf files this association is to OS-X's preview, which is quite satisfactory. + + + 24 February 2016 34 + + + + + +LATEXMK(1L) LATEXMK(1L) + + WARNING: Problem under MS-Windows: if acroread is used as the pdf previewer, and it is actually viewing a pdf file, the pdf file cannot be updated. Thus makes acroread a bad choice of @@ -2500,18 +2478,6 @@ LATEXMK(1L) LATEXMK(1L) changed. See the information on the variable $dvi_update_method for the codes. (Note that information needs be changed slightly so that for the value 4, to run a command to do the update, the - - - - 5 February 2015 38 - - - - - -LATEXMK(1L) LATEXMK(1L) - - command is specified by the variable $pdf_update_command, and for the value 2, to specify update by signal, the signal is specified by $pdf_update_signal.) @@ -2535,123 +2501,123 @@ LATEXMK(1L) LATEXMK(1L) $pdf_update_signal [Under UNIX: SIGHUP, which is a system-dependent value] - The number of the signal that is sent to the pdf viewer when it - is updated by sending a signal -- see the information on the - variable $pdf_update_method. The default value is the one + The number of the signal that is sent to the pdf viewer when it + is updated by sending a signal -- see the information on the + variable $pdf_update_method. The default value is the one appropriate for gv on a UNIX system. $pid_position[1 under UNIX, -1 under MS-Windows] - The variable $pid_position is used to specify which word in - lines of the output from $pscmd corresponds to the process ID. - The first word in the line is numbered 0. The default value of + The variable $pid_position is used to specify which word in + lines of the output from $pscmd corresponds to the process ID. + The first word in the line is numbered 0. The default value of 1 (2nd word in line) is correct for Solaris 2.6 and Linux. Set- - ting the variable to -1 is used to indicate that $pscmd is not + ting the variable to -1 is used to indicate that $pscmd is not to be used. - $postscript_mode [0] - If nonzero, generate a postscript version of the document. - Equivalent to the -ps option. - If some other request is made for which a postscript file is - needed, then $postscript_mode will be set to 1. - $preview_continuous_mode [0] - If nonzero, run a previewer to view the document, and continue - running latexmk to keep .dvi up-to-date. Equivalent to the -pvc - option. Which previewer is run depends on the other settings, - see the command line options -view=, and the variable $view. + 24 February 2016 35 - $preview_mode [0] - If nonzero, run a previewer to preview the document. Equivalent - to the -pv option. Which previewer is run depends on the other - settings, see the command line options -view=, and the variable - $view. - 5 February 2015 39 +LATEXMK(1L) LATEXMK(1L) + $postscript_mode [0] + If nonzero, generate a postscript version of the document. + Equivalent to the -ps option. + If some other request is made for which a postscript file is + needed, then $postscript_mode will be set to 1. -LATEXMK(1L) LATEXMK(1L) + $preview_continuous_mode [0] + If nonzero, run a previewer to view the document, and continue + running latexmk to keep .dvi up-to-date. Equivalent to the -pvc + option. Which previewer is run depends on the other settings, + see the command line options -view=, and the variable $view. + $preview_mode [0] + If nonzero, run a previewer to preview the document. Equivalent + to the -pv option. Which previewer is run depends on the other + settings, see the command line options -view=, and the variable + $view. $printout_mode [0] - If nonzero, print the document using lpr. Equivalent to the -p + If nonzero, print the document using lpr. Equivalent to the -p option. This is recommended not to be set from an RC file, oth- erwise you could waste lots of paper. $print_type = ["auto"] - Type of file to printout: possibilities are "auto", "dvi", + Type of file to printout: possibilities are "auto", "dvi", "none", "pdf", or "ps". See the option -print= for the meaning of the "auto" value. $pscmd Command used to get all the processes currently run by the user. - The -pvc option uses the command specified by the variable - $pscmd to determine if there is an already running previewer, - and to find the process ID (needed if latexmk needs to signal + The -pvc option uses the command specified by the variable + $pscmd to determine if there is an already running previewer, + and to find the process ID (needed if latexmk needs to signal the previewer about file changes). Each line of the output of this command is assumed to correspond - to one process. See the $pid_position variable for how the - process number is determined. + to one process. See the $pid_position variable for how the pro- + cess number is determined. - The default for pscmd is "NONE" under MS-Windows and cygwin + The default for pscmd is "NONE" under MS-Windows and cygwin (i.e., the command is not used), "ps --width 200 -f -u - $ENV{USER}" under linux, "ps -ww -u $ENV{USER}" under darwin - (Macintosh OS-X), and "ps -f -u $ENV{USER}" under other operat- - ing systems (including other flavors of UNIX). In these speci- + $ENV{USER}" under linux, "ps -ww -u $ENV{USER}" under darwin + (Macintosh OS-X), and "ps -f -u $ENV{USER}" under other operat- + ing systems (including other flavors of UNIX). In these speci- fications "$ENV{USER}" is substituted by the username. $ps2pdf ["ps2pdf %O %S %D"] Command to convert ps to pdf file. $ps_filter [empty] - The postscript file filter to be run on the newly produced post- - script file before other processing. Equivalent to specifying - the -pF option. + The postscript file filter to be run on the newly produced + postscript file before other processing. Equivalent to specify- + ing the -pF option. $ps_previewer ["start gv %O %S", but start %O %S under MS-WINDOWS] - The command to invoke a ps-previewer. (The default under MS- - WINDOWS will cause to be run whatever command the system has + The command to invoke a ps-previewer. (The default under MS- + WINDOWS will cause to be run whatever command the system has associated with .ps files.) - Note that gv could be used with the -watch option updates its - display whenever the postscript file changes, whereas ghostview - does not. However, different versions of gv have slightly dif- - ferent ways of writing this option. You can configure this - variable appropriately. + Note that gv could be used with the -watch option updates its + display whenever the postscript file changes, whereas ghostview + does not. However, different versions of gv have slightly dif- + ferent ways of writing this option. You can configure this - WARNING: Linux systems may have installed one (or more) versions - of gv under different names, e.g., ggv, kghostview, etc, but - perhaps not one called gv. - Important note: Normally you will want to have a previewer run - detached, so that latexmk doesn't wait for the previewer to ter- - minate before continuing its work. So normally you should pre- - fix the command by "start ", which flags to latexmk that it + 24 February 2016 36 - 5 February 2015 40 +LATEXMK(1L) LATEXMK(1L) -LATEXMK(1L) LATEXMK(1L) + variable appropriately. + WARNING: Linux systems may have installed one (or more) versions + of gv under different names, e.g., ggv, kghostview, etc, but + perhaps not one called gv. - should do the detaching of the previewer itself (by whatever - method is appropriate to the operating system). But sometimes + Important note: Normally you will want to have a previewer run + detached, so that latexmk doesn't wait for the previewer to ter- + minate before continuing its work. So normally you should pre- + fix the command by "start ", which flags to latexmk that it + should do the detaching of the previewer itself (by whatever + method is appropriate to the operating system). But sometimes letting latexmk do the detaching is not appropriate (for a vari- - ety of non-trivial reasons), so you should put the "start " bit + ety of non-trivial reasons), so you should put the "start " bit in yourself, whenever it is needed. - $ps_previewer_landscape ["start gv -swap %O %S", but start %O %S under + $ps_previewer_landscape ["start gv -swap %O %S", but start %O %S under MS-WINDOWS] The command to invoke a ps-previewer in landscape mode. @@ -2672,8 +2638,8 @@ LATEXMK(1L) LATEXMK(1L) $ps_update_signal [Under UNIX: SIGHUP, which is a system-dependent value] - The number of the signal that is sent to the pdf viewer when it - is updated by sending a signal -- see $ps_update_method. The + The number of the signal that is sent to the pdf viewer when it + is updated by sending a signal -- see $ps_update_method. The default value is the one appropriate for gv on a UNIX system. @@ -2685,23 +2651,22 @@ LATEXMK(1L) LATEXMK(1L) $quote_filenames [1] This specifies whether substitutions for placeholders in command specifications (as in $pdflatex) are surrounded by double - quotes. If this variable is 1 (or any other value Perl regards + quotes. If this variable is 1 (or any other value Perl regards as true), then quoting is done. Otherwise quoting is omitted. - The quoting method used by latexmk is tested to work correctly - under UNIX systems (including Linux and Mac OS-X) and under MS- - Windows. It allows the use of filenames containing special - characters, notably spaces. (But note that many versions of - LaTeX and PdfLaTeX cannot correctly deal with TeX files whose - names contain spaces. Latexmk's quoting only ensures that such + The quoting method used by latexmk is tested to work correctly + under UNIX systems (including Linux and Mac OS-X) and under MS- + Windows. It allows the use of filenames containing special + characters, notably spaces. (But note that many versions of + LaTeX and PdfLaTeX cannot correctly deal with TeX files whose + names contain spaces. Latexmk's quoting only ensures that such filenames are correctly treated by the operating system in pass- ing arguments to programs.) - - 5 February 2015 41 + 24 February 2016 37 @@ -2711,102 +2676,100 @@ LATEXMK(1L) LATEXMK(1L) $recorder [0] - Whether to use the -recorder option to latex and pdflatex. Use - of this option results in a file of extension .fls containing a - list of the files that these programs have read and written. - Latexmk will then use this file to improve its detection of - source files and generated files after a run of latex or pdfla- + Whether to use the -recorder option to latex and pdflatex. Use + of this option results in a file of extension .fls containing a + list of the files that these programs have read and written. + Latexmk will then use this file to improve its detection of + source files and generated files after a run of latex or pdfla- tex. - It is generally recommended to use this option (or to configure - the $recorder variable to be on.) But it only works if + It is generally recommended to use this option (or to configure + the $recorder variable to be on.) But it only works if (pdf)latex supports the -recorder option, which is true for most current implementations - Note about the name of the .fls file: Most implementations of - (pdf)latex produce an .fls file with the same basename as the - main document's LaTeX, e.g., for Document.tex, the .fls file is - Document.fls. However, some implementations instead produce - files named for the program, i.e., latex.fls or pdflatex.fls. - In this second case, latexmk copies the latex.fls or pdfla- - tex.fls to a file with the basename of the main LaTeX document, + Note about the name of the .fls file: Most implementations of + (pdf)latex produce an .fls file with the same basename as the + main document's LaTeX, e.g., for Document.tex, the .fls file is + Document.fls. However, some implementations instead produce + files named for the program, i.e., latex.fls or pdflatex.fls. + In this second case, latexmk copies the latex.fls or pdfla- + tex.fls to a file with the basename of the main LaTeX document, e.g., Document.fls. $search_path_separator [See below for default] The character separating paths in the environment variables TEX- - INPUTS, BIBINPUTS, and BSTINPUTS. This variable is mainly used - by latexmk when the -outdir, -output-directory, -auxdir, and/or - -aux-directory options are used. In that case latexmk needs to - communicate appropriately modified search paths to $bibtex, + INPUTS, BIBINPUTS, and BSTINPUTS. This variable is mainly used + by latexmk when the -outdir, -output-directory, -auxdir, and/or + -aux-directory options are used. In that case latexmk needs to + communicate appropriately modified search paths to $bibtex, dvipdf, dvips, and (pdf)latex. - [Comment to technically savvy readers: (pdf)latex doesn't actu- - ally need the modified search path, because it corrects it - internally. But, surprisingly, dvipdf and dvips do, because - sometimes graphics files get generated in the output or aux + [Comment to technically savvy readers: (pdf)latex doesn't actu- + ally need the modified search path, because it corrects it + internally. But, surprisingly, dvipdf and dvips do, because + sometimes graphics files get generated in the output or aux directories.] - The default under MSWin and Cygwin is ';' and under UNIX-like - operating systems (including Linux and OS-X) is ':'. Normally - the defaults give correct behavior. But there can be difficul- - ties if your operating system is of one kind, but some of your - software is running under an emulator for the other kind of - operating system; in that case you'll need to find out what is - needed, and set $search_path_separator explicitly. (The same - goes, of course, for unusual operating systems that are not in + The default under MSWin and Cygwin is ';' and under UNIX-like + operating systems (including Linux and OS-X) is ':'. Normally + the defaults give correct behavior. But there can be difficul- + ties if your operating system is of one kind, but some of your + software is running under an emulator for the other kind of + operating system; in that case you'll need to find out what is + needed, and set $search_path_separator explicitly. (The same + goes, of course, for unusual operating systems that are not in the MSWin, Linux, OS-X, Unix collection.) $silence_logfile_warnings [0] - Whether after a run of (pdf)latex to summarize warnings in the - log file about undefined citations and references. Setting - $silence_logfile_warnings=0 gives the summary of warnings (pro- - vided silent mode isn't also set), and this is useful to locate + Whether after a run of (pdf)latex to summarize warnings in the + log file about undefined citations and references. Setting + $silence_logfile_warnings=0 gives the summary of warnings (pro- + vided silent mode isn't also set), and this is useful to locate undefined citations and references without searching through the + much more verbose log file or the screen output of (pdf)latex. + But the summary can also be excessively annoying. The default + is not to give these warnings. The command line options + -silence_logfile_warning_list and -silence_logfile_warning_list- + also set this variable. - - - 5 February 2015 42 + Note that multiple occurrences for the same undefined object on + the same page and same line will be compressed to a single warn- + ing. + 24 February 2016 38 -LATEXMK(1L) LATEXMK(1L) - much more verbose log file or the screen output of (pdf)latex. - But the summary can also be excessively annoying. The default - is not to give these warnings. The command line options - -silence_logfile_warning_list and -silence_logfile_warning_list- - also set this variable. - Note that multiple occurrences for the same undefined object on - the same page and same line will be compressed to a single warn- - ing. +LATEXMK(1L) LATEXMK(1L) $silent [0] - Whether to run silently. Setting $silent to 1 has the same + Whether to run silently. Setting $silent to 1 has the same effect as the -quiet of -silent options on the command line. $sleep_time [2] - The time to sleep (in seconds) between checking for source file + The time to sleep (in seconds) between checking for source file changes when running with the -pvc option. This is subject to a - minimum of one second delay, except that zero delay is also + minimum of one second delay, except that zero delay is also allowed. - A value of exactly 0 gives no delay, and typically results in + A value of exactly 0 gives no delay, and typically results in 100% CPU usage, which may not be desirable. $texfile_search [""] - This is an obsolete variable, replaced by the @default_files + This is an obsolete variable, replaced by the @default_files variable. - For backward compatibility, if you choose to set $tex- - file_search, it is a string of space-separated filenames, and + For backward compatibility, if you choose to set $tex- + file_search, it is a string of space-separated filenames, and then latexmk replaces @default_files with the filenames in $tex- file_search to which is added "*.tex". @@ -2816,60 +2779,60 @@ LATEXMK(1L) LATEXMK(1L) $tmpdir [See below for default] - Directory to store temporary files that latexmk may generate + Directory to store temporary files that latexmk may generate while running. - The default under MSWindows (including cygwin), is to set - $tmpdir to the value of the first of whichever of the system - environment variables TMPDIR or TEMP exists, otherwise to the - current directory. Under other operating systems (expected to - be UNIX/Linux, including OS-X), the default is the value of the - system environment variable TMPDIR if it exists, otherwise + The default under MSWindows (including cygwin), is to set + $tmpdir to the value of the first of whichever of the system + environment variables TMPDIR or TEMP exists, otherwise to the + current directory. Under other operating systems (expected to + be UNIX/Linux, including OS-X), the default is the value of the + system environment variable TMPDIR if it exists, otherwise "/tmp". $use_make_for_missing_files [0] Whether to use make to try and make files that are missing after - a run of latex or pdflatex, and for which a custom dependency + a run of latex or pdflatex, and for which a custom dependency + has not been found. This is generally useful only when latexmk + is used as part of a bigger project which is built by using the + make program. + Note that once a missing file has been made, no further calls to + make will be made on a subsequent run of latexmk to update the + file. Handling this problem is the job of a suitably defined + Makefile. See the section "USING latexmk WITH make" for how to + do this. The intent of calling make from latexmk is merely to + detect dependencies. + $view ["default"] + Which kind of file is to be previewed if a previewer is used. + The possible values are "default", "dvi", "ps", "pdf". The + value of "default" means that the "highest" of the kinds of file + generated is to be used (among dvi, ps and pdf). - 5 February 2015 43 +CUSTOM DEPENDENCIES + In any RC file a set of custom dependencies can be set up to convert a + file with one extension to a file with another. An example use of this + 24 February 2016 39 -LATEXMK(1L) LATEXMK(1L) - has not been found. This is generally useful only when latexmk - is used as part of a bigger project which is built by using the - make program. - Note that once a missing file has been made, no further calls to - make will be made on a subsequent run of latexmk to update the - file. Handling this problem is the job of a suitably defined - Makefile. See the section "USING latexmk WITH make" for how to - do this. The intent of calling make from latexmk is merely to - detect dependencies. - $view ["default"] - Which kind of file is to be previewed if a previewer is used. - The possible values are "default", "dvi", "ps", "pdf". The - value of "default" means that the "highest" of the kinds of file - generated is to be used (among dvi, ps and pdf). +LATEXMK(1L) LATEXMK(1L) -CUSTOM DEPENDENCIES - In any RC file a set of custom dependencies can be set up to convert a - file with one extension to a file with another. An example use of this would be to allow latexmk to convert a .fig file to .eps to be included in the .tex file. - The old method of configuring latexmk was to directly manipulate the - @cus_dep_list array that contains information defining the custom - dependencies. This method still works. But now there are subroutines - that allow convenient manipulations of the custom dependency list. + The old method of configuring latexmk was to directly manipulate the + @cus_dep_list array that contains information defining the custom + dependencies. This method still works. But now there are subroutines + that allow convenient manipulations of the custom dependency list. These are add_cus_dep( fromextension, toextension, must, subroutine ) @@ -2880,55 +2843,43 @@ CUSTOM DEPENDENCIES follow: from extension: - The extension of the file we are converting from (e.g. "fig"). + The extension of the file we are converting from (e.g. "fig"). It is specified without a period. to extension: The extension of the file we are converting to (e.g. "eps"). It is specified without a period. - must: If non-zero, the file from which we are converting must exist, - if it doesn't exist latexmk will give an error message and exit + must: If non-zero, the file from which we are converting must exist, + if it doesn't exist latexmk will give an error message and exit unless the -f option is specified. If must is zero and the file we are converting from doesn't exist, then no action is taken. function: - The name of the subroutine that latexmk should call to perform - the file conversion. The first argument to the subroutine is + The name of the subroutine that latexmk should call to perform + the file conversion. The first argument to the subroutine is the base name of the file to be converted without any extension. - - - - 5 February 2015 44 - - - - - -LATEXMK(1L) LATEXMK(1L) - - - The subroutines are declared in the syntax of Perl. The func- - tion should return 0 if it was successful and a nonzero number + The subroutines are declared in the syntax of Perl. The func- + tion should return 0 if it was successful and a nonzero number if it failed. - It is invoked whenever latexmk detects that a run of latex/pdflatex - needs to read a file, like a graphics file, whose extension is the to- + It is invoked whenever latexmk detects that a run of latex/pdflatex + needs to read a file, like a graphics file, whose extension is the to- extension of a custom dependency. Then latexmk examines whether a file - exists with the same name, but with the corresponding from-extension, - as specified in the custom-dependency rule. If it does, then whenever - the destination file (the one with the to-extension) is out-of-date + exists with the same name, but with the corresponding from-extension, + as specified in the custom-dependency rule. If it does, then whenever + the destination file (the one with the to-extension) is out-of-date with respect to the corresponding source file. - To make the new destination file, the Perl subroutine specified in the + To make the new destination file, the Perl subroutine specified in the rule is invoked, with an argument that is the base name of the files in - question. Simple cases just involve a subroutine invoking an external - program; this can be done by following the templates below, even by - those without knowledge of the Perl programming language. Of course, + question. Simple cases just involve a subroutine invoking an external + program; this can be done by following the templates below, even by + those without knowledge of the Perl programming language. Of course, experts could do something much more elaborate. - One other item in each custom-dependency rule labeled "must" above - specifies how the rule should be applied when the source file fails to + One other item in each custom-dependency rule labeled "must" above + specifies how the rule should be applied when the source file fails to exist. A simple and typical example of code in an initialization rcfile is @@ -2938,44 +2889,44 @@ LATEXMK(1L) LATEXMK(1L) system( "fig2dev -Leps \"$_[0].fig\" \"$_[0].eps\"" ); } - The first line adds a custom dependency that converts a file with - extension "fig", as created by the xfig program, to an encapsulated - postscript file, with extension "eps". The remaining lines define a - subroutine that carries out the conversion. If a rule for converting - "fig" to "eps" files already exists (e.g., from a previously read-in - initialization file), the latexmk will delete this rule before making - the new one. + The first line adds a custom dependency that converts a file with - Suppose latexmk is using this rule to convert a file "figure.fig" to - "figure.eps". Then it will invoke the fig2eps subroutine defined in - the above code with a single argument "figure", which is the basename - of each of the files (possibly with a path component). This argument - is referred to by Perl as $_[0]. In the example above, the subroutine - uses the Perl command system to invoke the program fig2dev. The double - quotes around the string are a Perl idiom that signify that each string - of the form of a variable name, $_[0] in this case, is to be substi- - tuted by its value. - If the return value of the subroutine is non-zero, then latexmk will - assume an error occurred during the execution of the subroutine. In - the above example, no explicit return value is given, and instead the - return value is the value returned by the last (and only) statement, - i.e., the invocation of system, which returns the value 0 on success. + 24 February 2016 40 - 5 February 2015 45 +LATEXMK(1L) LATEXMK(1L) + extension "fig", as created by the xfig program, to an encapsulated + postscript file, with extension "eps". The remaining lines define a + subroutine that carries out the conversion. If a rule for converting + "fig" to "eps" files already exists (e.g., from a previously read-in + initialization file), the latexmk will delete this rule before making + the new one. -LATEXMK(1L) LATEXMK(1L) + Suppose latexmk is using this rule to convert a file "figure.fig" to + "figure.eps". Then it will invoke the fig2eps subroutine defined in + the above code with a single argument "figure", which is the basename + of each of the files (possibly with a path component). This argument + is referred to by Perl as $_[0]. In the example above, the subroutine + uses the Perl command system to invoke the program fig2dev. The double + quotes around the string are a Perl idiom that signify that each string + of the form of a variable name, $_[0] in this case, is to be substi- + tuted by its value. + If the return value of the subroutine is non-zero, then latexmk will + assume an error occurred during the execution of the subroutine. In + the above example, no explicit return value is given, and instead the + return value is the value returned by the last (and only) statement, + i.e., the invocation of system, which returns the value 0 on success. - If you use pdflatex instead of latex, then you will probably prefer to - convert your graphics files to pdf format, in which case you would + If you use pdflatex instead of latex, then you will probably prefer to + convert your graphics files to pdf format, in which case you would replace the above code in an initialization file by add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' ); @@ -2983,55 +2934,42 @@ LATEXMK(1L) LATEXMK(1L) system( "fig2dev -Lpdf \"$_[0].fig\" \"$_[0].pdf\"" ); } - Note 1: In the command lines given in the system commands in the above - examples, double quotes have been inserted around the file names - (implemented by '\"' in the Perl language). They immunize the running - of the program against special characters in filenames. Very often - these quotes are not necessary, i.e., they can be omitted. But it is + Note 1: In the command lines given in the system commands in the above + examples, double quotes have been inserted around the file names + (implemented by '\"' in the Perl language). They immunize the running + of the program against special characters in filenames. Very often + these quotes are not necessary, i.e., they can be omitted. But it is normally safer to keep them in. Even though the rules for quoting vary - between operating systems, command shells and individual pieces of + between operating systems, command shells and individual pieces of software, the quotes in the above examples do not cause problems in the cases I have tested. - Note 2: One case in which the quotes are important is when the files - are in a subdirectory and your operating system is Microsoft Windows. - Then the separator character for directory components can be either a - forward slash '/' or Microsoft's more usual backward slash '\'. For- - ward slashes are generated by latexmk, to maintain its sanity from - software like MiKTeX that mixes both directory separators; but their + Note 2: One case in which the quotes are important is when the files + are in a subdirectory and your operating system is Microsoft Windows. + Then the separator character for directory components can be either a + forward slash '/' or Microsoft's more usual backward slash '\'. For- + ward slashes are generated by latexmk, to maintain its sanity from + software like MiKTeX that mixes both directory separators; but their correct use normally requires quoted filenames. (See a log file from a - run of MiKTeX (at least in v. 2.9) for an example of the use of both + run of MiKTeX (at least in v. 2.9) for an example of the use of both directory separators.) - If you have some general custom dependencies defined in the system or - user initialization file, you may find that for a particular project - they are undesirable. So you might want to delete the unneeded ones. + If you have some general custom dependencies defined in the system or + user initialization file, you may find that for a particular project + they are undesirable. So you might want to delete the unneeded ones. For example, you remove any "fig" to "eps" rule by the line remove_cus_dep( 'fig', 'eps' ); - If you have complicated sets of custom dependencies, you may want to - get a listing of the custom dependencies. This is done by using the + If you have complicated sets of custom dependencies, you may want to + get a listing of the custom dependencies. This is done by using the line show_cus_dep(); - in an initialization file. - - Another example of a custom dependency overcomes a limitation of - latexmk concerning index files. The only index-file conversion built- - in to latexmk is from an ".idx" file written on one run of latex/pdfla- - tex to an ".ind" file to be read in on a subsequent run. But with the - index.sty package you can create extra indexes with extensions that you - configure. Latexmk does not know how to deduce the extensions from the - information it has. But you can easily write a custom dependency. For - example if your latex file uses the command "\newindex{spe- - cial}{ndx}{nnd}{Special index}" you will need to convert files with the - extension .ndx to .nnd. The following lines in an initialization RC - - 5 February 2015 46 + 24 February 2016 41 @@ -3040,6 +2978,18 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + in an initialization file. + + Another example of a custom dependency overcomes a limitation of + latexmk concerning index files. The only index-file conversion built- + in to latexmk is from an ".idx" file written on one run of latex/pdfla- + tex to an ".ind" file to be read in on a subsequent run. But with the + index.sty package you can create extra indexes with extensions that you + configure. Latexmk does not know how to deduce the extensions from the + information it has. But you can easily write a custom dependency. For + example if your latex file uses the command "\newindex{spe- + cial}{ndx}{nnd}{Special index}" you will need to convert files with the + extension .ndx to .nnd. The following lines in an initialization RC file will cause this to happen: add_cus_dep('ndx', 'nnd', 0, 'makendx2nnd'); @@ -3047,37 +2997,38 @@ LATEXMK(1L) LATEXMK(1L) system( "makeindex -o \"$_[0].nnd\" \"$_[0].ndx\"" ); } - (You will need to modify this code if you use filenames with spaces in + (You will need to modify this code if you use filenames with spaces in them, to provide correct quoting of the filenames.) - Those of you with experience with Makefiles, will undoubtedly be con- + Those of you with experience with Makefiles, will undoubtedly be con- cerned that the .ndx file is written during a run of latex/pdflatex and - is always later than the .nnd last read in. Thus the .nnd appears to - be perpetually out-of-date. This situation, of circular dependencies, + is always later than the .nnd last read in. Thus the .nnd appears to + be perpetually out-of-date. This situation, of circular dependencies, is endemic to latex, and latexmk in its current version works correctly - with circular dependencies. It examines the contents of the files (by - use of an md5 checksum), and only does a remake when the file contents + with circular dependencies. It examines the contents of the files (by + use of an md5 checksum), and only does a remake when the file contents have actually changed. - Of course if you choose to write random data to the .nnd (or and .aux - file, etc) that changes on each new run, then you will have a problem. - For real experts: See the %hash_cal_ignore_pattern if you have to deal + Of course if you choose to write random data to the .nnd (or and .aux + file, etc) that changes on each new run, then you will have a problem. + For real experts: See the %hash_cal_ignore_pattern if you have to deal with such problems. Glossaries can be dealt with similarly. + OLD METHOD OF DEFINING CUSTOM DEPENDENCIES - In previous versions of latexmk, the only method of defining custom - dependencies was to directly manipulate the table of custom dependen- + In previous versions of latexmk, the only method of defining custom + dependencies was to directly manipulate the table of custom dependen- cies. This is contained in the @cus_dep_list array. It is an array of - strings, and each string in the array has four items in it, each sepa- - rated by a space, the from-extension, the to-extension, the "must" - item, and the name of the subroutine for the custom dependency. These + strings, and each string in the array has four items in it, each sepa- + rated by a space, the from-extension, the to-extension, the "must" + item, and the name of the subroutine for the custom dependency. These were all defined above. An example of the old method of defining custom dependencies is as fol- - lows. It is the code in an RC file to ensure automatic conversion of + lows. It is the code in an RC file to ensure automatic conversion of .fig files to .eps files: push @cus_dep_list, "fig eps 0 fig2eps"; @@ -3085,19 +3036,92 @@ OLD METHOD OF DEFINING CUSTOM DEPENDENCIES system( "fig2dev -Lps \"$_[0].fig\" \"$_[0].eps\"" ); } - This method still works, and is equivalent to the earlier code using - the add_cus_dep subroutine, except that it doesn't delete any previous - custom-dependency for the same conversion. So the new method is + This method still works, and is equivalent to the earlier code using + the add_cus_dep subroutine, except that it doesn't delete any previous + custom-dependency for the same conversion. So the new method is preferable. + 24 February 2016 42 + + + + + +LATEXMK(1L) LATEXMK(1L) + + +ADVANCED CONFIGURATION: Some extra resources and advanced tricks + For most purposes, simple configuration for latexmk along the lines of + the examples given is sufficient. But sometimes you need something + harder. In this section, I indicate some extra possibilities. Gener- + ally to use these, you need to be fluent in the Perl language, since + this is what is used in the rc files. + + See also the section DEALING WITH ERRORS, PROBLEMS, ETC. See also the + examples in the directory example_rcfiles in the latexmk distributions. + Even if none of the examples apply to your case, they may give ideas + + + Variables and subroutines for processing a rule + A step in the processing is called a rule. One possibility to implement + the processing of a rule is by a Perl subroutine. This is always the + case for custom dependencies. Also, for any other rule, you can use a + subroutine by prefixing the command specification by the word "inter- + nal" -- see the section FORMAT OF COMMAND SPECIFICATIONS. + + When you use a subroutine for processing a rule, all the possibilities + of Perl programming are available, of course. In addition, some of + latexmk's internal variables and subroutines are available. The ones + listed below are intended to be available to (advanced) users, and + their specifications will generally have stability under upgrades. Gen- + erally, the variables should be treated as read-only: Changing their + values can have bad consequences, since it is liable to mess up the + consistency of what latexmk is doing. + + + $rule This variable has the name of the rule, as known to latexmk. + Note that the exact contents of this variable for a given rule + may be dependent on the version of latexmk + + + $$Psource + This gives the name of the primary source file. Note the double + dollar signs. + + + $$Pdest + This gives the name of the main output file if any. Note the + double dollar signs. + + + rdb_ensure_file( $rule, file ) + This a subroutine that ensures that the given file is among the + source files for the specified rule. It is typically used when, + during the processing of a rule, it is known that a particular + extra file is among the dependencies that latexmk should know, + but its default methods don't find the dependency. Almost always + the first argument is the name of the rule currently being pro- + cessed, so it is then appropriate to specify it by $rule. + + For examples of its use, see some of the files in the directory + example_rcfiles of latexmk's distribution. Currently the cases + that use this subroutine are exceltex_latexmkrc and texinfo- + latexmkrc. These illustrate typical cases where latexmk's nor- + mal processing fails to detect certain extra source files. + + rdb_remove_files( $rule, file, ... ) + This subroutine removes one or more files from the dependency + list for the given rule. - 5 February 2015 47 + + + 24 February 2016 43 @@ -3106,40 +3130,40 @@ OLD METHOD OF DEFINING CUSTOM DEPENDENCIES LATEXMK(1L) LATEXMK(1L) -USING latexmk WITH make - This section is targeted only at advanced users who use the make pro- + Advanced configuration: Using latexmk with make + This section is targeted only at advanced users who use the make pro- gram for complex projects, as for software development, with the depen- dencies specified by a Makefile. - Now the basic task of latexmk is to run the appropriate programs to - make a viewable version of a LaTeX document. However, the usual make - program is not suited to this purpose for at least two reasons. First + Now the basic task of latexmk is to run the appropriate programs to + make a viewable version of a LaTeX document. However, the usual make + program is not suited to this purpose for at least two reasons. First is that the use of LaTeX involves circular dependencies (e.g., via .aux files), and these cannot be handled by the standard make program. Sec- - ond is that in a large document the set of source files can change - quite frequently, particularly with included graphics files; in this - situation keeping a Makefile manually updated is inappropriate and - error-prone, especially when the dependencies can be determined auto- + ond is that in a large document the set of source files can change + quite frequently, particularly with included graphics files; in this + situation keeping a Makefile manually updated is inappropriate and + error-prone, especially when the dependencies can be determined auto- matically. Latexmk solves both of these problems robustly. - Thus for many standard LaTeX documents latexmk can be used by itself - without the make program. In a complex project it simply needs to be - suitably configured. A standard configuration would be to define cus- - tom dependencies to make graphics files from their source files (e.g., - as created by the xfig program). Custom dependencies are latexmk's + Thus for many standard LaTeX documents latexmk can be used by itself + without the make program. In a complex project it simply needs to be + suitably configured. A standard configuration would be to define cus- + tom dependencies to make graphics files from their source files (e.g., + as created by the xfig program). Custom dependencies are latexmk's equivalent of pattern rules in Makefiles. - Nevertheless there are projects for which a Makefile is appropriate, + Nevertheless there are projects for which a Makefile is appropriate, and it is useful to know how to use latexmk from a Makefile. A typical - example would be to generate documentation for a software project. - Potentially the interaction with the rest of the rules in the Makefile + example would be to generate documentation for a software project. + Potentially the interaction with the rest of the rules in the Makefile could be quite complicated, for example if some of the source files for a LaTeX document are generated by the project's software. In this section, I give a couple of examples of how latexmk can be use- - fully invoked from a Makefile. The examples use specific features of - current versions of GNU make, which is the default on both linux and - OS-X systems. They may need modifications for other versions of make. + fully invoked from a Makefile. The examples use specific features of + current versions of GNU make, which is the default on both linux and + OS-X systems. They may need modifications for other versions of make. The simplest method is simply to delegate all the relevant tasks to latexmk, as is suitable for a straightforward LaTeX document. For this @@ -3160,10 +3184,20 @@ USING latexmk WITH make The above example has a pattern rule for making a .pdf file from a .tex file, and it is defined to use latexmk in the obvious way. There is a + conventional default target named "all", with a prerequisite of + try.pdf. So when make is invoked, by default it makes try.pdf. The + only complication is that there may be many source files beyond + try.tex, but these aren't specified in the Makefile, so changes in them + will not by themselves cause latexmk to be invoked. Instead, the pat- + tern rule is equipped with a "phony" prerequisite FORCE_MAKE; this has + the effect of causing the rule to be always out-of-date, so that + latexmk is always run. It is latexmk that decides whether any action + is needed, e.g., a rerun of pdflatex. Effectively the Makefile dele- + gates all decisions to latexmk, while make has no knowledge of the list - 5 February 2015 48 + 24 February 2016 44 @@ -3172,16 +3206,6 @@ USING latexmk WITH make LATEXMK(1L) LATEXMK(1L) - conventional default target named "all", with a prerequisite of - try.pdf. So when make is invoked, by default it makes try.pdf. The - only complication is that there may be many source files beyond - try.tex, but these aren't specified in the Makefile, so changes in them - will not by themselves cause latexmk to be invoked. Instead, the pat- - tern rule is equipped with a "phony" prerequisite FORCE_MAKE; this has - the effect of causing the rule to be always out-of-date, so that - latexmk is always run. It is latexmk that decides whether any action - is needed, e.g., a rerun of pdflatex. Effectively the Makefile dele- - gates all decisions to latexmk, while make has no knowledge of the list of source files except for primary LaTeX file for the document. If there are, for example, graphics files to be made, these must be made by custom dependencies configured in latexmk. @@ -3207,49 +3231,37 @@ LATEXMK(1L) LATEXMK(1L) %.pdf : %.fig fig2dev -Lpdf $< $@ - (Again, the lines containing the commands for the rules should be + (Again, the lines containing the commands for the rules should be started with tabs.) This example was inspired by how GNU automake han- dles automatic dependency tracking of C source files. - After each run of latexmk, dependency information is put in a file in - the .deps subdirectory. The Makefile causes these dependency files to + After each run of latexmk, dependency information is put in a file in + the .deps subdirectory. The Makefile causes these dependency files to be read by make, which now has the full dependency information for each - target .pdf file. To make things less trivial it is specificed that - two files document1.pdf and document2.pdf are the targets. The depen- + target .pdf file. To make things less trivial it is specificed that + two files document1.pdf and document2.pdf are the targets. The depen- dency files are .deps/document1.pdfP and .deps/document2.pdfP. - There is now no need for the phony prerequisite for the rule to make + There is now no need for the phony prerequisite for the rule to make .pdf files from .tex files. But I have added a rule to make .pdf files - from .fig files produced by the xfig program; these are commonly used - for graphics insertions in LaTeX documents. Latexmk is arranged to - output a dependency file after each run. It is given the -recorder + from .fig files produced by the xfig program; these are commonly used + for graphics insertions in LaTeX documents. Latexmk is arranged to + output a dependency file after each run. It is given the -recorder option, which improves its detection of files generated during a run of - pdflatex; such files should not be in the dependency list. The -e - options are used to turn off all custom dependencies, and to document - - - - 5 February 2015 49 - - - - - -LATEXMK(1L) LATEXMK(1L) - - - this. Instead the -use-make is used to delegate the making of missing + pdflatex; such files should not be in the dependency list. The -e + options are used to turn off all custom dependencies, and to document + this. Instead the -use-make is used to delegate the making of missing files to make itself. - Suppose in the LaTeX file there is a command \includegraphics{graph}, - and an xfig file "graph.fig" exists. On a first run, pdflatex reports - a missing file, named "graph". Latexmk succeeds in making "graph.pdf" + Suppose in the LaTeX file there is a command \includegraphics{graph}, + and an xfig file "graph.fig" exists. On a first run, pdflatex reports + a missing file, named "graph". Latexmk succeeds in making "graph.pdf" by calling "make graph.pdf", and after completion of its work, it lists "fig.pdf" among the dependents of the file latexmk is making. Then let - "fig.fig" be updated, and then let make be run. Make first remakes + "fig.fig" be updated, and then let make be run. Make first remakes "fig.pdf", and only then reruns latexmk. - Thus we now have a method by which all the subsidiary processing is + Thus we now have a method by which all the subsidiary processing is delegated to make. @@ -3258,44 +3270,11 @@ SEE ALSO BUGS Sometimes a viewer (gv) tries to read an updated .ps or .pdf file after - its creation is started but before the file is complete. Work around: - manually refresh (or reopen) display. Or use one of the other preview- - ers and update methods. + its creation is started but before the file is complete. Work around: - (The following isn't really a bug, but concerns features of preview- - ers.) Preview continuous mode only works perfectly with certain pre- - viewers: Xdvi on UNIX/LINUX works for dvi files. Gv on UNIX/LINUX - works for both postscript and pdf. Ghostview on UNIX/LINUX needs a - manual update (reopen); it views postscript and pdf. Gsview under MS- - Windows works for both postscript and pdf, but only reads the updated - file when its screen is refreshed. Acroread under UNIX/LINUX views - pdf, but the file needs to be closed and reopened to view an updated - version. Under MS-Windows, acroread locks its input file and so the - pdf file cannot be updated. (Remedy: configure latexmk to use suma- - trapdf instead.) -THANKS TO - Authors of previous versions. Many users with their feedback, and - especially David Coppit (username david at node coppit.org) who made - many useful suggestions that contributed to version 3, and Herbert - Schulz. (Please note that the e-mail addresses are not written in - their standard form to avoid being harvested by worms and viruses.) -AUTHOR - Current version, by John Collins (username jcc8 at node psu.edu). - (Version 4.43a). - - Released version can be obtained from CTAN: <http://www.ctan.org/tex- - archive/support/latexmk/>, and from the author's website - <http://www.phys.psu.edu/~collins/software/latexmk/>. - Modifications and enhancements by Evan McLean (Version 2.0) - Original script called "go" by David J. Musliner (RCS Version 3.2) - - - - - - 5 February 2015 50 + 24 February 2016 45 @@ -3304,10 +3283,37 @@ AUTHOR LATEXMK(1L) LATEXMK(1L) + manually refresh (or reopen) display. Or use one of the other preview- + ers and update methods. + (The following isn't really a bug, but concerns features of preview- + ers.) Preview continuous mode only works perfectly with certain pre- + viewers: Xdvi on UNIX/LINUX works for dvi files. Gv on UNIX/LINUX + works for both postscript and pdf. Ghostview on UNIX/LINUX needs a + manual update (reopen); it views postscript and pdf. Gsview under MS- + Windows works for both postscript and pdf, but only reads the updated + file when its screen is refreshed. Acroread under UNIX/LINUX views + pdf, but the file needs to be closed and reopened to view an updated + version. Under MS-Windows, acroread locks its input file and so the + pdf file cannot be updated. (Remedy: configure latexmk to use suma- + trapdf instead.) +THANKS TO + Authors of previous versions. Many users with their feedback, and + especially David Coppit (username david at node coppit.org) who made + many useful suggestions that contributed to version 3, and Herbert + Schulz. (Please note that the e-mail addresses are not written in + their standard form to avoid being harvested by worms and viruses.) +AUTHOR + Current version, by John Collins (username jcc8 at node psu.edu). + (Version 4.44). + Released version can be obtained from CTAN: <http://www.ctan.org/tex- + archive/support/latexmk/>, and from the author's website + <http://www.phys.psu.edu/~collins/software/latexmk/>. + Modifications and enhancements by Evan McLean (Version 2.0) + Original script called "go" by David J. Musliner (RCS Version 3.2) @@ -3345,22 +3351,6 @@ LATEXMK(1L) LATEXMK(1L) - - - - - - - - - - - - - - - - - 5 February 2015 51 + 24 February 2016 46 |