From 96a97518eb514799c5613b37c1fe9da018aab47b Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Fri, 4 Dec 2009 05:00:45 +0000 Subject: add man page of latexmk to texfm/doc/man/man1 and to the tlpsrc file git-svn-id: svn://tug.org/texlive/trunk@16294 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf/doc/man/man1/latexmk.1 | 1609 +++++++++++++++++++++++++++++++++++ 1 file changed, 1609 insertions(+) create mode 100644 Master/texmf/doc/man/man1/latexmk.1 (limited to 'Master/texmf/doc/man') diff --git a/Master/texmf/doc/man/man1/latexmk.1 b/Master/texmf/doc/man/man1/latexmk.1 new file mode 100644 index 00000000000..5ef13279d0e --- /dev/null +++ b/Master/texmf/doc/man/man1/latexmk.1 @@ -0,0 +1,1609 @@ +.TH LATEXMK 1L "24 November 2009" "" +.SH NAME +latexmk \- generate LaTeX document +.SH SYNOPSIS +.B latexmk [options] [file ...] +.SH DESCRIPTION +.I Latexmk +completely automates the process of compiling a LaTeX document. +Essentially, it is like a specialized relative of the general +\fImake\fR utility, but one which determines dependencies +automatically and has some other very useful features. In its basic +mode of operation \fIlatexmk\fR 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. +.PP +By default \fIlatexmk\fR will run the commands necessary to generate a +.dvi file. +.PP +\fILatexmk\fR 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. +.PP +\fILatexmk\fR determines which are the source files by examining the +log file. When \fIlatexmk\fR is run, it examines properties of the +source files, and if any have been changed since the last document +generation, \fIlatexmk\fR 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, +\fIlatexmk\fR will also run bibtex and/or makeindex. In addition, +\fIlatexmk\fR 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. +.PP +\fILatexmk\fR has two different previewing options. In the simple +\fB-pv\fR 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. +.PP +The second previewing option is the powerful \fB-pvc\fR option +(mnemonic: "preview continuously"). In this case, \fIlatexmk\fR runs +continuously, regularly monitoring all the source files to see if any +have changed. Every time a change is detected, \fIlatexmk\fR runs all +the programs necessary to generate a new version of the document. A +good previewer (like \fIgv\fR) will then automatically update its +display. Thus the user can simply edit a file and, when the changes +are written to disk, \fIlatexmk\fR completely 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. +.PP +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. +.PP +\fILatexmk\fR 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. +.PP +\fILatexmk\fR is highly configurable, both from the command line and +in configuration 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 \fIlatexmk\fR often works +without special configuration on MS-Windows, cygwin, Linux, OS-X, and +other UNIX systems (notably Solaris). +.PP +A very annoying complication handled very reliably by \fILatexmk\fR, +is that LaTeX is a multiple pass system. On each run, LaTeX reads in +information 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, \fIlatexmk\fR 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 \fIlatexmk\fR generates an extra file (with extension +\fR.fdb_latexmk\fR, by default) that contains the source file +information. + +.SH LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE +(All options can be introduced by single or double "-" characters, +e.g., "latexmk -help" or "latexmk --help".) +.TP +.B file +One or more files can be specified. If no files are specified, +\fIlatexmk\fR will, by default, run on all files in the current working directory +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 +.B -bm +A banner message to print diagonally across each page when converting +the dvi file to postscript. The message must be a single argument on +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 +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 +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 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 +\fIbibtex\fR except dvi, postscript and pdf. These files are a +combination of log files, aux files, latexmk's database file of source +file information, +and those with extensions +specified in the \fI@generated_exts\fR configuration variable. In addition, +files with extensions by the \fI$clean_ext\fR configuration variable are +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. +.TP +.B -C +Clean up (remove) all regeneratable files generated by \fIlatex\fR and +\fIbibtex\fR. This is the same as the \fB-c\fR option with the +addition of dvi, postscript and pdf files, and those with extensions +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. +.TP +.B -CA +Clean up (remove) absolutely all regeneratable files. It is now +equivalent to the \fB-C\fR option + +This cleanup is instead of a regular make. +See the \fB-gg\fR option if you want to do a cleanup then a +make. +.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 +page when converting the dvi file to postscript. Size and intensity +can be modified with the \fB-bs\fR and \fB-bi\fR options. The \fB-bm\fR +option will override this option as this is really just a short way of +specifying: + + latexmk -bm DRAFT + +Note that if the \fB-d\fR option is specified, the \fB-ps\fR option is +assumed. +.TP +.B -dF +Dvi file filtering. The argument to this option is a filter which will +generate a filtered dvi file with the extension ".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 +.TP +.B -diagnostics +Print detailed diagnostics during a run. This may help for debugging +problems or to understand \fI.latexmk\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 +Execute the specified initialization code before processing. The code +is \fIPerl\fR code of the same form as is used in \fIlatexmk\fR's +initialization files -- for more details, see the information on the +\fB-r\fR option, and the section about "Configuration/initialization +(RC) files". The code is typically a sequence of assignment +statements separated by semicolons. + +The code is executed when the \fB-e\fR option is encountered during +\fIlatexmk\fR's parsing of its command line. See the \fB-r\fR option +for a way of executing initialization code from a file. 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. + +Some care is needed to deal with proper quoting of special characters +in the code on the command line. For example, suppose you want +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 single quotes block normal UNIX/LINUX command shells +from treating the characters inside the quotes as special. +(In this example, the q/.../ construct is a +\fIPerl\fR idiom equivalent to using +single quotes. This avoids the complications of getting a quote +character inside an already quoted string in a way that is independent +of both the shell and the operating-system.) + +The above command line will NOT work under MS-Windows with cmd.exe or +command.com or 4nt.exe. For MS-Windows with these command shells you +could use + + latexmk -e "$latex=q/latex %O -shell-escape %S/" file.tex + +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. +Normally, when \fIlatexmk\fR detects that LaTeX or another program has +found an error which will not be resolved by further processing, no +further processing is carried out. +.TP +.B -f- +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 +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-CA\fR had been given, and then do a regular make. +.TP +.B -h, -help +Print help information. +.TP +.B -l +Run in landscape mode, using the landscape mode for the previewers and +the dvi to postscript converters. This option is not normally needed +nowadays, since current previewers normally determine this information +automatically. +.TP +.B -l- +Turn off \fB-l\fR. +.TP +.B -new-viewer +When in continuous-preview mode, always start a new viewer to view the +generated file. By default, \fIlatexmk\fR will, in continuous-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. +.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 -p +Print out the document. By default it is +the generated postscript file that is printed. But you can use the +\fB-print=...\fR option to print the dvi or pdf files instead, and you +can configure this in a start up file (by setting the +\fI$print_type\fR variable). + +However, printing is enabled by default only under UNIX/LINUX systems, +where the default is to use the lpr command. In general, 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 configured the print commands used by +\fIlatexmk\fR. This can be non-trivial. See the documentation on the +\fI$lpr\fR, \fI$lpr_dvi\fR, and \fI$lpr_pdf\fR configuration variables +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 +.B -pdf +Generate pdf version of document using pdflatex. +.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 -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. +.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 +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. +.TP +.B -pv +Run file previewer. If the \fB-view\fR option is used, this will select +the kind of file to be previewed (dvi, ps or pdf). +Otherwise the viewer views the "highest" kind of file selected, by the +\fB-dvi\fR, \fB-ps\fR, \fB-pdf\fR, \fB-pdfps\fR options, in the +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 +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 \fB-pv\fR +option. +The preview-continuous option \fB-pvc\fR 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 +\fB-p\fR and \fB-pv\fR options, so it turns these options off + +With a good previewer the display will be automatically updated. +(Under \fIsome but not all\fR 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 \fB-view=dvi\fR and +\fB-view=ps\fR options. + +There are some other methods for arranging an update, notably useful +for many versions of xdvi and xpdf. These are best set in +\fIlatexmk\fR's configuration; see below. + +Note that if \fIlatexmk\fR dies or is stopped by the user, the +"forked" previewer will continue to run. Successive invocations with +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 +Read the specified initialization file ("RC file") before processing. + +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 \fB-r\fR option, it is read during this second step. +Thus an initialization file specified with the \fB-r\fR option can +override both the standard initialization files and \fIpreviously\fR +specified options. But all of these can be overridden by \fIlater\fR +options. + +The contents of the RC file just comprise a piece of code in the +\fIPerl\fR programming language +(typically a sequence of assignment statements); they are executed +when the \fB-r\fR option is encountered during \fIlatexmk\fR's parsing +of its command line. See the \fB-e\fR option for a way of giving +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 -silent +Run commands silently, i.e., with options that reduce the amount of +diagnostics generated. For example, with the default settings for +commands under UNIX, the command "latex -interaction=batchmode" is used +for latex. + +Also reduce the number of informational messages that \fIlatexmk\fR +generates. +.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 +Set the kind of file used when previewing is requested (e.g., by the +\fB-pv\fR or \fB-pvc\fR switches). The default is to view the "highest" +kind of requested file (in the order dvi, ps, pdf). +.PP +The preview-continuous option \fB-pvc\fR can only work with one file. +So in this case you will normally only specify one filename on +the command line. +.PP +Options \fB-p\fR, \fB-pv\fR and \fB-pvc\fR are mutually exclusive. So +each of these options turns the others off. + +.SH EXAMPLES +.nf +.ta 2i +% \fBlatexmk thesis\fR \fI# run latex enough times to resolve + cross-references\fR + +% \fBlatexmk -pvc -ps thesis\fR \fI# 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. + +% \fBlatexmk -c\fR \fI# remove .aux, .log, .bbl, .blg, .dvi, + .pdf, .ps & .bbl files\fR + + +.SH CONFIGURATION/INITIALIZATION (RC) FILES +.PP +\fILatexmk\fR can be customized using initialization files, which are +read at startup in the following order: +.PP +1) The system RC file, if it exists. + On a UNIX system, \fIlatexmk\fR searches for following places for its +system 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". +.PP +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. +.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 +found is used, if any. +.PP +4) Any RC file(s) specified on the command line with the \fB-r\fR option. +.PP +Each RC file is a sequence of \fIPerl\fR 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 \fILatexmk\fR. Straightforward cases can be handled +without knowledge of the \fIPerl\fR 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 \fB-r\fR option can override previous options but can be itself +overridden by later options on the command line. There is also the +\fB-e\fR option, which allows initialization code to be specified in +\fIlatexmk\fR's command line. + +.SH HOW TO SET VARIABLES IN INITIALIZATION FILES +.PP +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: +.PP + $bibtex = 'bibtex %O %B'; +.PP +for the setting of a string variable, +.PP + $preview_mode = 1; +.PP +for the setting of a numeric variable, and +.PP + @default_files = ('paper', 'paper1'); +.PP +for the setting of an array of strings. It is possible to append an +item to an array variable as follows: + + 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. + +Strings should be enclosed in single quotes. (You could use double +quotes, as in many programming languages. But then the \fIPerl\fR +programming language brings into play some special rules for +interpolating variables into strings. People not fluent in \fIPerl\fR +will want to avoid these complications.) + +You can do much more complicated things, but for this you will need to +consult a manual for the \fIPerl\fR programming language. + + + +.SH FORMAT OF COMMAND SPECIFICATIONS + +Some of the variables set the commands that \fIlatexmk\fR 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. + +\fBPlaceholders\fR: Supposed you wanted \fIlatexmk\fR 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: +.PP + $latex = 'elatex --shell-escape %O %S'; +.PP +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 \fIlatexmk\fR 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: +.TP +.B %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. +.TP +.B %D +destination file (e.g., the name of the postscript file when +converting a dvi file to postscript). +.TP +.B %O +options +.TP +.B %R +root filename. This is the base name for the main tex file. +.TP +.B %S +source file (e.g., the name of the dvi file when converting a dvi file +to ps). +.TP +.B %T +The name of the primary tex file. +.PP +If for some reason you need a literal % character in your string not +subject to the above rules, use a pair of these characters. Thus with +the command specification $ps_previewer = 'latex -ad=%%Sfile.ad %S', +the %%S will become %S when the command is executed, but the %S will +be replaced by the source filename, which in this case would be the +name of a postscript file to be viewed. +.PP +Appropriate quoting will be applied to the filename substitutions, so +you mustn't supply them yourself even if you the names of your have +spaces in them. (But if your TeX filenames have spaces in them, +beware that many versions of the TeX program cannot correctly handle +filenames containing spaces.) In case latexmk's quoting does not work +correctly on your system, you can turn it off -- see the documentation +for the variable \fI$quote_filenames\fR. +.PP +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 +document with several bibliographies, the bibliography files will have +a variety of names. Since bibtex is invoked with the basename of the +bibliography file, the setting for the bibtex command should therefore +be +.PP + $bibtex = 'bibtex %O %B'; +.PP +Generally, you should use %B rather than %R. Similarly for most +purposes, 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 +appropriate usage. + +If you omit to supply any placeholders whatever in the specification +of a command, \fIlatexmk\fR will supply what its author thinks are +appropriate defaults. This gives compatibility with configuration +files for previous versions of \fIlatexmk\fR, which didn't use +placeholders. + +\fB"Detaching" a command\fR: Normally when \fIlatexmk\fR 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 \fIlatexmk\fR 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 +.PP + $dvi_previewer = 'start xdvi %O %S'; +.PP +This will be translated to whatever is appropriate for your operating +system. + +Notes: (1) In some circumstances, \fIlatex\fR will always run a +command detached. This is the case for a previewer in preview +continuous mode, since otherwise previewing continuously makes no +sense. (2) This precludes the possibility of running a command named +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. + +\fBCommand names containing spaces\fR: 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 +.PP + $lpr_pdf = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p %S'; +.PP +\fBUsing MS-Windows file associations\fR: A useful trick under modern +versions of MS-Windows (e.g., WinXP) is to use just the command +'start' by itself: +.PP + $dvi_previewer = 'start %S'; +.PP +Under recent versions of MS-Windows, this will cause to be run +whatever program the system has associated with dvi files. (The same +applies for a postscript viewer and a pdf viewer.) + +\fBNot using a certain command\fR: If a command is not to be run, the +command name NONE is used, as in +.PP + $lpr = 'NONE lpr'; +.PP +This typically is used when an appropriate command does not exist on +your system. The string after the "NONE" is effectively a comment. + +\fBOptions to commands\fR: +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 \fIlatexmk\fR to use latex with source specials +enabled. Then you might use the following line in an initialization +file: +.PP + $latex = 'latex --src-specials %O %S'; +.PP + +\fBAdvanced tricks\fR: Normally one specifies a single command for the +commands invoked by \fIlatexmk\fR. 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 \fIlatexmk\fR to use your script in +place of the standard program. + +It is also possible to configure \fIlatexmk\fR to run multiple +commands. For example, if when running pdflatex to generate a pdf +file from a tex file you need to run another program after pdflatex to +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. + + +.SH LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES +.PP +Default values are indicated in brackets. +.TP +.B $banner [0] +If nonzero, the banner message is printed across each page when +converting the dvi file to postscript. Without modifying the variable +\fI$banner_message\fR, this is equivalent to specifying the \fB-d\fR +option. + +Note that if \fB$banner\fR is nonzero, the \fB$postscript_mode\fR is +assumed and the postscript file is always generated, even if it is newer +than the dvi file. +.TP +.B $banner_intensity [0.95] +Equivalent to the \fB-bi\fR option, this is a decimal number between 0 +and 1 that specifies how dark to print the banner message. 0 is black, +1 is white. The default is just right if your toner cartridge isn't +running too low. +.TP +.B $banner_message ["DRAFT"] +The banner message to print across each page when converting the dvi +file to postscript. This is equivalent to the \fB-bm\fR option. +.TP +.B $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 +\fB-bs\fR option. +.TP +.B @BIBINPUTS +This is an array variable, now mostly obsolete, that specifies +directories where +\fIlatexmk\fR 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 system, 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 "\(rs" 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 \fIPerl\fR's rules for writing +strings. +.PP +\fIImportant note:\fR This variable is now mostly obsolete in the +current version of \fIlatexmk\fR, +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 \fI@BIBINPUTS\fR. +.TP +.B $bibtex ["bibtex %O %S"] +The BibTeX processing program. +.TP +.B $bibtex_silent_switch ["-terse"] +\fBSwitch(es)\fR for the BibTeX processing program when silent mode is on. +.TP +.B $cleanup_includes_generated [0] +If nonzero, specifies that cleanup also deletes files that are +detected in log file as being generated (see the \\openout lines in +the log file). It will also include files made from these first +generation generated files. +.TP +.B $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 specified by the +\fI$clean_ext\fR, \fI$clean_full_ext\fR and \fI@generated_exts\fR +variables.) +.PP +This variable is equivalent to specifying one of +the \fB-c\fR, \fB-c1\fR, or \fB-C\fR options. But there should be no need +to set this variable from an RC file. +.TP +.B $clean_ext [""] +Extra extensions of files for \fIlatexmk\fR to remove when any of the +clean-up options (\fB-c\fR, \fB-c1\fR, or \fB-C\fR) is selected. +The value of this variable is a string containing the extensions +separated by spaces. +.TP +.B $clean_full_ext [""] +Extra extensions of files for \fIlatexmk\fR to remove when the \fB-C\fR +option is selected, i.e., extensions of files to remove when the .dvi, +etc files are to be cleaned-up. +.TP +.B @cus_dep_list [()] +Custom dependency list -- see section on "Custom Dependencies". +.TP +.B @default_files [("*.tex")] +Default list of files to be processed. + +Normally, if no filenames are specified on the command line, +\fIlatexmk\fR processes all tex files specified in the \fI@default_files\fR +variable, which by default is set to all tex files ("*.tex") in the +current directory. This is a convenience: just run \fIlatexmk\fR 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 +\fI@default_files\fR 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 \fI@default_files\fR 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 +\fI@default_files\fR is an array variable, i.e., a sequence of +filename specifications is possible. +.TP +.B $dvi_filter [empty] +The dvi file filter to be run on the newly produced dvi file before +other processing. Equivalent to specifying the \fB-dF\fR option. +.TP +.B $dvi_mode [See below for default] +If nonzero, generate a dvi version of the document. +Equivalent to the \fB-dvi\fR option. +.PP +The variable $dvi_mode defaults to 0, but if no explicit requests are +made for other types of file (postscript, pdf), then $dvi_mode will be +set to 1. In addition, if a request for a file for which a .dvi file +is a prerequisite, then $dvi_mode will be set to 1. +.TP +.B $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 will cause to be run whatever command the system has +associated with .dvi files.] +.TP +.B $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 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 +use the dvipdfm command, which needs its arguments in a different 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. +.TP +.B $dvips ["dvips %O -o %D %S"] +The program to used as a filter to convert a .dvi file to a .ps file. +If pdf is going to be generated from pdf, then the value of the +$dvips_pdf_switch -- see below -- will be included in the options +substituted for "%O". +.TP +.B $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. +.TP +.B $dvips_pdf_switch ["-P pdf"] +Switch(es) for dvips program when pdf file is to be generated from +ps file. +.TP +.B $dvips_silent_switch ["-q"] +Switch(es) for dvips program when silent mode is on. +.TP +.B $dvi_update_command [""] +When the dvi previewer is set to be updated by running a command, this +is the command that is run. See the information for the variable +\fI$dvi_update_method\fR for further information, and see information +on the variable \fI$pdf_update_method\fR for an example for the +analogous case of a pdf previewer. +.TP +.B $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 \fI$pdf_update_method\fR and to +the \fI$ps_update_method\fR 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 +\fI$dvi_update_signal\fR. 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.) + 4 => run a command to do the update. The command is specified by +the variable \fI$dvi_update_command\fR. + +See information on the variable \fI$pdf_update_method\fR for an +example of updating by command. +.TP +.B $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 +\fI$dvi_update_method\fR. The default value is the one appropriate +for xdvi on a UNIX system. +.TP +.B $fdb_ext ["fdb_latexmk"] +The extension of the file which \fIlatexmk\fR generates to contain a +database of information on source files. You will not normally need +to change this. +.TP +.B $force_mode [0] +If nonzero, continue processing past minor \fIlatex\fR errors +including unrecognized cross references. Equivalent to specifying the +\fB-f\fR option. +.TP +.B @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 \fB-c\fR, \fB-C\fR, \fB-CA\fR, \fB-g\fR +and \fB-gg\fR 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 \fIlatexmk\fR 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.) +.TP +.B $go_mode [0] +If nonzero, process files regardless of timestamps, and is then +equivalent to the \fB-g\fR option. +.TP +.B %hash_calc_ignore_pattern +\fB!!!This variable is for experts only!!!\fR + +The general rule \fIlatexmk\fR 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, \fIlatex\fR sees +that the eps file has changed, and therefore reruns latex. This +causes an infinite loop, only exited becaues \fIlatexmk\fR 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 \fIlatex\fR to ignore the offending line as follows: + + $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: '; + +This creates a rule for files with extension \fI.eps\fR about lines to +ignore. The left-hand side is a \fIPerl\fR 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 containing a +regular expresssion. (See documentation on \fIPerl\fR 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 \fI.eps\fR +has changed. +.TP +.B $kpsewhich ["kpsewhich %S"] +The program called to locate a source file when the name alone is not +sufficient. Most filenames used by \fIlatexmk\fR have sufficient path +information to be found directly. But sometimes, notably when +.bib files are found from the log file of a bibtex run, the name of +the file, but not its path is known. The program specified by +$kpsewhich is used to find it. + +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 $landscape_mode [0] +If nonzero, run in landscape mode, using the landscape mode previewers and +dvi to postscript converters. Equivalent to the \fB-l\fR option. +Normally not needed with current previewers. +.TP +.B $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"; +.TP +.B %latex_input_extensions +This variable specifies the extensions tried by latexmk when it finds +that a LaTeX run resulted in an error that a file has not been found, +and the file is given without an extension. This typically happens when +LaTeX commands of the form \input{file} or \includegraphics{figure}, +when the relevant source file does not exist. + +In this situation, latexmk searches for custom dependencies to make +the missing file(s), but restricts it to the extensions specified by +the variable %latex_input_extensions. The default extensions are +'tex' and 'eps'. + +(For Perl experts: %latex_input_extensions is a hash whose keys are +the extensions. The values are irrelevant.) Two subroutines are +provided for manipulating this and the related variable +%pdflatex_input_extensions, add_input_ext and remove_input_ext. They +are used as in the following examples are possible lines in an +initialization file: + + remove_input_ext( 'latex', 'tex' ); + +removes the extension 'tex' from latex_input_extensions + + add_input_ext( 'latex', 'asdf' ); + +add the extension 'asdf to latex_input_extensions. (Naturally with +such an extension, you should have made an appropriate custom +dependency for latexmk, 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. +Under MS-Windows, the default value is changed to +"-interaction=batchmode -c-style-errors", as used by MikTeX and fpTeX. +.TP +.B $lpr ["lpr %O %S" under UNIX/LINUX, \(dqNONE lpr\(dq under MS-WINDOWS] +The command to print postscript files. + +Under MS-Windows (unlike UNIX/LINUX), there is no standard program 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 variable \fI$lpr\fR. The double +quotes are part of the string passed to the operating system to get +the command obeyed; this is necessary because one part of the command +name ("Program Files") contains a space which would otherwise be +misinterpreted. +.TP +.B $lpr_dvi ["NONE lpr_dvi"] +The printing program to print dvi files. +.TP +.B $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 misinterpreted. + +.TP +.B $makeindex ["makeindex %O -o %D %S"] +The index processing program. +.TP +.B $max_repeat [5] +The maximum number of times \fIlatexmk\fR will run latex/pdflatex +before deciding that there may be an infinite loop and that it needs +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.) +.TP +.B $new_viewer_always [0] +This variable applies to \fIlatexmk\fR \fBonly\fR in +continuous-preview mode. If \fI$new_viewer_always\fR is 0, +\fIlatexmk\fR will check for a previously running previewer on the +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 $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 pdflatex. +If equal to 2, generate a pdf version of the document from the ps +file, by using the command specified by the \fI$ps2pdf\fR variable. +If equal to 3, generate a pdf version of the document from the dvi +file, by using the command specified by the \fI$dvipdf\fR variable. + +Equivalent to the \fB-pdf-\fR, \fB-pdf\fR, \fB-pdfdvi\fR, +\fB-pdfps\fR options. +.TP +.B $pdflatex ["pdflatex %O %S"] +The LaTeX processing program in the version that makes a pdf file instead +of a dvi file. +.TP +.B %pdflatex_input_extensions +This variable specifies the extensions tried by latexmk when it finds +that a pdfLaTeX run resulted in an error that a file has not been found, +and the file is given without an extension. This typically happens when +LaTeX commands of the form \input{file} or \includegraphics{figure}, +when the relevant source file does not exist. + +In this situation, latexmk searches for custom dependencies to make +the missing file(s), but restricts it to the extensions specified by +the variable %pdflatex_input_extensions. The default extensions are +'tex', 'pdf', 'jpg, and 'png'. + +(For Perl experts: %pdflatex_input_extensions is a hash whose keys are +the extensions. The values are irrelevant.) Two subroutines are +provided for manipulating this and the related variable +%latex_input_extensions, add_input_ext and remove_input_ext. They +are used as in the following examples are possible lines in an +initialization file: + + remove_input_ext( 'pdflatex', 'tex' ); + +removes the extension 'tex' from pdflatex_input_extensions + + add_input_ext( 'pdflatex', 'asdf' ); + +add the extension 'asdf to pdflatex_input_extensions. (Naturally with +such an extension, you should have made an appropriate custom +dependency for latexmk, 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 pdflatex and its graphics/graphicx +packages.) + +.TP +.B $pdflatex_silent_switch ["-interaction=batchmode"] +Switch(es) for the pdflatex program (specified in the variable +\fI$pdflatex\fR 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. +.TP +.B $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 +associated with .pdf files.] + +\fBWARNING\fR: 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 \fIlatexmk\fR's +previous-continuous mode (option \fB-pvc\fR) under MS-windows. +This problem does not occur if ghostview, gv or gsview is used to +view pdf files. +.TP +.B $pdf_update_command [""] +When the pdf previewer is set to be updated by running a command, this +is the command that is run. See the information for the variable +\fI$pdf_update_method\fR. +.TP +.B $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 \fI$dvi_update_method\fR +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 \fI$pdf_update_command\fR, and for the +value 2, to specify update by signal, the signal is specified by +\fI$pdf_update_signal\fR.) + +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"; + +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 +updated by sending a signal -- see the information on the variable +\fI$pdf_update_method\fR. The default value is the one appropriate +for gv on a UNIX system. +.TP +.B $pid_position[1 under UNIX, -1 under MS-Windows] +The variable \fI$pid_position\fR is used to +specify which word in lines of the output from \fI$pscmd\fR +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. Setting the variable to -1 is used to indicate that +\fI$pscmd\fR is not to be used. +.TP +.B $postscript_mode [0] +If nonzero, generate a postscript version of the document. +Equivalent to the \fB-ps\fR option. +.PP +If some other request is made for which a postscript file is needed, +then $postscript_mode will be set to 1. +.TP +.B $preview_continuous_mode [0] +If nonzero, run a previewer to view the document, and +continue running \fIlatexmk\fR to keep .dvi up-to-date. Equivalent to +the \fB-pvc\fR option. +Which previewer is run depends on the other settings, see the command +line options \fB-view=\fR, and the variable \fI$view\fR. +.TP +.B $preview_mode [0] +If nonzero, run a previewer to preview the document. +Equivalent to the \fB-pv\fR option. +Which previewer is run depends on the other settings, see the command +line options \fB-view=\fR, and the variable \fI$view\fR. +.TP +.B $printout_mode [0] +If nonzero, print the document using \fIlpr\fR. Equivalent to the +\fB-p\fR option. This is recommended \fBnot\fR to be set from an RC +file, otherwise you could waste lots of paper. +.TP +.B $print_type = ["ps"] +Type of file to printout: possibilities are "dvi", "none", "pdf", or "ps". +.TP +.B $pscmd +Command used to get all the processes currently run by the user. The +-pvc option uses the command specified by the variable \fI$pscmd\fR to +determine if there is an already running previewer, and to find the +process ID (needed if \fIlatexmk\fR 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 \fI$pid_position\fR variable for how the process +number is determined. + +The default for \fIpscmd\fR 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 operating systems (including other +flavors of UNIX). In these specifications "$ENV{USER}" is substituted +by the username. +.TP +.B $ps2pdf ["ps2pdf %O %S %D"] +Command to convert ps to pdf file. +.TP +.B $ps_filter [empty] +The postscript file filter to be run on the newly produced postscript +file before other processing. Equivalent to specifying the \fB-pF\fR +option. +.TP +.B $ps_previewer ["start gv %O %S", but \(dqstart %O %S" under MS-WINDOWS] +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 different ways of +writing this option. You can configure this variable apppropriately. + +\fBWARNING\fR: 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. +.TP +.B $ps_previewer_landscape ["start gv -swap %O %S", but \(dqstart %O %S" under MS-WINDOWS] +The command to invoke a ps-previewer in landscape mode. +.TP +.B $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 +\fI$ps_update_method\fR. +.TP +.B $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 \fI$dvi_update_method\fR +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 \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 $quote_filenames [1] +This specifies whether substitutions for placeholders in command +specifications (as in \fI$pdflatex\fR) are surrounded by double +quotes. If this variable is 1 (or any other value Perl regards as +true), then quoting is done. Otherwise quoting is omitted. +.PP +The quoting method used by latexmk is tested to work correctly under +UNIX systems (including Linux and Mac OS-X) and under MS-Windows. It +allows the use of filenames containing special characters, notably +spaces. (But note that many versions of LaTeX and PdfLaTeX cannot +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 $sleep_time [2] +The time to sleep (in seconds) between checking for source file +changes when running the \fB-pvc\fR option. +.TP +.B $texfile_search [""] +This is an obsolete variable, replaced by the \fI@default_files\fR +variable. + +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 $tmpdir [See below for default] +Directory to store temporary files that \fIlatexmk\fR may generate while +running. + +The default under MSWindows (including cygwin), is to set +\fI$tmpdir\fR 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". +.TP +.B $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). + +.SH CUSTOM DEPENDENCIES +.PP +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. + +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 + + 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: +.TP +.B from extension: +The extension of the file we are converting from (e.g. "fig"). +It is specified without a period. +.TP +.B to extension: +The extension of the file we are converting to (e.g. "eps"). +It is specified without a period. +.TP +.B must: +If non-zero, the file from which we are converting \fBmust\fR exist, if it +doesn't exist \fIlatexmk\fR will give an error message and exit unless +the \fB-f\fR option is specified. If \fImust\fR is zero and the file +we are converting from doesn't exist, then no action is taken. +.TP +.B function: +The name of the subroutine that \fIlatexmk\fR 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 \fIPerl\fR. The function should return 0 if +it was successful and a nonzero number if it failed. +.PP +It 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 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 \fIPerl\fR 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 \fIPerl\fR 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 \fIlatexmk\fR will delete this rule before +making the new one. + +Suppose \fIlatexmk\fR 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 \fIPerl\fR as $_[0]. In +the example above, the subroutine uses the \fIPerl\fR command system +to invoke the program fig2dev. The double quotes around the string +are a \fIPerl\fR idiom that signify that each string of the form of a +variable name, $_[0] in this case, is to be substituted by its value. + +If the return value of the subroutine is non-zero, then \fIlatexmk\fR +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, i.e., the invocation of system, which returns the value 0 +on success. + +If you use filenames with spaces in them, and if your LaTeX system and +all other relevant software correctly handle such filenames, then you +could put single quotes around filenames in the command line that is +executed: + + add_cus_dep( 'fig', 'eps', 0, 'fig2eps' ); + sub fig2eps { + system("fig2dev -Lps '$_[0].fig' '$_[0].eps'"); + } + +This causes the invocation of the \fIfig2dev\fR program to have quoted +filenames; it should therefore work with filenames containing spaces. +\fBHowever, not all software deals correctly with filenames that +contain spaces. Moreover, the rules, if any, for quoting filenames +vary between operating systems, command shells and individual pieces +of software, so this code may not always work.\fR + +If you use pdflatex instead of latex, then you will probably prefer to +convert your graphics files to pdf format, in which case you would +replace the above code in an initialization file by + + add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' ); + sub fig2pdf { + system("fig2dev -Lpdf $_[0].fig $_[0].pdf"); + } + +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 +\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 { + system("makeindex -o $_[0].nnd $_[0].ndx"); + } + +(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 +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. + +Of course if you choose to write random data to the \fI.nnd\fR (or and +\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 +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 +it, each separated 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. +.PP +An example of the old method of defining custom dependencies is as +follows. It is the code in an RC file to ensure automatic conversion +of \fI.fig\fR files to \fI.eps\fR files: + + push @cus_dep_list, "fig eps 0 fig2eps"; + sub fig2eps { + system("fig2dev -Lps $_[0].fig $_[0].eps"); + } + +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. + +.SH SEE ALSO +latex(1), bibtex(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 +around: manually refresh (or reopen) display. Or use one of the other +previewers and update methods. + +(The following isn't really a bug, but concerns features of previewers.) +Preview continuous mode only works perfectly with certain previewers: +Xdvi on UNIX/LINUX works for dvi files. +Gv on UNIX/LINUX 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 \fIlatexmk\fR to use gsview +instead.) +.SH 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.) +.SH AUTHOR +Current version, by John Collins (username collins at node phys.psu.edu). +(Version 4.11). + +Released version can be obtained from CTAN: +, and from the +author's website . +.br +Modifications and enhancements by Evan McLean (Version 2.0) +.br +Original script called "go" by David J. Musliner (RCS Version 3.2) + +\" LocalWords: fR fIlatexmk dvi ps fILatexmk pdflatex bibtex makeindex fB pv +\" LocalWords: pvc fIgv xdvi gsview cygwin fdb TP tex bm bs fIlatex fIbibtex +\" LocalWords: gg regeneratable dep exts dF dviF dviselect fI fR's lpr pdfps +\" LocalWords: pdfdvi dvipdf pF psF psnup fIsome gv acroread xpdf rcfile cus +\" LocalWords: batchmode latexmkrc elatex basename texfile WinXP BIBINPUTS +\" LocalWords: kpsewhich BibTeX dtx dvipdfm dvips fpTeX MikTeX fBWARNING pid +\" LocalWords: pscmd fIlpr fBnot ENV OSX SIGHUP tmpdir MSWindows tmp eps dev +\" LocalWords: fImust fIperl Lps fIfig -- cgit v1.2.3