summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2016-10-15 22:55:38 +0000
committerKarl Berry <karl@freefriends.org>2016-10-15 22:55:38 +0000
commitc3861279bf2a89f2e1b13a1608f8a2f2f376ab67 (patch)
tree47fc395f819b02f7af0d6f27ba83056ff8955194 /Master/texmf-dist/doc/man
parent058b77a3ba0ce417a9dea9433252df4d95e86f98 (diff)
latexmk (13oct16)
git-svn-id: svn://tug.org/texlive/trunk@42272 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/man')
-rw-r--r--Master/texmf-dist/doc/man/man1/latexmk.1154
-rw-r--r--Master/texmf-dist/doc/man/man1/latexmk.man1.pdfbin177663 -> 155174 bytes
2 files changed, 128 insertions, 26 deletions
diff --git a/Master/texmf-dist/doc/man/man1/latexmk.1 b/Master/texmf-dist/doc/man/man1/latexmk.1
index 30f027fa75c..e2af193039b 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 "22 April 2016" ""
+.TH LATEXMK 1L "5 September 2016" ""
.SH NAME
latexmk \- generate LaTeX document
.SH SYNOPSIS
@@ -148,17 +148,16 @@ with a ".tex" extension. This behavior can be changed: see the
description concerning the \fI@default_files\fR variable in the
section "List of configuration variables usable in initialization
files".
-.PP
+
If a file is specified without an extension, then the ".tex" extension
is automatically added, just as LaTeX does. Thus, if you specify:
latexmk foo
then \fIlatexmk\fR will operate on the file "foo.tex".
-.TP
+.TP
.B -auxdir=FOO or -aux-directory=FOO
-
Sets the directory for auxiliary output files of (pdf)latex
(.aux, .log etc). This
achieves its effect by the \fB-aux-directory\fR option of (pdf)latex,
@@ -171,14 +170,18 @@ configuration variables of \fIlatexmk\fR. In particular, see the
documentation of \fI$out_dir\fR for some complications on what
directory names are suitable.
-.TP
+If you also use the \fB-cd\fR option, and the specified auxiliary output
+directory is a relative path, then the path is interpreted relative to
+the document directory.
+.TP
.B -bibtex
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
+
.TP
.B -bibtex-
Never run bibtex or biber.
@@ -189,6 +192,7 @@ 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.
+
.TP
.B -bibtex-cond
When the source file uses bbl file(s) for the bibliography, run
@@ -210,6 +214,7 @@ problem should not arise, since \fIlatexmk\fR uses the \fIkpsewhich\fR
program to do the search, and \fIkpsewhich\fR should use the same
search path as \fIbibtex\fR and \fIbiber\fR. If this problem arises, use the
\fB-bibtex\fR option when invoking \fIlatexmk\fR.)
+
.TP
.B -bm <message>
A banner message to print diagonally across each page when converting
@@ -218,11 +223,13 @@ the command line so be careful with quoting spaces and such.
Note that if the \fB-bm\fR option is specified, the \fB-ps\fR option is
assumed.
+
.TP
.B -bi <intensity>
How dark to print the banner message. A decimal number between 0 and 1.
0 is black and 1 is white. The default is 0.95, which is OK unless your
toner cartridge is getting low.
+
.TP
.B -bs <scale>
A decimal number that specifies how large the banner message will be
@@ -230,10 +237,12 @@ printed. Experimentation is necessary to get the right scale for your
message, as a rule of thumb the scale should be about equal to 1100
divided by the number of characters in the message. The default is 220.0
which is just right for 5 character messages.
+
.TP
.B -commands
List the commands used by \fIlatexmk\fR for processing files, and then
exit.
+
.TP
.B -c
Clean up (remove) all regeneratable files generated by \fIlatex\fR and
@@ -254,6 +263,7 @@ non-regeneratable.
If \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.
+
.TP
.B -C
Clean up (remove) all regeneratable files generated by \fIlatex\fR and
@@ -270,10 +280,12 @@ non-regeneratable.
If \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.
+
.TP
.B -CA
(Obsolete). Now equivalent to the \fB-C\fR option. See that option
for details.
+
.TP
.B -cd
Change to the directory containing the main source file before processing
@@ -283,6 +295,7 @@ relative to the source file.
This option is particularly useful when \fIlatexmk\fR is invoked from
a GUI configured to invoke \fIlatexmk\fR with a full pathname for the
source file.
+
.TP
.B -cd-
Do NOT change to the directory containing the main source file before processing
@@ -294,10 +307,12 @@ This is the default behavior and corresponds to the behavior of the
behavior when \fIlatexmk\fR is invoked by a GUI configured to invoke
\fIlatexmk\fR with a full pathname for the source file. See the
\fB-cd\fR option.
+
.TP
.B -CF
Remove the file containing the database of source file information,
before doing the other actions requested.
+
.TP
.B -d
Set draft mode. This prints the banner message "DRAFT" across your
@@ -310,8 +325,9 @@ specifying:
Note that if the \fB-d\fR option is specified, the \fB-ps\fR option is
assumed.
+
.TP
-.B -deps
+.B -deps
Show a list of dependent files after processing. This is in the form
of a dependency list of the form used by the \fImake\fR program, and
it is therefore suitable for use in a Makefile. It gives an overall
@@ -331,24 +347,29 @@ the \fB-deps\fR option is very similar in its purpose and results to
the \fB-M\fR option to \fIgcc\fR. (In fact, \fIlatexmk\fR also has
options \fB-M\fR, \fB-MF\fR, and \fB-MP\fR options that behave like
those of \fIgcc\fR.)
+
.TP
-.B -dependents
+.B -dependents
Equivalent to \fB-deps\fR.
+
.TP
-.B -deps-
+.B -deps-
Do not show a list of dependent files after processing. (This is the
default.)
+
.TP
-.B -dependents-
+.B -dependents-
Equivalent to \fB-deps-\fR.
+
.TP
-.B -deps-out=FILENAME
+.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
sent to stdout.
Use of this option also turns on the output of the list of dependent
files after processing.
+
.TP
.B -dF
Dvi file filtering. The argument to this option is a filter which will
@@ -359,20 +380,24 @@ 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
+
.TP
.B -diagnostics
Print detailed diagnostics during a run. This may help for debugging
problems or to understand \fIlatexmk\fR's behavior in difficult
situations.
+
.TP
.B -dvi
Generate dvi version of document.
+
.TP
.B -dvi-
Turn off generation of dvi version of document. (This may get
overridden, if some other file is made (e.g., a .ps file) that is
generated from the dvi file, or if no generated file at all is
requested.)
+
.TP
.B -e <code>
Execute the specified initialization code before processing. The code
@@ -415,6 +440,7 @@ or
latexmk -e "$latex='latex %O -shell-escape %S'" file.tex
The last two examples will NOT work with UNIX/LINUX command shells.
+
.TP
.B -f
Force \fIlatexmk\fR to continue document processing despite errors.
@@ -434,6 +460,7 @@ this by an option that is passed to the program, e.g., by
Turn off the forced processing-past-errors such as is set by the
\fB-f\fR option. This could be used to override a setting in a
configuration file.
+
.TP
.B -g
Force \fIlatexmk\fR to process document fully, even under situations
@@ -441,16 +468,20 @@ where \fIlatexmk\fR would normally decide that no changes in the
source files have occurred since the previous run.
This option is useful, for example, if you change some options and
wish to reprocess the files.
+
.TP
.B -g-
Turn off \fB-g\fR.
+
.TP
.B -gg
"Super go mode" or "clean make": clean out generated files as if
\fB-C\fR had been given, and then do a regular make.
+
.TP
.B -h, -help
Print help information.
+
.TP
.B -jobname=STRING
Set the basename of output files(s) to STRING, instead of the default,
@@ -467,9 +498,11 @@ Run in landscape mode, using the landscape mode for the previewers and
the dvi to postscript converters. This option is not normally needed
nowadays, since current previewers normally determine this information
automatically.
+
.TP
.B -l-
Turn off \fB-l\fR.
+
.TP
.B -latex="COMMAND"
This sets the string specifying the command to run latex, and is
@@ -490,6 +523,7 @@ latex) see the \fB-pdflatex\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$latex\fR variable. See the explanation of the \fB-e\fR option.
+
.TP
.B -lualatex
Use lualatex. That is, use lualatex to process the source file(s) to
@@ -502,16 +536,19 @@ specifying the following sequence of options:
.B -M
Show list of dependent files after processing. This is equivalent to
the \fB-deps\fR option.
+
.TP
.B -MF file
If a list of dependents is made, the \fB-MF\fR specifies the file to
write it to.
+
.TP
.B -MP
If a list of dependents is made, includes 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.
+
.TP
.B -new-viewer
When in continuous-preview mode, always start a new viewer to view the
@@ -521,11 +558,13 @@ not start a new one if a previous previewer is running. However, its
test sometimes fails (notably if there is an already-running previewer
that is viewing a file of the same name as the current file, but in a
different directory). This option turns off the default behavior.
+
.TP
.B -new-viewer-
The inverse of the \fB-new-viewer\fR option. It puts \fIlatexmk\fR
in its normal behavior that in preview-continuous mode it checks for
an already-running previewer.
+
.TP
.B -nobibtex
Never run bibtex or biber.
@@ -536,6 +575,7 @@ 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.
+
.TP
.B -norc
Turn off the automatic reading of initialization (rc) files.
@@ -544,8 +584,8 @@ N.B. Normally the initialization files are read and obeyed, and then
command line options are obeyed in the order they are encountered.
But \fB-norc\fR is an exception to this rule: it is acted on first,
no matter where it occurs on the command line.
-.TP
+.TP
.B -outdir=FOO or -output-directory=FOO
Sets the directory for the output files of (pdf)latex. This achieves
@@ -560,8 +600,11 @@ configuration variables of \fIlatexmk\fR. In particular, see the
documentation of \fI$out_dir\fR for some complications on what
directory names are suitable.
-.TP
+If you also use the \fB-cd\fR option, and the specified output
+directory is a relative path, then the path is interpreted relative to
+the document directory.
+.TP
.B -p
Print out the document. By default the file to be printed is
the first in the list postscript, pdf, dvi that is being made.
@@ -582,8 +625,8 @@ to see how to set the commands for printing.
This option is incompatible with the \fB-pv\fR and \fB-pvc\fR options,
so it turns them off.
-.TP
+.TP
.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
@@ -594,16 +637,19 @@ options \fB-lualatex\fR or \fB-xelatex\fR applies.) To configure
.TP
.B -pdfdvi
Generate pdf version of document from the dvi file, by default using dvipdf.
+
.TP
.B -pdfps
Generate pdf version of document from the ps file, by default using
ps2pdf.
+
.TP
.B -pdf-
Turn off generation of pdf version of document.
(This can be used to override a setting in a configuration file.
It may get overridden if some other option requires the generation of
a pdf file.)
+
.TP
.B -pdflatex="COMMAND"
This sets the string specifying the command to run pdflatex, and is
@@ -635,6 +681,7 @@ 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
@@ -645,15 +692,18 @@ The (default) case
the set of files that is being made. The first in the list
postscript, pdf, dvi that is among the files to be made is the one
used for print out.
+
.TP
.B -ps
Generate postscript version of document.
+
.TP
.B -ps-
Turn off generation of postscript version of document.
This can be used to override a setting in a configuration file.
(It may get overridden by some other option that requires a postscript
file, for example a request for printing.)
+
.TP
.B -pF
Postscript file filtering. The argument to this option is a filter
@@ -672,6 +722,7 @@ or
Whether to use single or double quotes round the "psnup -2" will
depend on your command interpreter, as used by the particular version
of perl and the operating system on your computer.
+
.TP
.B -pv
Run file previewer. If the \fB-view\fR option is used, this will select
@@ -682,9 +733,11 @@ order dvi, ps, pdf (low to high).
If no file type has been selected, the dvi previewer will be used.
This option is incompatible with the \fB-p\fR and \fB-pvc\fR options,
so it turns them off.
+
.TP
.B -pv-
Turn off \fB-pv\fR.
+
.TP
.B -pvc
Run a file previewer and continually update the .dvi, .ps, and/or .pdf
@@ -724,12 +777,15 @@ the \fB-pvc\fR option will not fork new previewers, but \fIlatexmk\fR
will normally use the existing previewer. (At least this will happen
when \fIlatexmk\fR is running under an operating system where it knows
how to determine whether an existing previewer is running.)
+
.TP
.B -pvc-
Turn off \fB-pvc\fR.
+
.TP
.B -quiet
Same as -silent
+
.TP
.B -r <rcfile>
Read the specified initialization file ("RC file") before processing.
@@ -753,8 +809,9 @@ initialization code directly on \fIlatexmk\fR's command line. An
error results in \fIlatexmk\fR stopping. Multiple instances of the
\fB-r\fR and \fB-e\fR options can be used, and they are executed in
the order they appear on the command line.
+
.TP
-.B -recorder
+.B -recorder
Use 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
@@ -764,16 +821,20 @@ run of \fIlatex\fR or \fIpdflatex\fR.
For further information, see the documentation for the \fI$recorder\fR
configuration variable.
+
.TP
-.B -recorder-
+.B -recorder-
Do not use the -recorder option with \fIlatex\fR and \fIpdflatex\fR.
+
.TP
-.B -rules
+.B -rules
Show a list of \fIlatemk\fR's rules and dependencies after processing.
+
.TP
-.B -rules-
+.B -rules-
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
@@ -841,6 +902,7 @@ 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.
+
.TP
.B -use-make
When after a run of \fIlatex\fR or \fIpdflatex\fR, there are warnings
@@ -859,15 +921,19 @@ appropriate \fIpdflatex\fR).
See also the documentation for the \fI$use_make_for_missing_files\fR
configuration variable.
+
.TP
.B -use-make-
Do not use the make program to try to make missing files. (Default.)
+
.TP
.B -v, -version
Print version number of \fIlatexmk\fR.
+
.TP
.B -verbose
Opposite of \fB-silent\fR. This is the default setting.
+
.TP
.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
@@ -878,8 +944,8 @@ 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.
-.TP
+.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
@@ -953,7 +1019,7 @@ d. Further tricks can involve replacing the standard commands that
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).
+at http://mirror.ctan.org/support/latexmk/example_rcfiles).
Even if these examples don't do what you want, they may provide
suitable inspiration.
@@ -1008,13 +1074,31 @@ that of cygwin), \fIlatexmk\fR reads for the first it finds of
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, "$HOME/.latexmkrc", if it exists. Here $HOME
+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
+directory. The other possibility is "latexmk/latexmkrc" in the user's
+XDG configuration home directory. The actual file read is the first
+of "$XDG_CONFIG_HOME/latexmk/latexmkrc" or "$HOME/.latexmkrc" which
+exists. (See
+https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+for details on the XDG Base Directory Specification.)
+
+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
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.]
+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
+it.]
+
+$XDG_CONFIG_HOME is the value of the environment variable
+XDG_CONFIG_HOME if it exists. If this environment variable does not
+exist, but $HOME is non-blank, then $XDG_CONFIG_HOME is set to the
+default value of $HOME/.config. Otherwise $XDG_CONFIG_HOME is blank,
+and \fIlatexmk\fR does not look for an RC file under it.
+
.PP
3) The RC file in the current working directory. This file can be
named either "latexmkrc" or ".latexmkrc", and the first of these to be
@@ -1040,7 +1124,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
-http://www.ctan.org/tex-archive/support/latexmk/example_rcfiles).
+http://mirror.ctan.org/support/latexmk/example_rcfiles).
\fR
.SH HOW TO SET VARIABLES IN INITIALIZATION FILES
@@ -1352,6 +1436,10 @@ MiKTeX version of (pdf)latex.
See also the documentation of \fI$out_dir\fR for some complications on
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
@@ -2274,7 +2362,7 @@ correctly deal with TeX files whose names contain spaces. Latexmk's
quoting only ensures that such filenames are correctly treated by the
operating system in passing arguments to programs.)
.TP
-.B $recorder [0]
+.B $recorder [1]
Whether to use the \fB-recorder\fR option to \fIlatex\fR and
\fIpdflatex\fR. Use of this option results in a file of extension
\fI.fls\fR containing a list of the files that these programs have
@@ -2664,6 +2752,20 @@ files.
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, ... )
+.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.
+
.SS Advanced configuration: Using \fIlatexmk\fB with \fImake\fR
@@ -2828,11 +2930,11 @@ 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.45).
+(Version 4.48).
Released version can be obtained from CTAN:
-<http://www.ctan.org/tex-archive/support/latexmk/>, and from the
-author's website <http://www.phys.psu.edu/~collins/software/latexmk/>.
+<http://www.ctan.org/pkg/latexmk/>, and from the
+author's website <http://www.personal.psu.edu/jcc8/latexmk/>.
.br
Modifications and enhancements by Evan McLean (Version 2.0)
.br
diff --git a/Master/texmf-dist/doc/man/man1/latexmk.man1.pdf b/Master/texmf-dist/doc/man/man1/latexmk.man1.pdf
index b137535f4f3..01fd9cd499e 100644
--- a/Master/texmf-dist/doc/man/man1/latexmk.man1.pdf
+++ b/Master/texmf-dist/doc/man/man1/latexmk.man1.pdf
Binary files differ