CTAN sync 202203180301

1 files changed, 56 insertions, 34 deletions

diff --git a/support/latexmk/latexmk.1 b/support/latexmk/latexmk.1
index 50a39b39cb..f81bb0fb2a 100644
--- a/support/latexmk/latexmk.1
+++ b/support/latexmk/latexmk.1
@@ -1,4 +1,4 @@
-.TH LATEXMK 1 "20 November 2021" ""
+.TH LATEXMK 1 "17 March 2022" ""
 .SH NAME
 latexmk \- generate LaTeX document
 .SH SYNOPSIS
@@ -2136,9 +2136,9 @@ created by *latex, which can contain erroneous
 information. Therefore this variable is turned off by default, and
 then files to be deleted are restricted to those explicitly 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). 
+\fIclean_full_ext\fR, and \fI@generated_exts\fR.  Standard cases (e.g., .log
+files) appear in \fIlatexmk\fR's initial value for the array
+\fI@generated_exts\fR. 
 .TP
 .B $cleanup_mode [0]
 If nonzero, specifies cleanup mode: 1 for full cleanup, 2 for cleanup
@@ -2169,12 +2169,20 @@ 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).
 
-The files to be deleted are relative to the directory specified by
-\fI$aux_dir\fR.  (Note that if \fI$out_dir\fR but not \fI$aux_dir\fR
-is set, then in its initialization, \fIlatexmk\fR sets \fI$aux_dir\fR
-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.)
+Most of the files to be deleted are relative to the directory specified by
+\fI$aux_dir\fR.  Note that if \fI$out_dir\fR but not \fI$aux_dir\fR is
+set, then in its initialization, \fIlatexmk\fR sets \fI$aux_dir\fR 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 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
+\fI$emulate_aux variable.
+
+If \fI$out_dir\fR and \fI$aux_dir\fR different, latexmk actually deletes
+any files of the specified names in both \fI$aux_dir\fR and \fI$out_dir\fR;
+this is because under certain error conditions, the files may be put in
+\fI$out_dir\fR instead of \fI$aux_dir\fR.  This also handles the case of
+deleting any fls file, since that file is in \fI$out_dir\fR.
 
 The filenames specified for a clean-up operation can refer not only to
 regular files but also to directories.  Directories are only deleted
@@ -2184,7 +2192,11 @@ both the files and the directory by setting
 
     $clean_ext = "pythontex-files-%R pythontex-files-%R";
 
-See also the variable \fI@generated_exts\fR.
+See also the (array) variable \fI@generated_exts\fR.  In the past, this
+variable had certain uses beyond that of \fI$clean_ext\fR.  But now, they
+accomplish the same things.  In fact, after initialization including the
+processing of command line options, \fIlatexmk\fR simply appends the list
+of extensions in \fI$clean_ext\fR to the array \fI@generated_exts\fR.
 .TP
 .B $clean_full_ext [""]
 Extra extensions of files for \fIlatexmk\fR to remove when the \fB-C\fR
@@ -2522,28 +2534,37 @@ mode is used and diagnostic mode is not on.
 If nonzero, continue processing past minor \fIlatex\fR errors 
 including unrecognized cross references.  Equivalent to specifying the
 \fB-f\fR option.
+
 .TP
-.B @generated_exts [( "aux", "bbl", "idx", "ind", "lof", "lot", "out", "toc", $fdb_ext )]
+.B @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 \fI*latex\fR.
-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 *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.)
+processing, and that should be deleted during a main clean up operation, as
+invoked by the command line option \fB-c\fR.  (The use of \fB-C\fR or
+\fB-gg\fR gives this clean up and more.)  
+
+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.)
+
+After initialization of latexmk and the processing of its command line, the
+items in \fIclean_ext\fR are appended to \fI@generated_exts\fR.  So these
+two variables have the same meaning (contrary to older versions of
+latexmk).
+
+The items in \fI@generated_exts\fR 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 \fI$clean_ext\fR.   
+
+In addition to specifying files to be deleted in a clean up, latexmk 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 \fI@generated_exts\fR is normally unimportant, given the usual
+accuracy 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
@@ -2553,7 +2574,8 @@ RC file.  E.g.,
 
 adds the extension "end" to the list of predefined generated
 extensions.  (This extension is used by the RevTeX package, for
-example.) 
+example.)
+
 .TP
 .B $go_mode [0]
 If nonzero, process files regardless of timestamps, and is then
@@ -3825,7 +3847,7 @@ is being called.
   set_tex_cmds( CMD_SPEC );
 
 Here CMD_SPEC is the command line without the program name. This
-results in \fI$latex = 'CMD_SPEC'\fR, and similarly for
+results in \fI$latex = 'latex CMD_SPEC'\fR, and similarly for
 \fI$pdflatex\fR, \fI$lualatex\fR, and \fI$xelatex\fR. An example would
 be 
 
@@ -3996,7 +4018,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.76).
+(Version 4.77).
 Report bugs etc to his e-mail (jcc8 at psu.edu).
 
 Released version can be obtained from CTAN: