diff options
| author | Norbert Preining <norbert@preining.info> | 2023-11-08 03:02:04 +0000 |
|---|---|---|
| committer | Norbert Preining <norbert@preining.info> | 2023-11-08 03:02:04 +0000 |
| commit | dada699771828d1aa3c78ecf55a2131e5f5799f3 (patch) | |
| tree | 454888fc413a3cff3d4aec62d5950c02446c364e /support/latexmk/latexmk.txt | |
| parent | 02646b6e89ef69971235e0c883e86fd746955e2b (diff) | |
CTAN sync 202311080302
Diffstat (limited to 'support/latexmk/latexmk.txt')
| -rw-r--r-- | support/latexmk/latexmk.txt | 940 |
1 files changed, 536 insertions, 404 deletions
diff --git a/support/latexmk/latexmk.txt b/support/latexmk/latexmk.txt index 31bcadb0a5..720022a634 100644 --- a/support/latexmk/latexmk.txt +++ b/support/latexmk/latexmk.txt @@ -61,7 +61,7 @@ DESCRIPTION - 4 April 2023 1 + 6 November 2023 1 @@ -127,7 +127,7 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE - 4 April 2023 2 + 6 November 2023 2 @@ -193,7 +193,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 3 + 6 November 2023 3 @@ -259,7 +259,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 4 + 6 November 2023 4 @@ -325,7 +325,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 5 + 6 November 2023 5 @@ -391,7 +391,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 6 + 6 November 2023 6 @@ -457,7 +457,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 7 + 6 November 2023 7 @@ -523,7 +523,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 8 + 6 November 2023 8 @@ -589,7 +589,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 9 + 6 November 2023 9 @@ -655,7 +655,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 10 + 6 November 2023 10 @@ -721,7 +721,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 11 + 6 November 2023 11 @@ -787,7 +787,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 12 + 6 November 2023 12 @@ -853,7 +853,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 13 + 6 November 2023 13 @@ -919,7 +919,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 14 + 6 November 2023 14 @@ -985,7 +985,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 15 + 6 November 2023 15 @@ -1051,7 +1051,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 16 + 6 November 2023 16 @@ -1117,7 +1117,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 17 + 6 November 2023 17 @@ -1183,7 +1183,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 18 + 6 November 2023 18 @@ -1249,7 +1249,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 19 + 6 November 2023 19 @@ -1315,7 +1315,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 20 + 6 November 2023 20 @@ -1381,7 +1381,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 21 + 6 November 2023 21 @@ -1447,7 +1447,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 22 + 6 November 2023 22 @@ -1513,7 +1513,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 23 + 6 November 2023 23 @@ -1579,7 +1579,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 24 + 6 November 2023 24 @@ -1645,7 +1645,7 @@ EXAMPLES - 4 April 2023 25 + 6 November 2023 25 @@ -1711,7 +1711,7 @@ DEALING WITH ERRORS, PROBLEMS, ETC - 4 April 2023 26 + 6 November 2023 26 @@ -1777,7 +1777,7 @@ AUXILIARY AND OUTPUT DIRECTORIES - 4 April 2023 27 + 6 November 2023 27 @@ -1843,7 +1843,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 28 + 6 November 2023 28 @@ -1909,7 +1909,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 29 + 6 November 2023 29 @@ -1975,7 +1975,7 @@ ALLOWING FOR CHANGE OF OUTPUT FILE TYPE - 4 April 2023 30 + 6 November 2023 30 @@ -2041,7 +2041,7 @@ CONFIGURATION/INITIALIZATION (RC) FILES - 4 April 2023 31 + 6 November 2023 31 @@ -2107,7 +2107,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 32 + 6 November 2023 32 @@ -2173,7 +2173,7 @@ FORMAT OF COMMAND SPECIFICATIONS - 4 April 2023 33 + 6 November 2023 33 @@ -2239,7 +2239,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 34 + 6 November 2023 34 @@ -2305,7 +2305,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 35 + 6 November 2023 35 @@ -2371,7 +2371,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 36 + 6 November 2023 36 @@ -2437,7 +2437,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 37 + 6 November 2023 37 @@ -2503,7 +2503,7 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES - 4 April 2023 38 + 6 November 2023 38 @@ -2569,7 +2569,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 39 + 6 November 2023 39 @@ -2635,7 +2635,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 40 + 6 November 2023 40 @@ -2701,7 +2701,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 41 + 6 November 2023 41 @@ -2767,7 +2767,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 42 + 6 November 2023 42 @@ -2833,7 +2833,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 43 + 6 November 2023 43 @@ -2899,7 +2899,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 44 + 6 November 2023 44 @@ -2965,7 +2965,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 45 + 6 November 2023 45 @@ -3031,7 +3031,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 46 + 6 November 2023 46 @@ -3097,7 +3097,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 47 + 6 November 2023 47 @@ -3163,7 +3163,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 48 + 6 November 2023 48 @@ -3229,7 +3229,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 4 April 2023 49 + 6 November 2023 49 @@ -3271,6 +3271,51 @@ LATEXMK(1) General Commands Manual LATEXMK(1) need to change this. + @file_not_found + This an array of Perl regular expressions that are patterns to + find messages in the .log file from a run of *latex that indi- + cate that a file was looked for and not found. To see the cur- + rent default set, you should look at the definition of + @file_not_found in the latexmk.pl file. + + In the regular expression, the string for the name of the miss- + ing file should be enclosed in parentheses. That carries the + implication that after latexmk gets a succesful match to the + pattern, the variable $1 is set to the filename, which is then + picked up by latexmk. + + If you happen to encounter a package that gives a missing file + message of a different form than one that matches one of the + built-in patterns, you can add another pattern to the array. An + example would be + + push @file_not_found, '^No file\\s+(.+)\\s*$'; + + The regular expression itself is + + + + 6 November 2023 50 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + + ^Missing file\s+(.+)\s*$ + + But the corresponding string specification in the push statement + has to have the backslashes doubled. + + This regular expression matches a line that starts with 'No + file', then has one or more white space characters, then any + number of characters forming the filename, then possible white + space, and finally the end of the line. (See documentation on + Perl regular expressions for details.) + + $fls_uses_out_dir [0] This variable determines whether or not the .fls file should be in the output directory instead of the natural directory, which @@ -3291,19 +3336,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) of the .fls file to be generated. - - - - - 4 April 2023 50 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - $force_mode [0] If nonzero, continue processing past minor latex errors includ- ing unrecognized cross references. Equivalent to specifying the @@ -3325,8 +3357,20 @@ 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). + ated_exts. So these two variables have the same meaning + + + + 6 November 2023 51 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + + (contrary 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 @@ -3359,17 +3403,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) If nonzero, process files regardless of timestamps, and is then equivalent to the -g option. - - - 4 April 2023 51 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - %hash_calc_ignore_pattern !!!This variable is for experts only!!! @@ -3391,6 +3424,18 @@ 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 + + + + 6 November 2023 52 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + in a hash. Note that the file extension is specified without a period. The value, on the right-hand side, is a string contain- ing a regular expression. (See documentation on Perl for how @@ -3424,18 +3469,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) This specifies the jobname, i.e., the basename that is used for generated files (.aux, .log, .dvi, .ps, .pdf, etc). If this - - - - 4 April 2023 52 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - variable is a null string, then the basename is the basename of the main tex file. (At present, the string in $jobname should not contain spaces.) @@ -3458,6 +3491,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1) latexmk -pdf *.tex + + + 6 November 2023 53 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + both files will be compiled. The .aux, .log, and .pdf files will have basenames test1-MSWin32 ante test2-MSWin32 on a MS- Windows system, test1-darwin and test2-darwin on an OS-X system, @@ -3490,18 +3534,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $kpsewhich_show [0] Whether to show diagnostics about invocations of kpsewhich: the - - - - 4 April 2023 53 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - command line use to invoke it and the results. These diagnos- tics are shown if $kpsewhich_show is non-zero or if diagnostics mode is on. (But in the second case, lots of other diagnostics @@ -3524,6 +3556,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) To do a coordinated setting of all of $dvilualatex, $latex, $pdflatex, $lualatex, and $xelatex, see the section "Advanced + + + + 6 November 2023 54 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + Configuration". @@ -3555,22 +3599,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1) add the extension 'asdf to latex_input_extensions. (Naturally with such an extension, you should have made an appropriate cus- - tom dependency for latexmk, and should also have done the - - - - 4 April 2023 54 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - - appropriate programming in the LaTeX source file to enable the - file to be read. The standard extensions are handled by LaTeX - and its graphics/graphicx packages.) + tom dependency for latexmk, and should also have done the appro- + priate programming in the LaTeX source file to enable the file + to be read. The standard extensions are handled by LaTeX and + its graphics/graphicx packages.) $latex_silent_switch ["-interaction=batchmode"] Switch(es) for the LaTeX processing program when silent mode is @@ -3590,6 +3622,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 example, if you have gsview installed, you could use it with the + + + + 6 November 2023 55 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + option "/p": $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p'; @@ -3622,18 +3666,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $lualatex ["lualatex %O %S"] Specifies the command line for the LaTeX processing program that - - - - 4 April 2023 55 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - is to be used when the lualatex program is called for (e.g., by the option -lualatex. @@ -3656,6 +3688,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 + + + + 6 November 2023 56 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + that equally applies to %lualatex_input_extensions. $lualatex_silent_switch ["-interaction=batchmode"] @@ -3688,18 +3732,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) bail out, rather than rerunning *latex again to resolve cross- references, etc. The default value covers all normal cases. - - - - 4 April 2023 56 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - (Note that the "etc" covers a lot of cases where one run of *la- tex generates files to be read in on a later run.) @@ -3721,10 +3753,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 + + + + 6 November 2023 57 + + + + + +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. @@ -3755,17 +3799,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - - - 4 April 2023 57 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - $pdf_mode [0] If zero, do NOT generate a pdf version of the document. If equal to 1, generate a pdf version of the document using pdfla- @@ -3788,6 +3821,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Specifies the command line for the LaTeX processing program in a version that makes a pdf file instead of a dvi file. + + + 6 November 2023 58 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + An example use of this variable is to add certain options to the command line for the program, e.g., @@ -3820,18 +3864,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) See details of the %latex_input_extensions for other information that equally applies to %pdflatex_input_extensions. - - - - 4 April 2023 58 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - $pdflatex_silent_switch ["-interaction=batchmode"] Switch(es) for the pdflatex program (specified in the variable $pdflatex) when silent mode is on. @@ -3854,6 +3886,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) preview, which is quite satisfactory. WARNING: Problem under MS-Windows: if acroread is used as the + + + + 6 November 2023 59 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + pdf previewer, and it is actually viewing a pdf file, the pdf file cannot be updated. Thus makes acroread a bad choice of previewer if you use latexmk's previous-continuous mode (option @@ -3887,17 +3931,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Note that acroread under MS-Windows (but not UNIX) locks the pdf file, so the default value is then 3. - - - 4 April 2023 59 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - Arranging to use a command to get a previewer explicitly updated requires three variables to be set. For example: @@ -3918,6 +3951,19 @@ LATEXMK(1) General Commands Manual LATEXMK(1) variable $pdf_update_method. The default value is the one ap- propriate for gv on a UNIX system. + + + + + 6 November 2023 60 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + $pid_position[1 under UNIX, -1 under MS-Windows] The variable $pid_position is used to specify which word in lines of the output from $pscmd corresponds to the process ID. @@ -3953,17 +3999,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - - - 4 April 2023 60 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - $preview_continuous_mode [0] If nonzero, run a previewer to view the document, and continue running latexmk to keep .dvi up-to-date. Equivalent to the -pvc @@ -3982,6 +4017,19 @@ LATEXMK(1) General Commands Manual LATEXMK(1) mended not to be set from an RC file, otherwise you could waste lots of paper. + + + + + 6 November 2023 61 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + $print_type = ["auto"] Type of file to printout: possibilities are "auto", "dvi", "none", "pdf", or "ps". See the option -print= for the meaning @@ -4018,18 +4066,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Note that gv could be used with the -watch option updates its display whenever the postscript file changes, whereas ghostview - - - - 4 April 2023 61 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - does not. However, different versions of gv have slightly dif- ferent ways of writing this option. You can configure this variable appropriately. @@ -4049,6 +4085,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1) in yourself, whenever it is needed. + + + 6 November 2023 62 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + $ps_previewer_landscape ["start gv -swap %O %S", but start %O %S under MS-Windows] The command to invoke a ps-previewer in landscape mode. @@ -4085,17 +4132,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) The period of inactivity, in minutes, after which pvc mode times out. This is used if $pvc_timeout is nonzero. - - - 4 April 2023 62 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - $pvc_view_file_via_temporary [1] The same as $always_view_file_via_temporary, except that it only applies in preview-continuous mode (-pvc option). @@ -4115,6 +4151,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1) correctly treated by the operating system in passing arguments to programs.) + + + 6 November 2023 63 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + $rc_report [1] After initialization, whether to give a list of the RC files read. @@ -4150,18 +4197,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) [Comment to technically savvy readers: *latex doesn't actually need the modified search path. But, surprisingly, dvipdf and - - - - 4 April 2023 63 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - dvips do, because sometimes graphics files get generated in the output or aux directories.] @@ -4181,6 +4216,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Note: On MS Windows, this is clock time. On other OSs it is the CPU time used (by latexmk and the child processes it invokes). + + + + 6 November 2023 64 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + The OS-dependence is because of a limitation of Windows. If you wish to force the use of clock instead of CPU time, you can set @@ -4217,17 +4264,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) A value of exactly 0 gives no delay, and typically results in 100% CPU usage, which may not be desirable. - - - 4 April 2023 64 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - $texfile_search [""] This is an obsolete variable, replaced by the @default_files variable. @@ -4245,10 +4281,22 @@ LATEXMK(1) General Commands Manual LATEXMK(1) while running. The default under MSWindows (including cygwin), is to set $tm- - pdir to the value of the first of whichever of the system envi- - ronment variables TMPDIR or TEMP exists, otherwise to the cur- - rent directory. Under other operating systems (expected to be - UNIX/Linux, including OS-X), the default is the value of the + pdir to the value of the first of whichever of the system + + + + 6 November 2023 65 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + + environment variables TMPDIR or TEMP exists, otherwise to the + current directory. Under other operating systems (expected to + be UNIX/Linux, including OS-X), the default is the value of the system environment variable TMPDIR if it exists, otherwise "/tmp". @@ -4282,18 +4330,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) When the variable is non-zero, latexmk at the end of its run will return a non-zero status code to the operating system if - - - - 4 April 2023 65 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - any of the files processed gives a warning about problems with citations or references (i.e., undefined citations or references or multiply defined references). This is after latexmk has com- @@ -4312,6 +4348,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) ings as errors that require the overall build process to be aborted. Of course, since multiple runs of *latex are generally needed to resolve references and citations, what matters is not + + + + 6 November 2023 66 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + the warnings on the first run, but the warnings on the last run; latexmk takes this into account appropriately. @@ -4348,18 +4396,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Note about xelatex: latexmk uses xelatex to make an .xdv rather than .pdf file, with the .pdf file being created in a separate - - - - 4 April 2023 66 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - step. This is enforced by the use of the -no-pdf option. If %O is part of the command for invoking xelatex, then latexmk will insert the -no-pdf option automatically, otherwise you must pro- @@ -4378,6 +4414,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 + + + + 6 November 2023 67 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + file does not exist. In this situation, latexmk searches for custom dependencies to @@ -4415,17 +4463,6 @@ CUSTOM DEPENDENCIES A better method is to use the subroutines that allow convenient manipu- lations of the custom dependency list. These are - - - 4 April 2023 67 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - add_cus_dep( fromextension, toextension, must, subroutine ) remove_cus_dep( fromextension, toextension ) show_cus_dep() @@ -4443,6 +4480,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 + + + + 6 November 2023 68 + + + + + +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. @@ -4480,18 +4529,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) rule is invoked, with an argument that is the base name of the files in question. Simple cases just involve a subroutine invoking an external program; this can be done by following the templates below, even by - - - - 4 April 2023 68 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - those without knowledge of the Perl programming language. Of course, experts could do something much more elaborate. @@ -4509,6 +4546,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 + + + + 6 November 2023 69 + + + + + +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. @@ -4546,18 +4595,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) of the form of a variable name, $_[0] in this case, is to be substi- tuted by its value. - - - - 4 April 2023 69 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - If the return value of the subroutine is non-zero, then latexmk will assume an error occurred during the execution of the subroutine. In the above example, no explicit return value is given, and instead the @@ -4575,6 +4612,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) } Note 1: In the command lines given in the system commands in the above + + + + 6 November 2023 70 + + + + + +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 @@ -4613,17 +4662,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) remove_cus_dep( 'fig', 'eps' ); - - - 4 April 2023 70 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - If you have complicated sets of custom dependencies, you may want to get a listing of the custom dependencies. This is done by using the line @@ -4639,13 +4677,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 + + + + 6 November 2023 71 + + + + + +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. @@ -4678,18 +4728,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) function to simplify the definitions to use a single function: add_cus_dep( 'ndx', 'nnd', 0, 'dx2nd' ); - - - - 4 April 2023 71 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - add_cus_dep( 'adx', 'and', 0, 'dx2nd' ); sub dx2nd { return Run_subst( "makeindex -o %D %S" ); @@ -4706,6 +4744,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 + + + + 6 November 2023 72 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + any customization you have made for the standard index also applies to your extra indexes. @@ -4744,18 +4794,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) } This method still works, and is almost equivalent to the code given - - - - 4 April 2023 72 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - earlier that used the add_cus_dep subroutine. However, the old method doesn't delete any previous custom-dependency for the same conversion. So the new method is preferable. @@ -4771,8 +4809,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 + + + + 6 November 2023 73 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + + useful ideas Utility subroutines @@ -4809,20 +4859,8 @@ Advanced configuration: Some extra resources and advanced tricks nal" -- see the section FORMAT OF COMMAND SPECIFICATIONS. When you use a subroutine for processing a rule, all the possibilities - of Perl programming are available, of course. In addition, some of - - - - 4 April 2023 73 - - - - - -LATEXMK(1) General Commands Manual LATEXMK(1) - - - latexmk's internal variables and subroutines are available. The ones + of Perl programming are available, of course. In addition, some of la- + texmk's internal variables and subroutines are available. The ones listed below are intended to be available to (advanced) users, and their specifications will generally have stability under upgrades. Gen- erally, the variables should be treated as read-only: Changing their @@ -4837,17 +4875,87 @@ LATEXMK(1) General Commands Manual LATEXMK(1) This gives the name of the primary source file. Note the double dollar signs. + + + + + 6 November 2023 74 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + $$Pdest This gives the name of the main output file if any. Note the double dollar signs. + + pushd( path ), popd() + These subroutines are used when it is needed to temporarily + change the working directory, as in + + pushd( 'some_directory' ); + ... Processing done with 'some_directory' as the working + directory + popd() + + They perform exactly the same function as the commands of the + same names in operating system command shells like bash on Unix, + and cmd.exe on the Windows. + + + rdb_add_generated( file, ... ) + This subroutine is to be used in the context of a rule, that is, + from within a subroutine that is carrying out processing of a + rule. Such is the case for the subroutine implementing a custom + dependency, or the subroutine invoked by using the "internal" + keyword in the command specification like that in the variable + $latex. + + Its arguments are a sequence of filenames which are generated + during the running of the rule. The names might arise from an + analysis of the results of the run, e.g., in a log file, or from + knowledge of properties of the specific rule. Calling + rdb_add_generated with these filenames ensures that these files + are flagged as generated by the rule in latexmk's internal data + structures. Basically, no action is taken if the files have al- + ready been flagged as generated. + + A main purpose of using this subroutine is for the situation + when a generated file is also the source file for some rule, so + that latexmk can correctly link the dependency information in + its network of rules. + + Note: Unlike some other subroutines in this section, there is no + argument for a rule for rdb_add_generated. Instead, the subrou- + tine is to be invoked during the processing of a rule when la- + texmk has set up an appropriate context (i.e., appropriate vari- + ables). In contrast, subroutines with a rule argument can be + used also outside a rule context. + + rdb_ensure_file( $rule, file ) - This a subroutine that ensures that the given file is among the - source files for the specified rule. It is typically used when, - during the processing of a rule, it is known that a particular - extra file is among the dependencies that latexmk should know, - but its default methods don't find the dependency. Almost always - the first argument is the name of the rule currently being pro- + This subroutine ensures that the given file is among the source + files for the specified rule. It is typically used when, during + the processing of a rule, it is known that a particular extra + file is among the dependencies that latexmk should know, but its + + + + 6 November 2023 75 + + + + + +LATEXMK(1) General Commands Manual LATEXMK(1) + + + default methods don't find the dependency. Almost always the + first argument is the name of the rule currently being pro- cessed, so it is then appropriate to specify it by $rule. For examples of its use, see some of the files in the directory @@ -4857,16 +4965,34 @@ LATEXMK(1) General Commands Manual LATEXMK(1) where latexmk's normal processing fails to detect certain extra source files. + Note that rdb_ensure_file only has one filename argument, unlike + other subroutines in this section. If you want to apply its ac- + tion to multiple files, you will need one call to rdb_en- + sure_file for each file. + + rdb_remove_files( $rule, file, ... ) - This subroutine removes one or more files from the dependency + This subroutine removes one or more files from the dependency list for the given rule. + + rdb_remove_generated( file, ... ) + This subroutine is to be used in the context of a rule, that is, + from within a subroutine that is carrying out processing of a + rule. It performs the opposite action to rdb_add_generated. + Its effect is to ensure that the given filenames are not listed + in latexmk's internal data structures as being generated by the + rule. + + rdb_list_source( $rule ) This subroutine returns the list of source files (i.e., the de- pendency list) for the given rule. + rdb_set_source( $rule, file, ... ) + 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 @@ -4876,10 +5002,16 @@ LATEXMK(1) General Commands Manual LATEXMK(1) dency list. + Run_subst( command_spec ) + This subroutine runs the command specified by command_spec. The + specification is a string in the format listed in the section + "Format of Command Specifications". An important action of the + Run_subst is to make substitutions of placeholders, e.g., %S and + %D for source and destination files; these get substituted - 4 April 2023 74 + 6 November 2023 76 @@ -4888,14 +5020,8 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - Run_subst( command_spec ) - This subroutine runs the command specified by command_spec. The - specification is a string in the format listed in the section - "Format of Command Specifications". An important action of the - Run_subst is to make substitutions of placeholders, e.g., %S and - %D for source and destination files; these get substituted be- - fore the command is run. In addition, the command after substi- - tution is printed to the screen unless latexmk is running in + before the command is run. In addition, the command after sub- + stitution is printed to the screen unless latexmk is running in silent mode. @@ -4942,10 +5068,16 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Note that when '%O' appears after the added option, as here, options provided on the command line to latexmk can override the supplied one. + A more general command line can be set up by using the placeholder '%C' + in CMD_SPEC. The '%C' is substituted by the basic name of the command, + i.e., whichever of 'latex', 'pdflatex', etc is appropriate. (More than + one occurrence of '%C' is allowed.) For example to use the develop- + ment/pre-release versions of latex, etc, which have names, 'latex-dev', + 'pdflatex-dev', etc, you could use - 4 April 2023 75 + 6 November 2023 77 @@ -4954,13 +5086,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - A more general command line can be set up by using the placeholder '%C' - in CMD_SPEC. The '%C' is substituted by the basic name of the command, - i.e., whichever of 'latex', 'pdflatex', etc is appropriate. (More than - one occurrence of '%C' is allowed.) For example to use the develop- - ment/pre-release versions of latex, etc, which have names, 'latex-dev', - 'pdflatex-dev', etc, you could use - set_tex_cmds( '%C-dev %O %S' ); This results in $latex = 'latex-dev %O %S', etc. (The pre-release pro- @@ -5008,25 +5133,25 @@ LATEXMK(1) General Commands Manual LATEXMK(1) suitable Makefile is like .PHONY : FORCE_MAKE + all : try.pdf + %.pdf : %.tex FORCE_MAKE + latexmk -pdf -dvi- -ps- $< + (Note: the last line must be introduced by a tab for the Makefile to + function correctly!) Naturally, if making try.pdf from its associated + LaTeX file try.tex were the only task to be performed, a direct use of - 4 April 2023 76 + 6 November 2023 78 -LATEXMK(1) General Commands Manual LATEXMK(1) +LATEXMK(1) General Commands Manual LATEXMK(1) - all : try.pdf - %.pdf : %.tex FORCE_MAKE - latexmk -pdf -dvi- -ps- $< - (Note: the last line must be introduced by a tab for the Makefile to - function correctly!) Naturally, if making try.pdf from its associated - LaTeX file try.tex were the only task to be performed, a direct use of latexmk without a Makefile would normally be better. The benefit of using a Makefile for a LaTeX document would be in a larger project, where lines such as the above would be only be a small part of a larger @@ -5074,10 +5199,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1) dles automatic dependency tracking of C source files. After each run of latexmk, dependency information is put in a file in + the .deps subdirectory. The Makefile causes these dependency files to + be read by make, which now has the full dependency information for each + target .pdf file. To make things less trivial it is specificed that + two files document1.pdf and document2.pdf are the targets. The depen- + dency files are .deps/document1.pdfP and .deps/document2.pdfP. + + There is now no need for the phony prerequisite for the rule to make - 4 April 2023 77 + 6 November 2023 79 @@ -5086,13 +5218,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - the .deps subdirectory. The Makefile causes these dependency files to - be read by make, which now has the full dependency information for each - target .pdf file. To make things less trivial it is specificed that - two files document1.pdf and document2.pdf are the targets. The depen- - dency files are .deps/document1.pdfP and .deps/document2.pdfP. - - There is now no need for the phony prerequisite for the rule to make .pdf files from .tex files. But I have added a rule to make .pdf files from .fig files produced by the xfig program; these are commonly used for graphics insertions in LaTeX documents. Latexmk is arranged to @@ -5140,24 +5265,23 @@ NON_ASCII CHARACTERS IN FILENAMES, RC FILES, ETC names on Windows, even though there were no corresponding problems on macOS and Linux. These problems are corrected in the present version. + DETAILS TO BE FILLED IN - 4 April 2023 78 - +SEE ALSO + latex(1), bibtex(1), lualatex(1), pdflatex(1), xelatex(1). -LATEXMK(1) General Commands Manual LATEXMK(1) + 6 November 2023 80 - DETAILS TO BE FILLED IN -SEE ALSO - latex(1), bibtex(1), lualatex(1), pdflatex(1), xelatex(1). +LATEXMK(1) General Commands Manual LATEXMK(1) BUGS (SELECTED) @@ -5186,12 +5310,12 @@ THANKS TO dard form to avoid being harvested too easily.) AUTHOR - Current version, by John Collins (Version 4.80). Report bugs etc to + Current version, by John Collins (Version 4.81). Report bugs etc to his e-mail (jcc8 at psu.edu). Released version can be obtained from CTAN: <http://www.ctan.org/pkg/latexmk/>, and from the author's website - <http://www.personal.psu.edu/jcc8/latexmk/>. + <https://www.cantab.net/users/johncollins/latexmk/>. Modifications and enhancements by Evan McLean (Version 2.0) Original script called "go" by David J. Musliner (RCS Version 3.2) @@ -5209,6 +5333,14 @@ AUTHOR - 4 April 2023 79 + + + + + + + + + 6 November 2023 81 |