summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man/man1
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-11-20 22:01:59 +0000
committerKarl Berry <karl@freefriends.org>2017-11-20 22:01:59 +0000
commit16db2735dd5c2cd2aa72643ed707730eb62e5bb1 (patch)
tree009a21f673192e806c3b4143d9ab932e371b5620 /Master/texmf-dist/doc/man/man1
parent21337afd777f807a4932c5b0a106798dcfd9d626 (diff)
latexmk (20nov17)
git-svn-id: svn://tug.org/texlive/trunk@45867 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/man/man1')
-rw-r--r--Master/texmf-dist/doc/man/man1/latexmk.1370
-rw-r--r--Master/texmf-dist/doc/man/man1/latexmk.man1.pdfbin148846 -> 182837 bytes
2 files changed, 247 insertions, 123 deletions
diff --git a/Master/texmf-dist/doc/man/man1/latexmk.1 b/Master/texmf-dist/doc/man/man1/latexmk.1
index e970ff1d6b2..17d952ea214 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 "19 January 2017" ""
+.TH LATEXMK 1 "20 November 2017" ""
.SH NAME
latexmk \- generate LaTeX document
.SH SYNOPSIS
@@ -177,18 +177,22 @@ When the source file uses bbl files for bibliography, run bibtex or
biber as needed to regenerate the bbl files.
This property can also be configured by setting the \fI$bibtex_use\fR
-variable to 2 in a configuration file
+variable to 2 in a configuration file.
.TP
.B -bibtex-
-Never run bibtex or biber.
+Never run bibtex or biber. Also, always treat .bbl files as precious,
+i.e., do not delete them in a cleanup operation.
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-bibtex-\fR option will prevent \fIlatexmk\fR from trying to run
\fIbibtex\fR or \fIbiber\fR, which would result in overwriting of the
-bbl files.
+bbl files.
+
+This property can also be configured by setting the \fI$bibtex_use\fR
+variable to 0 in a configuration file.
.TP
.B -bibtex-cond
@@ -198,7 +202,21 @@ only if the
relevant bib file(s) exist. Thus when the bib files are not
available, \fIbibtex\fR or \fIbiber\fR is not run, thereby avoiding
overwriting of
-the bbl file(s). This is the default setting.
+the bbl file(s).
+Also, always treat .bbl files as precious,
+i.e., do not delete them in a cleanup operation.
+
+This is the default setting.
+It can also be configured by setting the \fI$bibtex_use\fR
+variable to 1 in a configuration file.
+
+The reason for using this setting is that sometimes a .bbl file is
+available containing the bibliography for a document, but the .bib
+file is not available. An example would be for a scientific journal
+where authors submit .tex and .bbl files, but not the original .bib
+file. In that case, running \fIbibtex\fR or \fIbiber\fR would not
+work, and the .bbl file should be treated as a user source file, and
+not as a file that can be regenerated on demand.
(Note that it is possible for \fIlatexmk\fR to decide that the bib
file does not exist, even though the bib file does exist and
@@ -213,6 +231,18 @@ search path as \fIbibtex\fR and \fIbiber\fR. If this problem arises, use the
\fB-bibtex\fR option when invoking \fIlatexmk\fR.)
.TP
+.B -bibtex-cond1
+The same as \fB-bibtex-cond1\fR except that .bbl files are only
+treated as precious if one or more bibfiles fails to exist.
+
+Thus if all the bib files exist, \fIbibtex\fR or \fIbiber\fR is run to
+generate .bbl files as needed, and then it is appropriate to delete
+the bbl files in a cleanup operation since they can be re-generated.
+
+This property can also be configured by setting the \fI$bibtex_use\fR
+variable to 1.5 in a configuration file.
+
+.TP
.B -bm <message>
A banner message to print diagonally across each page when converting
the dvi file to postscript. The message must be a single argument on
@@ -254,12 +284,22 @@ 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.
-If \fI$bibtex_use\fR is set to 0 or 1, bbl files are counted as
-non-regeneratable.
+\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
+files are regeneratable, and are deleted in a clean up. But if
+\fI$bibtex_use\fR is 1.5 and a bib file doesn't exist, then the bbl
+files are treated as non-regeneratable and hence are not deleted.
-If \fI$cleanup_includes_cusdep_generated\fR is nonzero, regeneratable
+In contrast, if \fI$bibtex_use\fR is set to 2, bbl files are always
+treated as regeneratable, and are deleted in a cleanup.
+
+\fITreatment of files generated by custom dependencies:\fRIf
+\fI$cleanup_includes_cusdep_generated\fR is nonzero, regeneratable
files are considered as including those generated by custom
-dependencies and are also deleted. Otherwise these files are not deleted.
+dependencies and are also deleted. Otherwise these files are not
+deleted.
.TP
.B -C
@@ -271,8 +311,8 @@ in the \fI$clean_full_ext\fR configuration variable.
This cleanup is instead of a regular make. See the \fB-gg\fR option
if you want to do a cleanup than a make.
-If \fI$bibtex_use\fR is set to 0 or 1, bbl files are counted as
-non-regeneratable.
+See the \fB-c\fR option for the specification of whether or not .bbl
+files are treated as non-regeneratable or regeneratable.
If \fI$cleanup_includes_cusdep_generated\fR is nonzero, regeneratable
files are considered as including those generated by custom
@@ -683,6 +723,12 @@ Turn off generation of pdf version of document.
It may get overridden if some other option requires the generation of
a pdf file.)
+If after all options have been processed, pdf generation is still
+turned off, then generation of a dvi file will be turned on, and then
+the program used to compiled a document will be \fIlatex\fR (or, more
+precisely, whatever program is configured to be used in the
+\fI$latex\fR configuration variable).
+
.TP
.B -pdflatex="COMMAND"
This sets the string specifying the command to run \fIpdflatex\fR, and is
@@ -1445,6 +1491,29 @@ applies only if preview-continuous mode (-pvc option) is used. See
file is created.
.TP
+.B $analyze_input_log_always [1]
+
+After a run of latex (etc), always analyze .log for input files in the
+<...> and (...) constructions. Otherwise, only do the analysis when
+fls file doesn't exist or is out of date.
+
+Under normal circumstances, the data in the fls file is reliable, and
+the test of the log file gets lots of false positives; usually
+$analyze_input_log_always is best set to zero. But the test of the
+log file is needed at least in the following situation: When a user
+needs to persuade latexmk that a certain file is a source file, and
+latexmk doesn't otherwise find it. Then the user can write code that
+causes a line with (...) to be written to log file. One important
+case is for lualatex, which doesn't always generate lines in the .fls
+file for input lua files. (The situation with lualatex is HIGHLY
+version dependent, e.g., there was a big change between TeXLive 2016
+and TeXLive 2017.)
+
+To keep backward compatibility with older versions
+of latexmk, the default is to set
+$analyze_input_log_always to 1.
+
+.TP
.B $auto_rc_use [1]
Whether to automatically read the standard initialization (rc) files,
which are the system RC file, the user's RC file, and the RC file in
@@ -1455,7 +1524,6 @@ automatic reading of the later RC files.
This variable does not affect the reading of RC files specified on the
command line by the \fB-r\fR option.
-
.TP
.B $aux_dir [""]
The directory in which auxiliary files (aux, log, etc) are to be
@@ -1475,7 +1543,6 @@ what directory names are suitable.
If you also use the \fB-cd\fR option, and \fI$out_dir\fR (or \fI$aux_dir\fR) contains a
relative path, then the path is interpreted relative to the document
directory.
-
.TP
.B $banner [0]
If nonzero, the banner message is printed across each page when
@@ -1553,17 +1620,26 @@ from the log file that one (or more)
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 \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 \fIbibtex\fR or \fIbiber\fR if the bib
-files exist.
-2: run \fIbibtex\fR or \fIbiber\fR whenever it appears necessary to
+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, and also controls
+whether or not .bbl files are deleted in a cleanup operation.
+
+The possible values of \fI$bibtex_use\fR are:
+ 0: never use BibTeX or biber;
+never delete .bbl files in a cleanup.
+ 1: only use \fIbibtex\fR or \fIbiber\fR if the bib files exist;
+never delete .bbl files in a cleanup.
+ 1.5: only use \fIbibtex\fR or \fIbiber\fR if the bib files exist;
+conditionally delete .bbl files in a cleanup (i.e., delete them only
+when the bib files all 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.
+files, without testing for the existence of the bib files;
+always delete .bbl files in a cleanup.
+
.TP
.B $cleanup_includes_cusdep_generated [0]
If nonzero, specifies that cleanup also deletes files that are
@@ -1605,7 +1681,6 @@ in an initialization file will imply that when a clean-up operation is
specified, not only is the standard set of files deleted, but also
files of the form FOO.out, FOO-blx.bib, and %R-figures*.log, where FOO
stands for the basename of the file being processed (as in FOO.tex).
-
.TP
.B $clean_full_ext [""]
Extra extensions of files for \fIlatexmk\fR to remove when the \fB-C\fR
@@ -1613,7 +1688,6 @@ 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]
@@ -1650,11 +1724,9 @@ 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.
-
.TP
.B @cus_dep_list [()]
Custom dependency list -- see section on "Custom Dependencies".
-
.TP
.B @default_excluded_files [()]
When \fIlatexmk\fR is invoked with no files specified on the command
@@ -1681,7 +1753,6 @@ change the set of files to be processed.
Notes: 1. This variable has no effect except when no files are
specified on the \fIlatexmk\fR command line. 2. Wildcards are allowed
in \fI@default_excluded_files\fR.
-
.TP
.B @default_files [("*.tex")]
Default list of files to be processed.
@@ -1713,7 +1784,6 @@ filename specifications is possible.
If you want \fIlatexmk\fR to process all .tex files with a few
exceptions, see the \fI@default_excluded_files\fR array variable.
-
.TP
.B $dependents_phony [0]
If a list of dependencies is output, this variable determines whether
@@ -1765,14 +1835,12 @@ appropriate to the operating system). But sometimes letting
\fIlatexmk\fR do the detaching is not appropriate (for a variety of
non-trivial reasons), so you should put the "start " bit in
yourself, whenever it is needed.
-
.TP
.B $dvi_previewer_landscape ["start xdvi %O %S"]
The command to invoke a dvi-previewer in landscape mode.
[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
@@ -1784,7 +1852,6 @@ 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.
@@ -1961,7 +2028,6 @@ 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
files.
-
.TP
.B $kpsewhich_show [0]
Whether to show diagnostics about invocations of \fIkpsewhich\fR: the
@@ -1970,7 +2036,6 @@ shown if \fI$kpsewhich_show\fR is non-zero or if diagnostics mode is
on. (But in the second case, lots of other diagnostics are also
shown.) Without these diagnostics there is nothing visible in
\fIlatexmk\fR's screen output about invocations of \fIkpsewhich\fR.
-
.TP
.B $landscape_mode [0]
If nonzero, run in landscape mode, using the landscape mode previewers and
@@ -2015,7 +2080,6 @@ 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.
-
.TP
.B $latex_silent_switch ["-interaction=batchmode"]
Switch(es) for the LaTeX processing program when silent mode is on.
@@ -2060,12 +2124,10 @@ 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
@@ -2081,7 +2143,6 @@ 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
@@ -2089,11 +2150,9 @@ Switch(es) for the \fIlualatex\fR program (specified in the variable
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.
-
.TP
.B $makeindex ["makeindex %O -o %D %S"]
The index processing program.
@@ -2126,7 +2185,6 @@ 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
a Unix-like environment inside MS-Windows.)
-
.TP
.B $new_viewer_always [0]
This variable applies to \fIlatexmk\fR \fBonly\fR in
@@ -2136,7 +2194,6 @@ same file, and if one is running will not start a new one. If
\fI$new_viewer_always\fR is non-zero, this check will be skipped, and
\fIlatexmk\fR will behave as if no viewer is running.
.TP
-
.B $out_dir [""]
If non-blank, this variable specifies the directory in which output
files are to be written by a run of
@@ -2169,7 +2226,6 @@ higher-level directory, and you need to use \fImakeindex\fR or
operating system environment variable openout_any to "a" (as in
"all"), to override the default "paranoid" setting.
.TP
-
.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 \fIpdflatex\fR,
@@ -2186,9 +2242,7 @@ document using \fIxelatex\fR, using the commands specified by the
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.
-
.TP
-
.B $pdflatex ["pdflatex %O %S"]
The LaTeX processing program in a version that makes a pdf file instead
of a dvi file.
@@ -2203,7 +2257,6 @@ 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 \fIlatexmk\fR when it finds
@@ -2219,7 +2272,6 @@ are 'tex', 'pdf', 'jpg, and 'png'.
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 \fIpdflatex\fR program (specified in the variable
@@ -2227,7 +2279,6 @@ Switch(es) for the \fIpdflatex\fR program (specified in the variable
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.
@@ -2260,7 +2311,6 @@ appropriate to the operating system). But sometimes letting
\fIlatexmk\fR do the detaching is not appropriate (for a variety of
non-trivial reasons), so you should put the "start " bit in
yourself, whenever it is needed.
-
.TP
.B $pdf_update_command [""]
When the pdf previewer is set to be updated by running a command, this
@@ -2290,7 +2340,6 @@ The first setting arranges for the xpdf program to be used in its
"remote server mode", with the server name specified as the rootname
of the TeX file. The second setting arranges for updating to be done
in response to a command, and the third setting sets the update command.
-
.TP
.B $pdf_update_signal [Under UNIX: SIGHUP, which is a system-dependent value]
The number of the signal that is sent to the pdf viewer when it is
@@ -2405,18 +2454,15 @@ that for the value 4, to run a command to do the update, the command
is specified by the variable \fI$ps_update_command\fR, and for the
value 2, to specify update by signal, the signal is specified by
\fI$ps_update_signal\fR.)
-
.TP
.B $ps_update_signal [Under UNIX: SIGHUP, which is a system-dependent value]
The number of the signal that is sent to the pdf viewer when it is
updated by sending a signal -- see \fI$ps_update_method\fR. The
default value is the one appropriate for gv on a UNIX system.
-
.TP
.B $pvc_view_file_via_temporary [1]
The same as \fI$always_view_file_via_temporary\fR, except that it only
applies in preview-continuous mode (-pvc option).
-
.TP
.B $quote_filenames [1]
This specifies whether substitutions for placeholders in command
@@ -2452,7 +2498,6 @@ Document.fls. However, some implementations instead produce files
named for the program, i.e., latex.fls or pdflatex.fls. In this
second case, \fIlatexmk\fR copies the latex.fls or pdflatex.fls to a
file with the basename of the main LaTeX document, e.g., Document.fls.
-
.TP
.B $search_path_separator [See below for default]
The character separating paths in the environment variables TEXINPUTS,
@@ -2478,11 +2523,9 @@ you'll need to find out what is needed, and set
\fI$search_path_separator\fR explicitly. (The same goes, of course,
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
@@ -2498,12 +2541,10 @@ warnings. The command line options
Note that multiple occurrences for the same undefined object on the
same page and same line will be compressed to a single warning.
-
.TP
.B $silent [0]
Whether to run silently. Setting $silent to 1 has the same effect as
the \fB-quiet\fR of \fB-silent\fR options on the command line.
-
.TP
.B $sleep_time [2]
The time to sleep (in seconds) between checking for source file
@@ -2521,11 +2562,9 @@ For backward compatibility, if you choose to set
\fI$texfile_search\fR, it is a string of space-separated filenames, and
then \fIlatexmk\fR replaces \fI@default_files\fR with the filenames in
\fI$texfile_search\fR to which is added "*.tex".
-
.TP
.B $success_cmd [undefined]
See the documentation for $compiling_cmd.
-
.TP
.B $tmpdir [See below for default]
Directory to store temporary files that \fIlatexmk\fR may generate while
@@ -2557,24 +2596,20 @@ 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 $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
@@ -2590,7 +2625,6 @@ 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
@@ -2606,20 +2640,23 @@ that equally applies to \fI$xelatex_silent_switch\fR.
In any RC file a set of custom dependencies can be set up to convert a
file with one extension to a file with another. An example use of this
would be to allow \fIlatexmk\fR to convert a \fI.fig\fR file to
-\fI.eps\fR to be included in the \fI.tex\fR file.
+\fI.eps\fR to be included in the \fI.tex\fR file.
+
+.SS Defining a custom dependency:
+The old method of configuring \fIlatexmk\fR to use a custom dependency
+was to directly manipulate the \fB@cus_dep_list\fR array that contains
+information defining the custom dependencies. (See the section "Old Method of
+Defining Custom Dependencies" for details.) This method still
+works, but is no longer preferred.
-The old method of configuring \fIlatexmk\fR was to directly manipulate
-the \fB@cus_dep_list\fR array that contains information defining the
-custom dependencies. This method still works. But now there are
-subroutines that allow convenient manipulations of the custom
-dependency list. These are
+A better method is to use the subroutines that allow convenient
+manipulations of the custom dependency list. These are
add_cus_dep( fromextension, toextension, must, subroutine )
remove_cus_dep( fromextension, toextension )
show_cus_dep()
-The custom dependency is a list of rules, each of which is specified
-as follow:
+The arguments are as follows:
.TP
.B from extension:
The extension of the file we are converting from (e.g. "fig").
@@ -2641,14 +2678,28 @@ file conversion. The first argument to the subroutine is the base name
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
+
+Naturally \fIadd_cus_dep\fR adds a custom dependency with the
+specified from and to extensions. If a custom dependency has been
+previously defined (e.g., in an rcfile that was read earlier), then it
+is replaced by the new one.
+
+The subroutine \fIremove_cus_dep\fR removes the specified custom
+dependency. The subroutine \fIshow_cus_dep\fR causes a list of the
+currently defined custom dependencies to be sent to the screen
+output.
+
+.SS How custom dependencies are used:
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 the rule whenever the destination
+custom-dependency rule. If it does, then the rule is invoked whenever
+the destination
file (the one with the to-extension) is out-of-date with respect to
the corresponding source file.
@@ -2659,15 +2710,23 @@ 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 the specification of
+each custom-dependency rule, labeled "must" above,
specifies how the rule should be applied when the source file fails to
exist.
-A simple and typical example of code in an initialization rcfile is
+.SS Function to implement custom dependency, traditional method:
+The function that implements a custom dependency gets the information
+on the files to be processed in two ways. The first is through its
+one argument; the argument contains the base name of the source and
+destination files. The second way is described later.
+
+A simple and typical example of code in an initialization rcfile using
+the first method is:
add_cus_dep( 'fig', 'eps', 0, 'fig2eps' );
sub fig2eps {
- return 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
@@ -2701,12 +2760,13 @@ replace the above code in an initialization file by
add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' );
sub fig2pdf {
- return 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
+(implemented by '\\"' \" " COMMENT TO FOOL EDITOR INTO MATCHING DOUBLE QUOTES
+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
@@ -2724,10 +2784,21 @@ 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.)
+\fBNote 3:\fR The subroutines implementing custom dependencies in the
+examples given just have a single line invoking an external program.
+That's the usual situation. But since the subroutines are in the Perl
+language, you can implement much more complicated processing if you
+need it.
+
+.SS Removing custom dependencies, and when you might need to do this:
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.
-For example, you remove any "fig" to "eps" rule by the line
+A situation where this would be desirable is where there are multiple
+custom dependencies with the same from-extension or the same
+to-extension. In that case, \fIlatexmk\fR might choose a different one
+from the one you want for a specific project. As an example, to
+remove any "fig" to "eps" rule you would use:
remove_cus_dep( 'fig', 'eps' );
@@ -2739,44 +2810,92 @@ line
in an initialization file.
-Another example of a custom dependency overcomes a limitation of
-\fIlatexmk\fR concerning index files. The only index-file conversion
-built-in to \fIlatexmk\fR is from an ".idx" file written on one run of
-latex/pdflatex to an ".ind" file to be read in on a subsequent run.
-But with the index.sty package you can create extra indexes with
-extensions that you configure. \fILatexmk\fR does not know how to
-deduce the extensions from the information it has. But you can easily
-write a custom dependency. For example if your latex file uses the
-command "\\newindex{special}{ndx}{nnd}{Special index}" you will need to
-convert files with the extension \fI.ndx\fR to \fI.nnd\fR. The
-following lines in an initialization RC file will cause this to
-happen:
-
- add_cus_dep('ndx', 'nnd', 0, 'makendx2nnd');
- sub makendx2nnd {
+.SS Function implementing custom dependency, alternative methods:
+So far the examples for functions to implement custom dependencies
+have used the argument of the function to specify the base name of
+converted file. This method has been available since very old
+versions of \fIlatexmk\fR, and many examples can be found, e.g., on
+the web.
+
+However in later versions of \fIlatexmk\fR the internal structure of
+the implementation of its "rules" for the steps of processing,
+including custom dependencies, became much more powerful. The
+function implementing a custom dependency is executed within a special
+context where a number of extra variables and subroutines are
+defined. Publicly documented ones, intended to be long-term stable,
+are listed below, under the heading "Variables and subroutines for
+processing a rule".
+
+Examples of their use is given in the following examples, concerning
+multiple index files and glossaries.
+
+The only index-file conversion built-in to \fIlatexmk\fR is from an
+".idx" file written on one run of latex/pdflatex to an ".ind" file to
+be read in on a subsequent run. But with the index.sty package, for
+example, you can create extra indexes with extensions that you
+configure. \fILatexmk\fR does not know how to deduce the extensions
+from the information it has. But you can easily write a custom
+dependency. For example if your latex file uses the command
+"\\newindex{special}{ndx}{nnd}{Special index}" you will need to get
+\fIlatexmk\fR to convert files with the extension \fI.ndx\fR to
+\fI.nnd\fR. The most elementary method is to define a custom
+dependency as follows:
+
+ add_cus_dep( 'ndx', 'nnd', 0, 'ndx2nnd' );
+ sub ndx2nnd {
return system( "makeindex -o \\"$_[0].nnd\\" \\"$_[0].ndx\\"" );
}
+ push @generated_exts, 'ndx', 'nnd';
+
+Notice the added line compared with earlier examples. The extra line
+gets the extensions "ndx" and "nnd" added to the list of extensions
+for generated files; then the extra index files will be deleted by
+clean-up operations
+
+But if you have yet more indexes with yet different extensions, e.g.,
+"adx" and "and", then you will need a separate function for each pair
+of extensions. This is quite annoying. You can use the
+\fIRun_subst\fR function to simplify the definitions to use a single
+function:
+
+ add_cus_dep( 'ndx', 'nnd', 0, 'dx2nd' );
+ add_cus_dep( 'adx', 'and', 0, 'dx2nd' );
+ sub dx2nd {
+ return Run_subst( "makeindex -o %D %S" );
+ }
+ push @generated_exts, 'ndx', 'nnd', 'adx', 'and';
+
+You could also instead use
-Those of you with experience with Makefiles, will undoubtedly be
+ add_cus_dep( 'ndx', 'nnd', 0, 'dx2nd' );
+ add_cus_dep( 'adx', 'and', 0, 'dx2nd' );
+ sub dx2nd {
+ return Run_subst( $makeindex );
+ }
+ push @generated_exts, 'ndx', 'nnd', 'adx', 'and';
+
+This last example uses the command specification in \fB$makeindex\fR,
+and so any customization you have made for the standard index also
+applies to your extra indexes.
+
+Similar techniques can be applied for glossaries.
+
+Those of you with experience with Makefiles, may get
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.
Thus the \fI.nnd\fR appears to be perpetually out-of-date. This
-situation, of circular dependencies, is endemic to latex, and
-\fIlatexmk\fR in its current version works correctly with circular
-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.
+situation, of circular dependencies, is endemic to latex, and is one
+of the issues that \fIlatexmk\fR is programmed to overcome. It
+examines the contents of the files (by use of a 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 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.
-Glossaries can be dealt with similarly.
-
-
-.SH OLD METHOD OF DEFINING CUSTOM DEPENDENCIES
-In previous versions of \fIlatexmk\fR, the only method of defining
+.SS Old Method of Defining Custom Dependencies:
+In much older versions of \fIlatexmk\fR, the only method of defining
custom dependencies was to directly manipulate the table of custom
dependencies. This is contained in the \fB@cus_dep_list\fR array. It
is an array of strings, and each string in the array has four items in
@@ -2793,10 +2912,10 @@ of \fI.fig\fR files to \fI.eps\fR files:
return system( "fig2dev -Lps \\"$_[0].fig\\" \\"$_[0].eps\\"" );
}
-This method still works, and is equivalent to the earlier code using
-the add_cus_dep subroutine, except that it doesn't delete any previous
-custom-dependency for the same conversion. So the new method is
-preferable.
+This method still works, and is almost equivalent to the code given
+earlier that used the \fIadd_cus_dep\fR subroutine. However, the old
+method doesn't delete any previous custom-dependency for the same
+conversion. So the new method is preferable.
.SH ADVANCED CONFIGURATION: Some extra resources and advanced tricks
@@ -2810,7 +2929,7 @@ 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
+your case, they may give you useful ideas
.SS Variables and subroutines for processing a rule
@@ -2828,23 +2947,19 @@ 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
@@ -2857,29 +2972,38 @@ 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.
-
+cases that use this subroutine are \fIbib2gls-latexmkrc\fR,
+\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.
-
.TP
.B rdb_list_source( $rule )
This subroutine returns the list of source files (i.e., the dependency
list) for the given rule.
-
.TP
.B rdb_set_source( $rule, file, ... )
+.TP
.B rdb_set_source( $rule, @files )
This subroutine sets the dependency list for the given rule to be the
specified files. Files that are already in the list have unchanged
information. Files that were not in the list are added to it. Files
in the previous dependency list that are not in the newly specified
list of files are removed from the dependency list.
+.TP
+.B Run_subst( command_spec )
+This subroutine runs the command specified by \fIcommand_spec\fR. The
+specification is a string in the format listed in the section "Format
+of Command Specifications". An important action of the
+\fIRun_subst\fR is to make substitutions of placeholders, e.g., %S and
+%D for source and destination files; these get substituted before the
+command is run. In addition, the command after substitution is
+printed to the screen unless \fIlatexmk\fR is running in silent mode.
+
+.PP
.SS Advanced configuration: Using \fIlatexmk\fB with \fImake\fR
@@ -3015,7 +3139,7 @@ Thus we now have a method by which all the subsidiary processing is
delegated to \fImake\fR.
.SH SEE ALSO
-latex(1), bibtex(1).
+latex(1), bibtex(1), lualatex(1), pdflatex(1), xelatex(1).
.SH BUGS
Sometimes a viewer (gv) tries to read an updated .ps or .pdf file
after its creation is started but before the file is complete. Work
@@ -3042,10 +3166,10 @@ David Coppit (username david at node coppit.org) who made many useful
suggestions that contributed to version 3, and Herbert Schulz.
(Please note that the
e-mail addresses are not written in their standard form to avoid being
-harvested by worms and viruses.)
+harvested too easily.)
.SH AUTHOR
Current version, by John Collins (username jcc8 at node psu.edu).
-(Version 4.52c).
+(Version 4.54).
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 c90a405c97d..d3ce7128f26 100644
--- a/Master/texmf-dist/doc/man/man1/latexmk.man1.pdf
+++ b/Master/texmf-dist/doc/man/man1/latexmk.man1.pdf
Binary files differ