From 2dd8fea11f36f8ba29c512d4e0a6d16b8e82cfdb Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 7 Aug 2018 22:07:43 +0000 Subject: latexmk (7aug18) git-svn-id: svn://tug.org/texlive/trunk@48369 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/support/latexmk/CHANGES | 24 + Master/texmf-dist/doc/support/latexmk/INSTALL | 10 +- Master/texmf-dist/doc/support/latexmk/README | 4 +- .../example_rcfiles/tikz-externalized-latexmkrc | 75 + Master/texmf-dist/doc/support/latexmk/latexmk.pdf | Bin 191173 -> 195352 bytes Master/texmf-dist/doc/support/latexmk/latexmk.txt | 3006 ++++++++++---------- 6 files changed, 1644 insertions(+), 1475 deletions(-) create mode 100644 Master/texmf-dist/doc/support/latexmk/example_rcfiles/tikz-externalized-latexmkrc (limited to 'Master/texmf-dist/doc/support') diff --git a/Master/texmf-dist/doc/support/latexmk/CHANGES b/Master/texmf-dist/doc/support/latexmk/CHANGES index 775e879c8fb..5910c8dc950 100644 --- a/Master/texmf-dist/doc/support/latexmk/CHANGES +++ b/Master/texmf-dist/doc/support/latexmk/CHANGES @@ -621,3 +621,27 @@ From v. 4.55a to 4.56 Add use of environment variable LATEXMKRCSYS to specify system rc file. +From v. 4.56 to 4.57 + Correct problem that in calculation of md5 checksum, an error + sometimes occurs about malformed utf8 characters. This can happen + if the environment variable PERL_UNICODE is set. + Add configuration variable $bibtex_fudge to allow to choose + whether to use the fudge that made bibtex run correctly when + an output directory (or aux directory) is specified. (A + planned future version of bibtex in TeXLive will not need + the fudge.) + +From v. 4.57 to 4.59 + Deal with double quote ('"') characters in files on command line to + correspond to behavior of tex programs. Remove balanced pairs, + and give fatal error for unbalanced double quotes. (Note MiKTeX's + tex programs simply remove unbalanced quotes.) In all cases, the + '"' character is not allowed in a filename read by tex and + friends. + Give fatal error when name of tex file on command line is either not + allowed by tex and friends are gives problematic behavior. + Use TEXINPUTS as search path for source files for custom + dependency. + Only give warning about differing expected and output filenames when + the extensions differ. All other cases gave only false positives. + Do better to ensure xelatex gets its -no-pdf option. diff --git a/Master/texmf-dist/doc/support/latexmk/INSTALL b/Master/texmf-dist/doc/support/latexmk/INSTALL index ede38726136..4b70285165d 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.56, 25 May 2018) + (Version 4.59, 7 August 2018) John Collins Physics Department @@ -76,7 +76,7 @@ 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 +installation of Perl should enable latexmk to work. Installing on UNIX/LINUX/OS-X @@ -219,7 +219,11 @@ 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. +with the manual installation explained below. + +Similarly if you have MiKTeX, you can install latexmk by using +MiKTeX's package manager. But to allow latexmk to work, you will also +need to install a distribution of Perl if you haven't done so already. 1. Make sure you have working installations of Perl and TeX/LaTeX, complete with viewers for dvi and/or postscript files. You will diff --git a/Master/texmf-dist/doc/support/latexmk/README b/Master/texmf-dist/doc/support/latexmk/README index 119b64d0f89..55bd8fa5c03 100644 --- a/Master/texmf-dist/doc/support/latexmk/README +++ b/Master/texmf-dist/doc/support/latexmk/README @@ -1,4 +1,4 @@ -Latexmk, version 4.56, 25 May 2018 +Latexmk, version 4.59, 7 Aug 2018 ---------------------------------- Latexmk completely automates the process of generating a LaTeX @@ -91,7 +91,7 @@ NOTES:- John Collins ---------------------------- "latexmk -h" ---------------------------- -Latexmk 4.56: Automatic LaTeX document generation routine +Latexmk 4.59: Automatic LaTeX document generation routine Usage: latexmk [latexmk_options] [filename ...] diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/tikz-externalized-latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/tikz-externalized-latexmkrc new file mode 100644 index 00000000000..22ed6f7d388 --- /dev/null +++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/tikz-externalized-latexmkrc @@ -0,0 +1,75 @@ +# This shows how to deal with tikz when it is used in its externalized mode. +# +# Here is an example of a document that uses externalization. +# Externalization results in a .pdf file for each tikzpicture +# environment. +# +# \documentclass{article} +# \usepackage{tikz,pgfplots} +# \usetikzlibrary{external} +# \tikzexternalize[mode=list and make] +# +# \begin{document} +# \begin{tikzpicture} +# \begin{axis} +# \addplot coordinates {(1,1) (2,2) (3,5)}; +# \end{axis} +# \end{tikzpicture}% +# \end{document} + + +$clean_ext .= ' %R.figlist %R-figure* %R.makefile fls.tmp'; + +$latex = 'internal tikzlatex latex %B %O %S'; +$pdflatex = 'internal tikzlatex pdflatex %B %O %S'; +$lualatex = 'internal tikzlatex lualatex %B %O %S'; +$xelatex = 'internal tikzlatex xelatex %B %O %S'; + +$hash_calc_ignore_pattern{'pdf'} = '^(/CreationDate|/ModDate|/ID)'; +$hash_calc_ignore_pattern{'ps'} = '^%%CreationDate'; + +sub tikzlatex { + my ($engine, $base, @args) = @_; + my $ret = 0; + print "Tikzlatex: ===Running '$engine @args'...\n"; + $ret = system( $engine, @args ); + print "Tikzlatex: Fixing .fls file ...\n"; + system "echo INPUT \"$aux_dir1$base.figlist\" > \"$aux_dir1$base.fls.tmp\""; + system "echo INPUT \"$aux_dir1$base.makefile\" >> \"$aux_dir1$base.fls.tmp\""; + system "cat \"$aux_dir1$base.fls\" >> \"$aux_dir1$base.fls.tmp\""; + rename "$aux_dir1$base.fls.tmp", "$aux_dir1$base.fls"; + if ($ret) { return $ret; } + if ( -e "$aux_dir1$base.makefile" ) { + if ($engine eq 'xelatex') { + print "Tikzlatex: ---Correcting '$aux_dir1$base.makefile' made under xelatex\n"; + system( 'perl', '-i', '-p', '-e', 's/^\^\^I/\t/', "$aux_dir1$base.makefile" ); + } + elsif ($engine eq 'latex') { + print "Tikzlatex: ---Correcting '$aux_dir1$base.makefile' made under latex\n"; + system( 'perl', '-i', '-p', '-e', 's/\.epsi/\.ps/', "$aux_dir1$base.makefile" ); + } + print "Tikzlatex: ---Running 'make -f $aux_dir1$base.makefile' ...\n"; + if ($aux_dir) { + # latexmk has set $ENV{TEXINPUTS} in this case. + my $SAVETEXINPUTS = $ENV{TEXINPUTS}; + $ENV{TEXINPUTS} = good_cwd().$search_path_separator.$ENV{TEXINPUTS}; + pushd( $aux_dir ); + $ret = system "make", "-j", "5", "-f", "$base.makefile"; + &popd; + $ENV{TEXINPUTS} = $SAVETEXINPUTS; + } + else { + $ret = system "make", "-j", "5", "-f", "$base.makefile"; + } + if ($ret) { + print "Tikzlatex: !!!!!!!!!!!!!! Error from make !!!!!!!!! \n", + " The log files for making the figures '$aux_dir1$base-figure*.log'\n", + " may have information\n"; + } + } + else { + print "Tikzlatex: No '$aux_dir1$base.makefile', so I won't run make.\n"; + } + return $ret; +} + diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.pdf b/Master/texmf-dist/doc/support/latexmk/latexmk.pdf index 9d22eb8a023..ef944e90fc0 100644 Binary files a/Master/texmf-dist/doc/support/latexmk/latexmk.pdf and b/Master/texmf-dist/doc/support/latexmk/latexmk.pdf differ diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.txt b/Master/texmf-dist/doc/support/latexmk/latexmk.txt index 5bf1c69056c..edf5b6b4dd8 100644 --- a/Master/texmf-dist/doc/support/latexmk/latexmk.txt +++ b/Master/texmf-dist/doc/support/latexmk/latexmk.txt @@ -61,7 +61,7 @@ DESCRIPTION - 25 May 2018 1 + 7 August 2018 1 @@ -127,7 +127,7 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE - 25 May 2018 2 + 7 August 2018 2 @@ -172,313 +172,328 @@ LATEXMK(1) General Commands Manual LATEXMK(1) then latexmk will operate on the file "foo.tex". + There are certain restrictions on what characters can be in a + filename; certain characters are either prohibited or problem- + atic for the latex etc programs. These characters are: "$", + "%", "\", "~", the double quote character, and the control char- + acters null, tab, form feed, carriage return, line feed, and + delete. In addition "&" is prohibited when it is the first + character of a filename. - -auxdir=FOO or -aux-directory=FOO - Sets the directory for auxiliary output files of (pdf)latex - (.aux, .log etc). This achieves its effect by the -aux-direc- - tory option of (pdf)latex, which currently is only implemented - on the MiKTeX version of (pdf)latex. + Latexmk gives a fatal error when it detects any of the above + characters in the TeX filename(s) specified on the command line. + However before testing for illegal characters, latexmk removes + matching pairs of double quotes from a filename. This matches + the behavior of latex etc, and deals with problems that occa- + sionally result from filenames that have been incorrectly quoted + on the command line. In addition, under Microsoft Windows, the + forward slash character "\" is a directory separator, so latexmk + replaces it by a backward slash "/", which is also a legal + directory separator in Windows, and is accepted by latex etc. - See also the -outdir/-output-directory options, and the - $aux_dir, $out_dir, and $search_path_separator configuration - variables of latexmk. In particular, see the documentation of - $out_dir for some complications on what directory names are - suitable. - If you also use the -cd option, and the specified auxiliary out- - put directory is a relative path, then the path is interpreted - relative to the document directory. + 7 August 2018 3 - 25 May 2018 3 +LATEXMK(1) General Commands Manual LATEXMK(1) + -auxdir=FOO or -aux-directory=FOO + Sets the directory for auxiliary output files of (pdf)latex + (.aux, .log etc). This achieves its effect by the -aux-direc- + tory option of (pdf)latex, which currently is only implemented + on the MiKTeX version of (pdf)latex. + See also the -outdir/-output-directory options, and the + $aux_dir, $out_dir, and $search_path_separator configuration + variables of latexmk. In particular, see the documentation of + $out_dir for some complications on what directory names are + suitable. -LATEXMK(1) General Commands Manual LATEXMK(1) + If you also use the -cd option, and the specified auxiliary out- + put directory is a relative path, then the path is interpreted + relative to the document directory. -bibtex When the source file uses bbl files for bibliography, run bibtex or biber as needed to regenerate the bbl files. - This property can also be configured by setting the $bibtex_use + This property can also be configured by setting the $bibtex_use variable to 2 in a configuration file. -bibtex- - Never run bibtex or biber. Also, always treat .bbl files as + Never run bibtex or biber. Also, always treat .bbl files as precious, i.e., do not delete them in a cleanup operation. - A common use for this option is when a document comes from an - external source, complete with its bbl file(s), and the user - does not have the corresponding bib files available. In this - situation use of the -bibtex- option will prevent latexmk from + A common use for this option is when a document comes from an + external source, complete with its bbl file(s), and the user + does not have the corresponding bib files available. In this + situation use of the -bibtex- option will prevent latexmk from trying to run bibtex or biber, which would result in overwriting of the bbl files. - This property can also be configured by setting the $bibtex_use + This property can also be configured by setting the $bibtex_use variable to 0 in a configuration file. -bibtex-cond - When the source file uses bbl file(s) for the bibliography, run - bibtex or biber as needed to regenerate the bbl files, but only - if the relevant bib file(s) exist. Thus when the bib files are - not available, bibtex or biber is not run, thereby avoiding - overwriting of the bbl file(s). Also, always treat .bbl files + When the source file uses bbl file(s) for the bibliography, run + bibtex or biber as needed to regenerate the bbl files, but only + if the relevant bib file(s) exist. Thus when the bib files are + not available, bibtex or biber is not run, thereby avoiding + overwriting of the bbl file(s). Also, always treat .bbl files as precious, i.e., do not delete them in a cleanup operation. - This is the default setting. It can also be configured by set- + This is the default setting. It can also be configured by set- ting the $bibtex_use variable to 1 in a configuration file. - The reason for using this setting is that sometimes a .bbl file + The reason for using this setting is that sometimes a .bbl file is available containing the bibliography for a document, but the - .bib file is not available. An example would be for a scien- - tific journal where authors submit .tex and .bbl files, but not - the original .bib file. In that case, running bibtex or biber - would not work, and the .bbl file should be treated as a user - source file, and not as a file that can be regenerated on - demand. + .bib file is not available. An example would be for a - (Note that it is possible for latexmk to decide that the bib - file does not exist, even though the bib file does exist and - bibtex or biber finds it. The problem is that the bib file may - not be in the current directory but in some search path; the - places latexmk and bibtex or biber cause to be searched need not - be identical. On modern installations of TeX and related pro- - grams this problem should not arise, since latexmk uses the - kpsewhich program to do the search, and kpsewhich should use the - same search path as bibtex and biber. If this problem arises, - use the -bibtex option when invoking latexmk.) + 7 August 2018 4 - 25 May 2018 4 +LATEXMK(1) General Commands Manual LATEXMK(1) -LATEXMK(1) General Commands Manual LATEXMK(1) + scientific journal where authors submit .tex and .bbl files, but + not the original .bib file. In that case, running bibtex or + biber would not work, and the .bbl file should be treated as a + user source file, and not as a file that can be regenerated on + demand. + + (Note that it is possible for latexmk to decide that the bib + file does not exist, even though the bib file does exist and + bibtex or biber finds it. The problem is that the bib file may + not be in the current directory but in some search path; the + places latexmk and bibtex or biber cause to be searched need not + be identical. On modern installations of TeX and related pro- + grams this problem should not arise, since latexmk uses the + kpsewhich program to do the search, and kpsewhich should use the + same search path as bibtex and biber. If this problem arises, + use the -bibtex option when invoking latexmk.) -bibtex-cond1 - The same as -bibtex-cond1 except that .bbl files are only + The same as -bibtex-cond1 except that .bbl files are only treated as precious if one or more bibfiles fails to exist. - Thus if all the bib files exist, bibtex or biber is run to gen- + Thus if all the bib files exist, bibtex or biber is run to gen- erate .bbl files as needed, and then it is appropriate to delete the bbl files in a cleanup operation since they can be re-gener- ated. - This property can also be configured by setting the $bibtex_use + This property can also be configured by setting the $bibtex_use variable to 1.5 in a configuration file. -bm - A banner message to print diagonally across each page when con- - verting the dvi file to postscript. The message must be a sin- + 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. - Note that if the -bm option is specified, the -ps option is + Note that if the -bm option is specified, the -ps option is assumed. -bi - How dark to print the banner message. A decimal number between + How dark to print the banner message. A decimal number between 0 and 1. 0 is black and 1 is white. The default is 0.95, which is OK unless your toner cartridge is getting low. -bs - 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 + A decimal number that specifies how large the banner message + will be printed. Experimentation is necessary to get the right + scale for your message, as a rule of thumb the scale should be + about equal to 1100 divided by the number of characters in the message. The default is 220.0 which is just right for 5 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, - files specified by the $clean_ext configuration variable are - removed. - This cleanup is instead of a regular make. See the -gg option - if you want to do a cleanup then a make. + 7 August 2018 5 - 25 May 2018 5 +LATEXMK(1) General Commands Manual LATEXMK(1) + -commands + List the commands used by latexmk for processing files, and then + exit. -LATEXMK(1) General Commands Manual LATEXMK(1) + -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. + This cleanup is instead of a regular make. See the -gg option + if you want to do a cleanup then a make. - Treatment of .bbl files: If $bibtex_use is set to 0 or 1, bbl - files are always treated as non-regeneratable. If $bibtex_use + Treatment of .bbl files: If $bibtex_use is set to 0 or 1, bbl + files are always treated as non-regeneratable. If $bibtex_use is set to 1.5, bbl files are counted as non-regeneratable condi- - tionally: If the bib file exists, then bbl files are regenerat- - able, and are deleted in a clean up. But if $bibtex_use is 1.5 - and a bib file doesn't exist, then the bbl files are treated as + tionally: If the bib file exists, then bbl files are regenerat- + able, and are deleted in a clean up. But if $bibtex_use is 1.5 + and a bib file doesn't exist, then the bbl files are treated as non-regeneratable and hence are not deleted. - In contrast, if $bibtex_use is set to 2, bbl files are always + In contrast, if $bibtex_use is set to 2, bbl files are always treated as regeneratable, and are deleted in a cleanup. - Treatment of files generated by custom dependencies:If - $cleanup_includes_cusdep_generated is nonzero, regeneratable - files are considered as including those generated by custom - dependencies and are also deleted. Otherwise these files are + Treatment of files generated by custom dependencies:If + $cleanup_includes_cusdep_generated is nonzero, regeneratable + files are considered as including those generated by custom + dependencies and are also deleted. Otherwise these files are not deleted. -C Clean up (remove) all regeneratable files generated by latex and - bibtex or biber. This is the same as the -c option with the - addition of dvi, postscript and pdf files, and those specified + bibtex or biber. This is the same as the -c option with the + addition of dvi, postscript and pdf files, and those specified in the $clean_full_ext configuration variable. - This cleanup is instead of a regular make. See the -gg option + This cleanup is instead of a regular make. See the -gg option if you want to do a cleanup than a make. - See the -c option for the specification of whether or not .bbl + See the -c option for the specification of whether or not .bbl files are treated as non-regeneratable or regeneratable. - If $cleanup_includes_cusdep_generated is nonzero, regeneratable - files are considered as including those generated by custom - dependencies and are also deleted. Otherwise these files are + If $cleanup_includes_cusdep_generated is nonzero, regeneratable + files are considered as including those generated by custom + dependencies and are also deleted. Otherwise these files are not deleted. - -CA (Obsolete). Now equivalent to the -C option. See that option + -CA (Obsolete). Now equivalent to the -C option. See that option for details. - -cd Change to the directory containing the main source file before - processing it. Then all the generated files (aux, log, dvi, - pdf, etc) will be relative to the source file. - - This option is particularly useful when latexmk is invoked from - a GUI configured to invoke latexmk with a full pathname for the - source file. - -cd- Do NOT change to the directory containing the main source file - before processing it. Then all the generated files (aux, log, - dvi, pdf, etc) will be relative to the current directory rather - than the source file. + 7 August 2018 6 - This is the default behavior and corresponds to the behavior of - 25 May 2018 6 +LATEXMK(1) General Commands Manual LATEXMK(1) + -cd Change to the directory containing the main source file before + processing it. Then all the generated files (.aux, .log, .dvi, + .pdf, etc) will be relative to the source file. + This option is particularly useful when latexmk is invoked from + a GUI configured to invoke latexmk with a full pathname for the + source file. -LATEXMK(1) General Commands Manual LATEXMK(1) + -cd- Do NOT change to the directory containing the main source file + before processing it. Then all the generated files (.aux, .log, + .dvi, .pdf, etc) will be relative to the current directory + rather than the source file. - the latex and pdflatex programs. However, it is not desirable - behavior when latexmk is invoked by a GUI configured to invoke - latexmk with a full pathname for the source file. See the -cd + 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 + latexmk with a full pathname for the source file. See the -cd option. - -CF Remove the file containing the database of source file informa- + -CF Remove the file containing the database of source file informa- tion, before doing the other actions requested. - -d Set draft mode. This prints the banner message "DRAFT" across - your page when converting the dvi file to postscript. Size and + -d Set draft mode. This prints the banner message "DRAFT" across + your page when converting the dvi file to postscript. Size and intensity can be modified with the -bs and -bi options. The -bm - option will override this option as this is really just a short + option will override this option as this is really just a short way of specifying: latexmk -bm DRAFT - Note that if the -d option is specified, the -ps option is + Note that if the -d option is specified, the -ps option is assumed. -deps Show a list of dependent files after processing. This is in the - form of a dependency list of the form used by the make program, + form of a dependency list of the form used by the make program, and it is therefore suitable for use in a Makefile. It gives an overall view of the files without listing intermediate files, as well as latexmk can determine them. - By default the list of dependent files is sent to stdout (i.e., - normally to the screen unless you've redirected latexmk's out- + By default the list of dependent files is sent to stdout (i.e., + normally to the screen unless you've redirected latexmk's out- put). But you can set the filename where the list is sent by the -deps-out= option. - See the section "USING latexmk WITH make" for an example of how + See the section "USING latexmk WITH make" for an example of how to use a dependency list with make. - Users familiar with GNU automake and gcc will find that the - -deps option is very similar in its purpose and results to the - -M option to gcc. (In fact, latexmk also has options -M, -MF, - and -MP options that behave like those of gcc.) + Users familiar with GNU automake and gcc will find that the + -deps option is very similar in its purpose and results to the + -M option to gcc. (In fact, latexmk also has options -M, -MF, - -dependents - Equivalent to -deps. + 7 August 2018 7 - -deps- Do not show a list of dependent files after processing. (This - is the default.) - -dependents- - Equivalent to -deps-. +LATEXMK(1) General Commands Manual LATEXMK(1) + and -MP options that behave like those of gcc.) - 25 May 2018 7 + -dependents + Equivalent to -deps. + -deps- Do not show a list of dependent files after processing. (This + is the default.) -LATEXMK(1) General Commands Manual LATEXMK(1) + -dependents- + Equivalent to -deps-. -deps-out=FILENAME - Set the filename to which the list of dependent files is writ- - ten. If the FILENAME argument is omitted or set to "-", then + Set the filename to which the list of dependent files is writ- + ten. If the FILENAME argument is omitted or set to "-", then the output is sent to stdout. - Use of this option also turns on the output of the list of + Use of this option also turns on the output of the list of dependent files after processing. - -dF Dvi file filtering. The argument to this option is a filter - which will generate a filtered dvi file with the extension - ".dviF". All extra processing (e.g. conversion to postscript, - preview, printing) will then be performed on this filtered dvi + -dF Dvi file filtering. The argument to this option is a filter + which will generate a filtered dvi file with the extension + ".dviF". All extra processing (e.g. conversion to postscript, + preview, printing) will then be performed on this filtered dvi file. Example usage: To use dviselect to select only the even pages of @@ -488,7 +503,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -diagnostics - Print detailed diagnostics during a run. This may help for + Print detailed diagnostics during a run. This may help for debugging problems or to understand latexmk's behavior in diffi- cult situations. @@ -496,56 +511,56 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -dvi Generate dvi version of document. - -dvi- Turn off generation of dvi version of document. (This may get - overridden, if some other file is made (e.g., a .ps file) that - is generated from the dvi file, or if no generated file at all + -dvi- Turn off generation of dvi version of document. (This may get + overridden, if some other file is made (e.g., a .ps file) that + is generated from the dvi file, or if no generated file at all is requested.) -e - Execute the specified initialization code before processing. - The code is Perl code of the same form as is used in latexmk's - initialization files. For more details, see the information on - the -r option, and the section about "Configuration/initializa- - tion (RC) files". The code is typically a sequence of assign- - ment statements separated by semicolons. + Execute the specified initialization code before processing. + The code is Perl code of the same form as is used in latexmk's - The code is executed when the -e option is encountered during - latexmk's parsing of its command line. See the -r option for a - way of executing initialization code from a file. An error - results in latexmk stopping. Multiple instances of the -r and - -e options can be used, and they are executed in the order they - appear on the command line. - Some care is needed to deal with proper quoting of special char- - acters in the code on the command line. For example, suppose - you want to set the latex command to use its -shell-escape + 7 August 2018 8 - 25 May 2018 8 +LATEXMK(1) General Commands Manual LATEXMK(1) -LATEXMK(1) General Commands Manual LATEXMK(1) + initialization files. For more details, see the information on + the -r option, and the section about "Configuration/initializa- + tion (RC) files". The code is typically a sequence of assign- + ment statements separated by semicolons. + The code is executed when the -e option is encountered during + latexmk's parsing of its command line. See the -r option for a + way of executing initialization code from a file. An error + results in latexmk stopping. Multiple instances of the -r and + -e options can be used, and they are executed in the order they + appear on the command line. + Some care is needed to deal with proper quoting of special char- + acters in the code on the command line. For example, suppose + you want to set the latex command to use its -shell-escape option, then under UNIX/Linux you could use the line latexmk -e '$latex=q/latex %O -shell-escape %S/' file.tex - Note that the single quotes block normal UNIX/Linux command - shells from treating the characters inside the quotes as spe- - cial. (In this example, the q/.../ construct is a Perl idiom - equivalent to using single quotes. This avoids the complica- - tions of getting a quote character inside an already quoted - string in a way that is independent of both the shell and the + Note that the single quotes block normal UNIX/Linux command + shells from treating the characters inside the quotes as spe- + cial. (In this example, the q/.../ construct is a Perl idiom + equivalent to using single quotes. This avoids the complica- + tions of getting a quote character inside an already quoted + string in a way that is independent of both the shell and the operating-system.) - The above command line will NOT work under MS-Windows with - cmd.exe or command.com or 4nt.exe. For MS-Windows with these + The above command line will NOT work under MS-Windows with + cmd.exe or command.com or 4nt.exe. For MS-Windows with these command shells you could use latexmk -e "$latex=q/latex %O -shell-escape %S/" file.tex @@ -554,48 +569,50 @@ LATEXMK(1) General Commands Manual LATEXMK(1) latexmk -e "$latex='latex %O -shell-escape %S'" file.tex - The last two examples will NOT work with UNIX/Linux command + The last two examples will NOT work with UNIX/Linux command shells. - (Note: the above examples show are to show how to use the -e to - specify initialization code to be executed. But the particular + (Note: the above examples show are to show how to use the -e to + specify initialization code to be executed. But the particular effect can be achieved also by the use of the -latex option with less problems in dealing with quoting.) - -f Force latexmk to continue document processing despite errors. + -f Force latexmk to continue document processing despite errors. Normally, when latexmk detects that LaTeX or another program has found an error which will not be resolved by further processing, no further processing is carried out. - Note: "Further processing" means the running of other programs - or the rerunning of latex (etc) that would be done if no errors - 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, - e.g., by latexmk's option -interaction=nonstopmode. + Note: "Further processing" means the running of other programs + or the rerunning of latex (etc) that would be done if no errors + had occurred. If instead, or additionally, you want the latex - -f- Turn off the forced processing-past-errors such as is set by the - -f option. This could be used to override a setting in a con- - figuration file. + 7 August 2018 9 - -g Force latexmk to process document fully, even under situations - where latexmk would normally decide that no changes in the - source files have occurred since the previous run. This option - is useful, for example, if you change some options and wish to - reprocess the files. - 25 May 2018 9 +LATEXMK(1) General Commands Manual LATEXMK(1) + (etc) program not to pause for user input after an error, you + should arrange this by an option that is passed to the program, + e.g., by latexmk's option -interaction=nonstopmode. -LATEXMK(1) General Commands Manual LATEXMK(1) + -f- Turn off the forced processing-past-errors such as is set by the + -f option. This could be used to override a setting in a con- + figuration file. + + + -g Force latexmk to process document fully, even under situations + where latexmk would normally decide that no changes in the + source files have occurred since the previous run. This option + is useful, for example, if you change some options and wish to + reprocess the files. -g- Turn off -g. @@ -610,17 +627,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -jobname=STRING - Set the basename of output files(s) to STRING, instead of the + Set the basename of output files(s) to STRING, instead of the default, which is the basename of the specified TeX file. - This is like the same option for current implementations of the - latex, pdflatex, etc, and the passing of this option to these + This is like the same option for current implementations of the + latex, pdflatex, etc, and the passing of this option to these programs is part of latexmk's implementation of -jobname. -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 + ers and the dvi to postscript converters. This option is not + normally needed nowadays, since current previewers normally determine this information automatically. @@ -629,105 +646,105 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -latex="COMMAND" This sets the string specifying the command to run latex, and is - typically used to add desired options. Since the string nor- + typically used to add desired options. Since the string nor- mally contains spaces, it should be quoted, e.g., latexmk -latex="latex --shell-escape %O %S" foo.tex - The specification of the contents of the string are the same as - for the $latex configuration variable. Depending on your oper- - ating system and the command-line shell you are using, you may - need to change the single quotes to double quotes (or something - else). + The specification of the contents of the string are the same as - To set the command for running pdflatex (rather than the command - for latex) see the -pdflatex option. - -logfilewarninglist - -logfilewarnings After a run of (pdf)latex, give a list of warn- - ings about undefined citations and references (unless silent - mode is on). + 7 August 2018 10 - See also the $silence_logfile_warnings configuration variable. +LATEXMK(1) General Commands Manual LATEXMK(1) - 25 May 2018 10 + for the $latex configuration variable. Depending on your oper- + ating system and the command-line shell you are using, you may + need to change the single quotes to double quotes (or something + else). + To set the command for running pdflatex (rather than the command + for latex) see the -pdflatex option. + -logfilewarninglist + -logfilewarnings After a run of (pdf)latex, give a list of warn- + ings about undefined citations and references (unless silent + mode is on). -LATEXMK(1) General Commands Manual LATEXMK(1) + 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. -lualatex - Use lualatex. That is, use lualatex to process the source - file(s) to pdf. The generation of dvi and postscript files is + Use lualatex. That is, use lualatex to process the source + file(s) to pdf. The generation of dvi and postscript files is turned off. This option is equivalent to using the following set of options -pdflua -dvi- -ps- - (Note: Note that the method of implementation of this option, - but not its intended effect, differ from some earlier versions + (Note: Note that the method of implementation of this option, + but not its intended effect, differ from some earlier versions of latexmk.) - -M Show list of dependent files after processing. This is equiva- + -M Show list of dependent files after processing. This is equiva- lent to the -deps option. -MF file - If a list of dependents is made, the -MF specifies the file to + If a list of dependents is made, the -MF specifies the file to write it to. -MP If a list of dependents is made, include a phony target for each - source file. If you use the dependents list in a Makefile, the - dummy rules work around errors the program make gives if you + source file. If you use the dependents list in a Makefile, the + dummy rules work around errors the program make gives if you remove header files without updating the Makefile to match. - -new-viewer - When in continuous-preview mode, always start a new viewer to - view the generated file. By default, latexmk will, in continu- - ous-preview mode, test for a previously running previewer for - the same file and not start a new one if a previous previewer is - running. However, its test sometimes fails (notably if there is - an already-running previewer that is viewing a file of the same - name as the current file, but in a different directory). This - option turns off the default behavior. - -new-viewer- - The inverse of the -new-viewer option. It puts latexmk in its - normal behavior that in preview-continuous mode it checks for an - already-running previewer. + 7 August 2018 11 - 25 May 2018 11 +LATEXMK(1) General Commands Manual LATEXMK(1) + -new-viewer + When in continuous-preview mode, always start a new viewer to + view the generated file. By default, latexmk will, in continu- + ous-preview mode, test for a previously running previewer for + the same file and not start a new one if a previous previewer is + running. However, its test sometimes fails (notably if there is + an already-running previewer that is viewing a file of the same + name as the current file, but in a different directory). This + option turns off the default behavior. -LATEXMK(1) General Commands Manual LATEXMK(1) + -new-viewer- + The inverse of the -new-viewer option. It puts latexmk in its + normal behavior that in preview-continuous mode it checks for an + already-running previewer. -nobibtex @@ -736,71 +753,71 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -norc Turn off the automatic reading of initialization (rc) files. - N.B. Normally the initialization files are read and obeyed, and - then command line options are obeyed in the order they are - encountered. But -norc is an exception to this rule: it is + N.B. Normally the initialization files are read and obeyed, and + then command line options are obeyed in the order they are + encountered. But -norc is an exception to this rule: it is acted on first, no matter where it occurs on the command line. -outdir=FOO or -output-directory=FOO - Sets the directory for the output files of (pdf)latex. This - achieves its effect by the -output-directory option of + Sets the directory for the output files of (pdf)latex. This + 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. + on the common versions of (pdf)latex, i.e., MiKTeX and TeXLive. It may not be present in other versions. - See also the -auxdir/-aux-directory options, and the $aux_dir, - $out_dir, and $search_path_separator configuration variables of - latexmk. In particular, see the documentation of $out_dir for + See also the -auxdir/-aux-directory options, and the $aux_dir, + $out_dir, and $search_path_separator configuration variables of + latexmk. In particular, see the documentation of $out_dir for some complications on what directory names are suitable. - If you also use the -cd option, and the specified output direc- - tory is a relative path, then the path is interpreted relative + If you also use the -cd option, and the specified output direc- + tory is a relative path, then the path is interpreted relative to the document directory. - -p Print out the document. By default the file to be printed is - the first in the list postscript, pdf, dvi that is being made. + -p Print out the document. By default the file to be printed is + the first in the list postscript, pdf, dvi that is being made. But you can use the -print=... option to change the type of file to be printed, and you can configure this in a start up file (by setting the $print_type variable). - However, printing is enabled by default only under UNIX/Linux - systems, where the default is to use the lpr command and only on - postscript files. In general, the correct behavior for printing - very much depends on your system's software. In particular, - under MS-Windows you must have suitable program(s) available, - and you must have configured the print commands used by latexmk. - This can be non-trivial. See the documentation on the $lpr, - $lpr_dvi, and $lpr_pdf configuration variables to see how to set - the commands for printing. + However, printing is enabled by default only under UNIX/Linux - This option is incompatible with the -pv and -pvc options, so it - turns them off. - -pdf Generate pdf version of document using pdflatex. (If you wish - to use lualatex or xelatex, you can use whichever of the options - -pdflua, -pdfxe, -lualatex or -xelatex applies.) To configure - latexmk to have such behavior by default, see the section on + 7 August 2018 12 - 25 May 2018 12 +LATEXMK(1) General Commands Manual LATEXMK(1) + systems, where the default is to use the lpr command and only on + postscript files. In general, the correct behavior for printing + very much depends on your system's software. In particular, + under MS-Windows you must have suitable program(s) available, + and you must have configured the print commands used by latexmk. + This can be non-trivial. See the documentation on the $lpr, + $lpr_dvi, and $lpr_pdf configuration variables to see how to set + the commands for printing. -LATEXMK(1) General Commands Manual LATEXMK(1) + This option is incompatible with the -pv and -pvc options, so it + turns them off. + -pdf Generate pdf version of document using pdflatex. (If you wish + to use lualatex or xelatex, you can use whichever of the options + -pdflua, -pdfxe, -lualatex or -xelatex applies.) To configure + latexmk to have such behavior by default, see the section on "Configuration/initialization (rc) files". -pdfdvi - Generate pdf version of document from the dvi file, by default + Generate pdf version of document from the dvi file, by default using dvipdf. @@ -808,73 +825,73 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Generate pdf version of document using lualatex. - -pdfps Generate pdf version of document from the ps file, by default + -pdfps Generate pdf version of document from the .ps file, by default using ps2pdf. - -pdfxe Generate pdf version of document using xelatex. Note that to - optimize processing time, latexmk uses xelatex to generate an - xdv file rather than a pdf file directly. Only after possibly - multiple runs to generate a fully up-to-date xdv does latexmk - then call xdvipdfmx to generate the final pdf file. + -pdfxe Generate pdf version of document using xelatex. Note that to + optimize processing time, latexmk uses xelatex to generate an + .xdv file rather than a pdf file directly. Only after possibly + multiple runs to generate a fully up-to-date .xdv file does + latexmk then call xdvipdfmx to generate the final .pdf file. - (Note: When the document includes large graphics files, espe- - cially png files, the last step can be quite time consuming, - even when the creation of the xdv file by xelatex is fast. So - the use of the intermediate xdv file can result in substantial - gains in procesing time, since the pdf file is produced once + (Note: When the document includes large graphics files, espe- + cially .png files, the last step can be quite time consuming, + even when the creation of the .xdv file by xelatex is fast. So + the use of the intermediate .xdv file can result in substantial + gains in procesing time, since the .pdf file is produced once rather than on every run of xelatex.) - -pdf- Turn off generation of pdf version of document. (This can be - used to override a setting in a configuration file. It may get + -pdf- Turn off generation of pdf version of document. (This can be + used to override a setting in a configuration file. It may get overridden if some other option requires the generation of a pdf file.) - If after all options have been processed, pdf generation is - still turned off, then generation of a dvi file will be turned - on, and then the program used to compiled a document will be - latex (or, more precisely, whatever program is configured to be - used in the $latex configuration variable). + If after all options have been processed, pdf generation is + still turned off, then generation of a dvi file will be turned - -pdflatex="COMMAND" - This sets the string specifying the command to run pdflatex, and - is typically used to add desired options. Since the string nor- - mally contains spaces, it should be quoted, e.g., - latexmk -pdf -pdflatex="pdflatex --shell-escape %O %S" - foo.tex + 7 August 2018 13 - 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 - 25 May 2018 13 +LATEXMK(1) General Commands Manual LATEXMK(1) + on, and then the program used to compiled a document will be + latex (or, more precisely, whatever program is configured to be + used in the $latex configuration variable). -LATEXMK(1) General Commands Manual LATEXMK(1) + -pdflatex="COMMAND" + This sets the string specifying the command to run pdflatex, and + is typically used to add desired options. Since the string nor- + mally contains spaces, it should be quoted, e.g., + latexmk -pdf -pdflatex="pdflatex --shell-escape %O %S" + foo.tex - something else). + 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). - To set the command for running latex (rather than the command + To set the command for running latex (rather than the command for pdflatex) see the -latex option. -print=dvi, -print=ps, -print=pdf, -print=auto, - Define which kind of file is printed. This option also ensures + Define which kind of file is printed. This option also ensures that the requisite file is made, and turns on printing. The (default) case -print=auto determines the kind of print file - automatically from the set of files that is being made. The - first in the list postscript, pdf, dvi that is among the files + automatically from the set of files that is being made. The + first in the list postscript, pdf, dvi that is among the files to be made is the one used for print out. @@ -882,13 +899,13 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -ps- Turn off generation of postscript version of document. This can - be used to override a setting in a configuration file. (It may - get overridden by some other option that requires a postscript + be used to override a setting in a configuration file. (It may + get overridden by some other option that requires a postscript file, for example a request for printing.) - -pF Postscript file filtering. The argument to this option is a - filter which will generate a filtered postscript file with the + -pF Postscript file filtering. The argument to this option is a + filter which will generate a filtered postscript file with the extension ".psF". All extra processing (e.g. preview, printing) will then be performed on this filtered postscript file. @@ -900,98 +917,99 @@ LATEXMK(1) General Commands Manual LATEXMK(1) latexmk -ps -pF "psnup -2" foo.tex - Whether to use single or double quotes round the "psnup -2" will - depend on your command interpreter, as used by the particular - version of perl and the operating system on your computer. - -pv Run file previewer. If the -view option is used, this will - 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. + 7 August 2018 14 - -pv- Turn off -pv. +LATEXMK(1) General Commands Manual LATEXMK(1) - 25 May 2018 14 + Whether to use single or double quotes round the "psnup -2" will + depend on your command interpreter, as used by the particular + version of perl and the operating system on your computer. + -pv Run file previewer. If the -view option is used, this will + select the kind of file to be previewed (.dvi, .ps or .pdf). + Otherwise the viewer views the "highest" kind of file selected, + by the -dvi, -ps, -pdf, -pdfps options, in the order .dvi, .ps, + .pdf (low to high). If no file type has been selected, the dvi + previewer will be used. This option is incompatible with the -p + and -pvc options, so it turns them off. -LATEXMK(1) General Commands Manual LATEXMK(1) + -pv- Turn off -pv. - -pvc Run a file previewer and continually update the .dvi, .ps, + -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 + 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. - The -pvc option also turns off force mode (-f), as is normally - best for continuous preview mode. If you really want force + The -pvc option also turns off force mode (-f), as is normally + best for continuous preview mode. If you really want force mode, use the options in the order -pvc -f. With a good previewer the display will be automatically updated. - (Under some but not all versions of UNIX/Linux "gv -watch" does - this for postscript files; this can be set by a configuration - variable. This would also work for pdf files except for an - apparent bug in gv that causes an error when the newly updated - pdf file is read.) Many other previewers will need a manual + (Under some but not all versions of UNIX/Linux "gv -watch" does + this for postscript files; this can be set by a configuration + variable. This would also work for pdf files except for an + apparent bug in gv that causes an error when the newly updated + pdf file is read.) Many other previewers will need a manual update. Important note: the acroread program on MS-Windows locks the pdf - file, and prevents new versions being written, so it is a bad - idea to use acroread to view pdf files in preview-continuous - mode. It is better to use a different viewer: SumatraPDF and + file, and prevents new versions being written, so it is a bad + idea to use acroread to view pdf files in preview-continuous + mode. It is better to use a different viewer: SumatraPDF and gsview are good possibilities. - There are some other methods for arranging an update, notably - useful for many versions of xdvi and xpdf. These are best set + There are some other methods for arranging an update, notably + useful for many versions of xdvi and xpdf. These are best set in latexmk's configuration; see below. - Note that if latexmk dies or is stopped by the user, the + Note that if latexmk dies or is stopped by the user, the "forked" previewer will continue to run. Successive invocations - with the -pvc option will not fork new previewers, but latexmk - will normally use the existing previewer. (At least this will - happen when latexmk is running under an operating system where - it knows how to determine whether an existing previewer is run- - ning.) + with the -pvc option will not fork new previewers, but latexmk + will normally use the existing previewer. (At least this will + happen when latexmk is running under an operating system where - -pvc- Turn off -pvc. + 7 August 2018 15 - -pvctimeout - Do timeout in pvc mode after period of inactivity, which is 30 - min. by default. Inactivity means a period when latexmk has - detected no file changes and hence has not taken any actions - like compiling the document. - -pvctimeout- - Don't do timeout in pvc mode after inactivity. +LATEXMK(1) General Commands Manual LATEXMK(1) + + it knows how to determine whether an existing previewer is run- + ning.) - 25 May 2018 15 + -pvc- Turn off -pvc. + -pvctimeout + Do timeout in pvc mode after period of inactivity, which is 30 + min. by default. Inactivity means a period when latexmk has + detected no file changes and hence has not taken any actions + like compiling the document. -LATEXMK(1) General Commands Manual LATEXMK(1) + -pvctimeout- + Don't do timeout in pvc mode after inactivity. -pvctimeoutmins=