latexmk (25may18)

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

1 files changed, 95 insertions, 15 deletions

diff --git a/Master/texmf-dist/doc/man/man1/latexmk.1 b/Master/texmf-dist/doc/man/man1/latexmk.1
index 0334565101f..2823348f536 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 "17 January 2018" ""
+.TH LATEXMK 1 "25 May 2018" ""
 .SH NAME
 latexmk \- generate LaTeX document
 .SH SYNOPSIS
@@ -284,7 +284,7 @@ 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.
 
-\fITreatment of .bbl files:\fR If \fI$bibtex_use\fR is set to 0 or 1,
+\fITreatment of .bbl files: \fR If \fI$bibtex_use\fR is set to 0 or 1,
 bbl files are always treated as non-regeneratable.  If
 \fI$bibtex_use\fR is set to 1.5, bbl files are counted as
 non-regeneratable conditionally: If the bib file exists, then bbl
@@ -1023,6 +1023,18 @@ option, when you want \fIlatexmk\fR to do a compilation automatically
 whenever source file(s) change, but do not want a previewer to be opened.
 
 .TP
+.B -Werror
+This causes \fIlatexmk\fR to return a non-zero status code if any of
+the files processed gives a warning about problems with citations or
+references (i.e., undefined citations or references or about multiply
+defined references).  This is \fBafter\fR \fIlatexmk\fR has completed
+all the runs it needs to try and resolve references and citations.
+Thus \fB-Werror\fR causes \fIlatexmk\fR to treat such warnings as
+errors, but only when they occur on the last run of (pdf)latex and
+only after processing is complete.  Also can be set by the
+configuration variable \fI$warnings_as_errors\fR. 
+
+.TP
 .B -xelatex
 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.
@@ -1160,9 +1172,12 @@ that of cygwin), \fIlatexmk\fR reads the first it finds of
    "/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
-file name replaced "LatexMk" replaced by "latexmkrc". 
+file name replaced "LatexMk" replaced by "latexmkrc".
+
+If the environment variable LATEXMKRCSYS is set, its value is used as
+the name of the system RC file, instead of any of the above.
 .PP
 2) The user's RC file, if it exists.  This can be in one of two
 places.  The traditional one is ".latexmkrc" in the user's home
@@ -1703,26 +1718,37 @@ option is selected, i.e., extensions of files to remove when the .dvi,
 etc files are to be cleaned-up.
 
 More general patterns are allowed, as for \fI$clean_ext\fR.
+
 .TP
-.B $compiling_cmd [undefined], $failure_cmd [undefined], $success_cmd [undefined]
+.B $compiling_cmd [""], $failure_cmd [""], $warning_cmd [""], $success_cmd [""]
 
 These variables specify commands that are executed at certain points
 of compilations during preview-continuous mode.  One motivation for
-their existance is to allow convenient visual indications of
+their existance is to allow very useful convenient visual indications of
 compilation status even when the window receiving the screen output of
-the compilation is hidden.
+the compilation is hidden. 
 
 The commands are executed at the following points:
-$compiling_cmd at the start of compilation, $success_cmd at the end of
-a successful compilation, and $failure_cmd at the end of an
-unsuccessful compilation.  If any of above variables is undefined (the
-default situation) or blank, then the corresponding command is not
-executed.  
-
-An example of a typical setting of these variables is as follows
+\fI$compiling_cmd\fR at the start of compilation, \fI$success_cmd\fR
+at the end of a completely successful compilation, \fI$failure_cmd\fR
+at the end of an unsuccessful compilation, \fI$warning_cmd\fR at the
+of an otherwise successful compilation that gives warnings about
+undefined citations or references or about multiply defined
+references. If any of above variables is undefined or blank (the
+default situation), then the corresponding command is not executed.
+
+However, when \fI$warning_cmd\fR is not set, then in the case of a
+compilation with warnings about references or citations, but with no
+other error, one or other of \fI$success_cmd\fR or \fI$failure_cmd\fR
+is used (if it is set) according to the setting of
+\fI$warnings_as_errors\fR.
+
+An example of a simple setting of these variables is as follows
 
     $compiling_cmd = "xdotool search --name \\"%D\\" set_window --name \\"%D compiling\\"";
     $success_cmd   = "xdotool search --name \\"%D\\" set_window --name \\"%D OK\\"";
+    $warning_cmd   = "xdotool search --name \\"%D\\" ".
+                     "set_window --name \\"%D CITE/REF ISSUE\\"";
     $failure_cmd   = "xdotool search --name \\"%D\\" set_window --name \\"%D FAILURE\\"";
 
 These assume that the program \fIxdotool\fR is installed, that the
@@ -1739,6 +1765,17 @@ the title of the edit window. The visual indication in a window title
 can useful, since the user does not have to keep shifting attention to
 the (possibly hidden) compilation window to know the status of the
 compilation.
+
+More complicated situations can best be handled by defining a Perl
+subroutine to invoke the necessary commands, and using the "internal"
+keyword in the definitions to get the subroutine to be invoked.  (See
+the section Format of Command Specifications for how to do this.)
+
+Naturally, the above settings that invoke the \fIxdotool\fR program
+are only applicable when the X-Window system is used for the relevant
+window(s).  For other cases, you will have to find what software
+solutions are available.  
+
 .TP
 .B @cus_dep_list [()]
 Custom dependency list -- see section on "Custom Dependencies".
@@ -2676,6 +2713,49 @@ Which kind of file is to be previewed if a previewer is used.  The
 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 $warnings_as_errors [0]
+Normally \fIlatexmk\fR copies the behavior of \fIlatex\fR in treating
+undefined references and citations and multiply defined references as
+conditions that give a warning but not an error.  The variable
+\fI$warnings_as_errors\fR controls whether this behavior is modified.
+
+When the variable is non-zero, \fIlatexmk\fR at the end of its run
+will return a non-zero status code to the operating system if any of
+the files processed gives a warning about problems with citations or
+references (i.e., undefined citations or references or multiply
+defined references).  This is \fBafter\fR \fIlatexmk\fR has completed
+all the runs it needs to try and resolve references and citations.
+Thus \fI$warnings_as_errors\fR being nonzero causes \fIlatexmk\fR to
+treat such warnings as errors, but only when they occur on the last
+run of (pdf)latex and only after processing is complete.  A non-zero
+value \fI$warnings_as_errors\fR can be set by the command-line option
+\fB-Werror\fR.
+
+The default behavior is normally satisfactory in the usual
+edit-compile-edit cycle.  But, for example, \fIlatexmk\fR can also be
+used as part of a build process for some bigger project, e.g., for
+creating documentation in the build of a software application.  Then
+it is often sensible to treat citation and reference warnings as
+errors that require the overall build process to be aborted.  Of
+course, since multiple runs of (pdf)latex are generally needed to
+resolve references and citations, what matters is \fInot\fR the
+warnings on the first run, but the warnings on the \fIlast\fR run;
+\fIlatexmk\fR takes this into account appropriately.
+
+In addition, when preview-continuous mode is used, a non-zero value
+for \fI$warnings_as_errors\fR changes the use of the commands
+\fI$failure_cmd\fR, \fI$warning_cmd\fR, and \fI$success_cmd\fR after a
+compliation.  If there are citation or reference warnings, but no
+other errors, the behavior is as follows. If \fI$warning_cmd\fR is
+set, it is used.  If it is not set, then then if
+\fI$warnings_as_errors\fR is non-zero and \fI$failure_cmd\fR is set,
+then \fI$failure_cmd\fR.  Otherwise \fI$success_cmd\fR is used, if it
+is set.  (The foregoing explanation is rather complicated, because
+\fIlatexmk\fR has to deal with the case that one or more of the
+commands isn't set.)
+
 .TP
 .B $xdvipdfmx ["xdvipdfmx -o %D %O %S"]
 
@@ -3249,7 +3329,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.55).
+(Version 4.56).
 
 Released version can be obtained from CTAN:
 <http://www.ctan.org/pkg/latexmk/>, and from the