latexmk (19mar19)

git-svn-id: svn://tug.org/texlive/trunk@50472 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 236 insertions, 27 deletions

diff --git a/Master/texmf-dist/doc/man/man1/latexmk.1 b/Master/texmf-dist/doc/man/man1/latexmk.1
index 151970fed87..82cd96f1867 100644
--- a/Master/texmf-dist/doc/man/man1/latexmk.1
+++ b/Master/texmf-dist/doc/man/man1/latexmk.1
@@ -1,4 +1,4 @@
-.TH LATEXMK 1 "25 October 2018" ""
+.TH LATEXMK 1 "17 March 2019" ""
 .SH NAME
 latexmk \- generate LaTeX document
 .SH SYNOPSIS
@@ -69,7 +69,9 @@ needed, call an external program to do other postprocessing on
 generated dvi and postscript files.  (See the options \fB-dF\fR and
 \fB-pF\fR, and the documentation for the \fI$dvi_filter\fR and
 \fI$ps_filter\fR configuration variables.)  These capabilities are
-leftover from older versions of \fIlatexmk\fR.  More flexibility can
+leftover from older versions of \fIlatexmk\fR, but \fBare currently
+non-functional\fR.
+More flexibility can
 be obtained in current versions, since the command strings for running
 \fIlatex\fR, \fIpdflatex\fR, etc can now be configured to run multiple
 commands. 
@@ -299,8 +301,8 @@ combination of log files, aux files, \fIlatexmk\fR's database file of
 source file information, 
 and those with extensions
 specified in the \fI@generated_exts\fR configuration variable.  In addition,
-files specified by the \fI$clean_ext\fR configuration variable are
-removed.  
+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.
@@ -316,7 +318,7 @@ files are treated as non-regeneratable and hence are not deleted.
 In contrast, if \fI$bibtex_use\fR is set to 2, bbl files are always
 treated as regeneratable, and are deleted in a cleanup.
 
-\fITreatment of files generated by custom dependencies:\fRIf
+\fITreatment of files generated by custom dependencies:\fR If
 \fI$cleanup_includes_cusdep_generated\fR is nonzero, regeneratable
 files are considered as including those generated by custom
 dependencies and are also deleted.  Otherwise these files are not
@@ -559,13 +561,38 @@ Print help information.
 .TP
 .B -jobname=STRING
 Set the basename of output files(s) to STRING, instead of the default,
-which is the basename of the specified TeX file.
+which is the basename of the specified TeX file.  (At present, STRING
+should not contain spaces.)
 
 This is like the same option for current implementations of the
 \fIlatex\fR, \fIpdflatex\fR, etc, and the passing of this option to
 these programs is part of \fIlatexmk\fR's implementation of
 \fB-jobname\fR.
 
+There is one enhancement, that the STRING may contain the
+placeholder '%A'. This will be substituted by the basename of the TeX
+file.  The primary purpose is when multiple files are specified on the
+command line to \fIlatexmk\fR, and you wish to use a jobname with a
+different file-dependent value for each file.  For example, suppose
+you had .tex files test1.tex and test2.tex, and you wished to compare
+the results of compilation by \fIpdflatex\fR and those with
+\fIxelatex\fR.  Then under a unix-type operating system you could use
+the command line 
+
+    latexmk -pdf -jobname=%A-pdflatex *.tex
+    latexmk -pdfxe -jobname=%A-xelatex *.tex
+
+Then the .aux, .log, and .pdf files from the use of \fIpdflatex\fR
+would have basenames test1-pdflatex and test2-pdflatex, while from
+\fIxelatex\fR, the basenames would be test1-xelatex and test2-xelatex.
+
+Under MS-Windows with cmd.exe, you would need to double the percent
+sign, so that the percent character is passed to latexmk rather than
+being used to substitute an environment variable:
+
+    latexmk -pdf -jobname=%%A-pdflatex *.tex
+    latexmk -pdfxe -jobname=%%A-xelatex *.tex
+
 .TP
 .B -l
 Run in landscape mode, using the landscape mode for the previewers and
@@ -788,7 +815,7 @@ behaves like the \fB-pdflatex\fR option, but sets the variable
 
 .TP
 .B -pdfxelatex="COMMAND"
-This sets the string specifying the command to run \fIlualatex\fR.  It
+This sets the string specifying the command to run \fIxelatex\fR.  It
 behaves like the \fB-pdflatex\fR option, but sets the variable
 \fI$xelatex\fR.
 
@@ -1263,6 +1290,82 @@ j. Or ask me (the author of \fIlatexmk\fR).  My e-mail is at the end
 of this documentation.
 
 
+.SH ALLOWING FOR CHANGE OF OUTPUT FILE TYPE
+
+When one of the latex engines is run, the usual situation is that
+\fIlatex\fR produces a .dvi file, while \fIpdflatex\fR and
+\fIlualatex\fR produce a .pdf file.  For \fIxelatex\fR the default is
+to produce a .pdf file, but to optimize processing time \fIlatexmk\fR
+runs \fIxelatex\fR its \fB-no-pdf\fR option so that it produces
+an .xdv file.  Further processing by \fIlatexmk\fR takes this as a
+starting point.
+
+However, the actual output file may differ from the normal
+expectation; and then \fIlatexmk\fR can adjust its processing to
+accommodate this situation.  The difference in output file type can
+happen for two reasons: One is that for \fIlatex\fR, \fIpdflatex\fR
+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.)
+
+Under \fIlatex\fR and \fIpdflatex\fR, control of the output format by
+the document is done by setting the \\pdfoutput macro.  Under
+\fIlualatex\fR, the \\outputmode macro is used instead.
+
+One example of an important use-case for document control of the
+output format is a document that uses the psfrag package to insert
+graphical elements in the output file. The psfrag package achieves its
+effects by inserting postscript code in the output of the compilation
+of the document.  This entails the use of compilation to a .dvi file,
+followed by the use of conversion to a postscript file (either
+directly, as by \fIdvips\fR or implicitly, as an intermediate step by
+\fIdvipdf\fR).  Then it is useful to force output to be of the .dvi
+format by inserting \\pdfoutput=0 in the preamble of the document.
+
+Another example is where the document uses graphics file of
+the .pdf, .jpg, and png types.  With the default setting for the
+graphicx package, these can be processed in compilation to .pdf but
+not with compilation to .dvi.  In this case, it is useful to insert
+\\pdfoutput=1 in the preamble of the document to force compilation
+to .pdf output format.
+
+In all of these cases, it is needed that \fIlatexmk\fR has to adjust
+its processing to deal with a mismatch between the actual output
+format (out of .pdf, .dvi, .xdv) and the initially expected output, if
+possible.  \fILatexmk\fR does this provided the following conditions
+are met.
+
+The first is that \fIlatexmk\fR's \fI$allow_switch\fR configuration
+variable is set to a non-zero value as it is by default.  If this
+variable is zero, a mismatch of filetypes in the compilation results
+in an erro.
+
+The second condition for \fIlatexmk\fR to be able to handle a change
+of output type is that no explicit requests for .dvi or .ps output
+files are made.  Explicit requests are by the \fB-dvi\fR and
+\fB-ps\fR, \fB-print=dvi\fR, \fB-print=ps\fR, \fB-view=dvi\fR, and
+\fB-view=ps\fR options, and by corresponding settings of the
+\fI$dvi_mode\fR, \fI$postscript_mode\fR, \fI$print_type\fR, and
+\fI$view\fR configuration variables.  The print-type and view-type
+restrictions only apply when printing and viewing are explicitly
+requested, respectively.  For this purpose, the use of the
+\fB-pdfdvi\fR and \fB-pdfps\fR options (and the corresponding setting
+of the \fI$pdf_mode\fR variable) does not count as an explicit request
+for the .dvi and .ps files; they are merely regarded as a request for
+making a .pdf file together with an initial proposal for the
+processing route to make it.
+
+Note that when accommodating a change in output file type, there is
+involved a substantial change in the network of rules that
+\fIlatexmk\fR uses in its actions.  The second condition applied to
+accommodate a change is to avoid situations where the change in the
+rule network is too radical to be readily handled automatically.
+
+
 .SH CONFIGURATION/INITIALIZATION (RC) FILES
 .PP
 \fILatexmk\fR can be customized using initialization files, which are
@@ -1405,6 +1508,11 @@ invocation of \fIlatexmk\fR,  it results in the replacement of %O by
 
 The available placeholders are:
 .TP
+.B %A
+basename of the main tex file.  Unlike %R, this is unaffected by the
+setting of a jobname by  the \fI-jobname\fR option or the
+\fI$jobname\fR configuration value.
+.TP
 .B %B
 base of filename for current command.  E.g., if a postscript file
 document.ps is being made from the dvi file document.dvi, then the
@@ -1416,6 +1524,7 @@ converting a dvi file to postscript).
 .TP
 .B %O
 options
+.TP
 .B %P
 If the variable \fI$pre_tex_code\fR is non-empty, then %P is
 substituted by the contents of \fI$pre_tex_code\fR followed by
@@ -1428,7 +1537,11 @@ If the variable \fI$pre_tex_code\fR is the empty string, then %P is
 equivalent to %S.
 .TP
 .B %R
-root filename.  This is the base name for the main tex file.  
+root filename.  This is the base name for the main tex file.
+
+By default this is the basename of the main tex file.  However the
+value can be changed by the use of the \fI-jobname\fR option or the
+\fI$jobname\fR configuration variable.
 .TP
 .B %S
 source file (e.g., the name of the dvi file when converting a .dvi file
@@ -1436,6 +1549,7 @@ to ps).
 .TP
 .B %T
 The name of the primary tex file.
+.TP
 .B %U
 If the variable \fI$pre_tex_code\fR is non-empty, then its value is
 substituted for %U (appropriately quoted).  Otherwise it is replaced
@@ -1630,6 +1744,23 @@ indicates true, i.e., the behavior occurs, while a zero value
 indicates a false value, i.e., the behavior does not occur.
 
 .TP
+.B $allow_switch [1]
+
+This controls what happens when the output extension of latex,
+pdflatex, lualatex or xelatex differs from what is expected.  (The
+possible extensions are .dvi, .pdf, .xdv.)  This can happen with the
+use of the \\pdfoutput macro in a document compiled under \fIlatex\fR
+or \fIpdflatex\fR, or with the use of the \\outputmode macro under
+\fIlualatex\fR.  It can also happen with certain kinds of incorrect
+configuration. 
+
+In such a case, \fIlatexmk\fR can appropriately adjust its network of
+rules.  The adjustment is made if \fI$allow_switch\fR is on, and if no
+request for a dvi or ps file has been made.
+
+See the section ALLOWING FOR CHANGE OF OUTPUT EXTENSION.
+
+.TP
 .B $always_view_file_via_temporary [0]
 Whether .ps and .pdf files are initially to be made in a temporary
 directory and then moved to the final location.  (This applies to
@@ -1809,7 +1940,6 @@ Note that the value 1.5 does \fInot\fR work properly if the document
 uses \fIbiber\fR instead of \fIbibtex\fR.  (There's a long story why
 not.)
 
-
 .TP
 .B $cleanup_includes_cusdep_generated [0]
 If nonzero, specifies that cleanup also deletes files that are
@@ -1820,9 +1950,19 @@ previous run.)
 .TP
 .B $cleanup_includes_generated [0]
 If nonzero, specifies that cleanup also deletes files that are
-detected in log file as being generated (see the \\openout lines in
-the log file).  It will also include files made from these first
+detected in the fls file (or failing that, in log file) as being
+generated.  It will also include files made from these first
 generation generated files.
+
+This operation is somewhat dangerous, and can have unintended
+consequences, since the files to be deleted are determined from a file
+created by (pdf)latex, which can contain erroneous
+information. Therefore this variable is turned off by default, and
+then files to be deleted are restricted to those explictly specified
+by patterns configured in the variables \fIclean_ext\fR,
+\fIclean_full_ext\fR, and \fI@generated_exts\fR, together with those
+very standard cases that are hardwired into \fIlatexmk\fR (e.g., .log
+files). 
 .TP
 .B $cleanup_mode [0]
 If nonzero, specifies cleanup mode: 1 for full cleanup, 2 for cleanup
@@ -1845,7 +1985,7 @@ It is also possible to specify a more general pattern of file to be
 deleted, by using the place holder %R, as in commands, and it is also
 possible to use wildcards.  Thus setting
 
-  $clean_ext = "out %R-blx.bib %R-figures*.log pythontex-files-%R/*";
+    $clean_ext = "out %R-blx.bib %R-figures*.log pythontex-files-%R/*";
 
 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
@@ -1860,6 +2000,15 @@ equal to \fI$out_dir\fR.  A normal situation is therefore that \fI$aux_dir\fR
 equals \fI$out_dir\fR, which is the only case supported by
 TeXLive, unlike MiKTeX.)
 
+The filenames specfied 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 \fI@generated_exts\fR.
 .TP
 .B $clean_full_ext [""]
 Extra extensions of files for \fIlatexmk\fR to remove when the \fB-C\fR
@@ -2185,20 +2334,22 @@ 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 has two uses: (a) to set the kinds of file to be deleted in
-a cleanup operation (with the \fB-c\fR, \fB-C\fR, \fB-CA\fR, \fB-g\fR
-and \fB-gg\fR options), and (b) in the determination of whether a
-rerun of (pdf)LaTeX is needed after a run that gives an error.
-
-(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 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 \fIlatexmk\fR needs to distinguish
-user-generated and automatically generated files; it determines the
-automatically generated files as those with extensions in the list in
-@generated_exts.)
+This list specifies files known to be generated by latex (and
+pdflatex, etc).  It is used in two ways:
+(a) The specified files are deleted in a cleanup operation (with the
+\fB-c\fR, \fB-C\fR, \fB-CA\fR, \fB-g\fR and \fB-gg\fR options), and
+(b) It affects the determination of whether a rerun of (pdf)LaTeX 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 \fIlatexmk\fR needs
+to distinguish user-generated and automatically generated files; it
+determines the automatically generated files as those with extensions
+in the list in @generated_exts.)
 
 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
@@ -2263,6 +2414,36 @@ delete function, e.g.,
     delete $hash_calc_ignore_pattern{'eps'};
 
 .TP
+.B $jobname [""]
+
+This specifies the jobname, i.e., the basename that is used for
+generated files (.aux, .log, .dvi, .ps, .pdf, etc).  If this variable
+is a null string, then the basename is the basename of the main tex
+file.
+(At present, the string in \fI$jobname\fR should not contain spaces.)
+
+The placeholder '%A' is permitted. This will be substituted by the
+basename of the TeX file.  The primary purpose is when a variety of
+tex files are to be processed, and you want to use a different jobname
+for each but one that is distinct for each. Thus if you wanted to
+compare compilations of a set of files on different operating systems,
+with distinct filenames for all the cases, you could set
+
+   $jobname = "%A-$^O";
+
+in an initialization file.  (Here \fI$^O\fR is a variable provided by
+perl that contains perl's name for the operating system.)  
+
+Suppose you had .tex files test1.tex and test2.tex.  Then when you run
+
+   latexmk -pdf *.tex
+
+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, and a variety of
+similar cases on linux systems.
+
+.TP
 .B $kpsewhich ["kpsewhich %S"]
 The program called to locate a source file when the name alone is not
 sufficient.  Most filenames used by \fIlatexmk\fR have sufficient path
@@ -2511,6 +2692,7 @@ document using \fIxelatex\fR, using the commands specified by the
 
 In \fI$pdf_mode\fR=2, it is ensured that .dvi and .ps files are also made.
 In \fI$pdf_mode\fR=3, it is ensured that a .dvi file is also made.
+But this may be overridden by the document.
 .TP
 .B $pdflatex ["pdflatex %O %S"]
 Specifies the command line for
@@ -3304,6 +3486,33 @@ also the examples in the directory \fIexample_rcfiles\fR in the
 \fIlatexmk\fR distributions.  Even if none of the examples apply to
 your case, they may give you useful ideas
 
+.SS Utility subroutines
+
+.TP
+.B ensure_path( var, values ...)
+
+The first parameter is the name of one of the system's environment
+variables for search paths.  The remaining parameters are values that
+should be in the variable.  For each of the value parameters, if it
+isn't already in the variable, then it is prepended to the variable;
+in that case the environment variable is created if it doesn't already
+exist. For separating values, the character appropriate the the
+operating system is used -- see the configuration variable
+\fI$search_path_separator\fR. 
+
+Example:
+
+  ensure_path( 'TEXINPUTS', './custom_cls_sty_files//' );
+
+(In this example, the trailing '//' is documented by TeX systems to
+mean that latex, pdflatex, etc search for files in the specified
+directory and in all subdirectories.)
+
+Technically \fIensure_path\fR works by setting Perl's variable
+\fI$ENV{var}\fR, where \fIvar\fR is the name of the target variable.
+The changed value is then passed as an environment variable to any
+invoked programs.
+
 .SS Variables and subroutines for processing a rule
 
 A step in the processing is called a rule. One possibility to
@@ -3575,7 +3784,7 @@ e-mail addresses are not written in their standard form to avoid being
 harvested too easily.)
 .SH AUTHOR
 Current version, by John Collins (username jcc8 at node psu.edu).
-(Version 4.61).
+(Version 4.63b).
 
 Released version can be obtained from CTAN:
 <http://www.ctan.org/pkg/latexmk/>, and from the
diff --git a/Master/texmf-dist/doc/man/man1/latexmk.man1.pdf b/Master/texmf-dist/doc/man/man1/latexmk.man1.pdf
index 2e7c93a21cc..566081325bd 100644
--- a/Master/texmf-dist/doc/man/man1/latexmk.man1.pdf
+++ b/Master/texmf-dist/doc/man/man1/latexmk.man1.pdf