latexmk (17jan17)

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

2 files changed, 376 insertions, 271 deletions

diff --git a/Master/texmf-dist/doc/man/man1/latexmk.1 b/Master/texmf-dist/doc/man/man1/latexmk.1
index e2af193039b..e5b389b1c5b 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 1L "5 September 2016" ""
+.TH LATEXMK 1 "16 January 2017" ""
 .SH NAME
 latexmk \- generate LaTeX document
 .SH SYNOPSIS
@@ -42,7 +42,7 @@ updated figure file it can automatically generate a file in
 encapsulated postscript or another suitable format for reading by
 LaTeX.
 .PP
-\fILatexmk\fR has two different previewing options.  In the simple
+\fILatexmk\fR has two different previewing options.  With the simple
 \fB-pv\fR option, a dvi, postscript or pdf previewer is automatically
 run after generating the dvi, postscript or pdf version of the
 document.  The type of file to view is selected according to
@@ -53,14 +53,14 @@ The second previewing option is the powerful \fB-pvc\fR option
 continuously, regularly monitoring all the source files to see if any
 have changed.  Every time a change is detected, \fIlatexmk\fR runs all
 the programs necessary to generate a new version of the document.  A
-good previewer (like \fIgv\fR) will then automatically update its
+good previewer will then automatically update its
 display.  Thus the user can simply edit a file and, when the changes
 are written to disk, \fIlatexmk\fR completely automates the cycle of
-updating the .dvi (and possibly the .ps and .pdf) file, and refreshing
+updating the .dvi (and/or the .ps and .pdf) file, and refreshing
 the previewer's display.  It's not quite WYSIWYG, but usefully close.
 .PP
 For other previewers, the user may have to manually make the previewer
-update its display, which can be (some versions of \fIxdvi\fR and
+update its display, which can be (e.g., with some versions of \fIxdvi\fR and
 \fIgsview\fR) as simple as forcing a redraw of its display.
 .PP
 \fILatexmk\fR has the ability to print a banner in gray diagonally
@@ -71,17 +71,16 @@ generated dvi and postscript files.  (See the options \fB-dF\fR and
 \fI$ps_filter\fR configuration variables.)  These capabilities are
 leftover from older versions of \fIlatexmk\fR.  More flexibility can
 be obtained in current versions, since the command strings for running
-latex, pdflatex, etc can now be configured to run multiple commands.
-This also extends the possibility of postprocessing generated files to
-pdf files.
-files.
+\fIlatex\fR, \fIpdflatex\fR, etc can now be configured to run multiple
+commands. 
+This also extends the possibility of postprocessing generated files.
 .PP
 \fILatexmk\fR is highly configurable, both from the command line and
 in configuration files, so that it can accommodate a wide variety of
 user needs and system configurations.  Default values are set
 according to the operating system, so \fIlatexmk\fR often works 
 without special configuration on MS-Windows, cygwin, Linux, OS-X, and
-other UNIX systems (notably Solaris).
+other UNIX systems.
 .PP
 A very annoying complication handled very reliably by \fIlatexmk\fR,
 is that LaTeX is a multiple pass system.  On each run, LaTeX reads in
@@ -91,7 +90,7 @@ LaTeX suffices, and often the log file contains a message about the
 need for another pass.  However, there is a wide variety of add-on
 macro packages to LaTeX, with a variety of behaviors.  The result is
 to break simple-minded determinations of how many runs are needed and
-of which programs.  In its new version, \fIlatexmk\fR has a highly
+of which programs.  \fILatexmk\fR has a highly
 general and efficient solution to these issues.  The solution involves
 retaining between runs information on the source files, and a symptom
 is that \fIlatexmk\fR generates an extra file (with extension
@@ -123,19 +122,17 @@ information.
 \fBNote 2\fR: In this documentation, the program \fIpdflatex\fR is often
 referred to.  Users of programs like \fIlualatex\fR and \fIxelatex\fR
 should know that from \fIlatexmk\fR's point of view, these other
-programs behave like \fIpdflatex\fR, i.e., they make a pdf file from a
+programs behave very like \fIpdflatex\fR, i.e., they make a pdf file from a
 tex file, etc.  So whenever \fIpdflatex\fR is mentioned without
 mention of the other programs, the statements apply equally to
 \fIlualatex\fR, \fIxelatex\fR, and any other similar programs.
 \fILatexmk\fR can be easily configured to use whichever of these
 programs is needed.  See the documentation for the following options:
-\fB-pdflatex="COMMAND"\fR,
-\fB-lualatex\fR, and
-\fB-xelatex\fR,
+\fB-pdflua\fR, \fB-pdfxe\fR, \fB-lualatex\fR, and \fB-xelatex\fR,
 and also see the documentation for the 
-\fI$pdflatex\fR configuration variable.
-At present \fIlatexmk\fR cannot do automatic detection of which
-program is to be used.
+\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
@@ -402,7 +399,8 @@ requested.)
 .B -e <code>
 Execute the specified initialization code before processing.  The code
 is \fIPerl\fR code of the same form as is used in \fIlatexmk\fR's
-initialization files -- for more details, see the information on the
+initialization files.  For more details,
+see the information on the
 \fB-r\fR option, and the section about "Configuration/initialization
 (RC) files".  The code is typically a sequence of assignment
 statements separated by semicolons.
@@ -417,11 +415,11 @@ they appear on the command line.
 Some care is needed to deal with proper quoting of special characters
 in the code on the command line.  For example, suppose you want
 to set the latex command to use its -shell-escape option, then under
-UNIX/LINUX you could use the line
+UNIX/Linux you could use the line
 
 	latexmk -e '$latex=q/latex %O -shell-escape %S/' file.tex
 
-Note that the single quotes block normal UNIX/LINUX command shells
+Note that the single quotes block normal UNIX/Linux command shells
 from treating the characters inside the quotes as special.
 (In this example, the q/.../ construct is a
 \fIPerl\fR idiom equivalent to using 
@@ -439,7 +437,12 @@ or
 
 	latexmk -e "$latex='latex %O -shell-escape %S'" file.tex
 
-The last two examples will NOT work with UNIX/LINUX command shells.
+The last two examples will NOT work with UNIX/Linux command shells.
+
+(\fINote\fR: the above examples show are to show how to use the
+\fB-e\fR to specify initialization code to be executed.  But the
+particular effect can be achieved also by the use of the \fB-latex\fR
+option with less problems in dealing with quoting.)
 
 .TP
 .B -f
@@ -517,20 +520,37 @@ operating system and the command-line shell you are using, you may
 need to change the single quotes to double quotes (or something
 else). 
 
-To set the command for running pdflatex (rather than the command for
-latex) see the \fB-pdflatex\fR option.
+To set the command for running \fIpdflatex\fR (rather than the command for
+\fIlatex\fR) see the \fB-pdflatex\fR option.
+
+.TP
+.B -logfilewarninglist
+.B -logfilewarnings
+After a run of \fI(pdf)latex\fR, give a list of warnings about
+undefined citations and references (unless silent mode is on).
 
-Note that the effect of this option can also be achieved by using
-the \fB-e\fR option with a suitable line of Perl code to set the
-\fI$latex\fR variable.  See the explanation of the \fB-e\fR option.
+See also the \fI$silence_logfile_warnings\fR configuration variable.
+
+.TP
+.B -logfilewarninglist-
+.B -logfilewarnings-
+After a run of \fI(pdf)latex\fR, do not give a list of warnings about
+undefined citations and references.  (Default)
+
+See also the \fI$silence_logfile_warnings\fR configuration variable.
 
 .TP
 .B -lualatex
-Use lualatex.  That is, use lualatex to process the source file(s) to
-pdf (in place of pdflatex).  This option is exactly equivalent to
-specifying the following sequence of options: 
+Use \fIlualatex\fR.  That is, use \fIlualatex\fR to process the source file(s) to
+pdf.  The generation of dvi and postscript files is turned off.
+
+This option is equivalent to using the following set of options
+
+     -pdflua -dvi- -ps-
 
-     -pdflatex="lualatex %O %S" -pdf -dvi- -ps-
+(\fINote\fR: Note that the method of implementation of this option,
+but not its intended effect, differ from some earlier versions of
+\fIlatexmk\fR.)
 
 .TP
 .B -M
@@ -544,10 +564,10 @@ write it to.
 
 .TP
 .B -MP
-If a list of dependents is made, includes phony target for each source
+If a list of dependents is made, 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
-updating the Makefile to match.
+work around errors the program \fImake\fR gives if you remove header
+files without updating the Makefile to match.
 
 .TP
 .B -new-viewer
@@ -567,14 +587,7 @@ an already-running previewer.
 
 .TP
 .B -nobibtex
-Never run bibtex or biber.
-
-A common use for this option is when a document comes from an external
-source, complete with its bbl file(s), and the user does not have the
-corresponding bib files available.  In this situation use of the
-\fB-nobibtex\fR option will prevent \fIlatexmk\fR from trying to run
-\fIbibtex\fR or \fIbiber\fR, which would result in overwriting of the
-bbl files. 
+Never run bibtex or biber.  Equivalent to the \fB-bibtex-\fR option.
 
 .TP
 .B -norc
@@ -613,7 +626,7 @@ But you can use the
 can configure this in a start up file (by setting the
 \fI$print_type\fR variable).  
 
-However, printing is enabled by default only under UNIX/LINUX systems,
+However, printing is enabled by default only under UNIX/Linux systems,
 where the default is to use the lpr command and only on postscript
 files.  In general, the correct
 behavior for printing very much depends on your system's software.  In
@@ -630,7 +643,8 @@ so it turns them off.
 .B -pdf
 Generate pdf version of document using \fIpdflatex\fR.  (If you wish
 to use \fIlualatex\fR or \fIxelatex\fR, you can use whichever of the
-options \fB-lualatex\fR or \fB-xelatex\fR applies.)  To configure
+options \fB-pdflua\fR, \fB-pdfxe\fR, \fB-lualatex\fR or \fB-xelatex\fR
+applies.)  To configure 
 \fIlatexmk\fR to have such behavior by default, see the section on 
 "Configuration/initialization (rc) files".
 
@@ -639,9 +653,28 @@ options \fB-lualatex\fR or \fB-xelatex\fR applies.)  To configure
 Generate pdf version of document from the dvi file, by default using dvipdf.
 
 .TP
+.B -pdflua
+Generate pdf version of document using \fIlualatex\fR.
+
+.TP
 .B -pdfps
 Generate pdf version of document from the ps file, by default using
-ps2pdf. 
+\fIps2pdf\fR. 
+
+.TP
+.B -pdfxe
+Generate pdf version of document using \fIxelatex\fR.  Note that to
+optimize processing time, \fIlatexmk\fR uses \fIxelatex\fR to generate
+an xdv file rather than a pdf file directly.  Only after possibly
+multiple runs to generate a fully up-to-date xdv does \fIlatexmk\fR
+then call \fIxdvipdfmx\fR to generate the final pdf file.
+
+(\fINote:\fR When the document includes large graphics files,
+especially png files, the last step can be quite time consuming, even
+when the creation of the xdv file by \fIxelatex\fR is fast.  So the
+use of the intermediate xdv file can result in substantial gains in
+procesing time, since the pdf file is produced once rather than on
+every run of \fIxelatex\fR.)
 
 .TP
 .B -pdf-
@@ -652,7 +685,7 @@ a pdf file.)
 
 .TP
 .B -pdflatex="COMMAND"
-This sets the string specifying the command to run pdflatex, and is
+This sets the string specifying the command to run \fIpdflatex\fR, and is
 typically used to add desired options.  Since the string normally
 contains spaces, it should be quoted, e.g.,
 
@@ -664,24 +697,9 @@ operating system and the command-line shell you are using, you may
 need to change the single quotes to double quotes (or something
 else). 
 
-This option can also be used to set a program to be used instead of
-the standard \fIpdflatex\fR program, e.g., 
-
-     latexmk -pdf -pdflatex="lualatex %O %S"  foo.tex
-
-to use \fIlualatex\fR or
-
-     latexmk -pdf -pdflatex="xelatex %O %S"  foo.tex
-
-to use \fIxelatex\fR.
-
 To set the command for running \fIlatex\fR (rather than the command
 for \fIpdflatex\fR) see the \fB-latex\fR option.
 
-Note that the effect of this option can also be achieved by using
-the \fB-e\fR option with a suitable line of Perl code to set the
-\fI$pdflatex\fR variable. See the explanation of the \fB-e\fR option.
-
 .TP
 .B -print=dvi, -print=ps, -print=pdf, -print=auto,
 Define which kind of file is printed.  This option also ensures that
@@ -764,11 +782,11 @@ read.)  Many other previewers will need a manual update.
 \fBImportant note\fR: the acroread program on MS-Windows locks the pdf file,
 and prevents new versions being written, so it is a bad idea to use
 acroread to view pdf files in preview-continuous mode.  
-It is better to use a different viewer: SumatraPDF and gsview are
-good possibilities. 
+It is better to use a different viewer: \fISumatraPDF\fR and
+\fIgsview\fR are good possibilities. 
 
 There are some other methods for arranging an update, notably useful
-for many versions of xdvi and xpdf.  These are best set in
+for many versions of \fIxdvi\fR and \fIxpdf\fR.  These are best set in
 \fIlatexmk\fR's configuration; see below. 
 
 Note that if \fIlatexmk\fR dies or is stopped by the user, the
@@ -812,19 +830,20 @@ the order they appear on the command line.
 
 .TP
 .B -recorder
-Use the -recorder option with \fIlatex\fR and \fIpdflatex\fR.  In
+Give the -recorder option with \fIlatex\fR and \fIpdflatex\fR.  In
 (most) modern versions of these programs, this results in a file of
 extension \fI.fls\fR containing a list of the files that these
 programs have read and written.  \fILatexmk\fR will then use this file
 to improve its detection of source files and generated files after a
-run of \fIlatex\fR or \fIpdflatex\fR.
+run of \fIlatex\fR or \fIpdflatex\fR.  This is the default setting of
+\fIlatexmk\fR, unless overridden in an initialization file.
 
 For further information, see the documentation for the \fI$recorder\fR
 configuration variable.
 
 .TP
 .B -recorder-
-Do not use the -recorder option with \fIlatex\fR and \fIpdflatex\fR. 
+Do not supply the -recorder option with \fIlatex\fR and \fIpdflatex\fR.
 
 .TP
 .B -rules 
@@ -838,9 +857,9 @@ processing.  (This is the default.)
 .TP
 .B -showextraoptions
 Show the list of extra \fIlatex\fR and \fIpdflatex\fR options that
-\fIlatexmk\fR recognizes.  These are options for the \fIlatex\fR and
-\fIpdflatex\fR that \fIlatexmk\fR recognizes, but simply passes
-through to these programs when they are run.  These options are
+\fIlatexmk\fR recognizes, but that it simply passes
+through to the programs \fIlatex\fR, \fIpdflatex\fR, etc  when they
+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 \fIlatex\fR or
@@ -869,49 +888,46 @@ documentation.  These options are:
 \fB-output-directory=DIR\fR, \fB-quiet\fR, and \fB-recorder\fR.
 
 .TP
-.B -logfilewarninglist
-.B -logfilewarnings
-After a run of (pdf)latex, give a list of warnings about
-undefined citations and references (unless silent mode is on).
-
-See also the $silence_logfile_warnings configuration variable.
-
-.TP
-.B -logfilewarninglist-
-.B -logfilewarnings-
-After a run of (pdf)latex, do not give a list of warnings about
-undefined citations and references.  (Default)
-
-See also the $silence_logfile_warnings configuration variable.
-
-.TP
 .B -silent
 Run commands silently, i.e., with options that reduce the amount of
 diagnostics generated.  For example, with the default settings, the
-command "latex -interaction=batchmode" is used for latex.
+command "latex -interaction=batchmode" is used for \fI(pdf)latex\fR
+and friends.
 
 See also the \fB-logfilewarninglist\fR and \fB-logfilewarninglist-\fR
 options. 
 
 Also reduce the number of informational messages that \fIlatexmk\fR
-generates. 
+itself generates. 
 
 To change the options used to make the commands run silently, you need
 to configure \fIlatexmk\fR with changed values of its configuration
 variables, the relevant ones being \fI$bibtex_silent_switch\fR,
 \fI$biber_silent_switch\fR, \fI$dvipdf_silent_switch\fR, 
-\fI$dvips_silent_switch\fR, \fI$latex_silent_switch\fR, 
-\fI$makeindex_silent_switch\fR, and \fI$pdflatex_silent_switch\fR.
+\fI$dvips_silent_switch\fR, \fI$latex_silent_switch\fR,
+\fI$lualatex_silent_switch\fR
+\fI$makeindex_silent_switch\fR, \fI$pdflatex_silent_switch\fR,
+and \fI$xelatex_silent_switch\fR
+
+.TP
+.B -time
+Show CPU time used.
+See also the configuration variable \fI$show_time\fR.
+
+.TP
+.B -time-
+Do not show CPU time used.
+See also the configuration variable \fI$show_time\fR.
 
 .TP
 .B -use-make
 When after a run of \fIlatex\fR or \fIpdflatex\fR, there are warnings
 about missing files (e.g., as requested by the LaTeX \\input, \\include,
-and \\includgraphics), \fIlatexmk\fR tries to make them by a custom
+and \\includgraphics commands), \fIlatexmk\fR tries to make them by a custom
 dependency. If no relevant custom dependency with an appropriate
-source file is found, and if the -use-make option is set, then
-\fIlatexmk\fR will try as a resort using the make program to try to
-make the missing files.
+source file is found, and if the \fB-use-make\fR option is set, then
+as a last resort \fIlatexmk\fR will try to use the \fImake\fR program
+to try to make the missing files.
 
 Note that the filename may be specified without an extension, e.g.,
 by \\includegraphics{drawing} in a LaTeX file.  In that case,
@@ -938,20 +954,32 @@ Opposite of \fB-silent\fR.  This is the default setting.
 .B -view=default, -view=dvi, -view=ps, -view=pdf, -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 order dvi, ps, pdf).  
+kind of requested file (in the low-to-high order dvi, ps, pdf).  
 
 Note the possibility \fB-view=none\fR where no viewer is opened at
 all.  One example of is use is in conjunction with the \fB-pvc\fR
 option, when you want \fIlatexmk\fR to do a compilation automatically
-whenever source file(s) change, but do want a previewer to be opened.
+whenever source file(s) change, but do not want a previewer to be opened.
 
 .TP
 .B -xelatex
-Use xelatex.  That is, use xelatex to process the source file(s) to
-pdf (in place of pdflatex).  This option is exactly equivalent to
-specifying the following sequence of options: 
+Use \fIxelatex\fR.  That is, use \fIxelatex\fR to process the source file(s) to
+pdf.  The generation of dvi and postscript files is turned off.
+
+This option is equivalent to using the following set of options
+
+     -pdfxe -dvi- -ps-
+
+[\fINote\fR: Note that the method of implementation of this option,
+but not its intended primary effect, differ from some earlier versions
+of \fIlatexmk\fR. \fILatexmk\fR first uses \fIxelatex\fR to make an
+xdv file, and does all the extra runs needed (including those of
+\fIbibtex\fR, etc).  Only after that does it make the pdf file from
+the xdv file, using \fIxdvipdfmx\fR.  This procedure can result in
+considerable savings in run time, since the xdv-to-pdf conversion is
+quite time-consuming when large graphics files are used in the
+document.]
 
-     -pdflatex="xelatex %O %S" -pdf -dvi- -ps-
 
 .PP
 \fBCompatibility between options\fR
@@ -977,7 +1005,7 @@ each of these options turns the others off.
 					uses.  After any changes rerun latex
 					the appropriate number of times and
 					remake the postscript file.  If latex
-					encounters an error, latexmk will
+					encounters an error, \fIlatexmk\fR will
 					keep running, watching for
 					source file changes.
 
@@ -1015,7 +1043,7 @@ particular situations.  (But there is a lot of reading!)
 difficult situations.\fR
 
 d. Further tricks can involve replacing the standard commands that
-\fIlatexmk\fR by other commands or scripts.
+\fIlatexmk\fR runs by other commands or scripts.
 
 e. For possible examples of code for use in an RC file, see the
 directory example_rcfiles in the distribution of \fIlatexmk\fR (e.g.,
@@ -1043,13 +1071,13 @@ different name, change bar.baz to the name of your file.
 
 g. See also the section \fBADVANCED CONFIGURATION: Some extra resources\fR.
 
-g. Look on tex.stackexchange, i.e., at
+h. Look on tex.stackexchange, i.e., at
 http://tex.stackexchange.com/questions/tagged/latexmk  Someone may
 have already solved your problem.
 
-h. Ask a question at tex.stackexchange.com.
+i. Ask a question at tex.stackexchange.com.
 
-i. Or ask me (the author of \fIlatexmk\fR).  My e-mail is at the end
+j. Or ask me (the author of \fIlatexmk\fR).  My e-mail is at the end
 of this documentation.
 
 
@@ -1064,14 +1092,15 @@ system RC file, in the following order, and reads the first it finds:
    "/opt/local/share/latexmk/LatexMk",
    "/usr/local/share/latexmk/LatexMk",
    "/usr/local/lib/latexmk/LatexMk".
-   On a MS-WINDOWS system it looks for "C:\\latexmk\\LatexMk".
+   On a MS-Windows system it looks for "C:\\latexmk\\LatexMk".
    On a cygwin system (i.e., a MS-Windows system in which Perl is
-that of cygwin), \fIlatexmk\fR reads for the first it finds of
+that of cygwin), \fIlatexmk\fR reads the first it finds of
    "/cygdrive/c/latexmk/LatexMk",
    "/opt/local/share/latexmk/LatexMk",
    "/usr/local/share/latexmk/LatexMk",
    "/usr/local/lib/latexmk/LatexMk".
-   In addition, it then tries the same set of locations, but with the
+   
+In addition, it then tries the same set of locations, but with the
 file name replaced "LatexMk" replaced by "latexmkrc". 
 .PP
 2) The user's RC file, if it exists.  This can be in one of two
@@ -1087,7 +1116,7 @@ Here $HOME
 is the user's home directory.  [\fILatexmk\fR determines the user's
 home directory as follows:  It is the value of the environment variable
 HOME, if this variable exists, which normally is the case on UNIX-like
-systems (including LINUX and OS-X).  Otherwise the environment
+systems (including Linux and OS-X).  Otherwise the environment
 variable USERPROFILE is used, if it exists, which normally is the case
 on MS-Windows systems. Otherwise a blank string is used instead of
 $HOME, in which case \fIlatexmk\fR does not look for an RC file in
@@ -1104,7 +1133,8 @@ and \fIlatexmk\fR does not look for an RC file under it.
 named either "latexmkrc" or ".latexmkrc", and the first of these to be
 found is used, if any.
 .PP
-4) Any RC file(s) specified on the command line with the \fB-r\fR option.
+4) Any RC file(s) specified on the command line with the \fB-r\fR
+option.
 .PP
 Each RC file is a sequence of \fIPerl\fR commands.  Naturally, a user can use
 this in creative ways.  But for most purposes, one simply uses a
@@ -1123,7 +1153,7 @@ overridden by later options on the command line.  There is also the
 
 \fI
 For possible examples of code for in an RC file, see the directory
-example_rcfiles in the distribution of latexmk (e.g., at
+example_rcfiles in the distribution of \fIlatexmk\fR (e.g., at
 http://mirror.ctan.org/support/latexmk/example_rcfiles).
 \fR
 
@@ -1169,6 +1199,8 @@ Some of the variables set the commands that \fIlatexmk\fR uses for
 carrying out its work, for example to generate a dvi file from a tex
 file or to view a postscript file.  This section describes some
 important features of how the commands are specified.
+(Note\ that some of the possibilities listed here do not apply to
+the \fI$kpsewhich\fR variable; see its documentation.)
 
 \fBPlaceholders\fR:  Supposed you wanted \fIlatexmk\fR to use the
 command elatex in place of the regular latex command, and suppose
@@ -1181,8 +1213,9 @@ The two items starting with the % character are placeholders.  These
 are substituted by appropriate values before the command is run.  Thus
 %S will be replaced by the source file that elatex will be applied to,
 and %O will be replaced by any options that \fIlatexmk\fR has decided
-to use for this command.  (E.g., if you used the -silent option it
-would replace %O by "-interaction=batchmode".)
+to use for this command.  (E.g., if you used the \fB-silent\fR option in the
+invocation of \fIlatexmk\fR,  it results in the replacement of %O by
+"-interaction=batchmode".) 
 
 The available placeholders are:
 .TP
@@ -1213,7 +1246,10 @@ Name of directory for auxiliary output files (see the configuration
 variable \fI$aux_dir\fR).  A directory separation character ('/') is
 appended if \fI$aux_dir\fR is non-empty and does not end in a suitable
 character, with suitable characters being those appropriate to UNIX
-and MS-Windows, i.e., ':', '/' and '\\'. 
+and MS-Windows, i.e., ':', '/' and '\\'.   Note that if after
+initialization,  \fI$out_dir\fR is set, but \fI$aux_dir\fR is not set
+(i.e., it is blank), then \fIlatexmk\fR sets \fI$aux_dir\fR to the
+same value \fI$out_dir\fR. 
 .TP
 .B %Z
 Name of directory for output files (see the configuration
@@ -1223,17 +1259,13 @@ character, with suitable characters being those appropriate to UNIX
 and MS-Windows, i.e., ':', '/' and '\\'. 
 .PP
 If for some reason you need a literal % character in your string not
-subject to the above rules, use a pair of these characters.  Thus with
-the command specification $ps_previewer = 'latex -ad=%%Sfile.ad %S',
-the %%S will become %S when the command is executed, but the %S will
-be replaced by the source filename, which in this case would be the
-name of a postscript file to be viewed. 
+subject to the above rules, use "%%".
 .PP
 Appropriate quoting will be applied to the filename substitutions, so
 you mustn't supply them yourself even if the names of your files have
 spaces in them.  (But if your TeX filenames have spaces in them,
 beware that many versions of the TeX program cannot correctly handle
-filenames containing spaces.)  In case latexmk's quoting does not work
+filenames containing spaces.)  In case \fIlatexmk\fR's quoting does not work
 correctly on your system, you can turn it off -- see the documentation
 for the variable \fI$quote_filenames\fR.
 .PP
@@ -1294,14 +1326,15 @@ should be enclosed in double quotes, as in
      $pdf_previewer = 'start "c:/Program Files/SumatraPDF (x86)/SumatraPDF.exe" %O %S';
 
 .PP
-(Note about the above example: Forward slashes are equivalent to
-backslashes in filenames under MS-Windows, provided that the filename
+(Note about the above example: Under MS-Windows forward slashes are
+equivalent to backslashes in a filename under almost all circumstances,
+provided that the filename 
 is inside double quotes.  It is easier to use forward slashes in
 examples like the one above, since then one does not have to worry
 about the rules for dealing with forward slashes in strings in the
 Perl language.)
 
-\fBCommand names under Cygwin\fR: If latexmk is executed by Cygwin's
+\fBCommand names under Cygwin\fR: If \fIlatexmk\fR is executed by Cygwin's
 Perl, \fI be particularly certain that pathnames in commands have
 \fBforward\fI slashes\fR not the usual backslashes for the separator
 of pathname components.  See the above examples.  Backslashes often
@@ -1315,7 +1348,7 @@ command 'start' by itself:
 .PP
      $dvi_previewer = 'start %S';
 .PP
-Under recent versions of MS-Windows, this will cause to be run
+Under MS-Windows, this will cause to be run
 whatever program the system has associated with dvi files.  (The same
 applies for a postscript viewer and a pdf viewer.)  But note that this
 trick is not always suitable for the pdf previwer, if your system has
@@ -1367,8 +1400,8 @@ You can also use a Perl subroutine instead of a script -- see above.
 This is generally the most flexible and portable solution.
 
 It is also possible to configure \fIlatexmk\fR to run multiple
-commands.  For example, if when running pdflatex to generate a pdf
-file from a tex file you need to run another program after pdflatex to
+commands.  For example, if when running \fIpdflatex\fR to generate a pdf
+file from a tex file you need to run another program after \fIpdflatex\fR to
 perform some extra processing, you could do something like:
 
      $pdflatex = 'pdflatex --shell-escape %O %S; pst2pdf_for_latexmk %B';
@@ -1395,13 +1428,16 @@ Default values are indicated in brackets.
 .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
-dvips, dvipdf, and ps2pdf operations, and the filtering operators on
-dvi and ps files.  It does not apply to pdflatex, unfortunately.)
+\fIdvips\fR, \fIdvipdf\fR, and \fIps2pdf\fR operations, and the
+filtering operators on dvi and ps files.  It does not apply to
+\fIpdflatex\fR, unfortunately, since \fIpdflatex\fR provides no way of
+specifying a chosen name for the output file.)
 
 This use of a temporary file solves a problem that the making of these
-files can occupy a substantial time.  If a viewer sees that the file
-has changed, it reads the new file, and this can cause havoc if the
-program writing the file has not yet finished its work.
+files can occupy a substantial time.  If a viewer (notably \fIgv\fR)
+sees that the file has changed, it may read the new file before
+the program writing the file has not yet finished its work, which  can
+cause havoc.
 
 See the \fI$pvc_view_file_via_temporary\fR variable for a setting that
 applies only if preview-continuous mode (-pvc option) is used.  See
@@ -1429,9 +1465,9 @@ which is the directory to which general output files are to be
 written. 
 
 \fBImportant note\fR:  The effect of \fI$aux_dir\fR, if different from
-\fI$out_dir\fR, is achieved by giving (pdf)latex the
+\fI$out_dir\fR, is achieved by giving \fI(pdf)latex\fR the
 \fB-aux-directory\fR.  Currently (Dec. 2011 and later) this only works on the
-MiKTeX version of (pdf)latex.
+MiKTeX version of \fI(pdf)latex\fR.
 
 See also the documentation of \fI$out_dir\fR for some complications on
 what directory names are suitable.
@@ -1501,27 +1537,32 @@ the kpsewhich command, you may need to set the variable \fI@BIBINPUTS\fR.
 The biber processing program.
 .TP
 .B $biber_silent_switch ["--onlylog"]
-\fBSwitch(es)\fR for the biber processing program when silent mode is on.
+Switch(es) for the biber processing program when silent mode is on.
 .TP
 .B $bibtex ["bibtex %O %S"]
 The BibTeX processing program.
 .TP
 .B $bibtex_silent_switch ["-terse"]
-\fBSwitch(es)\fR for the BibTeX processing program when silent mode is on.
+Switch(es) for the BibTeX processing program when silent mode is on.
 .TP
 .B $bibtex_use [1]
-Under what conditions to run BibTeX or biber.  When \fIlatexmk\fR discovers
-from the log file that one (or more) BibTeX/biber-generated bibliographies
-are used, it can run BibTeX or biber whenever it appears necessary to
-regenerate the bbl file(s) from their source bib database file(s).  
+Under what conditions to run \fIbibtex\fR or \fIbiber\fR.  When
+\fIlatexmk\fR discovers
+from the log file that one (or more)
+\fIbibtex\fR/\fIbiber\fR-generated bibliographies 
+are used, it can run \fIbibtex\fR or \fIbiber\fR whenever it appears
+necessary to regenerate the bbl file(s) from their source bib database
+file(s).
 
 But sometimes, the bib file(s) are not available (e.g., for a document
 obtained from an external archive), but the bbl files are provided.
-In that case use of BibTeX or biber will result in incorrect
+In that case use of \fIbibtex\fR or \fIbiber\fR will result in incorrect
 overwriting of the precious bbl files.  The variable \fI$bibtex_use\fR
 controls whether this happens.  Its possible values are: 0: never use
-BibTeX or biber.  1: only use BibTeX or biber if the bib files exist.
-2: run BibTeX or biber whenever it appears necessary to update the bbl
+BibTeX or biber.  1: only use \fIbibtex\fR or \fIbiber\fR if the bib
+files exist. 
+2: run \fIbibtex\fR or \fIbiber\fR whenever it appears necessary to
+update the bbl 
 files, without testing for the existence of the bib files.
 .TP
 .B $cleanup_includes_cusdep_generated [0]
@@ -1711,9 +1752,9 @@ is a prerequisite, then $dvi_mode will be set to 1.
 .TP
 .B $dvi_previewer ["start xdvi %O %S" under UNIX]
 The command to invoke a dvi-previewer.
-[Default is "start" under MS-WINDOWS; under more recent versions of
-Windows, this will cause to be run whatever command the system has
-associated with .dvi files.]
+[Under MS-Windows the default is "start"; then \fIlatexmk\fR arranges to
+use the MS-Windows \fIstart\fR program, which will cause to be run
+whatever command the system has associated with .dvi files.]
 
 \fBImportant note\fR: Normally you will want to have a previewer run
 detached, so that \fIlatexmk\fR doesn't wait for the previewer to
@@ -1728,9 +1769,10 @@ yourself, whenever it is needed.
 .TP
 .B $dvi_previewer_landscape ["start xdvi %O %S"]
 The command to invoke a dvi-previewer in landscape mode.
-[Default is "start" under MS-WINDOWS; under more recent versions of
-Windows, this will cause to be run whatever command the system has
-associated with .dvi files.] 
+[Under MS-Windows the default is "start"; then \fIlatexmk\fR arranges to
+use the MS-Windows \fIstart\fR program, which will cause to be run
+whatever command the system has associated with .dvi files.]
+
 .TP
 .B $dvipdf ["dvipdf %O %S %D"]
 Command to convert dvi to pdf file.  A common reconfiguration is to
@@ -1742,6 +1784,7 @@ 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.
+
 .TP
 .B $dvipdf_silent_switch ["-q"]
 Switch(es) for dvipdf program when silent mode is on.
@@ -1749,24 +1792,25 @@ 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.
+has an effect.  The default setting is correct for \fIdvipdfm\fR and
+\fIdvipdfmx\fR.
 .TP
 .B $dvips ["dvips %O -o %D %S"]
 The program to used as a filter to convert a .dvi file to a .ps file.  
 If pdf is going to be generated from pdf, then the value of the
-$dvips_pdf_switch -- see below -- will be included in the options
-substituted for "%O".
+\fI$dvips_pdf_switch\fR variable -- see below -- will be included in
+the options substituted for "%O".
 .TP
 .B $dvips_landscape ["dvips -tlandscape %O -o %D %S"]
 The program to used as a filter to convert a .dvi file to a .ps file
 in landscape mode.
 .TP
 .B $dvips_pdf_switch ["-P pdf"]
-Switch(es) for dvips program when pdf file is to be generated from
-ps file. 
+Switch(es) for \fIdvips\fR program when pdf file is to be generated
+from ps file. 
 .TP
 .B $dvips_silent_switch ["-q"]
-Switch(es) for dvips program when silent mode is on.
+Switch(es) for \fIdvips\fR program when silent mode is on.
 .TP
 .B $dvi_update_command [""]
 When the dvi previewer is set to be updated by running a command, this
@@ -1784,9 +1828,9 @@ the \fI$ps_update_method\fR variables.
 viewer's window or may mean a more serious action.
     2 => Send the signal, whose number is in the variable
 \fI$dvi_update_signal\fR.  The default value under UNIX is
-suitable for xdvi. 
+suitable for \fIxdvi\fR. 
     3 => Viewer cannot do an update, because it locks the file. (As with
-acroread under MS-Windows.)
+\fIacroread\fR under MS-Windows.)
     4 => run a command to do the update.  The command is specified by
 the variable \fI$dvi_update_command\fR.   
 
@@ -1797,10 +1841,10 @@ example of updating by command.
 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
 \fI$dvi_update_method\fR.  The default value is the one appropriate
-for xdvi on a UNIX system.
+for \fIxdvi\fR on a UNIX system.
 .TP
 .B $failure_cmd [undefined]
-See the documentation for $compiling_cmd.
+See the documentation for \fI$compiling_cmd\fR.
 .TP
 .B $fdb_ext ["fdb_latexmk"]
 The extension of the file which \fIlatexmk\fR generates to contain a
@@ -1889,8 +1933,8 @@ to be ignored.
 
 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 read later.  To do this, you use Perl's delete
-function, e.g.,
+remove this in a file that is read later.  To do this, you use Perl's
+delete function, e.g.,
 
     delete $hash_calc_ignore_pattern{'eps'};
 
@@ -1898,11 +1942,21 @@ function, e.g.,
 .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
-information to be found directly.  But sometimes, notably 
-when .bib files are found from the log file of a bibtex or biber run,
-the name of 
-the file, but not its path is known.  The program specified by
-$kpsewhich is used to find it.  
+information to be found directly.  But sometimes, notably when a .bib
+or a .bst file is found from the log file of a \fIbibtex\fR or
+\fIbiber\fR run, only the base name of the file is known, but not its
+path. The program specified by \fI$kpsewhich\fR is used to find it.
+
+(\fIFor advanced users:\fR Because of the different way in which
+\fIlatexmk\fR uses the command specified in \fI$kpsewhich\fR, some of
+the possibilities listed in the FORMAT OF COMMAND SPECIFICATIONS do
+not apply.  The \fIinternal\fR and \fIstart\fR keywords are not
+available. A simple command specification with possible options and
+then "%S" is all that is guaranteed to work.  Note that for other
+commands, "%S" is substituted by a single source file. In contrast,
+for \fI$kpsewhich\fR, "%S" may be substituted by a long list of
+space-separated filenames, each of which is quoted.  The result on
+STDOUT of running the command is then piped to \fIlatexmk\fR.)
 
 See also the \fI@BIBINPUTS\fR variable for another way that \fIlatexmk\fR
 also uses to try to locate files; it applies only in the case of .bib
@@ -1921,13 +1975,13 @@ but also specify options to the program.  E.g.,
 	$latex = "latex --src-specials";
 .TP
 .B %latex_input_extensions
-This variable specifies the extensions tried by latexmk when it finds
+This variable specifies the extensions tried by \fIlatexmk\fR when it finds
 that a LaTeX run resulted in an error that a file has not been found,
 and the file is given without an extension.  This typically happens when
 LaTeX commands of the form \\input{file} or \\includegraphics{figure},
 when the relevant source file does not exist.
 
-In this situation, latexmk searches for custom dependencies to make
+In this situation, \fIlatexmk\fR searches for custom dependencies to make
 the missing file(s), but restricts it to the extensions specified by
 the variable %latex_input_extensions.  The default extensions 
 are 'tex' and 'eps'.
@@ -1947,7 +2001,7 @@ removes the extension 'tex' from latex_input_extensions
 
 add the extension 'asdf to latex_input_extensions.  (Naturally with
 such an extension, you should have made an appropriate custom
-dependency for latexmk, and should also have done the appropriate
+dependency for \fIlatexmk\fR, and should also have done the 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. 
@@ -1963,16 +2017,16 @@ initialization file
   $latex_silent_switch = "-interaction=batchmode -c-style-errors";
 
 .TP
-.B $lpr ["lpr  %O %S" under UNIX/LINUX, \(dqNONE lpr\(dq under MS-WINDOWS]
+.B $lpr ["lpr  %O %S" under UNIX/Linux, \(dqNONE lpr\(dq under MS-Windows]
 The command to print postscript files.
 
-Under MS-Windows (unlike UNIX/LINUX), there is no standard program for
+Under MS-Windows (unlike UNIX/Linux), there is no standard program for
 printing files.  But there are ways you can do it.  For example, if
-you have gsview installed, you could use it with the option "/p":
+you have \fIgsview\fR installed, you could use it with the option "/p":
 
     $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
 
-If gsview is installed in a different directory, you will need to make
+If \fIgsview\fR is installed in a different directory, you will need to make
 the appropriate change.  Note the combination of single and double
 quotes around the name.  The single quotes specify that this is a
 string to be assigned to the configuration variable \fI$lpr\fR.  The double
@@ -1987,17 +2041,46 @@ The printing program to print dvi files.
 .B $lpr_pdf ["NONE lpr_pdf"]
 The printing program to print pdf files.
 
-Under MS-Windows you could set this to use gsview, if it is installed,
+Under MS-Windows you could set this to use \fIgsview\fR, if it is installed,
 e.g.,
 
     $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
 
-If gsview is installed in a different directory, you will need to make
+If \fIgsview\fR is installed in a different directory, you will need to make
 the appropriate change.  Note the double quotes around the name: this
 is necessary because one part of the command name ("Program Files")
 contains a space which would otherwise be misinterpreted. 
 
 .TP
+.B $lualatex ["lualatex %O %S"]
+The LaTeX processing program that is to be used when the \fIlualatex\fR
+program is called for (e.g., by the option \fB-lualatex\fR.
+
+.TP
+.B %lualatex_input_extensions
+This variable specifies the extensions tried by \fIlatexmk\fR when it finds
+that a \fIlualatex\fR run resulted in an error that a file has not been found,
+and the file is given without an extension.  This typically happens when
+LaTeX commands of the form \\input{file} or \\includegraphics{figure},
+when the relevant source file does not exist.
+
+In this situation, \fIlatexmk\fR searches for custom dependencies to make
+the missing file(s), but restricts it to the extensions specified by
+the variable %pdflatex_input_extensions.  The default extensions 
+are 'tex', 'pdf', 'jpg, and 'png'.
+
+See details of the \fI%latex_input_extensions\fR for other information
+that equally applies to \fI%lualatex_input_extensions\fR.
+
+.TP
+.B $lualatex_silent_switch  ["-interaction=batchmode"]
+Switch(es) for the \fIlualatex\fR program (specified in the variable
+\fI$lualatex\fR) when silent mode is on.
+
+See details of the \fI$latex_silent_switch\fR for other information
+that equally applies to \fI$lualatex_silent_switch\fR.
+
+.TP
 .B $make ["make"]
 The make processing program.
 
@@ -2027,11 +2110,12 @@ character, which is the character used by Unix-like systems.
 
 For many programs under MS-Windows, both "\\" and "/" are acceptable
 as the directory separator character.  But some programs only accept
-"\\".  So for safety \fIlatexmk\fR makes a translation, by default.
+"\\" on the command line.  So for safety \fIlatexmk\fR makes a
+translation, by default.
 It is conceivable that under certain situations this is undesirable,
 so the configuration can be changed.  (A possible example might be
 when some of the software is implemented using Cygwin, which provides
-an Unix-like environment inside MS-Windows.)
+a Unix-like environment inside MS-Windows.)
 
 .TP
 .B $new_viewer_always [0]
@@ -2078,93 +2162,67 @@ operating system environment variable openout_any to "a" (as in
 
 .B $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 pdflatex.  
+If equal to 1, generate a pdf version of the document using \fIpdflatex\fR,
+using the command specified by the \fI$pdflatex\fR variable.  
 If equal to 2, generate a pdf version of the document from the ps
 file, by using the command specified by the \fI$ps2pdf\fR variable.  
 If equal to 3, generate a pdf version of the document from the dvi
 file, by using the command specified by the \fI$dvipdf\fR variable.  
+If equal to 4, generate a pdf version of the document using \fIlualatex\fR,
+using the command specified by the \fI$lualatex\fR variable.
+If equal to 5, generate a pdf version (and an xdv version) of the
+document using \fIxelatex\fR, using the commands specified by the
+\fI$xelatex\fR and \fIxdvipdfmx\fR variables.
+
+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.
 
-Equivalent to the \fB-pdf-\fR, \fB-pdf\fR, \fB-pdfdvi\fR, 
-\fB-pdfps\fR options.
 .TP
 
 .B $pdflatex ["pdflatex %O %S"]
 The LaTeX processing program in a version that makes a pdf file instead
 of a dvi file.
 
-An example of the use of this variable is to arrange for 
-\fIlualatex\fR, \fIxelatex\fR or some similar program
-to be used instead of \fIpdflatex\fR.  
-Note that \fIlualatex\fR and \fIxelatex\fR only produce .pdf files
-(and not .dvi), so to use them you will also need to turn on
-production of .pdf files, and to turn off the production of .dvi
-(and .ps) files, either by command line options or by suitable
-settings in a configuration file. Thus to use \fIlualatex\fR, the
-following settings are appropriate:
-
-     $pdflatex = "lualatex %O %S";
-     $pdf_mode = 1; $postscript_mode = $dvi_mode = 0;
-
-To use \fIxelatex\fR, the corresponding settings are:
-
-     $pdflatex = "xelatex %O %S";
-     $pdf_mode = 1; $postscript_mode = $dvi_mode = 0;
-
-Another use of the same variable is to add certain options to the
+An example use of this variable is to add certain options to the
 command line for the program, e.g.,
 
      $pdflatex = "pdflatex --shell-escape %O %S";
 
+(In some earlier versions of \fIlatexmk\fR, you needed to use an assignment
+to \fI$pdflatex\fR to allow the use of \fIlualatex\fR or \fIxelatex\fR
+instead of \fIpdflatex\fR.  There are now separate configuration
+variables for the use of \fIlualatex\fR or \fIxelatex\fR.  See
+\fI$lualatex\fR and \fI$xelatex\fR.)
 
 .TP
 .B %pdflatex_input_extensions
-This variable specifies the extensions tried by latexmk when it finds
-that a pdflatex run resulted in an error that a file has not been found,
+This variable specifies the extensions tried by \fIlatexmk\fR when it finds
+that a \fIpdflatex\fR run resulted in an error that a file has not been found,
 and the file is given without an extension.  This typically happens when
 LaTeX commands of the form \\input{file} or \\includegraphics{figure},
 when the relevant source file does not exist.
 
-In this situation, latexmk searches for custom dependencies to make
+In this situation, \fIlatexmk\fR searches for custom dependencies to make
 the missing file(s), but restricts it to the extensions specified by
 the variable %pdflatex_input_extensions.  The default extensions 
 are 'tex', 'pdf', 'jpg, and 'png'.
 
-(For Perl experts: %pdflatex_input_extensions is a hash whose keys are
-the extensions.  The values are irrelevant.)  Two subroutines are
-provided for manipulating this and the related variable
-%latex_input_extensions, add_input_ext and remove_input_ext.  They
-are used as in the following examples are possible lines in an
-initialization file:
-
-    remove_input_ext( 'pdflatex', 'tex' );
-
-removes the extension 'tex' from pdflatex_input_extensions
-
-    add_input_ext( 'pdflatex', 'asdf' );
-
-add the extension 'asdf to pdflatex_input_extensions.  (Naturally with
-such an extension, you should have made an appropriate custom
-dependency for latexmk, and should also have done the appropriate
-programming in the LaTeX source file to enable the file to be read.
-The standard extensions are handled by pdflatex and its graphics/graphicx
-packages.)
+See details of the \fI%latex_input_extensions\fR for other information
+that equally applies to \fI%pdflatex_input_extensions\fR.
 
 .TP
 .B $pdflatex_silent_switch  ["-interaction=batchmode"]
-Switch(es) for the pdflatex program (specified in the variable
-\fI$pdflatex\fR when silent mode is on.
+Switch(es) for the \fIpdflatex\fR program (specified in the variable
+\fI$pdflatex\fR) when silent mode is on.
 
-If you use MikTeX, you may prefer the results if you configure the
-options to include -c-style-errors, e.g., by the following line in an
-initialization file
-
-  $latex_silent_switch = "-interaction=batchmode -c-style-errors";
+See details of the \fI$latex_silent_switch\fR for other information
+that equally applies to \fI$pdflatex_silent_switch\fR.
 
 .TP
 .B $pdf_previewer ["start acroread %O %S"]
 The command to invoke a pdf-previewer.
 
-On MS-WINDOWS, the default is changed to "cmd /c start """; under more recent versions of
+On MS-Windows, the default is changed to "cmd /c start """; under more recent versions of
 Windows, this will cause to be run whatever command the system has
 associated with .pdf files.  But this may be undesirable if this
 association is to \fIacroread\fR -- see the notes in the explanation
@@ -2180,7 +2238,7 @@ if acroread is used as the 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 \fIlatexmk\fR's
 previous-continuous mode (option \fB-pvc\fR) under MS-windows.
-This problem does not occur if, for example, SumatraPDF or gsview is
+This problem does not occur if, for example, \fISumatraPDF\fR or \fIgsview\fR is
 used to view pdf files.
 
 \fBImportant note\fR: Normally you will want to have a previewer run
@@ -2228,14 +2286,16 @@ in response to a command, and the third setting sets the update command.
 The number of the signal that is sent to the pdf viewer when it is
 updated by sending a signal -- see the information on the variable
 \fI$pdf_update_method\fR.  The default value is the one appropriate
-for gv on a UNIX system.
+for \fIgv\fR on a UNIX system.
 .TP
 .B $pid_position[1 under UNIX, -1 under MS-Windows]     
 The variable \fI$pid_position\fR is used to
 specify which word in lines of the output from \fI$pscmd\fR
 corresponds to the process ID.  The first word in the line is numbered
 0.  The default value of 1 (2nd word in line) is correct for Solaris
-2.6 and Linux.  Setting the variable to -1 is used to indicate that
+2.6, Linux, and OS-X with their default settings of \fI$pscmd\fR.
+
+Setting the variable to -1 is used to indicate that
 \fI$pscmd\fR is not to be used.
 .TP
 .B $postscript_mode [0]
@@ -2259,7 +2319,8 @@ Which previewer is run depends on the other settings, see the command
 line options \fB-view=\fR, and the variable \fI$view\fR.  
 .TP
 .B $printout_mode [0]
-If nonzero, print the document using \fIlpr\fR.  Equivalent to the
+If nonzero, print the document using the command specified in the
+\fI$lpr\fR variable.  Equivalent to the
 \fB-p\fR option.  This is recommended \fBnot\fR to be set from an RC
 file, otherwise you could waste lots of paper.
 .TP
@@ -2280,11 +2341,10 @@ one process.  See the \fI$pid_position\fR variable for how the process
 number is determined.
 
 The default for \fIpscmd\fR is "NONE" under MS-Windows and cygwin
-(i.e., the command is not used), "ps --width 200 -f -u $ENV{USER}"
-under linux, "ps -ww -u $ENV{USER}" under darwin (Macintosh OS-X), and
-"ps -f -u $ENV{USER}" under other operating systems (including other
-flavors of UNIX).  In these specifications "$ENV{USER}" is substituted
-by the username.
+(i.e., the command is not used), "ps -ww -u $ENV{USER}" under 
+OS-X, and 
+"ps -f -u $ENV{USER}" under other operating systems (including Linux).
+In these specifications "$ENV{USER}" is substituted by the username.
 .TP
 .B $ps2pdf ["ps2pdf  %O %S %D"]
 Command to convert ps to pdf file.  
@@ -2294,19 +2354,19 @@ The postscript file filter to be run on the newly produced postscript
 file before other processing.  Equivalent to specifying the \fB-pF\fR
 option.
 .TP
-.B $ps_previewer ["start gv %O %S", but "start %O %S" under MS-WINDOWS]
-The command to invoke a ps-previewer.  (The default under MS-WINDOWS
+.B $ps_previewer ["start gv %O %S", but "start %O %S" under MS-Windows]
+The command to invoke a ps-previewer.  (The default under MS-Windows
 will cause to be run whatever command the system has associated 
 with .ps files.)
 
-Note that gv could be used with the -watch option updates its display
+Note that \fIgv\fR could be used with the -watch option updates its display
 whenever the postscript file changes, whereas ghostview does not.
-However, different versions of gv have slightly different ways of
+However, different versions of \fIgv\fR have slightly different ways of
 writing this option.  You can configure this variable appropriately.
 
 \fBWARNING\fR: Linux systems may have installed one (or more) versions
-of gv under different names, e.g., ggv, kghostview, etc, but perhaps
-not one called gv.  
+of \fIgv\fR under different names, e.g., \fIggv\fR, \fIkghostview\fR,
+etc, but perhaps not one actually called \fIgv\fR.
 
 \fBImportant note\fR: Normally you will want to have a previewer run
 detached, so that \fIlatexmk\fR doesn't wait for the previewer to
@@ -2319,7 +2379,7 @@ non-trivial reasons), so you should put the "start " bit in
 yourself, whenever it is needed.
 
 .TP
-.B $ps_previewer_landscape ["start gv -swap %O %S", but "start %O %S" under MS-WINDOWS]
+.B $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.
 .TP
 .B $ps_update_command [""]
@@ -2354,11 +2414,11 @@ specifications (as in \fI$pdflatex\fR) are surrounded by double
 quotes.  If this variable is 1 (or any other value Perl regards as
 true), then quoting is done.  Otherwise quoting is omitted.  
 
-The quoting method used by latexmk is tested to work correctly under
+The quoting method used by \fIlatexmk\fR is tested to work correctly under
 UNIX systems (including Linux and Mac OS-X) and under MS-Windows.  It
 allows the use of filenames containing special characters, notably
-spaces.  (But note that many versions of LaTeX and PdfLaTeX cannot
-correctly deal with TeX files whose names contain spaces.  Latexmk's
+spaces.  (But note that many versions of \fIlatex\fR and \fIpdflatex\fR cannot
+correctly deal with TeX files whose names contain spaces.  \fILatexmk\fR's
 quoting only ensures that such filenames are correctly treated by the
 operating system in passing arguments to programs.)
 .TP
@@ -2390,12 +2450,12 @@ BIBINPUTS, and BSTINPUTS.  This variable is mainly used by
 \fIlatexmk\fR when the \fB-outdir\fR, \fB-output-directory\fR,
 \fB-auxdir\fR, and/or \fB-aux-directory\fR options are used.  In that
 case \fIlatexmk\fR needs to communicate appropriately modified search
-paths to $\fIbibtex\fR, \fIdvipdf\fR, \fIdvips\fR, and
+paths to \fIbibtex\fR, \fIdvipdf\fR, \fIdvips\fR, and
 \fI(pdf)latex\fR.  
 
 [Comment to technically savvy readers: \fI(pdf)latex\fR doesn't
-actually need the modified search path, because it corrects it
-internally.  But, surprisingly, \fIdvipdf\fR and \fIdvips\fR do,
+actually need the modified search path.  But, surprisingly,
+\fIdvipdf\fR and \fIdvips\fR do, 
 because sometimes graphics files get generated in the output or aux
 directories.] 
 
@@ -2410,6 +2470,10 @@ for unusual operating systems that are not in the MSWin, Linux, OS-X,
 Unix collection.)
 
 .TP
+.B $show_time [0]
+Whether to show CPU time used.
+
+.TP
 .B $silence_logfile_warnings [0]
 Whether after a run of (pdf)latex to summarize warnings in the log
 file about undefined citations and references.  Setting
@@ -2484,6 +2548,49 @@ possible values are "default", "dvi", "ps", "pdf".  The value
 of "default" means that the "highest" of the kinds of file generated is
 to be used (among dvi, ps and pdf).
 
+.TP
+.B $xdvipdfmx ["xdvipdfmx -o %D %O %S"]
+
+The program to make a pdf file from an xdv file (used in conjunction
+with \fIxelatex\fR when \fI$pdf_mode\fR=5).
+
+.TP
+.B $xdvipdfmx_silent_switch ["-q"]
+Switch(es) for the \fIxdvipdfmx\fR program when silent mode is on.
+
+.TP
+.B $xelatex ["xelatex %O %S"]
+The LaTeX processing program of in a version that makes a pdf file instead
+of a dvi file, when the \fIxelatex\fR program is called for.  See the
+documentation of the \fB-xelatex\fR option for some special properties
+of \fIlatexmk\fR's use of \fIxelatex\fR.
+
+.TP
+.B %xelatex_input_extensions
+This variable specifies the extensions tried by \fIlatexmk\fR when it finds
+that an \fIxelatex\fR run resulted in an error that a file has not been found,
+and the file is given without an extension.  This typically happens when
+LaTeX commands of the form \\input{file} or \\includegraphics{figure},
+when the relevant source file does not exist.
+
+In this situation, \fIlatexmk\fR searches for custom dependencies to make
+the missing file(s), but restricts it to the extensions specified by
+the variable %xelatex_input_extensions.  The default extensions 
+are 'tex', 'pdf', 'jpg, and 'png'.
+
+See details of the \fI%latex_input_extensions\fR for other information
+that equally applies to \fI%xelatex_input_extensions\fR.
+
+.TP
+.B $xelatex_silent_switch  ["-interaction=batchmode"]
+Switch(es) for the \fIxelatex\fR program (specified in the variable
+\fI$xelatex\fR) when silent mode is on.
+
+See details of the \fI$latex_silent_switch\fR for other information
+that equally applies to \fI$xelatex_silent_switch\fR.
+
+
+
 .SH CUSTOM DEPENDENCIES
 .PP
 In any RC file a set of custom dependencies can be set up to convert a
@@ -2525,12 +2632,13 @@ of the file to be converted without any extension.  The subroutines are
 declared in the syntax of \fIPerl\fR.  The function should return 0 if
 it was successful and a nonzero number if it failed.
 .PP
-It is invoked whenever \fIlatexmk\fR detects that a run of
+A custom dependency rule is invoked whenever \fIlatexmk\fR detects
+that a run of 
 latex/pdflatex needs to read a file, like a graphics file, whose
 extension is the to-extension of a custom dependency.  Then
 \fIlatexmk\fR examines whether a file exists with the same name, but
 with the corresponding from-extension, as specified in the
-custom-dependency rule.  If it does, then whenever the destination
+custom-dependency rule.  If it does, then the rule whenever the destination
 file (the one with the to-extension) is out-of-date with respect to
 the corresponding source file.
 
@@ -2541,7 +2649,7 @@ external program; this can be done by following the templates below,
 even by those without knowledge of the \fIPerl\fR programming language.  Of
 course, experts could do something much more elaborate.
 
-One other item in each custom-dependency rule labeled "must" above
+One other item in each custom-dependency rule, labeled "must" above,
 specifies how the rule should be applied when the source file fails to
 exist.
 
@@ -2549,11 +2657,11 @@ A simple and typical example of code in an initialization rcfile is
 
     add_cus_dep( 'fig', 'eps', 0, 'fig2eps' );
     sub fig2eps {
-        system( "fig2dev -Leps \\"$_[0].fig\\" \\"$_[0].eps\\"" ); 
+        return system( "fig2dev -Leps \\"$_[0].fig\\" \\"$_[0].eps\\"" ); 
     }
 
 The first line adds a custom dependency that converts a file with
-extension "fig", as created by the xfig program, to an encapsulated
+extension "fig", as created by the \fIxfig\fR program, to an encapsulated
 postscript file, with extension "eps".  The remaining lines define a
 subroutine that carries out the conversion.  If a rule for converting
 "fig" to "eps" files already exists (e.g., from a previously read-in
@@ -2577,13 +2685,13 @@ the return value is the value returned by the last (and only)
 statement, i.e., the invocation of system, which returns the value 0
 on success.
 
-If you use pdflatex instead of latex, then you will probably prefer to
+If you use \fIpdflatex\fR instead of latex, then you will probably prefer to
 convert your graphics files to pdf format, in which case you would
 replace the above code in an initialization file by
 
     add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' );
     sub fig2pdf {
-        system( "fig2dev -Lpdf \\"$_[0].fig\\" \\"$_[0].pdf\\"" ); 
+        return system( "fig2dev -Lpdf \\"$_[0].fig\\" \\"$_[0].pdf\\"" ); 
     }
 
 \fBNote 1:\fR In the command lines given in the system commands in the
@@ -2600,7 +2708,7 @@ the cases I have tested.
 files are in a subdirectory and your operating system is Microsoft
 Windows.  Then the separator character for directory components can be
 either a forward slash '/' or Microsoft's more usual backward slash
-\'\\'.  Forward slashes are generated by latexmk, to maintain its
+\'\\'.  Forward slashes are generated by \fIlatexmk\fR, to maintain its
 sanity from software like MiKTeX that mixes both directory
 separators; but their correct use normally requires quoted filenames. 
 (See a log file from a run of MiKTeX (at least in v. 2.9) for an
@@ -2636,12 +2744,9 @@ happen:
 
     add_cus_dep('ndx', 'nnd', 0, 'makendx2nnd');
     sub makendx2nnd {
-        system( "makeindex -o \\"$_[0].nnd\\" \\"$_[0].ndx\\"" );
+        return system( "makeindex -o \\"$_[0].nnd\\" \\"$_[0].ndx\\"" );
     }
 
-(You will need to modify this code if you use filenames
-with spaces in them, to provide correct quoting of the filenames.)
-
 Those of you with experience with Makefiles, will undoubtedly be
 concerned that the \fI.ndx\fR file is written during a run of
 latex/pdflatex and is always later than the \fI.nnd\fR last read in.
@@ -2652,7 +2757,7 @@ dependencies.  It examines the contents of the files (by use of an md5
 checksum), and only does a remake when the file contents have actually
 changed.
 
-Of course if you choose to write random data to the \fI.nnd\fR (or and
+Of course if you choose to write random data to the \fI.nnd\fR (or the
 \fI.aux\fR file, etc) that changes on each new run, then you will have
 a problem.  For real experts: See the \fI%hash_cal_ignore_pattern\fR
 if you have to deal with such problems.
@@ -2675,7 +2780,7 @@ of \fI.fig\fR files to \fI.eps\fR files:
 
     push @cus_dep_list, "fig eps 0 fig2eps";
     sub fig2eps {
-        system( "fig2dev -Lps \\"$_[0].fig\\" \\"$_[0].eps\\"" );
+        return system( "fig2dev -Lps \\"$_[0].fig\\" \\"$_[0].eps\\"" );
     }
 
 This method still works, and is equivalent to the earlier code using
@@ -2825,7 +2930,7 @@ project, where lines such as the above would be only be a small part
 of a larger Makefile.
 
 The above example has a pattern rule for making a .pdf file from 
-a .tex file, and it is defined to use latexmk in the obvious way.
+a .tex file, and it is defined to use \fIlatexmk\fR in the obvious way.
 There is a conventional default target named "all", with a
 prerequisite of try.pdf.  So when \fImake\fR is invoked, by default it
 makes try.pdf.  The only complication is that there may be many source
@@ -2867,7 +2972,7 @@ started with tabs.)  This example was inspired by how GNU
 \fIautomake\fR handles automatic dependency tracking of C source
 files.
 
-After each run of latexmk, dependency information is put in a file
+After each run of \fIlatexmk\fR, dependency information is put in a file
 in the .deps subdirectory.  The Makefile causes these dependency files
 to be read by \fImake\fR, which now has the full dependency
 information for each target .pdf file.  To make things less trivial it
@@ -2909,13 +3014,13 @@ previewers and update methods.
 
 (The following isn't really a bug, but concerns features of previewers.)
 Preview continuous mode only works perfectly with certain previewers:
-Xdvi on UNIX/LINUX works for dvi files.  
-Gv on UNIX/LINUX works for both postscript and pdf.
-Ghostview on UNIX/LINUX needs a manual update (reopen); it views
+Xdvi on UNIX/Linux works for dvi files.  
+Gv on UNIX/Linux works for both postscript and pdf.
+Ghostview on UNIX/Linux needs a 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 pdf, but the file needs to be closed
+Acroread under UNIX/Linux views 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 \fIlatexmk\fR to use
@@ -2930,7 +3035,7 @@ e-mail addresses are not written in their standard form to avoid being
 harvested by worms and viruses.)
 .SH AUTHOR
 Current version, by John Collins (username jcc8 at node psu.edu).
-(Version 4.48).
+(Version 4.52).
 
 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 01fd9cd499e..716b02f7f24 100644
--- a/Master/texmf-dist/doc/man/man1/latexmk.man1.pdf
+++ b/Master/texmf-dist/doc/man/man1/latexmk.man1.pdf