latexmk (13aug12)

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

2 files changed, 136 insertions, 40 deletions

diff --git a/Master/texmf/doc/man/man1/latexmk.1 b/Master/texmf/doc/man/man1/latexmk.1
index 45858eb1c56..d6df6565e50 100644
--- a/Master/texmf/doc/man/man1/latexmk.1
+++ b/Master/texmf/doc/man/man1/latexmk.1
@@ -1,4 +1,4 @@
-.TH LATEXMK 1L "30 March 2012" ""
+.TH LATEXMK 1L "12 August 2012" ""
 .SH NAME
 latexmk \- generate LaTeX document
 .SH SYNOPSIS
@@ -97,8 +97,28 @@ is that \fIlatexmk\fR generates an extra file (with extension
 information.
 
 .SH LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE
-(All options can be introduced by single or double "-" characters,
-e.g., "latexmk -help" or "latexmk --help".)
+In general the command line to invoke \fIlatexmk\fR has the form
+
+	latexmk [options] [file]
+
+All options can be introduced by single or double "-" characters,
+e.g., "latexmk -help" or "latexmk --help".
+
+\fBNote\fR: In addition to the options in the list below,
+\fIlatexmk\fR recognizes almost all the options recognized by the
+\fIlatex\fR and \fIpdflatex\fR programs in one of both of their
+current TeXLive and MiKTeX implementations.  Some of the options for
+these programs also trigger special action or behavior by
+\fIlatexmk\fR, in which case they are in this list.  Otherwise, they
+are just passed through to a called \fIlatex\fR or \fIpdflatex\fR
+program. Run \fIlatexmk\fR with the \fB-showextraoptions\fR to get a
+list of the options that \fIlatexmk\fR accepts and that are simply
+passed through to \fIlatex\fR or \fIpdflatex\fR.  See also the
+explanation of the \fB-showextraoptions\fR option for more
+information. 
+
+\fBDefinitions of options and arguments\fR
+
 .TP
 .B file
 One or more files can be specified.  If no files are specified,
@@ -197,8 +217,8 @@ exit.
 .B -c
 Clean up (remove) all regeneratable files generated by \fIlatex\fR and
 \fIbibtex\fR or \fIbiber\fR except dvi, postscript and pdf.  These files are a
-combination of log files, aux files, latexmk's database file of source
-file information, 
+combination of log files, aux files, \fIlatexmk\fR's database file of
+source file information, 
 and those with extensions
 specified in the \fI@generated_exts\fR configuration variable.  In addition,
 files with extensions by the \fI$clean_ext\fR configuration variable are
@@ -258,8 +278,8 @@ view of the files without listing intermediate files, as well as
 \fIlatexmk\fR can determine them.
 
 By default the list of dependent files is sent to stdout (i.e.,
-normally to the screen unless you've redirected latexmk's output).
-But you can set the filename where the list is sent by the
+normally to the screen unless you've redirected \fIlatexmk\fR's
+output). But you can set the filename where the list is sent by the
 \fB-deps-out=\fR option.
 
 See the section "USING \fIlatexmk\fR WITH \fImake\fR" for
@@ -283,7 +303,7 @@ Equivalent to \fB-deps-\fR.
 .TP
 .B   -deps-out=FILENAME  
 Set the filename to which the list of dependent files is written.  If
-the FILENAME argument is omitted or set to '-', then the output is
+the FILENAME argument is omitted or set to "-", then the output is
 sent to stdout. 
 
 Use of this option also turns on the output of the list of dependent
@@ -297,7 +317,7 @@ be performed on this filtered dvi file.
 
 Example usage: To use dviselect to select only the even pages of the dvi file:
 
-	latexmk -dF 'dviselect even' foo.tex
+	latexmk -dF "dviselect even" foo.tex
 .TP
 .B -diagnostics
 Print detailed diagnostics during a run.  This may help for debugging
@@ -383,6 +403,16 @@ Turn off \fB-g\fR.
 .B -h, -help
 Print help information.
 .TP
+.B -jobname=STRING
+Set the basename of output files(s) to STRING, instead of the default,
+which is the basename of the specified TeX file.
+
+This is like the same option for current implementations of the
+\fIlatex\fR and \fIpdflatex\fR, and the passing of this option to
+these programs is part of \fIlatexmk\fR's implementation of
+\fB-jobname\fR.
+
+.TP
 .B -l
 Run in landscape mode, using the landscape mode for the previewers and
 the dvi to postscript converters.  This option is not normally needed
@@ -392,12 +422,12 @@ automatically.
 .B -l-
 Turn off \fB-l\fR.
 .TP
-.B -latex='command'
+.B -latex="COMMAND"
 This sets the string specifying the command to run latex, and is
 typically used to add desired options.  Since the string normally
 contains spaces, it should be quoted, e.g.,
 
-     latex -latex='latex --shell-escape %O %S'  foo.tex
+     latex -latex="latex --shell-escape %O %S"  foo.tex
 
 The specification of the contents of the string are the same as for
 the \fI$latex\fR configuration variable.  Depending on your
@@ -512,12 +542,12 @@ Turn off generation of pdf version of document.
 It may get overridden if some other option requires the generation of
 a pdf file.)
 .TP
-.B -pdflatex='command'
+.B -pdflatex="COMMAND"
 This sets the string specifying the command to run pdflatex, and is
 typically used to add desired options.  Since the string normally
 contains spaces, it should be quoted, e.g.,
 
-     latex -pdf -pdflatex='pdflatex --shell-escape %O %S'  foo.tex
+     latex -pdf -pdflatex="pdflatex --shell-escape %O %S"  foo.tex
 
 The specification of the contents of the string are the same as for
 the \fI$pdflatex\fR configuration variable.  Depending on your
@@ -666,6 +696,39 @@ Show a list of \fIlatemk\fR's rules and dependencies after processing.
 Do not show a list of \fIlatexmk\fR's rules and dependencies after
 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
+(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
+\fIpdflatex\fR that is being used, that program will probably give an
+error message.)  These options are very numerous, but are not listed
+in this documentation because they have no effect on \fIlatexmk\fR's
+actions.
+
+There are a few options (\fB-includedirectory=dir\fR,
+\fB-initialize\fR, \fB-ini\fR) that are not recognized, either because
+they don't fit with \fIlatexmk\fR's intended operations, or because
+they need special processing by \fIlatexmk\fR that isn't implemented
+(at least, not yet).
+
+There are also options that are accepted by \fIlatex\fR etc, but
+instead trigger actions by \fIlatexmk\fR: \fB-help\fR,
+\fB-version\fR. 
+
+Finally, there are certain options for \fIlatex\fR and \fIpdflatex\fR
+(e.g., \fB-recorder\fR) that trigger special actions or behavior by
+\fIlatexmk\fR itself as well as being passed in some form to the
+called \fIlatex\fR and \fIpdflatex\fR program, or that affect other
+programs as well.  These options do have entries in this
+documentation.  These options are:
+\fB-jobname=STRING\fR, \fB-aux-directory=dir\fR,
+\fB-output-directory=DIR\fR, \fB-quiet\fR, and \fB-recorder\fR.
+
+.TP
 .B -silent
 Run commands silently, i.e., with options that reduce the amount of
 diagnostics generated.  For example, with the default settings, the
@@ -677,9 +740,9 @@ 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$dvips_silent_switch\fR, \fI$latex_silent_switch\fR, and
-\fI$pdflatex_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.
 .TP
 .B -use-make
 When after a run of \fIlatex\fR or \fIpdflatex\fR, there are warnings
@@ -884,12 +947,14 @@ to ps).
 .TP
 .B %T
 The name of the primary tex file.
+.TP
 .B %Y
 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 '\\'. 
+.TP
 .B %Z
 Name of directory for output files (see the configuration
 variable \fI$out_dir\fR).  A directory separation character ('/') is
@@ -1362,6 +1427,14 @@ 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.
+
+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.
+.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
@@ -1616,6 +1689,9 @@ The make processing program.
 .B $makeindex ["makeindex %O -o %D %S"]
 The index processing program.
 .TP
+.B $makeindex_silent_switch ["-q"]
+\fBSwitch(es)\fR for the index processing program when silent mode is on.
+.TP
 .B $max_repeat  [5]
 The maximum number of times \fIlatexmk\fR will run latex/pdflatex
 before deciding that there may be an infinite loop and that it needs
@@ -1625,6 +1701,23 @@ cross-references, etc.  The default value covers all normal cases.
 (Note that the "etc" covers a lot of cases where one run of
 latex/pdflatex generates files to be read in on a later run.)
 .TP
+.B $MSWin_back_slash [1]
+This configuration variable only has an effect when \fIlatexmk\fR is
+running under MS-Windows.  It determines whether, when a command is
+executed under MS-Windows, there should be substituted "\\" for the
+separator character between components of a directory name.
+Internally, \fIlatexmk\fR uses "/" for the directory separator
+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.
+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.)
+
+.TP
 .B $new_viewer_always [0]
 This variable applies to \fIlatexmk\fR \fBonly\fR in
 continuous-preview mode.  If \fI$new_viewer_always\fR is 0,
@@ -1866,7 +1959,7 @@ 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 \(dqstart %O %S" 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.)
@@ -1891,7 +1984,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 \(dqstart %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 [""]
@@ -2100,7 +2193,7 @@ 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"); 
+        system( "fig2dev -Leps \"$_[0].fig\" \"$_[0].eps\"" ); 
     }
 
 The first line adds a custom dependency that converts a file with
@@ -2128,32 +2221,35 @@ 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 filenames with spaces in them, and if your LaTeX system and
-all other relevant software correctly handle such filenames, then you
-could put single quotes around filenames in the command line that is
-executed:
-
-    add_cus_dep( 'fig', 'eps', 0, 'fig2eps' );
-    sub fig2eps {
-        system("fig2dev -Lps '$_[0].fig' '$_[0].eps'");
-    }
-
-This causes the invocation of the \fIfig2dev\fR program to have quoted
-filenames; it should therefore work with filenames containing spaces.
-\fBHowever, not all software deals correctly with filenames that
-contain spaces.  Moreover, the rules, if any, for quoting filenames
-vary between operating systems, command shells and individual pieces
-of software, so this code may not always work.\fR
-
 If you use pdflatex 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"); 
+        system( "fig2dev -Lpdf \"$_[0].fig\" \"$_[0].pdf\"" ); 
     }
 
+\fBNote 1:\fR In the command lines given in the system commands in the
+above examples, double quotes have been inserted around the file names
+(implemented by '\"' in the Perl language).  They immunize the running
+of the program against special characters in filenames.  Very often
+these quotes are not necessary, i.e., they can be omitted.  But it is
+normally safer to keep them in.  Even though the rules for quoting
+vary between operating systems, command shells and individual pieces
+of software, the quotes in the above examples do not cause problems in
+the cases I have tested.
+
+\fBNote 2:\fR One case in which the quotes are important is when the
+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
+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
+example of the use of both directory separators.)
+
 If you have some general custom dependencies defined in the system or
 user initialization file, you may find that for a particular project
 they are undesirable.  So you might want to delete the unneeded ones.
@@ -2184,7 +2280,7 @@ happen:
 
     add_cus_dep('ndx', 'nnd', 0, 'makendx2nnd');
     sub makendx2nnd {
-        system("makeindex -o $_[0].nnd $_[0].ndx");
+        system( "makeindex -o \"$_[0].nnd\" \"$_[0].ndx"\" );
     }
 
 (You will need to modify this code if you use filenames
@@ -2222,7 +2318,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");
+        system( "fig2dev -Lps \"$_[0].fig\" \"$_[0].eps\"" );
     }
 
 This method still works, and is equivalent to the earlier code using
@@ -2395,7 +2491,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 collins at node phys.psu.edu).
-(Version 4.31).
+(Version 4.33b).
 
 Released version can be obtained from CTAN:
 <http://www.tug.org/tex-archive/support/latexmk/>, and from the
diff --git a/Master/texmf/doc/man/man1/latexmk.man1.pdf b/Master/texmf/doc/man/man1/latexmk.man1.pdf
index bbfefcd087c..46ddae74617 100644
--- a/Master/texmf/doc/man/man1/latexmk.man1.pdf
+++ b/Master/texmf/doc/man/man1/latexmk.man1.pdf