summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexmk/latexmk.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/support/latexmk/latexmk.txt')
-rw-r--r--Master/texmf-dist/doc/support/latexmk/latexmk.txt1772
1 files changed, 1772 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.txt b/Master/texmf-dist/doc/support/latexmk/latexmk.txt
new file mode 100644
index 00000000000..7c99e946497
--- /dev/null
+++ b/Master/texmf-dist/doc/support/latexmk/latexmk.txt
@@ -0,0 +1,1772 @@
+
+NAME
+ latexmk - generate LaTeX document
+
+SYNOPSIS
+ latexmk [options] [file ...]
+
+DESCRIPTION
+ Latexmk completely automates the process of compiling a LaTeX document.
+ Essentially, it is like a specialized relative of the general make
+ utility, but one which determines dependencies automatically and has
+ some other very useful features. In its basic mode of operation
+ latexmk is given the name of the primary source file for a document,
+ and it issues the appropriate sequence of commands to generate a .dvi,
+ .ps, .pdf and/or hardcopy version of the document.
+
+ Latexmk can also be set to run continuously with a suitable previewer.
+ In that case the LaTeX program, etc, are rerun whenever one of the
+ source files is modified, and the previewer automatically updates the
+ on-screen view of the compiled document.
+
+ Latexmk determines which are the source files by examining the log
+ file. When latexmk is run, it examines properties of the source files,
+ and if any have been changed since the last document generation,
+ latexmk will run the various LaTeX processing programs as necessary.
+ In particular, it will repeat the run of LaTeX (or pdflatex) often
+ enough to resolve all cross references; depending on the macro packages
+ used. With some macro packages and document classes, four, or even
+ more, runs may be needed. If necessary, latexmk will also run bibtex
+ and/or makeindex. In addition, latexmk can be configured to generate
+ other necessary files. For example, from an updated figure file it can
+ automatically generate a file in encapsulated postscript or another
+ suitable format for reading by LaTeX.
+
+ Latexmk has two different previewing options. In the simple -pv
+ option, a dvi, postscript or pdf previewer is automatically run after
+ generating the dvi, postscript or pdf version of the document. The
+ type of file to view is selected according to configuration settings
+ and command line options.
+
+ The second previewing option is the powerful -pvc option (mnemonic:
+ "preview continuously"). In this case, latexmk runs continuously, reg-
+ ularly monitoring all the source files to see if any have changed.
+ Every time a change is detected, latexmk runs all the programs neces-
+ sary to generate a new version of the document. A good previewer (like
+ gv) will then automatically update its display. Thus the user can sim-
+ ply edit a file and, when the changes are written to disk, latexmk com-
+ pletely automates the cycle of updating the .dvi (and possibly the .ps
+ and .pdf) file, and refreshing the previewer's display. It's not quite
+ WYSIWYG, but usefully close.
+
+ For other previewers, the user may have to manually make the previewer
+ update its display, which can be (some versions of xdvi and gsview) as
+ simple as forcing a redraw of its display.
+
+ Latexmk has the ability to print a banner in gray diagonally across
+ each page when making the postscript file. It can also, if needed,
+ call an external program to do other postprocessing on the generated
+ files.
+
+
+
+
+ 1
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ Latexmk is highly configurable, both from the command line and in con-
+ figuration files, so that it can accommodate a wide variety of user
+ needs and system configurations. Default values are set according to
+ the operating system, so latexmk often works without special configura-
+ tion on MS-Windows, cygwin, Linux, OS-X, and other UNIX systems
+ (notably Solaris).
+
+ A very annoying complication handled very reliably by Latexmk, is that
+ LaTeX is a multiple pass system. On each run, LaTeX reads in informa-
+ tion generated on a previous run, for things like cross referencing and
+ indexing. In the simplest cases, a second run of LaTeX suffices, and
+ often the log file contains a message about the need for another pass.
+ However, there is a wide variety of add-on macro packages to LaTeX,
+ with a variety of behaviors. The result is to break simple-minded
+ determinations of how many runs are needed and of which programs. In
+ its new version, latexmk has a highly general and efficient solution to
+ these issues. The solution involves retaining between runs information
+ on the source files, and a symptom is that latexmk generates an extra
+ file (with extension .fdb_latexmk, by default) that contains the source
+ file information.
+
+
+LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE
+ (All options can be introduced by single or double "-" characters,
+ e.g., "latexmk -help" or "latexmk --help".)
+
+ file One or more files can be specified. If no files are specified,
+ latexmk will, by default, run on all files in the current work-
+ ing directory with a ".tex" extension. This behavior can be
+ changed: see the description concerning the @default_files vari-
+ able in the section "List of configuration variables usable in
+ initialization files".
+
+ 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 latexmk will operate on the file "foo.tex".
+
+ -bm <message>
+ A banner message to print diagonally across each page when con-
+ verting the dvi file to postscript. The message must be a sin-
+ gle argument on the command line so be careful with quoting
+ spaces and such.
+
+ Note that if the -bm option is specified, the -ps option is
+ assumed.
+
+ -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.
+
+
+
+
+ 28 September 2008 2
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ -bs <scale>
+ A decimal number that specifies how large the banner message
+ will be 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 charac-
+ ter messages.
+
+ -commands
+ List the commands used by latexmk for processing files, and then
+ exit.
+
+ -c Clean up (remove) all regeneratable files generated by latex and
+ bibtex except dvi, postscript and pdf. These files are a combi-
+ nation of log files, aux files, and those with extensions speci-
+ fied in the @generated_exts configuration variable. In addi-
+ tion, files with extensions by the $clean_ext configuration
+ variable are removed. But the file containing a database of
+ source file information is not removed.
+
+ This cleanup is instead of a regular make. See the -gg option
+ if you want to do a cleanup then a make.
+
+ -C Clean up (remove) all regeneratable files generated by latex and
+ bibtex. This is the same as the -c option with the addition of
+ dvi, postscript and pdf files, and those with extensions in the
+ $clean_full_ext configuration variable.
+
+ This cleanup is instead of a regular make. See the -gg option
+ if you want to do a cleanup than a make.
+
+ -CA Clean up (remove) absolutely all regeneratable files. This is
+ the action specified by -C with the addition of deleting the
+ file containing the database of source file information.
+
+ This cleanup is instead of a regular make. It is the same as -C
+ -CF. See the -gg option if you want to do a cleanup then a
+ make.
+
+ -CF Remove the file containing the database of source file informa-
+ tion, before doing the other actions requested.
+
+ -d Set draft mode. This prints the banner message "DRAFT" across
+ your page when converting the dvi file to postscript. Size and
+ intensity can be modified with the -bs and -bi options. The -bm
+ option will override this option as this is really just a short
+ way of specifying:
+
+ latexmk -bm DRAFT
+
+ Note that if the -d option is specified, the -ps option is
+ assumed.
+
+ -dF Dvi file filtering. The argument to this option is a filter
+ which will generate a filtered dvi file with the extension
+
+
+
+ 28 September 2008 3
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ ".dviF". All extra processing (e.g. conversion to postscript,
+ preview, printing) will then 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
+
+ -diagnostics
+ Print detailed diagnostics during a run. This may help for
+ debugging problems or to understand .latexmk's behavior in dif-
+ ficult situations.
+
+ -dvi Generate dvi version of document.
+
+ -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.)
+
+ -e <code>
+ Execute the specified initialization code before processing.
+ The code is Perl code of the same form as is used in latexmk's
+ initialization files -- for more details, see the information on
+ the -r option, and the section about "Configuration/initializa-
+ tion (RC) files". The code is typically a sequence of assign-
+ ment statements separated by semicolons.
+
+ The code is executed when the -e option is encountered during
+ latexmk's parsing of its command line. See the -r option for a
+ way of executing initialization code from a file. An error
+ results in latexmk stopping. Multiple instances of the -r and
+ -e options can be used, and they are executed in the order they
+ appear on the command line.
+
+ Some care is needed to deal with proper quoting of special char-
+ acters in the code on the command line. For example, suppose it
+ is desired to set the latex command to use its -shell-escape
+ option, then under UNIX/LINUX you could use the line
+
+ latexmk -e '$latex=q/latex %O -shell-escape %S/' file.tex
+
+ (Note that the q/.../ construct is a Perl idiom equivalent to
+ using single quotes. This is easier than arranging to get a
+ quote character correctly escaped in a way that is independent
+ of the shell and the operating-system.)
+
+ -f Force latexmk to continue document processing despite errors.
+ Normally, when latexmk detects that LaTeX or another program has
+ found an error which will not be resolved by further processing,
+ no further processing is carried out.
+
+ -f- Turn off the forced processing-past-errors such as is set by the
+ -f option. This could be used to override a setting in a
+
+
+
+ 28 September 2008 4
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ configuration file.
+
+ -g Force latexmk to process document fully, even under situations
+ where latexmk 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.
+
+ -g- Turn off -g.
+
+ -gg "Super go mode" or "clean make": clean out generated files as if
+ -CA had been given, and then do a regular make.
+
+ -h, -help
+ Print help information.
+
+ -l Run in landscape mode, using the landscape mode for the preview-
+ ers and the dvi to postscript converters. This option is not
+ normally needed nowadays, since current previewers normally
+ determine this information automatically.
+
+ -l- Turn off -l.
+
+ -new-viewer
+ When in continuous-preview mode, always start a new viewer to
+ view the generated file. By default, latexmk will, in continu-
+ ous-preview mode, test for a previously running previewer for
+ the same file and 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.
+
+ -new-viewer-
+ The inverse of the -new-viewer option. It puts latexmk in its
+ normal behavior that in preview-continuous mode it checks for an
+ already-running previewer.
+
+ -p Print out the document. By default it is the generated
+ postscript file that is printed. But you can use the -print=...
+ option to print the dvi or pdf files instead, and you can con-
+ figure this in a start up file (by setting the $print_type vari-
+ able).
+
+ However, printing is enabled by default only under UNIX/LINUX
+ systems, where the default is to use the lpr command. In gen-
+ eral, the correct behavior for printing very much depends on
+ your system's software. In particular, under MS-Windows you
+ must have suitable program(s) available, and you must have con-
+ figured the print commands used by latexmk. This can be non-
+ trivial. See the documentation on the $lpr, $lpr_dvi, and
+ $lpr_pdf configuration variables to see how to set the commands
+ for printing.
+
+ This option is incompatible with the -pv and -pvc options, so it
+
+
+
+ 28 September 2008 5
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ turns them off.
+
+ -pdf Generate pdf version of document using pdflatex.
+
+ -pdfdvi
+ Generate pdf version of document from the dvi file, by default
+ using dvipdf.
+
+ -pdfps Generate pdf version of document from the ps file, by default
+ using ps2pdf.
+
+ -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.)
+
+ -print=dvi, -print=ps, -print=pdf
+ Define which kind of file is printed. This option also ensures
+ that the requisite file is made, and turns on printing. The
+ default is to print a postscript file.
+
+ -ps Generate postscript version of document.
+
+ -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.)
+
+ -pF Postscript file filtering. The argument to this option is a
+ filter which will generate a filtered postscript file with the
+ extension ".psF". All extra processing (e.g. preview, printing)
+ will then be performed on this filtered postscript file.
+
+ Example of usage: Use psnup to print two pages on the one page:
+
+ latexmk -ps -pF 'psnup -2' foo.tex
+
+ or
+
+ latexmk -ps -pF "psnup -2" foo.tex
+
+ 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.
+
+ -pv Run file previewer. If the -view option is used, this will
+ select the kind of file to be previewed (dvi, ps or pdf). Oth-
+ erwise the viewer views the "highest" kind of file selected, by
+ the -dvi, -ps, -pdf, -pdfps options, in the order dvi, ps, pdf
+ (low to high). If no file type has been selected, the dvi pre-
+ viewer will be used. This option is incompatible with the -p
+ and -pvc options, so it turns them off.
+
+ -pv- Turn off -pv.
+
+
+
+
+ 28 September 2008 6
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ -pvc Run a file previewer and continually update the .dvi, .ps,
+ and/or .pdf files whenever changes are made to source files (see
+ the Description above). Which of these files is generated and
+ which is viewed is governed by the other options, and is the
+ same as for the -pv option. The preview-continuous option -pvc
+ can only work with one file. So in this case you will normally
+ only specify one filename on the command line. It is also
+ incompatible with the -p and -pv options, so it turns these
+ options off
+
+ With a good previewer the display will be automatically updated.
+ (Under some but not all versions of UNIX/Linux "gv -watch" does
+ this for postscript files; this can be set by a configuration
+ variable. This would also work for pdf files except for an
+ apparent bug in gv that causes an error when the newly updated
+ pdf file is read.) Many other previewers will need a manual
+ update.
+
+ Important note: the acroread program on MS-Windows locks the pdf
+ file, and prevents new versions being written, so it is a bad
+ idea to use acroread to view pdf files in preview-continuous
+ mode. It is better to use a dvi or ps viewer, as set by one of
+ the -view=dvi and -view=ps options.
+
+ There are some other methods for arranging an update, notably
+ useful for many versions of xdvi and xpdf. These are best set
+ in latexmk's configuration; see below.
+
+ Note that if latexmk dies or is stopped by the user, the
+ "forked" previewer will continue to run. Successive invocations
+ with the -pvc option will not fork new previewers, but latexmk
+ will normally use the existing previewer. (At least this will
+ happen when latexmk is running under an operating system where
+ it knows how to determine whether an existing previewer is run-
+ ning.)
+
+ -pvc- Turn off -pvc.
+
+ -quiet Same as -silent
+
+ -r <rcfile>
+ Read the specified initialization file ("RC file") before pro-
+ cessing.
+
+ Be careful about the ordering: (1) Standard initialization files
+ -- see the section below on "Configuration/initialization (RC)
+ files" -- are read first. (2) Then the options on the command
+ line are acted on in the order they are given. Therefore if an
+ initialization file is specified by the -r option, it is read
+ during this second step. Thus an initialization file specified
+ with the -r option can override both the standard initialization
+ files and previously specified options. But all of these can be
+ overridden by later options.
+
+ The contents of the RC file just comprise a piece of code in the
+
+
+
+ 28 September 2008 7
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ Perl programming language (typically a sequence of assignment
+ statements); they are executed when the -r option is encountered
+ during latexmk's parsing of its command line. See the -e option
+ for a way of giving initialization code directly on latexmk's
+ command line. An error results in latexmk stopping. Multiple
+ instances of the -r and -e options can be used, and they are
+ executed in the order they appear on the command line.
+
+ -silent
+ Run commands silently, i.e., with options that reduce the amount
+ of diagnostics generated. For example, with the default set-
+ tings for commands under UNIX, the command "latex -interac-
+ tion=batchmode" is used for latex.
+
+ Also reduce the number of informational messages that latexmk
+ generates.
+
+ -v, -version
+ Print version number of latexmk.
+
+ -verbose
+ Opposite of -silent. This is the default setting.
+
+ -view=default, -view=dvi, -view=ps, -view=pdf
+ Set the kind of file used when previewing is requested (e.g., by
+ the -pv or -pvc switches). The default is to view the "highest"
+ kind of requested file (in the order dvi, ps, pdf).
+
+ The preview-continuous option -pvc can only work with one file. So in
+ this case you will normally only specify one filename on the command
+ line.
+
+ Options -p, -pv and -pvc are mutually exclusive. So each of these
+ options turns the others off.
+
+
+EXAMPLES
+ % latexmk thesis # run latex enough times to resolve
+ cross-references
+
+ % latexmk -pvc -ps thesis# run latex enough times to resolve
+ cross-references, make a postscript
+ file, start a previewer. Then
+ watch for changes in the source
+ file thesis.tex and any files it
+ uses. After any changes rerun latex
+ the appropriate number of times and
+ remake the postscript file. If latex
+ encounters an error, latexmk will
+ keep running, watching for
+ source file changes.
+
+ % latexmk -c # remove .aux, .log, .bbl, .blg, .dvi,
+ .pdf, .ps & .bbl files
+
+
+
+
+ 28 September 2008 8
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+CONFIGURATION/INITIALIZATION (RC) FILES
+ Latexmk can be customized using initialization files, which are read at
+ startup in the following order:
+
+ 1) The system RC file, if it exists.
+ On a UNIX system, latexmk searches for following places for its sys-
+ tem RC file, in the following order, and reads the first it finds:
+ "/opt/local/share/latexmk/LatexMk",
+ "/usr/local/share/latexmk/LatexMk",
+ "/usr/local/lib/latexmk/LatexMk".
+ On a MS-WINDOWS system it looks for "C:\latexmk\LatexMk".
+
+ 2) The user's RC file, "$HOME/.latexmkrc", if it exists. Here $HOME is
+ the value of the environment variable HOME. On UNIX and clones
+ (including LINUX), this variable is set by the system; on MS-Windows,
+ the user may choose to set it.
+
+ 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
+ found is used, if any.
+
+ 4) Any RC file(s) specified on the command line with the -r option.
+
+ Each RC file is a sequence of Perl commands. Naturally, a user can use
+ this in creative ways. But for most purposes, one simply uses a
+ sequence of assignment statements that override some of the built-in
+ settings of Latexmk. Straightforward cases can be handled without
+ knowledge of the Perl language by using the examples in this document
+ as templates. Comment lines are introduced by the "#" character.
+
+ Note that command line options are obeyed in the order in which they
+ are written; thus any RC file specified on the command line with the -r
+ option can override previous options but can be itself overridden by
+ later options on the command line. There is also the -e option, which
+ allows initialization code to be specified in latexmk's command line.
+
+
+HOW TO SET VARIABLES IN INITIALIZATION FILES
+ The important variables that can be configured are described in the
+ section "List of configuration variables usable in initialization
+ files". Syntax for setting these variables is of the following forms:
+
+ $bibtex = 'bibtex %O %B';
+
+ for the setting of a string variable,
+
+ $preview_mode = 1;
+
+ for the setting of a numeric variable, and
+
+ @default_files = ('paper', 'paper1');
+
+ for the setting of an array of strings. It is possible to append an
+ item to an array variable as follows:
+
+
+
+
+ 28 September 2008 9
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ push @default_files, 'paper2';
+
+ Note that simple "scalar" variables have names that begin with a $
+ character and array variables have names that begin with a @ character.
+ Each statement ends with a semicolon.
+
+ You can do much more complicated things, but for this you will need to
+ consult a manual for the Perl programming language.
+
+
+
+
+FORMAT OF COMMAND SPECIFICATIONS
+ Some of the variables set the commands that latexmk uses for carrying
+ out its work, for example to generate a dvi file from a tex file or to
+ view a postscript file. This section describes some important features
+ of how the commands are specified.
+
+ Placeholders: Supposed you wanted latexmk to use the command elatex in
+ place of the regular latex command, and suppose moreover that you
+ wanted to give it the option "--shell-escape". You could do this by
+ the following setting:
+
+ $latex = 'elatex --shell-escape %O %S';
+
+ The two items starting with the % character are placeholders. These
+ are substituted by appropriate values before the command is run. Thus
+ %S will be replaced by the source file that elatex will be applied to,
+ and %O will be replaced by any options that latexmk has decided to use
+ for this command. (E.g., if you used the -silent option it would
+ replace %O by "-interaction=batchmode".)
+
+ The available placeholders are:
+
+ %B base of filename for current command. E.g., if a postscript
+ file document.ps is being made from the dvi file document.dvi,
+ then the basename is document.
+
+ %D destination file (e.g., the name of the postscript file when
+ converting a dvi file to postscript).
+
+ %O options
+
+ %R root filename. This is the base name for the main tex file.
+
+ %S source file (e.g., the name of the dvi file when converting a
+ dvi file to ps).
+
+ %T The name of the primary tex file.
+
+ The distinction between %B and %R needs a bit of care, since they are
+ often the same, but not always. For example on a simple document, the
+ basename of a bibtex run is the same as for the texfile. But in a doc-
+ ument with several bibliographies, the bibliography files will have a
+ variety of names. Since bibtex is invoked with the basename of the
+
+
+
+ 28 September 2008 10
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ bibliography file, the setting for the bibtex command should therefore
+ be
+
+ $bibtex = 'bibtex %O %B';
+
+ Generally, you should use %B rather than %R. Similarly for most pur-
+ poses, the name %T of the primary texfile is not a useful placeholder.
+
+ See the default values in the section "List of configuration variables
+ usable in initialization files" for what is normally the most appropri-
+ ate usage.
+
+ If you omit to supply any placeholders whatever in the specification of
+ a command, latexmk will supply what its author thinks are appropriate
+ defaults. This gives compatibility with configuration files for previ-
+ ous versions of latexmk, which didn't use placeholders.
+
+ "Detaching" a command: Normally when latexmk runs a command, it waits
+ for the command to run to completion. This is appropriate for commands
+ like latex, of course. But for previewers, the command should normally
+ run detached, so that latexmk gets the previewer running and then
+ returns to its next task (or exits if there is nothing else to do). To
+ achieve this effect of detaching a command, you need to precede the
+ command name with "start ", as in
+
+ $dvi_previewer = 'start xdvi %O %S';
+
+ This will be translated to whatever is appropriate for your operating
+ system.
+
+ Notes: (1) In some circumstances, latex 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 pre-
+ cludes the possibility of running a command named start. (3) If the
+ word start occurs more than once at the beginning of the command
+ string, that is equivalent to having just one. (4) Under cygwin, some
+ complications happen, since cygwin amounts to a complicated merging of
+ UNIX and MS-Windows. See the source code for how I've handled the
+ problem.
+
+ Command names containing spaces: Under MS-Windows it is common that the
+ name of a command includes spaces, since software is often installed in
+ a subdirectory of "C:Program Files". Such command names should be
+ enclosed in double quotes, as in
+
+ $lpr_pdf = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p
+ %S';
+
+ Using MS-Windows file associations: A useful trick under modern ver-
+ sions of MS-Windows (e.g., WinXP) is to use just the command
+
+ $dvi_previewer = 'start %S';
+
+ Under recent versions of MS-Windows, this will cause to be run whatever
+ program the system has associated with dvi files. (The same applies
+
+
+
+ 28 September 2008 11
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ for a postscript viewer and a pdf viewer.)
+
+ Not using a certain command: If a command is not to be run, the command
+ name NONE is used, as in
+
+ $lpr = 'NONE lpr';
+
+ This typically is used when an appropriate command does not exist on
+ your system. The string after the "NONE" is effectively a comment.
+
+ Options to commands: Setting the name of a command can be used not only
+ for changing the name of the command called, but also to add options to
+ command. Suppose you want latexmk to use latex with source specials
+ enabled. Then you might use the following line in an initialization
+ file:
+
+ $latex = 'latex --src-specials %O %S';
+
+
+ Advanced tricks: Normally one specifies a single command for the com-
+ mands invoked by latexmk. Naturally, if there is some complicated
+ additional processing you need to do in your special situation, you can
+ write a script (or batch file) to do the processing, and then configure
+ latexmk to use your script in place of the standard program.
+
+ It is also possible to configure latexmk 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 perform some
+ extra processing, you could do something like:
+
+ $pdflatex = 'pdflatex --shell-escape %O %S; pst2pdf_for_latexmk
+ %B';
+
+ This definition assumes you are using a UNIX-like system, so that the
+ two commands to be run are separated by the semicolon in the middle of
+ the string.
+
+
+
+LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES
+ Default values are indicated in brackets.
+
+ $banner [0]
+ If nonzero, the banner message is printed across each page when
+ converting the dvi file to postscript. Without modifying the
+ variable $banner_message, this is equivalent to specifying the
+ -d option.
+
+ Note that if $banner is nonzero, the $postscript_mode is assumed
+ and the postscript file is always generated, even if it is newer
+ than the dvi file.
+
+ $banner_intensity [0.95]
+ Equivalent to the -bi option, this is a decimal number between 0
+ and 1 that specifies how dark to print the banner message. 0 is
+
+
+
+ 28 September 2008 12
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ black, 1 is white. The default is just right if your toner car-
+ tridge isn't running too low.
+
+ $banner_message ["DRAFT"]
+ The banner message to print across each page when converting the
+ dvi file to postscript. This is equivalent to the -bm option.
+
+ $banner_scale [220.0]
+ A decimal number that specifies how large the banner message
+ will be 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 just right for 5 character messages.
+ This is equivalent to the -bs option.
+
+ @BIBINPUTS
+ This is an array variable, now mostly obsolete, that specifies
+ directories where latexmk should look for .bib files. By
+ default it is set from the BIBINPUTS environment variable of the
+ operating system. If that environment variable is not set, a
+ single element list consisting of the current directory is set.
+ The format of the directory names depends on your operating sys-
+ tem, of course. Examples for setting this variable are:
+
+ @BIBINPUTS = ( ".", "C:\bibfiles" );
+ @BIBINPUTS = ( ".", "\\server\bibfiles" );
+ @BIBINPUTS = ( ".", "C:/bibfiles" );
+ @BIBINPUTS = ( ".", "//server/bibfiles" );
+ @BIBINPUTS = ( ".", "/usr/local/texmf/bibtex/bib" );
+
+ Note that under MS Windows, either a forward slash "/" or a
+ backward slash "\" can be used to separate pathname components,
+ so the first two and the second two examples are equivalent.
+ Each backward slash should be doubled to avoid running afoul of
+ Perl's rules for writing strings.
+
+ Important note: This variable is now mostly obsolete in the current
+ version of latexmk, since it has a better method of searching for files
+ using the kpsewhich command. However, if your system is an unusual one
+ without the kpsewhich command, you may need to set the variable @BIBIN-
+ PUTS.
+
+ $bibtex ["bibtex %O %S"]
+ The BibTeX processing program.
+
+ $bibtex_silent_switch ["-terse"]
+ Switch(es) for the BibTeX processing program when silent mode is
+ on.
+
+ $cleanup_mode [0]
+ If nonzero, specifies cleanup mode: 1 for full cleanup, 2 for
+ cleanup except for dvi, ps and pdf files, 3 for cleanup except
+ for dep and aux files. (There is also extra cleaning as speci-
+ fied by the $clean_ext, $clean_full_ext and @generated_exts
+ variables.)
+
+
+
+ 28 September 2008 13
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ This variable is equivalent to specifying one of the -c, -c1, or -C
+ options. But there should be no need to set this variable from an RC
+ file.
+
+ $clean_ext [""]
+ Extra extensions of files for latexmk to remove when any of the
+ clean-up options (-c, -c1, or -C) is selected. The value of
+ this variable is a string containing the extensions separated by
+ spaces.
+
+ $clean_full_ext [""]
+ Extra extensions of files for latexmk to remove when the -C
+ option is selected, i.e., extensions of files to remove when the
+ .dvi, etc files are to be cleaned-up.
+
+ @cus_dep_list [()]
+ Custom dependency list -- see section on "Custom Dependencies".
+
+ @default_files [("*.tex")]
+ Default list of files to be processed.
+
+ Normally, if no filenames are specified on the command line,
+ latexmk processes all tex files specified in the @default_files
+ variable, which by default is set to all tex files ("*.tex") in
+ the current directory. This is a convenience: just run latexmk
+ and it will process an appropriate set of files. But sometimes
+ you want only some of these files to be processed. In this case
+ you set the @default_files in an initialization file (e.g., the
+ file "latexmkrc" in the current directory). Then if no files
+ are specified on the command line then the files you specify by
+ setting @default_files are processed.
+
+ Three examples:
+
+ @default_files = ("paper_current");
+
+ @default_files = ("paper1", "paper2.tex");
+
+ @default_files = ("*.tex", "*.dtx");
+
+ Note that more than file may be given, and that the default
+ extension is ".tex". Wild cards are allowed. The parentheses
+ are because @default_files is an array variable, i.e., a
+ sequence of filename specifications is possible.
+
+ $dvi_filter [empty]
+ The dvi file filter to be run on the newly produced dvi file
+ before other processing. Equivalent to specifying the -dF
+ option.
+
+ $dvi_mode [0]
+ If nonzero, generate a dvi version of the document. Equivalent
+ to the -dvi option.
+
+ $dvi_previewer ["start xdvi %O %S" under UNIX]
+ The command to invoke a dvi-previewer. [Default is "start"
+ under MS-WINDOWS; under more recent versions of Windows, this
+
+
+
+ 28 September 2008 14
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ will cause to be run whatever command the system has associated
+ with .dvi files.]
+
+ $dvi_previewer_landscape ["start xdvi %O %S"]
+ The command to invoke a dvi-previewer in landscape mode.
+ [Default is "start" under MS-WINDOWS; under more recent versions
+ of Windows, this will cause to be run whatever command the sys-
+ tem has associated with .dvi files.]
+
+ $dvipdf ["dvipdf %O %S %D"]
+ Command to convert dvi to pdf file. A common reconfiguration is
+ to use the dvipdfm command, which needs its arguments in a dif-
+ ferent order:
+
+ $dvipdf = "dvipdfm %O -o %D %S";
+
+ 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.
+
+ $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 $dvips_pdf_switch -- see below -- will be included in the
+ options substituted for "%O".
+
+ $dvips_landscape ["dvips -tlandscape %O -o %D %S"]
+ The program to used as a filter to convert a .dvi file to a .ps
+ file in landscape mode.
+
+ $dvips_pdf_switch ["-P pdf"]
+ Switch(es) for dvips program when pdf file is to be generated
+ from ps file.
+
+ $dvips_silent_switch ["-q"]
+ Switch(es) for dvips program when silent mode is on.
+
+ $dvi_update_command [""]
+ When the dvi previewer is set to be updated by running a com-
+ mand, this is the command that is run. See the information for
+ the variable $dvi_update_method for further information, and see
+ information on the variable $pdf_update_method for an example
+ for the analogous case of a pdf previewer.
+
+ $dvi_update_method [2 under UNIX, 1 under MS-Windows]
+ How the dvi viewer updates its display when the dvi file has
+ changed. The values here apply equally to the
+ $pdf_update_method and to the $ps_update_method variables.
+ 0 => update is automatic,
+ 1=> manual update by user, which may only mean a mouse click
+ on the viewer's window or may mean a more serious action.
+ 2 => Send the signal, whose number is in the variable
+ $dvi_update_signal. The default value under UNIX is suitable
+ for xdvi.
+ 3 => Viewer cannot do an update, because it locks the file.
+ (As with acroread under MS-Windows.)
+
+
+
+ 28 September 2008 15
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ 4 => run a command to do the update. The command is speci-
+ fied by the variable $dvi_update_command.
+
+ See information on the variable $pdf_update_method for an exam-
+ ple of updating by command.
+
+ $dvi_update_signal [Under UNIX: SIGUSR1, which is a system-dependent
+ value]
+ The number of the signal that is sent to the dvi viewer when it
+ is updated by sending a signal -- see the information on the
+ variable $dvi_update_method. The default value is the one
+ appropriate for xdvi on a UNIX system.
+
+ $fdb_ext ["fdb_latexmk"]
+ The extension of the file which latexmk generates to contain a
+ database of information on source files. You will not normally
+ need to change this.
+
+ $force_mode [0]
+ If nonzero, continue processing past minor latex errors includ-
+ ing unrecognized cross references. Equivalent to specifying the
+ -f option.
+
+ @generated_exts [( aux , bbl , idx , ind , lof , lot , out , toc ,
+ $fdb_ext )]
+ This contains a list of extensions for files that are generated
+ during a LaTeX run and that are read in by LaTeX in later runs,
+ either directly or indirectly.
+
+ This list has two uses: (a) to set the kinds of file to be
+ deleted in a cleanup operation (with the -c, -C, -CA, -g and -gg
+ options), and (b) in the determination of whether a rerun of
+ (pdf)LaTeX is needed after a run that gives an error.
+
+ (Normally, a change of a source file during a run should provoke
+ a rerun. This includes a file generated by LaTeX, e.g., an aux
+ file, that is read in on subsequent runs. But after a run that
+ results in an error, a new run should occur until the user has
+ made a change in the files. But the user may have corrected an
+ error in a source .tex file during the run. So latexmk needs to
+ distinguish user-generated and automatically generated files; it
+ determines the automatically generated files as those with
+ extensions in the list in @generated_exts.)
+
+ A convenient way to add an extra extension to the list, without
+ losing the already defined ones is to use a push command in the
+ line in an RC file. E.g.,
+
+ push @generated_exts, "end";
+
+ adds the extension "end" to the list of predefined generated
+ extensions. (This extension is used by the RevTeX package, for
+ example.)
+
+ $go_mode [0]
+ If nonzero, process files regardless of timestamps, and is then
+ equivalent to the -g option.
+
+
+
+ 28 September 2008 16
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ %hash_calc_ignore_pattern
+ !!!This variable is for experts only!!!
+
+ The general rule latexmk uses for determining when an extra run
+ of some program is needed is that one of the source files has
+ changed. But consider for example a latex package that causes
+ an encapsulated postscript file (an "eps" file) to be made that
+ is to be read in on the next run. The file contains a comment
+ line giving its creation date and time. On the next run the
+ time changes, latex sees that the eps file has changed, and
+ therefore reruns latex. This causes an infinite loop, only
+ exited becaues latexmk has a limit on the number of runs to
+ guard against pathological situations.
+
+ But the changing line has no real effect, since it is a comment.
+ You can instruct latex to ignore the offending line as follows:
+
+ $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: ';
+
+ This creates a rule for files with extension .eps about lines to
+ ignore. The left-hand side is a Perl idiom for setting an item
+ in a hash. Note that the file extension is specified without a
+ period. The value, on the right-hand side, is a string contain-
+ ing a regular expresssion. (See documentation on Perl for how
+ they are to be specified in general.) This particular regular
+ expression specifies that lines beginning with "%%CreationDate:
+ " are to be ignored in deciding whether a file of the given
+ extension .eps has changed.
+
+ $kpsewhich ["kpsewhich %S"]
+ The program called to locate a source file when the name alone
+ is not sufficient. Most filenames used by latexmk have suffi-
+ cient path information to be found directly. But sometimes,
+ notably when the file, but not its path is known. The program
+ specified by $kpsewhich is used to find it.
+
+ See also the @BIBINPUTS variable for another way that latexmk
+ also uses to try to locate files; it applies only in the case of
+ .bib files.
+
+ $landscape_mode [0]
+ If nonzero, run in landscape mode, using the landscape mode pre-
+ viewers and dvi to postscript converters. Equivalent to the -l
+ option. Normally not needed with current previewers.
+
+ $latex ["latex %O %S"]
+ The LaTeX processing program. Note that as with other programs,
+ you can use this variable not just to change the name of the
+ program used, but also specify options to the program. E.g.,
+
+ $latex = "latex --src-specials";
+
+ $latex_silent_switch ["-interaction=batchmode"]
+ Switch(es) for the LaTeX processing program when silent mode is
+ on. Under MS-Windows, the default value is changed to "-inter-
+ action=batchmode -c-style-errors", as used by MikTeX and fpTeX.
+
+
+
+
+ 28 September 2008 17
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ $lpr ["lpr %O %S" under UNIX/LINUX, "NONE lpr" under MS-WINDOWS]
+ The command to print postscript files.
+
+ Under MS-Windows (unlike UNIX/LINUX), there is no standard pro-
+ gram for printing files. But there are ways you can do it. For
+ example, if you have gsview installed, you could use it with the
+ option "/p":
+
+ $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
+
+ If gsview is installed in a different directory, you will need
+ to make the appropriate change. Note the combination of single
+ and double quotes around the name. The single quotes specify
+ that this is a string to be assigned to the configuration vari-
+ able $lpr. The double quotes are part of the string passed to
+ the operating system to get the command obeyed; this is neces-
+ sary because one part of the command name ("Program Files") con-
+ tains a space which would otherwise be misinterpreted.
+
+ $lpr_dvi ["NONE lpr_dvi"]
+ The printing program to print dvi files.
+
+ $lpr_pdf ["NONE lpr_pdf"]
+ The printing program to print pdf files.
+
+ Under MS-Windows you could set this to use gsview, if it is
+ installed, e.g.,
+
+ $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p';
+
+ If gsview 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 mis-
+ interpreted.
+
+
+ $makeindex ["makeindex %O -o %D %S"]
+ The index processing program.
+
+ $max_repeat [5]
+ The maximum number of times latexmk will run latex/pdflatex
+ before deciding that there may be an infinite loop and that it
+ needs to bail out, rather than rerunning latex/pdflatex again to
+ resolve 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.)
+
+ $new_viewer_always [0]
+ This variable applies to latexmk only in continuous-preview
+ mode. If $new_viewer_always is 0, latexmk will check for a pre-
+ viously running previewer on the same file, and if one is run-
+ ning will not start a new one. If $new_viewer_always is non-
+ zero, this check will be skipped, and latexmk will behave as if
+ no viewer is running.
+
+
+
+ 28 September 2008 18
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ $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 pdfla-
+ tex. If equal to 2, generate a pdf version of the document from
+ the ps file, by using the command specified by the $ps2pdf vari-
+ able. If equal to 3, generate a pdf version of the document
+ from the dvi file, by using the command specified by the $dvipdf
+ variable.
+
+ Equivalent to the -pdf-, -pdf, -pdfdvi, -pdfps options.
+
+ $pdflatex ["pdflatex %O %S"]
+ The LaTeX processing program in the version that makes a pdf
+ file instead of a dvi file.
+
+ $pdflatex_silent_switch ["-interaction=batchmode"]
+ Switch(es) for the pdflatex program (specified in the variable
+ $pdflatex when silent mode is on. Under MS-Windows, the default
+ value is changed to "-interaction=batchmode -c-style-errors", as
+ used by MikTeX and fpTeX.
+
+ $pdf_previewer ["start acroread %O %S"]
+ The command to invoke a pdf-previewer. [Default is changed to
+ "start" on MS-WINDOWS; under more recent versions of Windows,
+ this will cause to be run whatever command the system has asso-
+ ciated with .pdf files.]
+
+ WARNING: Potential problem under MS-Windows: if acroread is used
+ as the pdf previewer, and it is actually viewing a pdf file, the
+ pdf file cannot be updated. Thus makes acroread a bad choice of
+ previewer if you use latexmk's previous-continuous mode (option
+ -pvc) under MS-windows. This problem does not occur if
+ ghostview, gv or gsview is used to view pdf files.
+
+ $pdf_update_command [""]
+ When the pdf previewer is set to be updated by running a com-
+ mand, this is the command that is run. See the information for
+ the variable $pdf_update_method.
+
+ $pdf_update_method [1 under UNIX, 3 under MS-Windows]
+ How the pdf viewer updates its display when the pdf file has
+ changed. See the information on the variable $dvi_update_method
+ for the codes. (Note that information needs be changed slightly
+ so that for the value 4, to run a command to do the update, the
+ command is specified by the variable $pdf_update_command, and
+ for the value 2, to specify update by signal, the signal is
+ specified by $pdf_update_signal.)
+
+ Note that acroread under MS-Windows (but not UNIX) locks the pdf
+ file, so the default value is then 3.
+
+ Arranging to use a command to get a previewer explicitly updated
+ requires three variables to be set. For example:
+
+ $pdf_previewer = "start xpdf -remote %R %O %S";
+ $pdf_update_method = 4;
+ $pdf_update_command = "xpdf -remote %R -reload";
+
+
+
+ 28 September 2008 19
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ 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 set-
+ ting sets the update command.
+
+
+ $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 updated by sending a signal -- see the information on the
+ variable $pdf_update_method. The default value is the one
+ appropriate for gv on a UNIX system.
+
+ $pid_position[1 under UNIX, -1 under MS-Windows]
+ The variable $pid_position is used to specify which word in
+ lines of the output from $pscmd corresponds to the process ID.
+ The first word in the line is numbered 0. The default value of
+ 1 (2nd word in line) is correct for Solaris 2.6 and Linux. Set-
+ ting the variable to -1 is used to indicate that $pscmd is not
+ to be used.
+
+ $postscript_mode [0]
+ If nonzero, generate a postscript version of the document.
+ Equivalent to the -ps option.
+
+ $preview_continuous_mode [0]
+ If nonzero, run a previewer to view the document, and continue
+ running latexmk to keep .dvi up-to-date. Equivalent to the -pvc
+ option. Which previewer is run depends on the other settings,
+ see the command line options -view=, and the variable $view.
+
+ $preview_mode [0]
+ If nonzero, run a previewer to preview the document. Equivalent
+ to the -pv option. Which previewer is run depends on the other
+ settings, see the command line options -view=, and the variable
+ $view.
+
+ $printout_mode [0]
+ If nonzero, print the document using lpr. Equivalent to the -p
+ option. This is recommended not to be set from an RC file, oth-
+ erwise you could waste lots of paper.
+
+ $print_type = ["ps"]
+ Type of file to printout: possibilities are "dvi", "none",
+ "pdf", or "ps".
+
+ $pscmd Command used to get all the processes currently run by the user.
+ The -pvc option uses the command specified by the variable
+ $pscmd to determine if there is an already running previewer,
+ and to find the process ID (needed if latexmk needs to signal
+ the previewer about file changes).
+
+ Each line of the output of this command is assumed to correspond
+ to one process. See the $pid_position variable for how the pro-
+ cess number is determined.
+
+
+
+
+ 28 September 2008 20
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ The default for pscmd is "NONE" under MS-Windows and cygwin
+ (i.e., the command is not used), "ps --width 200 -f -u
+ $ENV{USER}" under linux, "ps -ww -u $ENV{USER}" under darwin
+ (Macintosh OS-X), and "ps -f -u $ENV{USER}" under other operat-
+ ing systems (including other flavors of UNIX). In these speci-
+ fications "$ENV{USER}" is substituted by the username.
+
+ $ps2pdf ["ps2pdf %O %S %D"]
+ Command to convert ps to pdf file.
+
+ $ps_filter [empty]
+ The postscript file filter to be run on the newly produced
+ postscript file before other processing. Equivalent to specify-
+ ing the -pF option.
+
+ $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.)
+
+ Note that gv could be used with the -watch option updates its
+ display whenever the postscript file changes, whereas ghostview
+ does not. However, different versions of gv have slightly dif-
+ ferent ways of writing this option. You can configure this
+ variable apppropriately.
+
+ WARNING: Linux systems may have installed one (or more) versions
+ of gv under different names, e.g., ggv, kghostview, etc, but
+ perhaps not one called gv.
+
+ $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.
+
+ $ps_update_command [""]
+ When the postscript previewer is set to be updated by running a
+ command, this is the command that is run. See the information
+ for the variable $ps_update_method.
+
+ $ps_update_method [0 under UNIX, 1 under MS-Windows]
+ How the postscript viewer updates its display when the ps file
+ has changed. See the information on the variable
+ $dvi_update_method for the codes. (Note that information needs
+ be changed slightly so that for the value 4, to run a command to
+ do the update, the command is specified by the variable
+ $ps_update_command, and for the value 2, to specify update by
+ signal, the signal is specified by $ps_update_signal.)
+
+
+ $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 $ps_update_method. The
+ default value is the one appropriate for gv on a UNIX system.
+
+ $sleep_time [2]
+ The time to sleep (in seconds) between checking for source file
+ changes when running the -pvc option.
+
+
+
+ 28 September 2008 21
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ $texfile_search [""]
+ This is an obsolete variable, replaced by the @default_files
+ variable.
+
+ For backward compatibility, if you choose to set $tex-
+ file_search, it is a string of space-separated filenames, and
+ then latexmk replaces @default_files with the filenames in $tex-
+ file_search to which is added "*.tex".
+
+ $tmpdir [See below for default]
+ Directory to store temporary files that latexmk may generate
+ while running.
+
+ The default under MSWindows (including cygwin), is to set
+ $tmpdir to the value of the first of whichever of the system
+ environment variables TMPDIR or TEMP exists, otherwise to the
+ current directory. Under other operating systems (expected to
+ be UNIX/Linux, including OS-X), the default is the value of the
+ system environment variable TMPDIR if it exists, otherwise
+ "/tmp".
+
+ $view ["default"]
+ 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).
+
+
+CUSTOM DEPENDENCIES
+ 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 latexmk to convert a .fig file to .eps to be included
+ in the .tex file.
+
+ The old method of configuring latexmk was to directly manipulate the
+ @cus_dep_list 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
+
+ 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:
+
+ from extension:
+ The extension of the file we are converting from (e.g. "fig").
+ It is specified without a period.
+
+ to extension:
+ The extension of the file we are converting to (e.g. "eps"). It
+ is specified without a period.
+
+ must: If non-zero, the file from which we are converting must exist,
+ if it doesn't exist latexmk will give an error message and exit
+ unless the -f option is specified. If must is zero and the file
+
+
+
+ 28 September 2008 22
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ we are converting from doesn't exist, then no action is taken.
+
+ function:
+ The name of the subroutine that latexmk should call to perform
+ the 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 Perl. The func-
+ tion should return 0 if it was successful and a nonzero number
+ if it failed.
+
+ It is invoked whenever latexmk 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 latexmk 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 whenever
+ the destination file (the one with the to-extension) is out-of-date
+ with respect to the corresponding source file.
+
+ To make the new destination file, the Perl subroutine specified in the
+ rule is invoked, with an argument that is the base name of the files in
+ question. Simple cases just involve a subroutine invoking an external
+ program; this can be done by following the templates below, even by
+ those without knowledge of the Perl programming language. Of course,
+ experts could do something much more elaborate.
+
+ One other item in each custom-dependency rule labelled "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
+
+ add_cus_dep( 'fig', 'eps', 0, 'fig2eps' );
+ sub fig2eps {
+ system("fig2dev -Leps $_[0].fig $_[0].eps");
+ }
+
+ The first line adds a custom dependency that converts a file with
+ extension "fig", as created by the xfig program, to an encapsulated
+ postscript file, with extension "eps". The remaining lines define a
+ subroutine that carries out the conversion. If a rule for converting
+ "fig" to "eps" files already exists (e.g., from a previously read-in
+ initialization file), the latexmk will delete this rule before making
+ the new one.
+
+ Suppose latexmk is using this rule to convert a file "figure.fig" to
+ "figure.eps". Then it will invoke the fig2eps subroutine defined in
+ the above code with a single argument "figure", which is the basename
+ of each of the files (possibly with a path component). This argument
+ is referred to by Perl as $_[0]. In the example above, the subroutine
+ uses the Perl command system to invoke the program fig2dev. The double
+ quotes around the string are a Perl idiom that signify that each string
+ of the form of a variable name, $_[0] in this case, is to be substi-
+ tuted by its value.
+
+ If the return value of the subroutine is non-zero, then latexmk will
+ assume an error occurred during the execution of the subroutine. In
+ the above example, no explicit return value is given, and instead the
+ return value is the value returned by the last (and only) statement,
+
+
+
+ 28 September 2008 23
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ 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 fig2dev program to have quoted file-
+ names; it should therefore work with filenames containing spaces. How-
+ ever, 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.
+
+ 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");
+ }
+
+ 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
+
+ remove_cus_dep( 'fig', 'eps' );
+
+ If you have complicated sets of custom dependencies, you may want to
+ get a listing of the custom dependencies. This is done by using the
+ line
+
+ show_cus_dep();
+
+ in an initialization file.
+
+ Another example of a custom dependency overcomes a limitation of
+ latexmk concerning index files. The only index-file conversion built-
+ in to latexmk is from an ".idx" file written on one run of latex/pdfla-
+ tex 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. Latexmk 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{spe-
+ cial}{ndx}{nnd}{Special index}" you will need to convert files with the
+ extension .ndx to .nnd. The following lines in an initialization RC
+ file will cause this to happen:
+
+ add_cus_dep('ndx', 'nnd', 0, 'makendx2nnd');
+ sub makendx2nnd {
+ system("makeindex -o $_[0].nnd $_[0].ndx");
+
+
+
+ 28 September 2008 24
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ }
+
+ (You will need to modify this code if you use filenames with spaces in
+ them, to provide correct quoting of the filenames.)
+
+ Those of you with experience with Makefiles, will undoubtedly be con-
+ cerned that the .ndx file is written during a run of latex/pdflatex and
+ is always later than the .nnd last read in. Thus the .nnd appears to
+ be perpetually out-of-date. This situation, of circular dependencies,
+ is endemic to latex, and latexmk 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.
+
+ Of course if you choose to write random data to the .nnd (or and .aux
+ file, etc) that changes on each new run, then you will have a problem.
+ For real experts: See the %hash_cal_ignore_pattern if you have to deal
+ with such problems.
+
+ Glossaries can be dealt with similarly.
+
+
+OLD METHOD OF DEFINING CUSTOM DEPENDENCIES
+ In previous versions of latexmk, the only method of defining custom
+ dependencies was to directly manipulate the table of custom dependen-
+ cies. This is contained in the @cus_dep_list array. It is an array of
+ strings, and each string in the array has four items in it, each sepa-
+ rated by a space, the from-extension, the to-extension, the "must"
+ item, and the name of the subroutine for the custom dependency. These
+ were all defined above.
+
+ An example of the old method of defining custom dependencies is as fol-
+ lows. It is the code in an RC file to ensure automatic conversion of
+ .fig files to .eps files:
+
+ push @cus_dep_list, "fig eps 0 fig2eps";
+ sub fig2eps {
+ 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.
+
+
+SEE ALSO
+ latex(1), bibtex(1).
+
+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 around:
+ manually refresh (or reopen) display. Or use one of the other preview-
+ ers and update methods.
+
+ (The following isn't really a bug, but concerns features of preview-
+ ers.) Preview continuous mode only works perfectly with certain pre-
+ viewers: Xdvi on UNIX/LINUX works for dvi files. Gv on UNIX/LINUX
+
+
+
+ 28 September 2008 25
+
+
+
+
+
+LATEXMK(1L) LATEXMK(1L)
+
+
+ works for both postscript and pdf. Ghostview on UNIX/LINUX needs a
+ manual update (reopen); it views postscript and pdf. Gsview under MS-
+ Windows works for both postscript and pdf, but only reads the updated
+ file when its screen is refreshed. Acroread under UNIX/LINUX views
+ pdf, but the file needs to be closed and reopened to view an updated
+ version. Under MS-Windows, acroread locks its input file and so the
+ pdf file cannot be updated. (Remedy: configure latexmk to use gsview
+ instead.)
+
+THANKS TO
+ Authors of previous versions. Many users with their feedback, and
+ especially 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.)
+
+AUTHOR
+ Current version, by John Collins (username collins at node
+ phys.psu.edu). (Version 4.01).
+
+ It can be obtained from CTAN: <http://www.tug.org/tex-archive/sup-
+ port/latexmk/>, and from the author's website
+ <http://www.phys.psu.edu/~collins/software/latexmk/>.
+ Modifications and enhancements by Evan McLean (Version 2.0)
+ Original script called "go" by David J. Musliner (RCS Version 3.2)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 28 September 2008 26
+
+