diff options
Diffstat (limited to 'Master/texmf-dist/doc/support')
16 files changed, 1020 insertions, 913 deletions
diff --git a/Master/texmf-dist/doc/support/latexmk/CHANGES b/Master/texmf-dist/doc/support/latexmk/CHANGES index 224d0b5b64e..c67b6bffd3c 100644 --- a/Master/texmf-dist/doc/support/latexmk/CHANGES +++ b/Master/texmf-dist/doc/support/latexmk/CHANGES @@ -789,3 +789,18 @@ From v. 4.75 to 4.76 Improve some diagnostics. Add /etc to list of locations for system rc files (with Unix-like OSs). +From v. 4.76 to 4.77 + Clean up and improvements in warnings etc + Ensured systematic use of STDOUT and STDERR, to more or less match that + of *tex: STDOUT for progress messages, and, normally, errors and + warnings caused by the compilation of a document. STDERR is for + within-latexmk errors etc: incorrect command line, configuration errors + etc. + Internal improvements and bug fixes. + Correctly handle non-ASCII filenames, UTF-8 coding of log files etc, + including on MS Wndows, and including correct parsing of wrapped + lines in log files. Adjust method of unwrapping of wrapped lines in + log file according to whether latex/pdflatex, lualatex or xelatex is + used, thereby reducing misparses of information in log file. + Reinstate Windows batch file for running latexmk, now called latexmk.cmd. + diff --git a/Master/texmf-dist/doc/support/latexmk/INSTALL b/Master/texmf-dist/doc/support/latexmk/INSTALL index 32e5c5d4efc..170a1889045 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.76, 20 Nov. 2021) + (Version 4.77, 17 Mar. 2022) John Collins Physics Department @@ -43,40 +43,36 @@ c. In addition, the installation of TeX and LaTex should, of course, documents to be compiled and processed. -!!!! IMPORTANT NOTE: !!!! -=========================== +!!!! IMPORTANT NOTES: !!!! +============================ -If you have installed a modern distribution of TeX and friends, you -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. +1. If you have installed a distribution of TeX and friends, you will +probably find that latexmk is already installed on your computer. This +applies to both the TeXLive and the MiKTeX distributions (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 or may not include latexmk; in +that case you should be able to use your distribution's package manager to +install latexmk. Having latexmk installed by a TeX distribution is +normally the recommended way to be able to use latexmk. -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. +2. The only extra requirement beyond having latexmk installed is to have an +installation of Perl. See above. -If you are on MS-Windows and you are using TeXLive (2009, or later), -this distribution also includes a distribution of Perl sufficient to -run latexmk.pl, so you don't need to install Perl separately. It also -includes an executable file latexmk.exe that runs latexmk. +3. You will normally need to use the manual installation method below if +you have a special need for it. However, you should still examine the +information on configuration below and in the main documentation to get +latexmk working exactly as you want it. -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 of Perl should enable latexmk to work. +4. 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 and will report its version number. 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. -BUT, you may need to configure latexmk to +BUT, you may need to configure latexmk to adjust its behavior to suit your +needs. See item 6 below, as well as the full documentation, for further +information. **Manual** installation on UNIX/LINUX/OS-X @@ -84,12 +80,13 @@ BUT, you may need to configure latexmk to (Power users can modify these as appropriate, of course.) -NOTE: If you are using TeXLive 2009 or later, you can install latexmk -simply by using the TeXLive package manager (that includes users of -MacTeX). 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 see item 6. +NOTE: If you are using TeXLive 2009 or later, or a moderately recent +version of MiKTeX, you can install latexmk simply by using the TeXLive +package manager (that includes users of MacTeX). In fact, depending on how +much of TeXLive or MiKTeX 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 see item 6. 1. Make sure you have working installations of Perl and TeX/LaTeX. @@ -98,7 +95,10 @@ Still you may need to examine the configuration instructions see item 6. /usr/local/bin. But if you are an ordinary user, you can put the file somewhere where you have access, and ensure that the PATH environment variable includes the directory where latexmk is - installed. + installed. + + If you are using MS-Windows, go to the corresponding items in the + instructions for Windows. 3. Rename this file to latexmk. @@ -141,13 +141,15 @@ Still you may need to examine the configuration instructions see item 6. If latexmk does not get one of more of these commands correct, put an override in a startup file: - a. For a system-wide installation, the correction should be in the + a. For a system-wide installation, the correction can be in the system startup file, which on a UNIX-like operating system is any one of + /etc/LatexMk, /opt/local/share/latexmk/LatexMk, /usr/local/share/latexmk/LatexMk, /usr/local/lib/latexmk/LatexMk, + /etc/latexmkrc, /opt/local/share/latexmk/latexmkrc, /usr/local/share/latexmk/latexmkrc, /usr/local/lib/latexmk/latexmkrc. @@ -161,9 +163,8 @@ Still you may need to examine the configuration instructions see item 6. 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. + b. You can also/instead put the configuration lines in the user + startup file, which is the file .latexmkrc in your home directory. (Under normal circumstances, latexmk's definition of home directory under Unix-like operating systems is the usual one, @@ -232,34 +233,48 @@ 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. +In either of these cases you don't normally need to bother with the manual +installation explained below. Still you may need to examine the +configuration instructions see item 6. + + 1. Make sure you have working installations of Perl and TeX/LaTeX, complete with viewers for dvi, postscript and/or pdf files. You will - also need whatever packages your document needs. + also need whatever packages your document needs. 2. If necessary, unpack the latexmk distribution. 3. **Difference compared with UNIX-type systems**: Copy the file - latexmk.pl to a suitable directory (your choice), and arrange for it to - be invoked as a command. (If you don't know how to do this, find out - about "executable extension for perl on windows", by a web search.) - -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. - - In Windows, there is a Control Panel setting for this. (Should be - under Advanced system settings->Environment variables.) + latexmk.pl to a suitable directory and arrange for it to be invoked as + a command. See the following sentences for what "suitable directory" + means. One way to ensure that you can invoke the latexmk command is to + also put the file latexmk.cmd in the same directory, and then follow + the next instructions: + + 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. In Windows, there is a Control Panel setting + for this. (It should be under Advanced system settings->Environment + variables.) Log out and back in to make sure the changed setting gets + used. + + Note: Each of TeXLive and MiKTeX make a suitable change to the PATH + environment variable, so that all the programs they install are + usable, including latexmk. + +4. You may need to reboot, or at least logoff and log back in, if you made + any changes to PATH. -5. (Optional) Copy documentation file(s) to a suitable directory. The - only requirement on the directory is your convenience: some convenient - place to look up documentation. The relevant files are latexmk.txt - which is a pure ASCII text file, and latexmk.pdf which is a postscript - file. +5. Concerning invocation of latexmk: See later items. -6. You may need to reboot, or at least logoff and log back in, if you made - any changes to PATH. +6. (Optional) Copy documentation file(s) to a suitable directory. The + only requirement on the directory is your convenience: i.e., some + convenient place to look up documentation. The relevant files are + latexmk.txt which is a pure ASCII text file, and latexmk.pdf which is a + postscript file. -7. Test out the installation at the command-line prompt: +7. Test out the installation at the command-line prompt (cmd.exe or Power + Shell): a. First do @@ -292,20 +307,22 @@ need to install a distribution of Perl if you haven't done so already. Also LOOK AT THE SECTION NAMED "TRICKY POINTS" below to see some hints. - 8. If the commands used by latexmk are incorrect, see the UNIX installation instructions for what to do. The only changes needed from the UNIX instructions are: - a. The system initialization file is C:\latexmk\LatexMk. (If - this is not suitable for some reason, you'll need to change - the latexmk.pl file where this filename appears.) + a. The system initialization file is either C:\latexmk\LatexMk or + C:\latexmk\latexmkrc. (If these is not suitable for some reason, + you'll need to change the latexmk.pl file where this filename + appears. But normally it's easier to change the user latexmkrc + file --- see the next item.) b. The user initialization file is .latexmkrc in the directory - specified by the environment variable HOME. If there is no HOME - variable, then the file is in the directory specified by the - environment variable USERPROFILE, which should have been set - by the MS-Windows operating system at login. + specified by the environment variable HOME, if that happens to be + defined, which it normally isn't. If there is no HOME variable, + then the file is in the directory specified by the environment + variable USERPROFILE, which should have been set by the MS-Windows + operating system at login. @@ -320,34 +337,39 @@ can update these instructions and possibly latexmk as well. Tricky points ============= - -1. BEWARE of filenames with double extensions, for example, - two.part.tex. The behavior of TeX-related software is not - consistent in this situation. You may, for example, find a log - file named two.log or two.part.log, depending on which version of - which implementation of TeX/LaTeX you use. Naturally, there is a - possibility in this situation that latexmk will get confused, and - not recognize, for example, that a dvi file has been generated. - Latexmk has configuration variables to deal with some of the - possibilities, so you could try playing with them --- see the - code. But it general, it is best to avoid such double extensions: - 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 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. Often things work without trouble. +(These aren't so much issues about installation as about use of latexmk.) + +1. BEWARE of filenames with double extensions, for example, two.part.tex. + The behavior of TeX-related software is not consistent in this + situation. You may, for example, find a log file named two.log or + two.part.log, depending on which version of which implementation of + TeX/LaTeX you use. Naturally, there is a possibility in this situation + that latexmk will get confused, and not recognize, for example, that a + dvi or other file has been generated. Latexmk has configuration + variables to deal with some of the possibilities, so you could try + playing with them --- see the code. But it general, it is best to + avoid such double extensions: they make your files non-portable. Do + something like two-part.tex or two_part.tex instead. + +2. Filenames and directory names with spaces in them can potentially cause + problems. Much software tends to interpret spaces as separators + between different filenames or between filenames and other text. This + coul cause problems in some of the programs called by latexmk. + + Even so, file and directory names containing spaces generally cause no + problems in both latexmk and the programs it calls. + +3. Non-ASCII characters in file and directory names: In the current + version of latexmk and current TeXLive and MiKTeX, these are generally + handled correctly, particular on linux and macOS systems. + + But it is worth being aware there is a potential for problems: (a) Default + installations of MS-Windows do not make all Unicode characters in + filenames available to Perl and hence latexmk. (b) Some annoying + issues may arise if you transfer files from a macOS HFS+ volume to a + volume used by another operating system for use with that OS. These + problems concern different ways of normalizing filenames containing + accented characters, and may entail renaming the transferred files. 4. If you need to remake documentation files, e.g., latexmk.pdf or latexmk.txt, from the man page file latexmk.1, the following @@ -378,7 +400,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-2019 by John Collins, and the previous authors; see the copyright +1998-2022 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 v. 2. diff --git a/Master/texmf-dist/doc/support/latexmk/README b/Master/texmf-dist/doc/support/latexmk/README index 471564ac8ae..e13a04f8a86 100644 --- a/Master/texmf-dist/doc/support/latexmk/README +++ b/Master/texmf-dist/doc/support/latexmk/README @@ -1,5 +1,5 @@ -Latexmk, version 4.76, 20 Nov 2021 ---------------------------------- +Latexmk, version 4.77, 17 Mar 2022 +---------------------------------- Latexmk completely automates the process of generating a LaTeX document. Essentially, it is a highly specialized cousin of the @@ -10,19 +10,18 @@ of the programs until cross references etc are resolved. Latexmk can also be set to run continuously with a previewer; the latex program, etc, are rerun whenever one of the source files is modified. -Latexmk automatically determines file dependencies from the LaTeX .log -file. It features: a fully reliable algorithm for deciding how many -times to run latex and related programs, automatic detection of -dependent files, the ability to generate pdf files using pdflatex or -via dvi or postscript files, and the continuous-preview mode. For -bibliographies, the current version now supports biber as well as the +Latexmk automatically determines file dependencies from the LaTeX .fls, +.log, and .aux files. It features: a fully reliable algorithm for deciding +how many times to run latex and related programs, automatic detection of +dependent files, the ability to generate pdf files using pdflatex or via +dvi or postscript files, and the continuous-preview mode. For +bibliographies, the current version supports biber as well as the traditional bibtex. Which of bibtex or biber to use is determined -automatically. +automatically. -Please read the man page (or the corresponding text or postscript file) for -details of what latexmk does and what all the features are. A copy of the -fast help that can be seen by running "latexmk -h" is at the end of this -file. +Please read the man page (or the corresponding text or pdf file) for +details of what latexmk does and what all the features are. A list of +available command-line options is available by running 'latexmk --help'. Latexmk is a perl script. It is licensed under the GNU General Public License v. 2. @@ -40,8 +39,7 @@ written by David J. Musliner. Now it is supported by http://www.personal.psu.edu/jcc8/ username jcc8 at node psu.edu -The start of the script file has copyright notices and disclaimers. It -also has a modification history for those who are interested. +The start of the script file has copyright notices and disclaimers. NOTES:- @@ -63,172 +61,3 @@ NOTES:- under development. John Collins ----------------------------- "latexmk -h" ---------------------------- -Latexmk 4.76: Automatic LaTeX document generation routine - -Usage: latexmk [latexmk_options] [filename ...] - - Latexmk_options: - -aux-directory=dir or -auxdir=dir - - set name of directory for auxiliary files (aux, log) - - Currently this only works with MiKTeX - -bibtex - use bibtex when needed (default) - -bibtex- - never use bibtex - -bibtex-cond - use bibtex when needed, but only if the bib file exists - -bibtex-cond1 - use bibtex when needed, but only if the bib file exists; - on cleanup delete bbl file only if bib file exists - -bibfudge or -bibtexfudge - change directory to output directory when running bibtex - -bibfudge- or -bibtexfudge- - don't change directory when running bibtex - -bm <message> - Print message across the page when converting to postscript - -bi <intensity> - Set contrast or intensity of banner - -bs <scale> - Set scale for banner - -commands - list commands used by latexmk for processing files - -c - clean up (remove) all nonessential files, except - dvi, ps and pdf files. - This and the other clean-ups are instead of a regular make. - -C - clean up (remove) all nonessential files - including aux, dep, dvi, postscript and pdf files - and file of database of file information - -CA - clean up (remove) all nonessential files. - Equivalent to -C option. - -CF - Remove file of database of file information before doing - other actions - -cd - Change to directory of source file when processing it - -cd- - Do NOT change to directory of source file when processing it - -dependents or -deps - Show list of dependent files after processing - -dependents- or -deps- - Do not show list of dependent files - -deps-out=file - Set name of output file for dependency list, - and turn on showing of dependency list - -dF <filter> - Filter to apply to dvi file - -dir-report - Before processing a tex file, report aux and out dir settings - -dir-report- - Before processing a tex file, do not report aux and out dir settings - -dvi - generate dvi - -dvi- - turn off required dvi - -e <code> - Execute specified Perl code (as part of latexmk start-up - code) - -emulate-aux-dir - emulate -aux-directory option for *latex - -emulate-aux-dir- - use -aux-directory option with *latex - -f - force continued processing past errors - -f- - turn off forced continuing processing past errors - -gg - Super go mode: clean out generated files (-CA), and then - process files regardless of file timestamps - -g - process at least one run of all rules - -g- - Turn off -g and -gg - -h - print help - -help - print help - -indexfudge or -makeindexfudge - change directory to output directory when running makeindex - -indexfudge- or -makeindexfudge- - don't change directory when running makeindex - -jobname=STRING - set basename of output file(s) to STRING. - (Like --jobname=STRING on command line for many current - implementations of latex/pdflatex.) - -l - force landscape mode - -l- - turn off -l - -latex=<program> - set program used for latex. - (replace '<program>' by the program name) - -latexoption=<option> - add the given option to the *latex command - -logfilewarninglist or -logfilewarnings - give list of warnings after run of *latex - -logfilewarninglist- or -logfilewarnings- - do not give list of warnings after run of *latex - -lualatex - use lualatex for processing files to pdf - and turn dvi/ps modes off - -M - Show list of dependent files after processing - -MF file - Specifies name of file to receives list dependent files - -MP - List of dependent files includes phony target for each source file. - -makeindexfudge - change directory to output directory when running makeindex - -makeindexfudge-- don't change directory to output directory when running makeindex - -MSWinBackSlash under MSWin use backslash (\) for directory separators - for filenames given to called programs - -MSWinBackSlash- under MSWin use forward slash (/) for directory separators - for filenames given to called programs - -new-viewer - in -pvc mode, always start a new viewer - -new-viewer- - in -pvc mode, start a new viewer only if needed - -nobibtex - never use bibtex - -nobibfudge or -nobibtexfudge - don't change directory when running bibtex - -nodependents - Do not show list of dependent files after processing - -noemulate-aux-dir - use -aux-directory option with *latex - -noindexfudge or -nomakeindexfudge - don't change directory when running makeindex - -norc - omit automatic reading of system, user and project rc files - -output-directory=dir or -outdir=dir - - set name of directory for output files - -output-format=FORMAT - - if FORMAT is dvi, turn on dvi output, turn off others - - if FORMAT is pdf, turn on pdf output, turn off others - - otherwise error - -pdf - generate pdf by pdflatex - -pdfdvi - generate pdf by dvipdf - -pdflatex=<program> - set program used for pdflatex. - (replace '<program>' by the program name) - -pdflualatex=<program> - set program used for lualatex. - (replace '<program>' by the program name) - -pdfps - generate pdf by ps2pdf - -pdflua - generate pdf by lualatex - -pdfxe - generate pdf by xelatex - -pdfxelatex=<program> - set program used for xelatex. - (replace '<program>' by the program name) - -pdf- - turn off pdf - -ps - generate postscript - -ps- - turn off postscript - -pF <filter> - Filter to apply to postscript file - -p - print document after generating postscript. - (Can also .dvi or .pdf files -- see documentation) - -pretex=<TeX code> - Sets TeX code to be executed before inputting source - file, if commands suitable configured - -print=dvi - when file is to be printed, print the dvi file - -print=ps - when file is to be printed, print the ps file (default) - -print=pdf - when file is to be printed, print the pdf file - -pv - preview document. (Side effect turn off continuous preview) - -pv- - turn off preview mode - -pvc - preview document and continuously update. (This also turns - on force mode, so errors do not cause latexmk to stop.) - (Side effect: turn off ordinary preview mode.) - -pvc- - turn off -pvc - -pvctimeout - timeout in pvc mode after period of inactivity - -pvctimeout- - don't timeout in pvc mode after inactivity - -pvctimeoutmins=<time> - set period of inactivity (minutes) for pvc timeout - -quiet - silence progress messages from called programs - -r <file> - Read custom RC file - (N.B. This file could override options specified earlier - on the command line.) - -rc-report - After initialization, report names of rc files read - -rc-report- - After initialization, do not report names of rc files read - -recorder - Use -recorder option for *latex - (to give list of input and output files) - -recorder- - Do not use -recorder option for *latex - -rules - Show list of rules after processing - -rules- - Do not show list of rules after processing - -showextraoptions - Show other allowed options that are simply passed - as is to latex and pdflatex - -silent - silence progress messages from called programs - -stdtexcmds - Sets standard commands for *latex - -time - show CPU time used - -time- - don't show CPU time used - -use-make - use the make program to try to make missing files - -use-make- - don't use the make program to try to make missing files - -usepretex - Sets commands for *latex to use extra code before inputting - source file - -usepretex=<TeX code> - Equivalent to -pretex=<TeX code> -usepretex - -v - display program version - -verbose - display usual progress messages from called programs - -version - display program version - -view=default - viewer is default (dvi, ps, pdf) - -view=dvi - viewer is for dvi - -view=none - no viewer is used - -view=ps - viewer is for ps - -view=pdf - viewer is for pdf - -Werror - treat warnings from called programs as errors - -xelatex - use xelatex for processing files to pdf - and turn dvi/ps modes off - - filename = the root filename of LaTeX document - --p, -pv and -pvc are mutually exclusive --h, -c and -C override all other options. --pv and -pvc require one and only one filename specified -All options can be introduced by '-' or '--'. (E.g., --help or -help.) - -In addition, latexmk recognizes many other options that are passed to -latex and/or pdflatex without interpretation by latexmk. Run latexmk -with the option -showextraoptions to see a list of these - -Report bugs etc to John Collins <jcc8 at psu.edu>. diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/asymptote_latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/asymptote_latexmkrc index 45f32979d0f..7a7425ff47e 100644 --- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/asymptote_latexmkrc +++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/asymptote_latexmkrc @@ -48,8 +48,7 @@ sub asy2tex { return asy2x( $_[0], 'tex' ); } sub asy2x { my $ret = system("asy -vv -f '$_[1]' '$_[0]' >& '$_[0].log'"); - my $FH = new FileHandle; - open $FH, "$_[0].log"; + open( my $FH, "<", "$_[0].log" ); %imp = (); while (<$FH>) { diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/chapterbib-latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/chapterbib-latexmkrc index e5c2cb62501..5a613382d1c 100644 --- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/chapterbib-latexmkrc +++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/chapterbib-latexmkrc @@ -26,11 +26,17 @@ sub bibtex_fix { if ( $base_bare eq $root ) { print "--- Will run bibtex on modified '$root.aux' file\n"; my $aux_mod_base = $base."-mod"; - local $out_fh = new FileHandle "> $aux_mod_base$ext"; + + # Open output (modified aux file) here rather than in fix_aux, and + # make the relevant variables local. This is instead opening both + # files in fix_aux itself. The reason: fix_aux calls itself + # recursively, but must always write to the same file. + open( local $out_fh, ">", $aux_mod_base$ext ); if (!$out_fh) { die "Cannot write to '$aux_mod_base$ext'\n"; } local $level = 0; fix_aux( $source ); close $out_fh; + # Override source, dest, and basenames, since they are to have the path given # in the arguments to this subroutine, instead of the path given in the # corresponding names in the rule. Latexmk may change directory before @@ -51,7 +57,7 @@ sub fix_aux { # removing \bibdata and \bibstyle lines that were in included .aux files. my $aux_file = $_[0]; print "Processing '$aux_file'\n"; - my $aux_fh = new FileHandle $aux_file; + open( my $aux_fh, "<", $aux_file ); if (!$aux_fh) { die "$My_name: Couldn't read aux file '$aux_file'\n"; } $level++; while (<$aux_fh>) { diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/clean_pattern_latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/clean_pattern_latexmkrc index b15507c6238..9a5fa3ac527 100644 --- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/clean_pattern_latexmkrc +++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/clean_pattern_latexmkrc @@ -2,7 +2,7 @@ # extension or something containing %R. # This is done by overriding latexmk's cleanup1 subroutine. -# Here is an example of a usefule application: +# Here is an example of a useful application: $clean_ext = "*-eps-converted-to.pdf"; sub cleanup1 { diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/dot2tex-latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/dot2tex-latexmkrc new file mode 100644 index 00000000000..64693cab33c --- /dev/null +++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/dot2tex-latexmkrc @@ -0,0 +1,175 @@ +# ================ Customization for dot2tex: ================================ + +push @generated_exts, '%R-dot2tex-fig*.tex', '%R-dot2tex-fig*.dot', + '%R-dot2tex-fig*.dot2texopts'; +add_cus_dep( 'dot', 'tex', 0, 'dot2tex' ); + +# Fancy: prefix string for each *latex by "internal" mylatex and basename of tex file +#foreach my $name ( 'latex', 'pdflatex', 'lualatex', 'xelatex' ) { +# ${$name} = "internal mylatex %B ". ${$name}; +#} + +$latex = 'internal mylatex %B latex %O %S'; +$lualatex = 'internal mylatex %B lualatex %O %S'; +$pdflatex = 'internal mylatex %B pdflatex %O %S'; +$xelatex = 'internal mylatex %B xelatex %O %S'; + + +#--------------------------------- + +sub dot2tex { + # Context for a dot2tex custom dependency assumed. + + # Default options: + my $opts = '--figonly -fpgf -tmath'; + + # File that contains the option string. (Written after analysis of the + # log file for the previous *latex run.) + my $opt_file = "$_[0].dot2texopts"; + + # Ensure that it is known as a source file of this rule, since some + # changes in the main .tex could affect the options only, but not the + # contents of the .dot file + rdb_ensure_file( $rule, $opt_file ); + + if ( -e $opt_file && open( my $fh, '<', $opt_file ) ) { + $opts = <$fh>; + close $opt_file; + } + else { warn "dot2tex: Cannot open '$opt_file'\n"; } + + my @cmd = ( 'dot2tex', split(/\s+/, $opts), '-o', $$Pdest, $$Psource ); + print "dot2tex command line to execute:\n ", join( ' ', @cmd), "\n"; + return system @cmd; +} + +#--------------------------------- + +sub mylatex { + # Context for a *latex rule assumed. + # Run *latex as specified in my arguments, and then process the log file + # to deal with dot2tex conversions needed by the dot2texi package. + + my ($base, @cmd) = @_; + my $log_name = "$aux_dir1$base.log"; + + my $return = system @cmd; + &examine_log_for_dot2tex( $log_name ); + return $return; +} + +#--------------------------------- + +sub examine_log_for_dot2tex { + # Context for a *latex rule assumed. + # From the log file given in the argument to this subroutine, + # find places where dot2tex would be invoked if *latex were used with + # the -shell-escape option. This invocation is on .dot files created + # by the dot2texi package. + # Find the basename of the .dot and .tex files (all assumed to be + # relative to the aux dir). (Basename includes a possible path + # component.) + # Ensure that for each .dot file the .tex file is in the source file of + # the current rule, so that latexmk will know to make a corresponding + # custom dependency. + # Put the option string in a file where the custom dependency for the + # dot-to-tex conversion can find it. + + my $log_name = $_[0]; + + # Map of basenames_with_relative_path of dot/tex file to option string + my %found = (); + + open( my $log_fh, '<', $log_name ) + or ( warn( "examine_log_for_dot2tex: Can't read '$log_name'\n" ), + return + ); +LINE: + while (my $line = <$log_fh> ) { + # Aim: find lines of form runsystem\(dot2tex followed by options + # followed by "-o file.tex file.dot)", for some value of file. + # Allow for continuation lines. + # Often use /.../x with x option to regex, to get space in pattern + # ignored, for readability + + # Ignore lines with wrong start: + if ( $line !~ /^runsystem\(dot2tex \s+ (.*)$/x ) { next; } + + # Rest of command line (after dot2tex) is in $1. + my $args = $1; + + # Only keep going if arguments begin with options and have -o (for + # output file): + if ( $args !~ /(-.*) \s+ -o \s+ (.*) $/x ) { + next LINE; + } + + # Putative options for command, then source and dest file: + my ($opts, $file_part) = ($1, $2); + # Remove superfluous space: + $opts =~ s/\s+/ /g; + $opts =~ s/\s*$//; + if ( $opts !~ /^(-\S+\s*)*$/x ) { + warn "Putative options for dot2tex in '$opts' aren't options\n"; + next LINE; + } + my $attempts = 0; + +CONT_LINE: + while ($attempts < 2) { + $attempts++; + if ($file_part =~ /^(.+) \.tex \s+ \1 \.dot\)/x ) { + ($found{$1} = $opts) =~ s/\s+/ /g; + last CONT_LINE; + } + if (length($line) >= 80) { + if (eof($log_fh)) { last LINE; } + $file_part .= <$log_fh>; + # Remove trailing new line characters: + $file_part =~ s/[\n\r]$//; + } + else { last CONT_LINE; } + } + } + close $log_fh; + + my @missing_files = (); + while (my ($base, $opts) = each %found) { + my $dot = "$aux_dir1$base.dot"; + my $tex = "$aux_dir1$base.tex"; + # File to save options for dot2tex command, so cusdep can read them: + my $opt_file = "$aux_dir1$base.dot2texopts"; + + write_to_file( $opt_file, "$opts\n" ); + if (! -e $tex) { push @missing_files, $tex; } + } + if (@missing_files) { + # No-file lines for missing .tex files will tell latexmk to try + # to find a cusdep to make them: + append_to_file( $log_name, map("No file $_.\n", @missing_files) ); + } +} + +#--------------------------------- + +sub write_to_file { + # Usage: write_to_file( name, items to write ) + my $file = shift; + open( my $fh, ">", $file ) + or (warn "Cannot write to '$file'\n", return 0 ); + print $fh @_; + close( $fh ); +} + +#--------------------------------- + +sub append_to_file { + # Usage: append_to_file( name, items to write ) + my $file = shift; + open( my $fh, ">>", $file ) + or (warn "Cannot append to '$file'\n", return 0 ); + print $fh @_; + close( $fh ); +} + +#--------------------------------- diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/exceltex_latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/exceltex_latexmkrc index e1cf68424fa..df265bdd1ed 100644 --- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/exceltex_latexmkrc +++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/exceltex_latexmkrc @@ -44,7 +44,7 @@ sub excel2tex { # changes, and to do this before running latex/pdflatex again. # First find dependency/ies on .xls files, by parsing the .excltx file, - my $Hsource = new FileHandle; + my $Hsource; my %xls = (); my $source = "$_[0].excltx"; if (! open $Hsource, "<$source") { diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/fix-aux.latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/fix-aux.latexmkrc index aefa206d5a8..abcee8e9f23 100644 --- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/fix-aux.latexmkrc +++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/fix-aux.latexmkrc @@ -3,6 +3,10 @@ # option. (Of the standard distributions, MiKTeX supports -aux-directory, # but TeXLive does not.) +# !!!IMPORTANT: THIS CONFIGURATION IS NO LONGER NECESSARY. From V. 4.74b onwards, +# latexmk can handle the aux_dir isssue itself --- see the documentation on the +# $emulate_aux variable. + foreach my $cmd ('latex', 'lualatex', 'pdflatex', 'xelatex' ) { ${$cmd} = "internal latex_fix_aux $cmd %O %S"; diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/glossaries_latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/glossaries_latexmkrc new file mode 100644 index 00000000000..7e8dfab3ac2 --- /dev/null +++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/glossaries_latexmkrc @@ -0,0 +1,39 @@ +# This shows how to use the glossaries package +# (http://www.ctan.org/pkg/glossaries) and the glossaries-extra package +# (http://www.ctan.org/pkg/glossaries-extra) with latexmk. + +# N.B. There is also the OBSOLETE glossary package +# (http://www.ctan.org/pkg/glossary), which has some differences. See item 2. + +# 1. If you use the glossaries or the glossaries-extra package, then you can use: + + add_cus_dep( 'acn', 'acr', 0, 'makeglossaries' ); + add_cus_dep( 'glo', 'gls', 0, 'makeglossaries' ); + $clean_ext .= " acr acn alg glo gls glg"; + + sub makeglossaries { + my ($base_name, $path) = fileparse( $_[0] ); + my @args = ( "-q", "-d", $path, $base_name ); + if ($silent) { unshift @args, "-q"; } + return system "makeglossaries", "-d", $path, $base_name; + } + +# 2. The above will tend to run makeglossaries more often than needed, since +# each out of date file will trigger the use of makeglossaries, even +# though makeglossaries makes all the glossaries. The following solution +# solves this, but at the expense of not having the convenience that +# makeglossaries can change how it makes the glossaries depending on the +# settings of the glossaries package. +# A better solution will need more advanced work. +# +# add_cus_dep( 'acn', 'acr', 0, 'makeglossaries' ); +# add_cus_dep( 'glo', 'gls', 0, 'makeglossaries' ); +# $clean_ext .= " acr acn alg glo gls glg"; +# +# sub makeglossaries { +# my @args = ( "-s", "$_[0].ist", "-t", "$$Psource.ilg", +# "-o", $$Pdest, $$Psource ); +# if ($silent) { unshift @args, "-q"; } +# return system "makeindex", @args; +# } + diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/glossary_latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/glossary_latexmkrc deleted file mode 100644 index cd75f2d2d0f..00000000000 --- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/glossary_latexmkrc +++ /dev/null @@ -1,44 +0,0 @@ -# This shows how to use the glossaries package -# (http://www.ctan.org/pkg/glossaries) and the glossaries-extra package -# (http://www.ctan.org/pkg/glossaries-extra) with latexmk. - -# N.B. There is also the OBSOLETE glossary package -# (http://www.ctan.org/pkg/glossary), which has some differences. See item 2. - -# 1. If you use the glossaries or the glossaries-extra package, then you use: - - add_cus_dep( 'acn', 'acr', 0, 'makeglossaries' ); - add_cus_dep( 'glo', 'gls', 0, 'makeglossaries' ); - $clean_ext .= " acr acn alg glo gls glg"; - sub makeglossaries { - my ($base_name, $path) = fileparse( $_[0] ); - pushd $path; - my $return = system "makeglossaries", $base_name; - popd; - return $return; - } - - -# 2. If you use the OBSOLETE glossary package, then you can do the following: -# (Note that the code lines are commented out to avoid trouble when this -# file is simply copied into a latexmkrc or this file is arranged to be -# read by latexmk, and one of the modern packages glossaries and -# glossaries-extra is used.) - - ## For the main glossary: - #add_cus_dep( 'glo', 'gls', 0, 'makeglo2gls' ); - #sub makeglo2gls { - # system("makeindex -s \"$_[0].ist\" -t \"$_[0].glg\" -o \"$_[0].gls\" \"$_[0].glo\"" ); - #} - - ## For acronyms: - ## - ## ===> WARNING: The code below is ONLY FOR PACKAGE glossary, NOT FOR - ## glossaries and glossaries-extra. In the current glossaries and - ## glossaries-extra packages the roles of the .acr and .acn files are - ## exchanged compared with the old glossary package. Hence the the - ## code below will fail with the more modern packages. - #add_cus_dep( 'acr', 'acn', 0, 'makeacr2acn' ); - #sub makeacr2acn { - # system( "makeindex -s \"$_[0].ist\" -t \"$_[0].alg\" -o \"$_[0].acn\" \"$_[0].acr\"" ); - #} diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/minted_latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/minted_latexmkrc new file mode 100644 index 00000000000..076c7fc15bd --- /dev/null +++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/minted_latexmkrc @@ -0,0 +1,38 @@ +# For the minted package (which does nice formatting of source code): +# +# 1. Need to use -shell-escape on *latex command. +# 2. Need to arrange passing of the output dir (actually aux dir if it +# differs from out dir) to minted. Then this directory information does +# not have to be specified in the .tex file itself. +# 3. In some cases, latexmk does an extra run of *latex than is +# needed. This is solved by getting latexmk to ignore certain lines in +# the aux file when latexmk looks for changes. These lines are written +# by minted and are irrelevant to the output file from *latex. +# +# The reason for the extra run of *latex that may happen is because +# after minted runs pygmentize to make the nicely formatted source code, +# minted saves cached information about the run(s) of pygmentize. This +# information is put in the aux file. So latexmk sees the changed aux +# file, and knows that may affect the output of *latex, which it +# therefore reruns. However the minted-written lines do not affect the +# output of *latex. +# +# The method works if the aux dir's name contains a string of MORE than one +# space That's a problem in minted's calls to pygmentize. +# Single spaces in the name are OK. +# Generally it helps to use only aux_dir and out_dir names without spaces, +# to avoid trouble. + +&set_tex_cmds( '-shell-escape %O ' + . '\'\PassOptionsToPackage{outputdir={%Y}}{minted}\input{%S}\'' + ); +# (Here the outer level of single quotes is for Perl. The dot is for +# Perl's string concatenation. The \' tell Perl to put actual single +# quotes in the string (given to the shell). In Unix, the shell is sh (or +# equivalent), so the string inside the single quotes is a single argument +# to the command is not changed at all.) +# +$hash_calc_ignore_pattern{aux} = '^\\\\gdef\\\\minted@oldcachelist\{,'. + '|^\s*default\.pygstyle,'. + '|^\s*[[:xdigit:]]+\.pygtex'; + diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/pythontex-latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/pythontex-latexmkrc index ba02de3ee78..825706a630b 100644 --- a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/pythontex-latexmkrc +++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/pythontex-latexmkrc @@ -21,7 +21,7 @@ sub mypythontex { my $result_dir = $aux_dir1."pythontex-files-$$Pbase"; my $ret = Run_subst( $pythontex, 2 ); rdb_add_generated( glob "$result_dir/*" ); - my $fh = new FileHandle $$Pdest, "r"; + open( my $fh, "<", $$Pdest ); if ($fh) { while (<$fh>) { if ( /^%PythonTeX dependency:\s+'([^']+)';/ ) { diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.cmd b/Master/texmf-dist/doc/support/latexmk/latexmk.cmd new file mode 100644 index 00000000000..63c4de15d0e --- /dev/null +++ b/Master/texmf-dist/doc/support/latexmk/latexmk.cmd @@ -0,0 +1,24 @@ +Rem This batch file is only of interest to a small subset of **Windows** users. + +Rem Under modern TeX distributions, MiKTeX and TeXLive, you do **NOT** +Rem need this batch file. Both distributions have a latexmk executable +Rem that correctly runs the latexmk Perl script itself. This file +Rem is only useful if you need to bypass that for some reason, e.g., +Rem if you have not upgraded to a current year's TeXLive, but want to +Rem run the latest version of latexmk. +Rem You may have to modify you copy of this file for your needs. + +Rem ============================== + +Rem This batch file executes perl so as to run latexmk.pl. As written it +Rem assumes that latexmk.pl is in a directory in the +Rem environment variable PATH. Of course this file latexmk.cmd should +Rem itself also have been copied to a directory in PATH. +Rem +Rem In addition, this file assumes that perl.exe is in a directory in PATH. +Rem If not, you should replace 'perl' by the full pathname of the perl +Rem executable, e.g., 'C:\perl\bin\perl.exe' or +Rem 'C:\Strawberry\perl\bin\perl.exe. (Current distributions of Perl +Rem for Windows do set PATH appropriately when installed in the default way. + +perl -S latexmk.pl %* diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.pdf b/Master/texmf-dist/doc/support/latexmk/latexmk.pdf Binary files differindex 3f5563b53d2..5fe93726fa0 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 53a9000985d..385fe1d21bb 100644 --- a/Master/texmf-dist/doc/support/latexmk/latexmk.txt +++ b/Master/texmf-dist/doc/support/latexmk/latexmk.txt @@ -61,7 +61,7 @@ DESCRIPTION - 20 November 2021 1 + 17 March 2022 1 @@ -127,7 +127,7 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE - 20 November 2021 2 + 17 March 2022 2 @@ -193,7 +193,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 3 + 17 March 2022 3 @@ -259,7 +259,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 4 + 17 March 2022 4 @@ -325,7 +325,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 5 + 17 March 2022 5 @@ -391,7 +391,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 6 + 17 March 2022 6 @@ -457,7 +457,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 7 + 17 March 2022 7 @@ -523,7 +523,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 8 + 17 March 2022 8 @@ -589,7 +589,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 9 + 17 March 2022 9 @@ -655,7 +655,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 10 + 17 March 2022 10 @@ -721,7 +721,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 11 + 17 March 2022 11 @@ -787,7 +787,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 12 + 17 March 2022 12 @@ -853,7 +853,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 13 + 17 March 2022 13 @@ -919,7 +919,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 14 + 17 March 2022 14 @@ -985,7 +985,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 15 + 17 March 2022 15 @@ -1051,7 +1051,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 16 + 17 March 2022 16 @@ -1117,7 +1117,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 17 + 17 March 2022 17 @@ -1183,7 +1183,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 18 + 17 March 2022 18 @@ -1249,7 +1249,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 19 + 17 March 2022 19 @@ -1315,7 +1315,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 20 + 17 March 2022 20 @@ -1381,7 +1381,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 21 + 17 March 2022 21 @@ -1447,7 +1447,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 22 + 17 March 2022 22 @@ -1513,7 +1513,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 23 + 17 March 2022 23 @@ -1579,7 +1579,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 24 + 17 March 2022 24 @@ -1645,7 +1645,7 @@ DEALING WITH ERRORS, PROBLEMS, ETC - 20 November 2021 25 + 17 March 2022 25 @@ -1711,7 +1711,7 @@ ALLOWING FOR CHANGE OF OUTPUT FILE TYPE - 20 November 2021 26 + 17 March 2022 26 @@ -1777,7 +1777,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 27 + 17 March 2022 27 @@ -1843,7 +1843,7 @@ CONFIGURATION/INITIALIZATION (RC) FILES - 20 November 2021 28 + 17 March 2022 28 @@ -1909,7 +1909,7 @@ HOW TO SET VARIABLES IN INITIALIZATION FILES - 20 November 2021 29 + 17 March 2022 29 @@ -1975,7 +1975,7 @@ FORMAT OF COMMAND SPECIFICATIONS - 20 November 2021 30 + 17 March 2022 30 @@ -2041,7 +2041,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 31 + 17 March 2022 31 @@ -2107,7 +2107,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 32 + 17 March 2022 32 @@ -2173,7 +2173,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 33 + 17 March 2022 33 @@ -2239,7 +2239,7 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES - 20 November 2021 34 + 17 March 2022 34 @@ -2305,7 +2305,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 35 + 17 March 2022 35 @@ -2371,7 +2371,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 36 + 17 March 2022 36 @@ -2437,7 +2437,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 37 + 17 March 2022 37 @@ -2503,7 +2503,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 38 + 17 March 2022 38 @@ -2514,9 +2514,9 @@ LATEXMK(1) General Commands Manual LATEXMK(1) files to be deleted are restricted to those explicitly specified by patterns configured in the variables clean_ext, - clean_full_ext, and @generated_exts, together with those very - standard cases that are hardwired into latexmk (e.g., .log - files). + clean_full_ext, and @generated_exts. Standard cases (e.g., .log + files) appear in latexmk's initial value for the array @gener- + ated_exts. $cleanup_mode [0] If nonzero, specifies cleanup mode: 1 for full cleanup, 2 for @@ -2548,94 +2548,94 @@ LATEXMK(1) General Commands Manual LATEXMK(1) figures*.log, and pythontex-files-FOO/*, where FOO stands for the basename of the file being processed (as in FOO.tex). - The files to be deleted are relative to the directory specified - by $aux_dir. (Note that if $out_dir but not $aux_dir is set, - then in its initialization, latexmk sets $aux_dir equal to - $out_dir. A normal situation is therefore that $aux_dir equals - $out_dir, which is the only case supported by TeXLive, unlike - MiKTeX.) + Most of the files to be deleted are relative to the directory + specified by $aux_dir. Note that if $out_dir but not $aux_dir + is set, then in its initialization, latexmk sets $aux_dir equal + to $out_dir. A normal situation is therefore that $aux_dir + equals $out_dir, which is the only case directly supported by + TeXLive, unlike MiKTeX. Note that even with TeXLive latexmk + does now support different values for the directories -- see the + explanation of the $emulate_aux variable. + + If $out_dir and $aux_dir different, latexmk actually deletes any + files of the specified names in both $aux_dir and $out_dir; this + is because under certain error conditions, the files may be put + in $out_dir instead of $aux_dir. This also handles the case of + deleting any fls file, since that file is in $out_dir. The filenames specified for a clean-up operation can refer not only to regular files but also to directories. Directories are only deleted if they are empty. An example of an application is - to pythontex, which creates files in a particular directory. - You can arrange to remove both the files and the directory by - setting - $clean_ext = "pythontex-files-%R pythontex-files-%R"; - See also the variable @generated_exts. + 17 March 2022 39 - 20 November 2021 39 +LATEXMK(1) General Commands Manual LATEXMK(1) + to pythontex, which creates files in a particular directory. + You can arrange to remove both the files and the directory by + setting -LATEXMK(1) General Commands Manual LATEXMK(1) + $clean_ext = "pythontex-files-%R pythontex-files-%R"; + See also the (array) variable @generated_exts. In the past, + this variable had certain uses beyond that of $clean_ext. But + now, they accomplish the same things. In fact, after initial- + ization including the processing of command line options, la- + texmk simply appends the list of extensions in $clean_ext to the + array @generated_exts. $clean_full_ext [""] - Extra extensions of files for latexmk to remove when the -C op- - tion is selected, i.e., extensions of files to remove when the + Extra extensions of files for latexmk to remove when the -C op- + tion 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. - The files specified by $clean_full_ext to be deleted are rela- + The files specified by $clean_full_ext to be deleted are rela- tive to the directory specified by $out_dir. $compiling_cmd [""], $failure_cmd [""], $warning_cmd [""], $success_cmd [""] - These variables specify commands that are executed at certain - points of compilations. One motivation for their existence is - to allow very useful convenient visual indications of compila- - tion status even when the window receiving the screen output of - the compilation is hidden. This is particularly useful in pre- + These variables specify commands that are executed at certain + points of compilations. One motivation for their existence is + to allow very useful convenient visual indications of compila- + tion status even when the window receiving the screen output of + the compilation is hidden. This is particularly useful in pre- view-continuous mode. - The commands are executed at the following points: $compil- - ing_cmd at the start of compilation, $success_cmd at the end of - a completely successful compilation, $failure_cmd at the end of + The commands are executed at the following points: $compil- + ing_cmd at the start of compilation, $success_cmd at the end of + a completely successful compilation, $failure_cmd at the end of an unsuccessful compilation, $warning_cmd at the of an otherwise successful compilation that gives warnings about undefined cita- tions or references or about multiply defined references. If any - of above variables is undefined or blank (the default situa- + of above variables is undefined or blank (the default situa- tion), then the corresponding command is not executed. - However, when $warning_cmd is not set, then in the case of a - compilation with warnings about references or citations, but - with no other error, one or other of $success_cmd or $fail- - ure_cmd is used (if it is set) according to the setting of + However, when $warning_cmd is not set, then in the case of a + compilation with warnings about references or citations, but + with no other error, one or other of $success_cmd or $fail- + ure_cmd is used (if it is set) according to the setting of $warnings_as_errors. An example of a simple 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 - --name \"%D OK\""; - $warning_cmd = "xdotool search --name \"%D\" ". - "set_window --name \"%D CITE/REF ISSUE\""; - $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 - file, which is the previewed file. The above commands result in - an appropriate string being appended to the filename in the + $success_cmd = "xdotool search --name \"%D\" set_window - 20 November 2021 40 + 17 March 2022 40 @@ -2644,23 +2644,36 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - window title: " compiling", " OK", or " FAILURE". + --name \"%D OK\""; + $warning_cmd = "xdotool search --name \"%D\" ". + "set_window --name \"%D CITE/REF ISSUE\""; + $failure_cmd = "xdotool search --name \"%D\" set_window + --name \"%D 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 + 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 window to know the status of the compilation. - More complicated situations can best be handled by defining a - Perl subroutine to invoke the necessary commands, and using the - "internal" keyword in the definitions to get the subroutine to + More complicated situations can best be handled by defining a + Perl subroutine to invoke the necessary commands, and using the + "internal" keyword in the definitions to get the subroutine to be invoked. (See the section "Format of Command Specifications" for how to do this.) - Naturally, the above settings that invoke the xdotool program - are only applicable when the X-Window system is used for the + Naturally, the above settings that invoke the xdotool program + are only applicable when the X-Window system is used for the relevant window(s). For other cases, you will have to find what software solutions are available. @@ -2669,15 +2682,15 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Custom dependency list -- see section on "Custom Dependencies". @default_excluded_files [()] - When latexmk is invoked with no files specified on the command + When latexmk is invoked with no files specified on the command line, then, by default, it will process all files in the current directory with the extension .tex. (In general, it will process the files specified in the @default_files variable.) But sometimes you want to exclude particular files from this de- - fault list. In that case you can specify the excluded files in + fault list. In that case you can specify the excluded files in the array @default_excluded_files. For example if you wanted to - process all .tex files with the exception of common.tex, which + process all .tex files with the exception of common.tex, which is a not a standard alone LaTeX file but a file input by some or all of the others, you could do @@ -2685,40 +2698,40 @@ LATEXMK(1) General Commands Manual LATEXMK(1) @default_excluded_files = ("common.tex"); - If you have a variable or large number of files to be processed, - this method saves you from having to list them in detail in @de- - fault_files and having to update the list every time you change - the set of files to be processed. - Notes: 1. This variable has no effect except when no files are - specified on the latexmk command line. 2. Wildcards are allowed - in @default_excluded_files. - @default_files [("*.tex")] - Default list of files to be processed. - If no filenames are specified on the command line, latexmk + 17 March 2022 41 - 20 November 2021 41 +LATEXMK(1) General Commands Manual LATEXMK(1) + If you have a variable or large number of files to be processed, + this method saves you from having to list them in detail in @de- + fault_files and having to update the list every time you change + the set of files to be processed. -LATEXMK(1) General Commands Manual LATEXMK(1) + Notes: 1. This variable has no effect except when no files are + specified on the latexmk command line. 2. Wildcards are allowed + in @default_excluded_files. + @default_files [("*.tex")] + Default list of files to be processed. - processes all tex files specified in the @default_files vari- - able, which by default is set to all tex files ("*.tex") in the - current directory. This is a convenience: just run latexmk and - it will process an appropriate set of files. But sometimes you + If no filenames are specified on the command line, latexmk pro- + cesses all tex files specified in the @default_files variable, + which by default is set to all tex files ("*.tex") in the cur- + rent directory. This is a convenience: just run latexmk and it + will process an appropriate set of files. But sometimes you want only some of these files to be processed. In this case you - can list the files to be processed by setting @default_files in - an initialization file (e.g., the file "latexmkrc" in the cur- - rent directory). Then if no files are specified on the command - line then the files you specify by setting @default_files are + can list the files to be processed by setting @default_files in + an initialization file (e.g., the file "latexmkrc" in the cur- + rent directory). Then if no files are specified on the command + line then the files you specify by setting @default_files are processed. Three examples: @@ -2729,55 +2742,54 @@ LATEXMK(1) General Commands Manual LATEXMK(1) @default_files = ("*.tex", "*.dtx"); - Note that more than file may be given, and that the default ex- + Note that more than file may be given, and that the default ex- tension is ".tex". Wild cards are allowed. The parentheses are because @default_files is an array variable, i.e., a sequence of filename specifications is possible. - If you want latexmk to process all .tex files with a few excep- + If you want latexmk to process all .tex files with a few excep- tions, see the @default_excluded_files array variable. $dependents_phony [0] - If a list of dependencies is output, this variable determines - whether to include a phony target for each source file. If you - use the dependents list in a Makefile, the dummy rules work - around errors make gives if you remove header files without up- + If a list of dependencies is output, this variable determines + whether to include a phony target for each source file. If you + use the dependents list in a Makefile, the dummy rules work + around errors make gives if you remove header files without up- dating the Makefile to match. $dependents_list [0] - Whether to display a list(s) of dependencies at the end of a + 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). + 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 - $do_cd [0] - Whether to change working directory to the directory specified - for the main source file before processing it. The default be- - havior is not to do this, which is the same as the behavior of - *latex programs. This variable is set by the -cd and -cd- op- - tions on latexmk's command line. - $dvi_filter [empty] - The dvi file filter to be run on the newly produced dvi file + 17 March 2022 42 - 20 November 2021 42 +LATEXMK(1) General Commands Manual LATEXMK(1) + "-", then the dependency list is set to stdout (i.e., normally + the screen). -LATEXMK(1) General Commands Manual LATEXMK(1) + $do_cd [0] + Whether to change working directory to the directory specified + for the main source file before processing it. The default be- + havior is not to do this, which is the same as the behavior of + *latex programs. This variable is set by the -cd and -cd- op- + tions on latexmk's command line. - before other processing. Equivalent to specifying the -dF op- - tion. + $dvi_filter [empty] + The dvi file filter to be run on the newly produced dvi file be- + fore other processing. Equivalent to specifying the -dF option. $dvi_mode [See below for default] If nonzero, generate a dvi version of the document. Equivalent @@ -2818,30 +2830,30 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $dvipdf = "dvipdfm %O -o %D %S"; - WARNING: The default dvipdf script generates pdf files with - bitmapped fonts, which do not look good when viewed by acroread. - That script should be modified to give dvips the options "-P - pdf" to ensure that type 1 fonts are used in the pdf file. - $dvipdf_silent_switch ["-q"] - Switch(es) for dvipdf program when silent mode is on. - N.B. The standard dvipdf program runs silently, so adding the - silent switch has no effect, but is actually innocuous. But if - an alternative program is used, e.g., dvipdfmx, then the silent - switch has an effect. The default setting is correct for + 17 March 2022 43 - 20 November 2021 43 +LATEXMK(1) General Commands Manual LATEXMK(1) -LATEXMK(1) General Commands Manual LATEXMK(1) + WARNING: The default dvipdf script generates pdf files with + bitmapped fonts, which do not look good when viewed by acroread. + That script should be modified to give dvips the options "-P + pdf" to ensure that type 1 fonts are used in the pdf file. + $dvipdf_silent_switch ["-q"] + Switch(es) for dvipdf program when silent mode is on. + N.B. The standard dvipdf program runs silently, so adding the + silent switch has no effect, but is actually innocuous. But if + an alternative program is used, e.g., dvipdfmx, then the silent + switch has an effect. The default setting is correct for dvipdfm and dvipdfmx. $dvips ["dvips %O -o %D %S"] @@ -2883,31 +2895,31 @@ LATEXMK(1) General Commands Manual LATEXMK(1) 4 => run a command to do the update. The command is speci- fied by the variable $dvi_update_command. - See information on the variable $pdf_update_method for an exam- - ple of updating by command. + See information on the variable $pdf_update_method for an - $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 ap- - propriate for xdvi on a UNIX system. - $emulate_aux [0] - Whether to emulate the use of aux_dir when $aux_dir and $out_dir - are different, rather than using the -aux-directory option for + 17 March 2022 44 - 20 November 2021 44 +LATEXMK(1) General Commands Manual LATEXMK(1) -LATEXMK(1) General Commands Manual LATEXMK(1) + example of updating by command. + $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 ap- + propriate for xdvi on a UNIX system. + $emulate_aux [0] + Whether to emulate the use of aux_dir when $aux_dir and $out_dir + are different, rather than using the -aux-directory option for the *latex programs. (MiKTeX supports -aux-directory, but TeXLive doesn't.) @@ -2950,29 +2962,29 @@ LATEXMK(1) General Commands Manual LATEXMK(1) the program was started. If the modification time is earlier than when the program was started, the file is a leftover file, which latexmk treats as if it were not created. If the filetime - is at least the program start time, then it can be assumed that - the file was created in the current run. - Unfortunately, this test can fail if the file is on a remote - system, since its system time is not necessarily synchronized - with that of the local system; the timestamps on the remote - files are set by the remote system, not the local system. Gen- - erally, modern operating systems regularly synchronize their - time with a server, so the non-synchronization is mostly small - (a second or so, or a few seconds). But even a small difference - can mess up latexmk's test. + 17 March 2022 45 - 20 November 2021 45 +LATEXMK(1) General Commands Manual LATEXMK(1) -LATEXMK(1) General Commands Manual LATEXMK(1) + is at least the program start time, then it can be assumed that + the file was created in the current run. + Unfortunately, this test can fail if the file is on a remote + system, since its system time is not necessarily synchronized + with that of the local system; the timestamps on the remote + files are set by the remote system, not the local system. Gen- + erally, modern operating systems regularly synchronize their + time with a server, so the non-synchronization is mostly small + (a second or so, or a few seconds). But even a small difference + can mess up latexmk's test. Latexmk measures the time difference between the time on the two systems and compensates for this. But the measurement (in a @@ -3003,35 +3015,23 @@ LATEXMK(1) General Commands Manual LATEXMK(1) ing unrecognized cross references. Equivalent to specifying the -f option. - @generated_exts [( aux , bbl , idx , ind , lof , lot , out , toc , - $fdb_ext )] + + @generated_exts [( 'aux', 'bcf', 'fls', 'idx', 'ind', 'lof', 'lot', + 'out', 'toc', 'blg', 'ilg', 'log', 'xdv' )] + 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, - either directly or indirectly. - - This list specifies files known to be generated by *latex. It - is used in two ways: (a) The specified files are deleted in a - cleanup operation (with the -c, -C, -CA, -g and -gg options), - and (b) It affects the determination of whether a rerun of *la- - tex is needed after a run that gives an error. - - (Concerning item (b): Normally, a change of a source file during - a run should provoke a rerun. This includes a file generated by - LaTeX, e.g., an aux file, that is read in on subsequent runs. - But after a run that results in an error, a new run should not - occur until the user has made a change in the files. But the - user may have corrected an error in a source .tex file during - the run. So latexmk needs to distinguish user-generated and au- - tomatically generated files; it determines the automatically - generated files as those with extensions in the list in @gener- - ated_exts.) + during processing, and that should be deleted during a main + clean up operation, as invoked by the command line option -c. + (The use of -C or -gg gives this clean up and more.) - A convenient way to add an extra extension to the list, without - losing the already defined ones is to use a push command in the + The default values are extensions for standard files generated + by *latex, bibtex, and the like. (Note that the clean up also + deletes the fdb_latexmk file, but that's separately coded into + latexmk, currently.) - 20 November 2021 46 + 17 March 2022 46 @@ -3040,6 +3040,29 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) + After initialization of latexmk and the processing of its com- + mand line, the items in clean_ext are appended to @gener- + ated_exts. So these two variables have the same meaning (con- + trary to older versions of latexmk). + + The items in @generated_exts are normally extensions of files, + whose base name is the same as the main tex file. But it is + also possible to specify patterns including that basename --- + see the explanation of the variable $clean_ext. + + In addition to specifying files to be deleted in a clean up, la- + texmk uses the same specification to assist its examination of + changes in source files: Under some situations it needs to find + those changes in files (since a previous run) that are expected + to be due to the user editing a file. This contrasts with the + cases of files that are generated by some program run by latexmk + and that differ from the results of the previous run. This use + of @generated_exts is normally unimportant, given the usual ac- + curacy of latexmk's other ways of determining these generated + files. + + A convenient way to add an extra extension to the list, without + losing the already defined ones is to use a push command in the line in an RC file. E.g., push @generated_exts, "end"; @@ -3048,6 +3071,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) tensions. (This extension is used by the RevTeX package, for example.) + $go_mode [0] If nonzero, process files regardless of timestamps, and is then equivalent to the -g option. @@ -3071,6 +3095,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: '; + + + 17 March 2022 47 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + 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 @@ -3094,18 +3129,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) causes lines starting with either "^%%CreationDate: " or "^%%Ti- tle: " to be ignored. - - - - 20 November 2021 47 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - It may happen that a pattern to be ignored is specified in, for example, in a system or user initialization file, and you wish to remove this in a file that is read later. To do this, you @@ -3138,6 +3161,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Suppose you had .tex files test1.tex and test2.tex. Then when you run + + + 17 March 2022 48 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + latexmk -pdf *.tex both files will be compiled. The .aux, .log, and .pdf files @@ -3160,18 +3194,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) sibilities listed in the FORMAT OF COMMAND SPECIFICATIONS do not apply. The internal and start keywords are not available. A simple command specification with possible options and then "%S" - - - - 20 November 2021 48 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - is all that is guaranteed to work. Note that for other com- mands, "%S" is substituted by a single source file. In contrast, for $kpsewhich, "%S" may be substituted by a long list of space- @@ -3204,6 +3226,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $latex = "latex --src-specials %O %S"; + + + + 17 March 2022 49 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + To do a coordinated setting of all of $latex, $pdflatex, $luala- tex, and $xelatex, see the section "Advanced Configuration". @@ -3225,20 +3259,8 @@ LATEXMK(1) General Commands Manual LATEXMK(1) 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_in- - put_ext. They are used as in the following examples are - - - - 20 November 2021 49 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - - possible lines in an initialization file: + put_ext. They are used as in the following examples are possi- + ble lines in an initialization file: remove_input_ext( 'latex', 'tex' ); @@ -3270,6 +3292,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Under MS-Windows (unlike UNIX/Linux), there is no standard pro- gram for printing files. But there are ways you can do it. For + + + + 17 March 2022 50 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + example, if you have gsview installed, you could use it with the option "/p": @@ -3293,17 +3327,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Under MS-Windows you could set this to use gsview, if it is in- stalled, e.g., - - - 20 November 2021 50 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p'; If gsview is installed in a different directory, you will need @@ -3335,6 +3358,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) fault extensions are 'tex', 'pdf', 'jpg, and 'png'. See details of the %latex_input_extensions for other information + + + + 17 March 2022 51 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + that equally applies to %lualatex_input_extensions. $lualatex_silent_switch ["-interaction=batchmode"] @@ -3357,19 +3392,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) will refuse to write its output and log files, for security rea- sons. - - - - - 20 November 2021 51 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - $makeindex_silent_switch ["-q"] Switch(es) for the index processing program when silent mode is on. @@ -3401,10 +3423,22 @@ LATEXMK(1) General Commands Manual LATEXMK(1) stitution from "/" to "\", by default. However there are also programs on MS-Windows for which a back - slash "\" is interpreted differently than as a directory separa- - tor; for these the directory separator should be "/". Programs - with this behavior include all the *latex programs in the - TeXLive implementation (but not the MiKTeX implementation). + slash "\" is interpreted differently than as a directory + + + + 17 March 2022 52 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + + separator; for these the directory separator should be "/". + Programs with this behavior include all the *latex programs in + the TeXLive implementation (but not the MiKTeX implementation). Hence if you use TeXLive on MS-Windows, then $MSWin_back_slash should be set to zero. @@ -3424,18 +3458,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) The effect of this variable (when non-blank) is achieved by us- ing the -output-directory option of *latex. This exists in the - - - - 20 November 2021 52 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - usual current (Dec. 2011 and later) implementations of TeX, i.e., MiKTeX and TeXLive. But it may not be present in other versions. @@ -3468,6 +3490,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) equal to 1, generate a pdf version of the document using pdfla- tex, using the command specified by the $pdflatex variable. If equal to 2, generate a pdf version of the document from the ps + + + + 17 March 2022 53 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + file, by using the command specified by the $ps2pdf variable. If equal to 3, generate a pdf version of the document from the dvi file, by using the command specified by the $dvipdf vari- @@ -3490,18 +3524,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $pdflatex = "pdflatex --shell-escape %O %S"; - - - - 20 November 2021 53 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - (In some earlier versions of latexmk, you needed to use an as- signment to $pdflatex to allow the use of lualatex or xelatex instead of pdflatex. There are now separate configuration vari- @@ -3534,6 +3556,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) See details of the $latex_silent_switch for other information that equally applies to $pdflatex_silent_switch. + + + + 17 March 2022 54 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + $pdf_previewer ["start acroread %O %S"] The command to invoke a pdf-previewer. @@ -3556,18 +3590,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) ample, SumatraPDF or gsview is used to view pdf files. Important note: Normally you will want to have a previewer run - - - - 20 November 2021 54 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - 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 @@ -3601,6 +3623,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $pdf_update_method = 4; $pdf_update_command = "xpdf -remote %R -reload"; + + + 17 March 2022 55 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + The first setting arranges for the xpdf program to be used in its "remote server mode", with the server name specified as the rootname of the TeX file. The second setting arranges for up- @@ -3622,18 +3655,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) with their default settings of $pscmd. Setting the variable to -1 is used to indicate that $pscmd is - - - - 20 November 2021 55 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - not to be used. $postscript_mode [0] @@ -3667,6 +3688,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) option. Which previewer is run depends on the other settings, see the command line options -view=, and the variable $view. + + + + 17 March 2022 56 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + $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 @@ -3688,18 +3721,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) 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 - - - - 20 November 2021 56 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - the previewer about file changes). Each line of the output of this command is assumed to correspond @@ -3733,6 +3754,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) WARNING: Linux systems may have installed one (or more) versions of gv under different names, e.g., ggv, kghostview, etc, but + + + + 17 March 2022 57 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + perhaps not one actually called gv. Important note: Normally you will want to have a previewer run @@ -3755,17 +3788,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) command, this is the command that is run. See the information for the variable $ps_update_method. - - - 20 November 2021 57 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - $ps_update_method [0 under UNIX, 1 under MS-Windows] How the postscript viewer updates its display when the .ps file has changed. See the information on the variable $dvi_up- @@ -3797,6 +3819,19 @@ LATEXMK(1) General Commands Manual LATEXMK(1) The same as $always_view_file_via_temporary, except that it only applies in preview-continuous mode (-pvc option). + + + + + 17 March 2022 58 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + $quote_filenames [1] This specifies whether substitutions for placeholders in command specifications (as in $pdflatex) are surrounded by double @@ -3820,18 +3855,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Whether to use the -recorder option to (latex 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 - - - - 20 November 2021 58 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - then use this file to improve its detection of source files and generated files after a run of *latex. @@ -3863,6 +3886,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) output or aux directories.] The default under MSWin and Cygwin is ';' and under UNIX-like + + + + 17 March 2022 59 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + 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 @@ -3887,17 +3922,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) lence_logfile_warning_list and -silence_logfile_warning_list- also set this variable. - - - 20 November 2021 59 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - Note that multiple occurrences for the same undefined object on the same page and same line will be compressed to a single warn- ing. @@ -3927,6 +3951,19 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $success_cmd [undefined] See the documentation for $compiling_cmd. + + + + + 17 March 2022 60 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + $tmpdir [See below for default] Directory to store temporary files that latexmk may generate while running. @@ -3953,17 +3990,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) do this. The intent of calling make from latexmk is merely to detect dependencies. - - - 20 November 2021 60 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - $view ["default"] Which kind of file is to be previewed if a previewer is used. The possible values are "default", "dvi", "ps", "pdf". The @@ -3992,6 +4018,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) The default behavior is normally satisfactory in the usual edit- compile-edit cycle. But, for example, latexmk can also be used + + + + 17 March 2022 61 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + as part of a build process for some bigger project, e.g., for creating documentation in the build of a software application. Then it is often sensible to treat citation and reference warn- @@ -4018,18 +4056,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) The program to make a pdf file from an xdv file (used in con- junction with xelatex when $pdf_mode=5). - - - - 20 November 2021 61 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - $xdvipdfmx_silent_switch ["-q"] Switch(es) for the xdvipdfmx program when silent mode is on. @@ -4058,6 +4084,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) not been found, and the file is given without an extension. This typically happens when LaTeX commands of the form \in- put{file} or \includegraphics{figure}, when the relevant source + + + + 17 March 2022 62 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + file does not exist. In this situation, latexmk searches for custom dependencies to @@ -4085,17 +4123,6 @@ CUSTOM DEPENDENCIES in the .tex file. - - - 20 November 2021 62 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - Defining a custom dependency: The old method of configuring latexmk to use a custom dependency was to directly manipulate the @cus_dep_list array that contains information @@ -4123,6 +4150,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) 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 + + + + 17 March 2022 63 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + we are converting from doesn't exist, then no action is taken. Generally, the appropriate value of must is zero. @@ -4150,18 +4189,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) tects that a run of *latex needs to read a file, like a graphics file, whose extension is the to-extension of a custom dependency. Then la- texmk examines whether a file exists with the same name, but with the - - - - 20 November 2021 63 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - corresponding from-extension, as specified in the custom-dependency. If it does, then a corresponding instance of the custom dependency is created, after which the rule is invoked whenever the destination file @@ -4189,6 +4216,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Note for advanced usage: The operating system's environment variable TEXINPUTS can be used to specify a search path for finding files by la- tex etc. Correspondingly, when a missing file is reported, latexmk + + + + 17 March 2022 64 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + looks in the directories specified in TEXINPUTS as well as in the cur- rent directory, to find a source file from which an instance of a cus- tom dependency can be used to make the missing file. @@ -4216,18 +4255,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) initialization file), the latexmk will delete this rule before making the new one. - - - - 20 November 2021 64 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - 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 @@ -4255,6 +4282,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) } Note 1: In the command lines given in the system commands in the above + + + + 17 March 2022 65 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + examples, double quotes have been inserted around the file names (im- plemented by '\"' in the Perl language). They immunize the running of the program against special characters in filenames. Very often these @@ -4281,19 +4320,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) need it. - - - - - 20 November 2021 65 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - Removing custom dependencies, and when you might need to do this: If you have some general custom dependencies defined in the system or user initialization file, you may find that for a particular project @@ -4321,13 +4347,25 @@ LATEXMK(1) General Commands Manual LATEXMK(1) file. This method has been available since very old versions of la- texmk, and many examples can be found, e.g., on the web. - However in later versions of latexmk the internal structure of the im- - plementation of its "rules" for the steps of processing, including cus- - tom dependencies, became much more powerful. The function implementing - a custom dependency is executed within a special context where a number - of extra variables and subroutines are defined. Publicly documented - ones, intended to be long-term stable, are listed below, under the - heading "Variables and subroutines for processing a rule". + However in later versions of latexmk the internal structure of the + + + + 17 March 2022 66 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + + implementation of its "rules" for the steps of processing, including + custom dependencies, became much more powerful. The function imple- + menting a custom dependency is executed within a special context where + a number of extra variables and subroutines are defined. Publicly doc- + umented ones, intended to be long-term stable, are listed below, under + the heading "Variables and subroutines for processing a rule". Examples of their use is given in the following examples, concerning multiple index files and glossaries. @@ -4349,17 +4387,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) } push @generated_exts, 'ndx', 'nnd'; - - - 20 November 2021 66 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - Notice the added line compared with earlier examples. The extra line gets the extensions "ndx" and "nnd" added to the list of extensions for generated files; then the extra index files will be deleted by clean-up @@ -4387,6 +4414,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) push @generated_exts, 'ndx', 'nnd', 'adx', 'and'; This last example uses the command specification in $makeindex, and so + + + + 17 March 2022 67 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + any customization you have made for the standard index also applies to your extra indexes. @@ -4415,17 +4454,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) item, and the name of the subroutine for the custom dependency. These were all defined above. - - - 20 November 2021 67 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - 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 .fig files to .eps files: @@ -4451,8 +4479,20 @@ ADVANCED CONFIGURATION: Some extra resources and advanced tricks 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 you use- - ful ideas + Even if none of the examples apply to your case, they may give you + + + + 17 March 2022 68 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + + useful ideas Utility subroutines @@ -4481,17 +4521,6 @@ ADVANCED CONFIGURATION: Some extra resources and advanced tricks invoked programs. - - - 20 November 2021 68 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - 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 @@ -4516,6 +4545,19 @@ LATEXMK(1) General Commands Manual LATEXMK(1) This gives the name of the primary source file. Note the double dollar signs. + + + + + 17 March 2022 69 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + $$Pdest This gives the name of the main output file if any. Note the double dollar signs. @@ -4546,18 +4588,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) rdb_set_source( $rule, file, ... ) - - - - 20 November 2021 69 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - rdb_set_source( $rule, @files ) This subroutine sets the dependency list for the given rule to be the specified files. Files that are already in the list have @@ -4582,6 +4612,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) pattern, you can use one of the following subroutines, std_tex_cmds, alt_tex_cmds, and set_tex_cmds. + + + + 17 March 2022 70 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + They work as follows &std_tex_cmds; @@ -4599,8 +4641,8 @@ LATEXMK(1) General Commands Manual LATEXMK(1) set_tex_cmds( CMD_SPEC ); Here CMD_SPEC is the command line without the program name. This re- - sults in $latex = 'CMD_SPEC', and similarly for $pdflatex, $lualatex, - and $xelatex. An example would be + sults in $latex = 'latex CMD_SPEC', and similarly for $pdflatex, $lu- + alatex, and $xelatex. An example would be set_tex_cmds( '--interaction=batchmode %O %S' ); @@ -4612,18 +4654,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) 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 - - - - 20 November 2021 70 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - 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- @@ -4647,9 +4677,21 @@ LATEXMK(1) General Commands Manual LATEXMK(1) 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 + In this section, I give a couple of examples of how latexmk can be + + + + 17 March 2022 71 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + + usefully 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 la- @@ -4677,25 +4719,13 @@ LATEXMK(1) General Commands Manual LATEXMK(1) 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 - - - - 20 November 2021 71 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - - 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. + the effect of causing the rule to be always out-of-date, so that la- + texmk is always run. It is latexmk that decides whether any action is + needed, e.g., a rerun of pdflatex. Effectively the Makefile delegates + 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 cus- + tom dependencies configured in latexmk. But something better is needed in more complicated situations, for ex- ample, when the making of graphics files needs to be specified by rules @@ -4714,6 +4744,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) mkdir $@ %.pdf : %.tex if [ ! -e $(DEPS_DIR) ]; then mkdir $(DEPS_DIR); fi + + + + 17 March 2022 72 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + $(LATEXMK) -pdf -dvi- -ps- -deps-out=$(DEPS_DIR)/$@P $< %.pdf : %.fig fig2dev -Lpdf $< $@ @@ -4744,18 +4786,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) 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 - - - - 20 November 2021 72 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - "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.pdf", and only then reruns latexmk. @@ -4780,6 +4810,18 @@ BUGS 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 + + + + 17 March 2022 73 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + 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- @@ -4793,7 +4835,7 @@ THANKS TO dard form to avoid being harvested too easily.) AUTHOR - Current version, by John Collins (Version 4.76). Report bugs etc to + Current version, by John Collins (Version 4.77). Report bugs etc to his e-mail (jcc8 at psu.edu). Released version can be obtained from CTAN: @@ -4813,48 +4855,6 @@ AUTHOR - 20 November 2021 73 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -4879,6 +4879,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 20 November 2021 74 + 17 March 2022 74 |