diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/latexmk/latexmk.txt')
-rw-r--r-- | Master/texmf-dist/doc/support/latexmk/latexmk.txt | 1772 |
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 + + |