From 8ca7af6e140fdaee415715e4a537d8f1a9305198 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Sat, 17 Apr 2021 03:00:41 +0000 Subject: CTAN sync 202104170300 --- support/latexmk/latexmk.1 | 160 +++++++++++++++++++++++++++++----------------- 1 file changed, 100 insertions(+), 60 deletions(-) (limited to 'support/latexmk/latexmk.1') diff --git a/support/latexmk/latexmk.1 b/support/latexmk/latexmk.1 index a122493709..7b32b20f38 100644 --- a/support/latexmk/latexmk.1 +++ b/support/latexmk/latexmk.1 @@ -1,4 +1,4 @@ -.TH LATEXMK 1 "29 September 2020" "" +.TH LATEXMK 1 "15 April 2021" "" .SH NAME latexmk \- generate LaTeX document .SH SYNOPSIS @@ -116,36 +116,23 @@ e.g., "latexmk -help" or "latexmk --help". supported engines, i.e., currently \fIlatex\fR, \fIlualatex\fR, \fIpdflatex\fR, \fIxelatex\fR. Mention of a specific one of these normally refers that specific engines. Earlier versions of this documentation -weren't so consistent. +weren't so consistent. Which of these is used to compile a document, +depends on the configuration and the command line arguments. \fBNote 2\fR: \fBIn addition to the options in the list below, \fIlatexmk\fR recognizes almost all the options recognized by the -\fI*latex\fR in their +\fI*latex\fR programs in their current TeXLive and MiKTeX implementations. Some of the options for -these programs also trigger special action or behavior by +these programs trigger special action or behavior by \fIlatexmk\fR, in which case they have specific explanations in this -document. Otherwise, they -are just passed through to a called \fI*latex\fR -program. Run \fIlatexmk\fR with the \fB-showextraoptions\fR to get a +document; in this case they may or may not be passed to *latex as well. + +Run \fIlatexmk\fR with the \fB-showextraoptions\fR to get a list of the options that \fIlatexmk\fR accepts and that are simply passed through to \fI*latex\fR. See also the explanation of the \fB-showextraoptions\fR option for more information. -\fBNote 3\fR: In this documentation, the term \fI*latex\fR is often -referred to, which refers to all the supported \fIlatex\fR-like programs, -whether the original \fIlatex\fR, or the later \fIpdflatex\fR, -\fIxelatex\fR, and \fIlualatex\fR. Users should know that from -\fIlatexmk\fR's point of view, all of these programs behave very much -alike, with the sole exception that by default \fIlatex\fR produces a dvi -file and all the others produce a pdf file. \fILatexmk\fR can be easily -configured to use whichever of these programs is needed. See the -documentation for the following options: \fB-pdflua\fR, \fB-pdfxe\fR, -\fB-lualatex\fR, and \fB-xelatex\fR, and also see the documentation for the -\fI$latex\fR, \fI$pdflatex\fR, \fI$lualatex\fR, and \fI$xelatex\fR -configuration variables. At present \fIlatexmk\fR does not do automatic -detection of which program is to be used. - \fBDefinitions of options and arguments\fR @@ -184,7 +171,7 @@ by a backward slash "/", which is also a legal directory separator in Windows, and is accepted by \fIlatex\fR etc. .TP -.B -auxdir=FOO or -aux-directory=FOO +.B -auxdir=FOO \fRor\fB -aux-directory=FOO Sets the directory for auxiliary output files of *latex (.aux, .log etc). This achieves its effect by the \fB-aux-directory\fR option of *latex, @@ -276,9 +263,14 @@ This property can also be configured by setting the \fI$bibtex_use\fR variable to 1.5 in a configuration file. .TP -.B -bibtexfudge, -bibtexfudge- -Turn on/off the change-directory fudge needed for old versions (pre-2019) -of bibtex. See documentation of \fI$bibtex_fudge\fR for details. +.B -bibtexfudge\fR or\fB -bibfudge +Turn on the change-directory fudge for bibtex. See documentation of +\fI$bibtex_fudge\fR for details. + +.TP +.B -bibtexfudge-\fR or\fB -bibfudge- +Turn off the change-directory fudge for +bibtex. See documentation of \fI$bibtex_fudge\fR for details. .TP .B -bm @@ -320,7 +312,7 @@ files specified by the \fI$clean_ext\fR and \fI@generated_exts\fR configuration variables are removed. This cleanup is instead of a regular make. See the \fB-gg\fR option -if you want to do a cleanup then a make. +if you want to do a cleanup followed by a make. \fITreatment of .bbl files: \fR If \fI$bibtex_use\fR is set to 0 or 1, bbl files are always treated as non-regeneratable. If @@ -347,7 +339,7 @@ addition of dvi, postscript and pdf files, and those specified in the \fI$clean_full_ext\fR configuration variable. This cleanup is instead of a regular make. See the \fB-gg\fR option -if you want to do a cleanup than a make. +if you want to do a cleanup followed by a make. See the \fB-c\fR option for the specification of whether or not .bbl files are treated as non-regeneratable or regeneratable. @@ -544,7 +536,8 @@ rerunning of \fIlatex\fR (etc) that would be done if no errors had occurred. If instead, or additionally, you want the \fIlatex\fR (etc) program not to pause for user input after an error, you should arrange this by an option that is passed to the program, e.g., by -\fIlatexmk\fR's option \fB-interaction=nonstopmode\fR. +\fIlatexmk\fR's option \fB-interaction=nonstopmode\fR (which \fIlatexmk\fR +passes to \fI*latex\fR). .TP .B -f- @@ -570,7 +563,7 @@ Turn off \fB-g\fR. \fB-C\fR had been given, and then do a regular make. .TP -.B -h, -help +.B -h \fRor\fB-non-help Print help information. .TP @@ -704,6 +697,16 @@ file. If you use the dependents list in a Makefile, the dummy rules work around errors the program \fImake\fR gives if you remove header files without updating the Makefile to match. +.TP +.B -makeindexfudge +Turn on the change-directory fudge for makeindex. See documentation of +\fI$makeindex_fudge\fR for details. + +.TP +.B -makeindexfudge- +Turn off the change-directory fudge for makeindex. See documentation of +\fI$makeindex_fudge\fR for details. + .TP .B -MSWinBackSlash This option only has an effect when \fIlatexmk\fR is running under @@ -751,9 +754,9 @@ an already-running previewer. Never run bibtex or biber. Equivalent to the \fB-bibtex-\fR option. .TP -.B -nobibtexfudge -Turn off the change-directory fudge needed for old versions (pre-2019) -of bibtex. See documentation of \fI$bibtex_fudge\fR for details. +.B -nobibtexfudge \fRor\fB -nobibfudge +Turn off the change-directory fudge for +bibtex. See documentation of \fI$bibtex_fudge\fR for details. .TP .B -norc @@ -765,7 +768,12 @@ But \fB-norc\fR is an exception to this rule: it is acted on first, no matter where it occurs on the command line. .TP -.B -outdir=FOO or -output-directory=FOO +.B -nomakeindexfudge +Turn off the change-directory fudge for makeindex. See documentation of +\fI$makeindex_fudge\fR for details. + +.TP +.B -outdir=FOO \fRor\fB -output-directory=FOO Sets the directory for the output files of *latex. This achieves its effect by the \fB-output-directory\fR option of *latex, which @@ -783,6 +791,23 @@ If you also use the \fB-cd\fR option, and the specified output directory is a relative path, then the path is interpreted relative to the document directory. +.TP +.B -output-format=FORMAT +This option is one that is allowed for \fIlatex\fR, \fIlualatex\fR, and +\fIpdflatex\fR. But it is not passed to these programs. Instead +\fIlatexmk\fR emulates it in a way suitable for the context of +\fIlatexmk\fR and its workflows. + +If FORMAT is dvi, then dvi output is turned on, and postscript and pdf +output are turned off. This is equivalent to using the options \fB-dvi -ps- +-pdf-\fR. + +If FORMAT is pdf, then pdf output is turned on, and dvi and postscript +output are turned off. This is equivalent to using the options \fB-pdf -ps- +-dvi-\fR. + +If FORMAT is anything else, \fIlatexmk\fR gives an error. + .TP .B -p Print out the document. By default the file to be printed is @@ -921,7 +946,7 @@ If you already have a suitable command configured, you only need latexmk -pretex='\\AtBeginDocument{Message\\par}' foo.tex .TP -.B -print=dvi, -print=ps, -print=pdf, -print=auto, +.B -print=dvi\fR,\fB -print=ps\fR,\fB -print=pdf\fR,\fB -print=auto, Define which kind of file is printed. This option also ensures that the requisite file is made, and turns on printing. @@ -1098,30 +1123,29 @@ are run. These options are (currently) a combination of those allowed by the TeXLive and MiKTeX implementations. (If a particular option is given to \fIlatexmk\fR but is not handled by the particular implementation of \fI*latex\fR -that is being used, that program will probably give an -error message.) These options are very numerous, but are not listed +that is being used, that program will probably give a warning or an +error.) These options are very numerous, but are not listed in this documentation because they have no effect on \fIlatexmk\fR's actions. -There are a few options (\fB-includedirectory=dir\fR, +There are a few options (e.g., \fB-includedirectory=dir\fR, \fB-initialize\fR, \fB-ini\fR) that are not recognized, either because they don't fit with \fIlatexmk\fR's intended operations, or because they need special processing by \fIlatexmk\fR that isn't implemented (at least, not yet). -There are also options that are accepted by \fIlatex\fR etc, but -instead trigger actions by \fIlatexmk\fR: \fB-help\fR, -\fB-version\fR. - -Finally, there are certain options for \fI*latex\fR -(e.g., \fB-recorder\fR) that trigger special actions or behavior by -\fIlatexmk\fR itself as well as being passed in some form to the -called \fI*latex\fR program, or that affect other -programs as well. These options do have entries in this -documentation. These options are: +There are certain options for \fI*latex\fR (e.g., \fB-recorder\fR) that +trigger special actions or behavior by \fIlatexmk\fR itself. Depending on +the action, they may also be passed in some form to the called \fI*latex\fR +program, and/or may affect other programs as well. These options do have +entries in this documentation. Among these options are: \fB-jobname=STRING\fR, \fB-aux-directory=dir\fR, \fB-output-directory=DIR\fR, \fB-quiet\fR, and \fB-recorder\fR. +There are also options that are accepted by \fI*latex\fR, but +instead trigger actions purely by \fIlatexmk\fR: \fB-help\fR, +\fB-version\fR. + .TP .B -silent Run commands silently, i.e., with options that reduce the amount of @@ -1207,7 +1231,7 @@ Equivalent to \fB-pretex=CODE -usepretex\fR. Example latexmk -usepretex='\\AtBeginDocument{Message\\par}' foo.tex .TP -.B -v, -version +.B -v \fRor\fB -version Print version number of \fIlatexmk\fR. .TP @@ -1215,7 +1239,7 @@ Print version number of \fIlatexmk\fR. Opposite of \fB-silent\fR. This is the default setting. .TP -.B -view=default, -view=dvi, -view=ps, -view=pdf, -view=none +.B -view=default\fR,\fB -view=dvi\fR,\fB -view=ps\fR,\fB -view=pdf\fR,\fB -view=none Set the kind of file used when previewing is requested (e.g., by the \fB-pv\fR or \fB-pvc\fR switches). The default is to view the "highest" kind of requested file (in the low-to-high order .dvi, .ps, .pdf). @@ -1392,9 +1416,7 @@ and \fIlualatex\fR the document itself can override the defaults. The other is that there may be a configuration, or misconfiguration, such that the program that \fIlatexmk\fR invokes to compile the document is not the expected one, or is given options incompatible with what -\fIlatexmk\fR initially expects. (E.g., the \fB-output-format=...\fR -option could be used with \fIlualatex\fR, or \fIxelatex\fR gets -invoked without the \fB-no-pdf\fR option.) +\fIlatexmk\fR initially expects. Under \fIlatex\fR and \fIpdflatex\fR, control of the output format by the document is done by setting the \\pdfoutput macro. Under @@ -1983,12 +2005,24 @@ Switch(es) for the biber processing program when silent mode is on. .B $bibtex ["bibtex %O %S"] The BibTeX processing program. .TP -.B $bibtex_fudge [0] -When using bibtex, whether to take special action to allow older -versions of bibtex to -work when $out_dir or $aux_dir is specified. With bibtex from about 2019, -this special action is longer be required; hence the default is not to do -it. +.B $bibtex_fudge [1] +When using bibtex, whether to change directory to $aux_dir before running +bibtex. + +The need arises as follows: + +a. With bibtex before about 2019, if the filename given to it contains a +path component, there was a bug that bibtex would not find extra aux files, +as produced by the \\include command in TeX. + +b. With all moderately recent versions of bibtex, bibtex may refuse to +write its bbl and blg files, for security reasons, for certain cases of the +path component of the filename given to it. + +However, there are also rare cases where the change-directory method +prevents bibtex from finding certain bib or bst files. Then +\fI$bibtex_fudge\fR needs to be set to 0. + .TP .B $bibtex_silent_switch ["-terse"] Switch(es) for the BibTeX processing program when silent mode is on. @@ -2074,7 +2108,7 @@ possible to use wildcards. Thus setting in an initialization file will imply that when a clean-up operation is specified, not only is the standard set of files deleted, but also -files of the form FOO.out, FOO-blx.bib, %R-figures*.log, and +files of the form FOO.out, FOO-blx.bib, FOO-figures*.log, and pythontex-files-FOO/*, where FOO stands for the basename of the file being processed (as in FOO.tex). @@ -2693,6 +2727,12 @@ The make processing program. .B $makeindex ["makeindex %O -o %D %S"] The index processing program. .TP +.B $makeindex_fudge [0] +When using makeindex, whether to change directory to $aux_dir before running +makeindex. Set to 1 if $aux_dir is not an explicit subdirectory of current +directory, otherwise makeindex will refuse to write its output and log +files, for security reasons. +.TP .B $makeindex_silent_switch ["-q"] \fBSwitch(es)\fR for the index processing program when silent mode is on. .TP @@ -3879,7 +3919,7 @@ e-mail addresses are not written in their standard form to avoid being harvested too easily.) .SH AUTHOR Current version, by John Collins -(Version 4.70b). +(Version 4.72b). Report bugs etc to his e-mail (jcc8 at psu.edu). Released version can be obtained from CTAN: -- cgit v1.2.3