latexmk (25feb16)

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

2 files changed, 107 insertions, 19 deletions

diff --git a/Master/texmf-dist/doc/man/man1/latexmk.1 b/Master/texmf-dist/doc/man/man1/latexmk.1
index a4e46dc36b3..6d74915dfb1 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 February 2015" ""
+.TH LATEXMK 1L "24 February 2016" ""
 .SH NAME
 latexmk \- generate LaTeX document
 .SH SYNOPSIS
@@ -106,7 +106,7 @@ In general the command line to invoke \fIlatexmk\fR has the form
 All options can be introduced by single or double "-" characters,
 e.g., "latexmk -help" or "latexmk --help".
 
-\fBNote 1\fR: In addition to the options in the list below,
+\fBNote 1\fR: \fBIn addition to the options in the list below,
 \fIlatexmk\fR recognizes almost all the options recognized by the
 \fIlatex\fR, \fIpdflatex\fR programs (and their relatives) in their 
 current TeXLive and MiKTeX implementations.  Some of the options for
@@ -919,8 +919,9 @@ each of these options turns the others off.
 					.pdf, .ps & .bbl files\fR
 
 
-.SH HOW TO CHANGE THE WAY LATEXMK BEHAVES, DEALING WITH PROBLEMS, ETC
+.SH DEALING WITH ERRORS, PROBLEMS, ETC
 
+.PP
 Some possibilities:
 
 a. If you get a strange error, do look carefully at the output that is
@@ -931,23 +932,32 @@ user to diagnose problems.  \fILatexmk\fR does repeat some messages at
 the end of a run that it thinks would otherwise be easy to miss in the
 middle of other output. 
 
-b. If \fIlatexmk\fR doesn't do things the way you would like, the
-first step in finding out what to do is to look in this documentation
-at the list of command line options and then at the sections on
-configuration/initialization files.  A lot of \fIlatexmk\fR's behavior
-is configurable to deal with particular situations.  (But there is a
-lot of reading.)
+b. Generally, remember that \fIlatexmk\fR does its work by running
+other programs.  Your first priority in dealing with errors should be
+to examine what went wrong with the individual programs.  Then you
+need to correct the causes of errors in the runs of these programs.
+(Often these come from errors in the source document, but they could
+also be about missing LaTeX packages, etc.)
+
+c. If \fIlatexmk\fR doesn't run the programs the way you would like,
+then you need to look in this documentation at the list of command
+line options and then at the sections on configuration/initialization
+files.  A lot of \fIlatexmk\fR's behavior is configurable to deal with
+particular situations.  (But there is a lot of reading!)
+
+\fIThe remainder of these notes consists of ideas for dealing with more
+difficult situations.\fR
 
-c. Further tricks can involve replacing the standard commands that
+d. Further tricks can involve replacing the standard commands that
 \fIlatexmk\fR by other commands or scripts.
 
-d. For possible examples of code for use in an RC file, see the
+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.,
 at http://www.ctan.org/tex-archive/support/latexmk/example_rcfiles).
 Even if these examples don't do what you want, they may provide
 suitable inspiration.
 
-e. There's a useful trick that can be used when you are \fIlualatex\fR
+f. There's a useful trick that can be used when you use \fIlualatex\fR
 instead of \fIpdflatex\fR (and in some related situations).  The
 problem is that \fIlatexmk\fR won't notice a dependency on a file,
 bar.baz say, that is input by the lua code in your document instead of
@@ -965,13 +975,15 @@ implying that the file bar.baz was read.  (At present I don't know a
 way of doing this automatically.)  Of course, if the file has a
 different name, change bar.baz to the name of your file.
 
-f. Look on tex.stackexchange, i.e., at
+g. See also the section \fBADVANCED CONFIGURATION: Some extra resources\fR.
+
+g. Look on tex.stackexchange, i.e., at
 http://tex.stackexchange.com/questions/tagged/latexmk  Someone may
 have already solved your problem.
 
-g. Ask a question at tex.stackexchange.com.
+h. Ask a question at tex.stackexchange.com.
 
-h. Or ask me (the author of \fIlatexmk\fR).  My e-mail is at the end
+i. Or ask me (the author of \fIlatexmk\fR).  My e-mail is at the end
 of this documentation.
 
 
@@ -1178,7 +1190,7 @@ command, you need to precede the command name with "start ", as in
 This will be translated to whatever is appropriate for your operating
 system.
 
-Notes: (1) In some circumstances, \fIlatex\fR will always run a
+Notes: (1) In some circumstances, \fIlatexmk\fR will always run a
 command detached.  This is the case for a previewer in preview
 continuous mode, since otherwise previewing continuously makes no
 sense.  (2) This precludes the possibility of running a command named
@@ -1255,6 +1267,10 @@ specification starting with "internal", as in
          return system 'latex', @args;
      }
 .PP
+For some of the more exotic possibilities that then become available,
+see the section "ADVANCED CONFIGURATION: Some extra resources and
+advanced tricks". Also see some of the examples in the directory
+\fIexample_rcfiles\fR in the \fIlatexmk\fR distribution.
 
 \fBAdvanced tricks\fR: Normally one specifies a single command for the
 commands invoked by \fIlatexmk\fR.  Naturally, if there is some
@@ -1263,6 +1279,9 @@ situation, you can write a script (or batch file) to do the
 processing, and then configure \fIlatexmk\fR to use your script in
 place of the standard program.
 
+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
@@ -1372,7 +1391,7 @@ the current directory is set.  The format of the directory names
 depends on your operating system, of course.  Examples for setting
 this variable are:
 
-        @BIBINPUTS = ( ".", "C:\\bibfiles" );
+        @BIBINPUTS = ( ".", "C:\\\\bibfiles" );
         @BIBINPUTS = ( ".", "\\\\server\\bibfiles" );
         @BIBINPUTS = ( ".", "C:/bibfiles" );
         @BIBINPUTS = ( ".", "//server/bibfiles" );
@@ -2552,6 +2571,7 @@ if you have to deal with such problems.
 
 Glossaries can be dealt with similarly.
 
+
 .SH OLD METHOD OF DEFINING CUSTOM DEPENDENCIES
 In previous versions of \fIlatexmk\fR, the only method of defining
 custom dependencies was to directly manipulate the table of custom
@@ -2576,8 +2596,76 @@ custom-dependency for the same conversion.  So the new method is
 preferable.
 
 
+.SH ADVANCED CONFIGURATION: Some extra resources and advanced tricks
+
+For most purposes, simple configuration for \fIlatexmk\fR along the
+lines of the examples given is sufficient.  But sometimes you need
+something harder.  In this section, I indicate some extra
+possibilities.  Generally to use these, you need to be fluent in the
+Perl language, since this is what is used in the rc files.
+
+See also the section DEALING WITH ERRORS, PROBLEMS, ETC.  See
+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 ideas
+
+.SS Variables and subroutines for processing a rule
+
+A step in the processing is called a rule. One possibility to
+implement the processing of a rule is by a Perl subroutine.  This is
+always the case for custom dependencies. Also, for any other rule, you
+can use a subroutine by prefixing the command specification by the
+word "internal" -- see the section FORMAT OF COMMAND SPECIFICATIONS.
+
+When you use a subroutine for processing a rule, all the possibilities
+of Perl programming are available, of course.  In addition, some of
+\fIlatexmk\fR's internal variables and subroutines are available.
+The ones listed below are intended to be available to (advanced)
+users, and their specifications will generally have stability under
+upgrades. Generally, the variables should be treated as read-only:
+Changing their values can have bad consequences, since it is liable to
+mess up the consistency of what \fIlatexmk\fR is doing.
+
+.TP
+.B $rule
+This variable has the name of the rule, as known to
+\fIlatexmk\fR. Note that the exact contents of this variable for a
+given rule may be dependent on the version of \fIlatexmk\fR
+
+.TP
+.B $$Psource
+This gives the name of the primary source file.  Note the double
+dollar signs.
+
+.TP
+.B $$Pdest
+This gives the name of the main output file if any.  Note the double
+dollar signs.
+
+.TP
+.B rdb_ensure_file( $rule, file )
+This a subroutine that ensures that the given file is among the source
+files for the specified rule.  It is typically used when, during the
+processing of a rule, it is known that a particular extra file is
+among the dependencies that \fIlatexmk\fR should know, but its default
+methods don't find the dependency. Almost always the first argument is
+the name of the rule currently being processed, so it is then
+appropriate to specify it by \fB$rule\fR.
+
+For examples of its use, see some of the files in the directory
+\fIexample_rcfiles\fR of \fIlatexmk\fR's distribution.  Currently the
+cases that use this subroutine are \fIexceltex_latexmkrc\fR and
+\fItexinfo-latexmkrc\fR.  These illustrate typical cases where
+\fIlatexmk\fR's normal processing fails to detect certain extra source
+files. 
+
+.TP
+.B rdb_remove_files( $rule, file, ... )
+This subroutine removes one or more files from the dependency list for
+the given rule. 
+
 
-.SH USING \fIlatexmk\fR WITH \fImake\fR
+.SS Advanced configuration: Using \fIlatexmk\fB with \fImake\fR
 
 This section is targeted only at advanced users who use the \fImake\fR
 program for complex projects, as for software development, with the
@@ -2740,7 +2828,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.43a).
+(Version 4.44).
 
 Released version can be obtained from CTAN:
 <http://www.ctan.org/tex-archive/support/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 7721ee89666..5426082977b 100644
--- a/Master/texmf-dist/doc/man/man1/latexmk.man1.pdf
+++ b/Master/texmf-dist/doc/man/man1/latexmk.man1.pdf