diff options
| author | Karl Berry <karl@freefriends.org> | 2011-03-22 23:35:00 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2011-03-22 23:35:00 +0000 |
| commit | 95b6c856b96c6328dc0e449574046ef4218c9f23 (patch) | |
| tree | 801301fe5272c05157403c30fc6a34352c2e3184 /Master/texmf-dist/doc/support | |
| parent | c231b52342d5ce2940f7d8b66a94ffd87ad016a0 (diff) | |
latexmk (22mar11)
git-svn-id: svn://tug.org/texlive/trunk@21806 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support')
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/CHANGES | 13 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/INSTALL | 2 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/README | 36 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/latexmk.pdf | bin | 82989 -> 95808 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/latexmk.txt | 1510 |
5 files changed, 943 insertions, 618 deletions
diff --git a/Master/texmf-dist/doc/support/latexmk/CHANGES b/Master/texmf-dist/doc/support/latexmk/CHANGES index 620b7dc9951..c046c2857a7 100644 --- a/Master/texmf-dist/doc/support/latexmk/CHANGES +++ b/Master/texmf-dist/doc/support/latexmk/CHANGES @@ -236,3 +236,16 @@ From v. 4.22d to v. 4.22e (Sometimes an error was incorrectly detected, after which latexmk stopped.) +From v. 4.22e to v. 4.23 + Deal with problem that if maximum number of runs of (pdf)latex is + exceeded, -pvc mode infinitely repeats (pdf)latex + Fix problem that changes in generated files during run of + (pdf)latex may not be detected if the run is shorter than the + granularity of file times. + Corrections of comments and messages. Documentation improvement. + Correctly parse blg files of biber 0.8 + Correct handling of errors given by rc files + Enhancements for convenient use of latexmk with Makefiles (options + -deps, -deps-out, -use-make) + -recorder option for improved detection of input and output files. + diff --git a/Master/texmf-dist/doc/support/latexmk/INSTALL b/Master/texmf-dist/doc/support/latexmk/INSTALL index fc116c4407f..b6b1966e736 100644 --- a/Master/texmf-dist/doc/support/latexmk/INSTALL +++ b/Master/texmf-dist/doc/support/latexmk/INSTALL @@ -1,6 +1,6 @@ INSTALLING latexmk ================== - (Version 4.22e, 3 February 2011) + (Version 4.23, 19 March 2011) John Collins Physics Department diff --git a/Master/texmf-dist/doc/support/latexmk/README b/Master/texmf-dist/doc/support/latexmk/README index c8e1faa0a94..196f0e6a392 100644 --- a/Master/texmf-dist/doc/support/latexmk/README +++ b/Master/texmf-dist/doc/support/latexmk/README @@ -1,4 +1,4 @@ -Latexmk, version 4.22e, 3 Feb. 2011 +Latexmk, version 4.23, 19 Mar. 2011 ----------------------------------- Latexmk completely automates the process of generating a LaTeX @@ -92,7 +92,7 @@ NOTES:- John Collins ---------------------------- "latexmk -h" ---------------------------- -Latexmk 4.22e: Automatic LaTeX document generation routine +Latexmk 4.23: Automatic LaTeX document generation routine Usage: latexmk [latexmk_options] [filename ...] @@ -110,18 +110,21 @@ Usage: latexmk [latexmk_options] [filename ...] -C - clean up (remove) all nonessential files including aux, dep, dvi, postscript and pdf files and file of database of file information - -CA - clean up (remove) absolutely ALL nonessential files. - Now equivalent to -C option. + -CA - clean up (remove) all nonessential files. + Equivalent to -C option. -CF - Remove file of database of file information before doing other actions -cd - Change to directory of source file when processing it -cd- - Do NOT change to directory of source file when processing it - -dependents - Show list of dependent files after processing - -dependents- - Do not show list of dependent files after processing + -dependents or -deps - Show list of dependent files after processing + -dependents- or -deps- - Do not show list of dependent files + -deps-out=file - Set name of output file for dependency list, + and turn on showing of dependency list -dF <filter> - Filter to apply to dvi file -dvi - generate dvi -dvi- - turn off required dvi - -e <code> - Execute specified PERL code + -e <code> - Execute specified Perl code (as part of latexmk start-up + code) -f - force continued processing past errors -f- - turn off forced continuing processing past errors -gg - Super go mode: clean out generated files (-CA), and then @@ -162,11 +165,18 @@ Usage: latexmk [latexmk_options] [filename ...] (Side effect: turn off ordinary preview mode.) -pvc- - turn off -pvc -r <file> - Read custom RC file - -silent - silence progress messages from called programs - -time - show CPU time used - -time- - don't show CPU time used - -v - display program version - -verbose - display usual progress messages from called programs + -recorder - Use -recorder option for (pdf)latex + (to give list of input and output files) + -recorder- - Do not use -recorder option for (pdf)latex + -rules - Show list of rules after processing + -rules- - Do not show list of rules after processing + -silent - silence progress messages from called programs + -time - show CPU time used + -time- - don't show CPU time used + -use-make - use the make program to try to make missing files + -use-make- - don't use the make program to try to make missing files + -v - display program version + -verbose - display usual progress messages from called programs -version - display program version -view=default - viewer is default (dvi, ps, pdf) -view=dvi - viewer is for dvi @@ -176,7 +186,7 @@ Usage: latexmk [latexmk_options] [filename ...] filename = the root filename of LaTeX document -p, -pv and -pvc are mutually exclusive --h, -c and -C overides all other options. +-h, -c and -C override all other options. -pv and -pvc require one and only one filename specified All options can be introduced by '-' or '--'. (E.g., --help or -help.) Contents of RC file specified by -r overrides options specified diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.pdf b/Master/texmf-dist/doc/support/latexmk/latexmk.pdf Binary files differindex ac989e8bba4..0cd8f9ef2ae 100644 --- a/Master/texmf-dist/doc/support/latexmk/latexmk.pdf +++ b/Master/texmf-dist/doc/support/latexmk/latexmk.pdf diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.txt b/Master/texmf-dist/doc/support/latexmk/latexmk.txt index 7ef1258c7b1..8ccb793ca4b 100644 --- a/Master/texmf-dist/doc/support/latexmk/latexmk.txt +++ b/Master/texmf-dist/doc/support/latexmk/latexmk.txt @@ -23,42 +23,42 @@ DESCRIPTION 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 + file. (Optionally, it also examines the list of input and output files + generated by the -recorder option of modern versions of latex and + pdflatex. See the documentation for the -recorder option of latexmk + below.) 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, - biber, and/or makeindex. In addition, latexmk can be configured to - generate other necessary files. For example, from an updated figure + used. With some macro packages and document classes, four, or even + more, runs may be needed. If necessary, latexmk will also run bibtex, + biber, 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 + 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: + 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- + 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 + 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 + 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, - 1 @@ -70,43 +70,45 @@ DESCRIPTION LATEXMK(1L) LATEXMK(1L) - call an external program to do other postprocessing on the generated + 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. - 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 + 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 + 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- + 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 + 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 + 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, + (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 + 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 + able in the section "List of configuration variables usable in initialization files". - If a file is specified without an extension, then the ".tex" extension + 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 @@ -117,17 +119,16 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE When the source file uses bbl files for bibliography, run bibtex or biber as needed to regenerate the bbl files. - This property can also be configured by setting the $bibtex_use + This property can also be configured by setting the $bibtex_use variable to 2 in a configuration file -bibtex- Never run bibtex or biber. - A common use for this option is when a document comes from an - 3 February 2011 2 + 21 March 2011 2 @@ -136,49 +137,50 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE LATEXMK(1L) LATEXMK(1L) - external source, complete with its bbl file(s), and the user - does not have the corresponding bib files available. In this - situation use of the -bibtex- option will prevent latexmk from + A common use for this option is when a document comes from an + external source, complete with its bbl file(s), and the user + does not have the corresponding bib files available. In this + situation use of the -bibtex- option will prevent latexmk from trying to run bibtex or biber, which would result in overwriting of the bbl files. -bibtex-cond - When the source file uses bbl file(s) for the bibliography, run - bibtex or biber as needed to regenerate the bbl files, but only - if the relevant bib file(s) exist. Thus when the bib files are - not available, bibtex or biber is not run, thereby avoiding + When the source file uses bbl file(s) for the bibliography, run + bibtex or biber as needed to regenerate the bbl files, but only + if the relevant bib file(s) exist. Thus when the bib files are + not available, bibtex or biber is not run, thereby avoiding overwriting of the bbl file(s). This is the default setting. - (Note that it is possible for latexmk to decide that the bib - file does not exist, even though the bib file does exist and - bibtex or biber finds it. The problem is that the bib file may - not be in the current directory but in some search path; the + (Note that it is possible for latexmk to decide that the bib + file does not exist, even though the bib file does exist and + bibtex or biber finds it. The problem is that the bib file may + not be in the current directory but in some search path; the places latexmk and bibtex or biber cause to be searched need not - be identical. On modern installations of TeX and related pro- - grams this problem should not arise, since latexmk uses the + be identical. On modern installations of TeX and related pro- + grams this problem should not arise, since latexmk uses the kpsewhich program to do the search, and kpsewhich should use the - same search path as bibtex and biber. If this problem arises, + same search path as bibtex and biber. If this problem arises, use the -bibtex option when invoking latexmk.) -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 + 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 + 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 + 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. -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 + 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. @@ -188,12 +190,12 @@ LATEXMK(1L) LATEXMK(1L) -c Clean up (remove) all regeneratable files generated by latex and bibtex or biber 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 + a combination of log files, aux files, latexmk's database file + of source file information, and those with extensions specified - 3 February 2011 3 + 21 March 2011 3 @@ -202,64 +204,65 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - in the @generated_exts configuration variable. In addition, - files with extensions by the $clean_ext configuration variable + in the @generated_exts configuration variable. In addition, + files with extensions by the $clean_ext configuration variable are removed. - This cleanup is instead of a regular make. See the -gg option + This cleanup is instead of a regular make. See the -gg option if you want to do a cleanup then a make. - If $bibtex_use is set to 0 or 1, bbl files are counted as non- + If $bibtex_use is set to 0 or 1, bbl files are counted as non- regeneratable. - If $cleanup_includes_cusdep_generated is nonzero, regeneratable - files are considered as including those generated by custom - dependencies and are also deleted. Otherwise these files are + If $cleanup_includes_cusdep_generated is nonzero, regeneratable + files are considered as including those generated by custom + dependencies and are also deleted. Otherwise these files are not deleted. -C Clean up (remove) all regeneratable files generated by latex and - bibtex or biber. This is the same as the -c option with the + bibtex or biber. This is the same as the -c option with the addition of dvi, postscript and pdf files, and those with exten- sions in the $clean_full_ext configuration variable. - This cleanup is instead of a regular make. See the -gg option + This cleanup is instead of a regular make. See the -gg option if you want to do a cleanup than a make. - If $bibtex_use is set to 0 or 1, bbl files are counted as non- + If $bibtex_use is set to 0 or 1, bbl files are counted as non- regeneratable. - If $cleanup_includes_cusdep_generated is nonzero, regeneratable - files are considered as including those generated by custom - dependencies and are also deleted. Otherwise these files are + If $cleanup_includes_cusdep_generated is nonzero, regeneratable + files are considered as including those generated by custom + dependencies and are also deleted. Otherwise these files are not deleted. - -CA Clean up (remove) absolutely all regeneratable files. It is now - equivalent to the -C option. See that option for details. + -CA (Obsolete). Now equivalent to the -C option. See that option + for details. - -CF Remove the file containing the database of source file informa- + -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 + -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 + 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 + 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 - ".dviF". All extra processing (e.g. conversion to postscript, - preview, printing) will then be performed on this filtered dvi - file. + -deps Show a list of dependent files after processing. This is in the + form of a dependency list of the form used by the make program, + and it is therefore suitable for use in a Makefile. It gives an + overall view of the files without listing intermediate files, as + well as latexmk can determine them. + By default the list of dependent files is sent to stdout (i.e., - 3 February 2011 4 + 21 March 2011 4 @@ -268,204 +271,238 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + normally to the screen unless you've redirected latexmk's out- + put). But you can set the filename where the list is sent by + the -deps-out= option. + + See the section "USING latexmk WITH make" for an example of how + to use a dependency list with make. + + Users familiar with GNU automake and gcc will find that the + -deps option is very similar in its purpose and results to the + -M option to gcc. + + -dependents + Equivalent to -deps. + + -deps- Do not show a list of dependent files after processing. (This + is the default.) + + -dependents- + Equivalent to -deps-. + + -deps-out=FILENAME + Set the filename to which the list of dependent files is writ- + ten. If the FILENAME argument is omitted or set to '-', then + the output is sent to stdout. + + Use of this option also turns on the output of the list of + dependent files after processing. + + -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 -diagnostics - Print detailed diagnostics during a run. This may help for + Print detailed diagnostics during a run. This may help for debugging problems or to understand latexmk's behavior in diffi- cult 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 + -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 + 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 - 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 + 21 March 2011 5 - Note that the single quotes block normal UNIX/LINUX command - shells from treating the characters inside the quotes as spe- - cial. (In this example, the q/.../ construct is a Perl idiom - equivalent to using single quotes. This avoids the complica- - tions 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(1L) LATEXMK(1L) - 3 February 2011 5 + 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 + 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 spe- + cial. (In this example, the q/.../ construct is a Perl idiom + equivalent to using single quotes. This avoids the complica- + tions 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(1L) LATEXMK(1L) + 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 + The last two examples will NOT work with UNIX/LINUX command shells. - -f Force latexmk to continue document processing despite errors. + -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 con- + -f option. This could be used to override a setting in a con- figuration 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 + -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. + + + + 21 March 2011 6 + + + + + +LATEXMK(1L) LATEXMK(1L) + + -gg "Super go mode" or "clean make": clean out generated files as if - -CA had been given, and then do a regular make. + -C 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 + 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 + 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 + 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 + 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. -nobibtex Never run bibtex or biber. - A common use for this option is when a document comes from an - - - - 3 February 2011 6 - - - - - -LATEXMK(1L) LATEXMK(1L) - - - external source, complete with its bbl file(s), and the user - does not have the corresponding bib files available. In this - situation use of the -nobibtex option will prevent latexmk from + A common use for this option is when a document comes from an + external source, complete with its bbl file(s), and the user + does not have the corresponding bib files available. In this + situation use of the -nobibtex option will prevent latexmk from trying to run bibtex or biber, which would result in overwriting of the bbl files. -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- + 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 + 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 turns them off. + + + 21 March 2011 7 + + + + + +LATEXMK(1L) LATEXMK(1L) + + -pdf Generate pdf version of document using pdflatex. -pdfdvi - Generate pdf version of document from the dvi file, by default + 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 + -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 + -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 + 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 + 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 + -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) - - - - 3 February 2011 7 - - - - - -LATEXMK(1L) LATEXMK(1L) - - will then be performed on this filtered postscript file. Example of usage: Use psnup to print two pages on the one page: @@ -477,69 +514,69 @@ LATEXMK(1L) LATEXMK(1L) 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 + 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 + -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. - -pvc Run a file previewer and continually update the .dvi, .ps, + -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. + the Description above). Which of these files is generated and - The -pvc option also turns off force mode (-f), as is normally - best for continuous preview mode. If you really want force - mode, use the options in the order -pvc -f. - 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. + 21 March 2011 8 - There are some other methods for arranging an update, notably - useful for many versions of xdvi and xpdf. These are best set - 3 February 2011 8 +LATEXMK(1L) LATEXMK(1L) + 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. + The -pvc option also turns off force mode (-f), as is normally + best for continuous preview mode. If you really want force + mode, use the options in the order -pvc -f. -LATEXMK(1L) LATEXMK(1L) + 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 + 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- + 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. @@ -547,50 +584,92 @@ LATEXMK(1L) LATEXMK(1L) -quiet Same as -silent -r <rcfile> - Read the specified initialization file ("RC file") before pro- + 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 + -- 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 - Perl programming language (typically a sequence of assignment + + + + 21 March 2011 9 + + + + + +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 + 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. + -recorder + Use the -recorder option with latex and pdflatex. In (most) + modern versions of these programs, this results in a file of + extension .fls containing a list of the files that these pro- + grams have read and written. Latexmk will then use this file to + improve its detection of source files and generated files after + a run of latex or pdflatex. + + For further information, see the documentation for the $recorder + configuration variable. + + -recorder- + Do not use the -recorder option with latex and pdflatex. + + -rules Show a list of latemk's rules and dependencies after processing. + + -rules- + Do not show a list of latexmk's rules and dependencies after + processing. (This is the default.) + -silent Run commands silently, i.e., with options that reduce the amount - of diagnostics generated. For example, with the default set- - tings, the command "latex -interaction=batchmode" is used for + of diagnostics generated. For example, with the default set- + tings, the command "latex -interaction=batchmode" is used for latex. - Also reduce the number of informational messages that latexmk + Also reduce the number of informational messages that latexmk generates. - To change the options used to make the commands run silently, + To change the options used to make the commands run silently, you need to configure latexmk with changed values of its config- - uration variables, the relevant ones being $bib- + uration variables, the relevant ones being $bib- tex_silent_switch, $biber_silent_switch, $dvips_silent_switch, $latex_silent_switch, and $pdflatex_silent_switch. - -v, -version - Print version number of latexmk. + -use-make + When after a run of latex or pdflatex, there are warnings about + missing files (e.g., as requested by the LaTeX \input, \include, + and \includgraphics), latexmk tries to make them by a custom + dependency. If no relevant custom dependency with an appropriate + source file is found, and if the -use-make option is set, then + latexmk will try as a resort using the make program to try to + make the missing files. + Note that the filename may be specified without an extension, + e.g., by \includegraphics{drawing} in a LaTeX file. In that + case, latexmk will try making drawing.ext with ext set in turn + to the possible extensions that are relevant for latex (or as - 3 February 2011 9 + 21 March 2011 10 @@ -599,6 +678,18 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + appropriate pdflatex). + + See also the documentation for the $use_make_for_missing_files + configuration variable. + + -use-make- + Do not use the make program to try to make missing files. + (Default.) + + -v, -version + Print version number of latexmk. + -verbose Opposite of -silent. This is the default setting. @@ -607,11 +698,11 @@ LATEXMK(1L) LATEXMK(1L) 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 + 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 -p, -pv and -pvc are mutually exclusive. So each of these options turns the others off. @@ -643,21 +734,10 @@ CONFIGURATION/INITIALIZATION (RC) FILES 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". - On a cygwin system (i.e., a MS-Windows system in which perl is - that of cygwin), latexmk reads for the first it finds of - "/cygdrive/c/latexmk/LatexMk", - "/opt/local/share/latexmk/LatexMk", - "/usr/local/share/latexmk/LatexMk", - "/usr/local/lib/latexmk/LatexMk". - - 3 February 2011 10 + 21 March 2011 11 @@ -666,34 +746,45 @@ CONFIGURATION/INITIALIZATION (RC) FILES LATEXMK(1L) LATEXMK(1L) + "/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". + On a cygwin system (i.e., a MS-Windows system in which perl is + that of cygwin), latexmk reads for the first it finds of + "/cygdrive/c/latexmk/LatexMk", + "/opt/local/share/latexmk/LatexMk", + "/usr/local/share/latexmk/LatexMk", + "/usr/local/lib/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 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 + 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 + 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 + 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 + 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 + 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'; @@ -706,92 +797,83 @@ HOW TO SET VARIABLES IN INITIALIZATION FILES @default_files = ('paper', 'paper1'); - for the setting of an array of strings. It is possible to append an + 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 Perl program- - ming language brings into play some special rules for interpolating - variables into strings. People not fluent in Perl will want to avoid - these complications.) + 21 March 2011 12 - 3 February 2011 11 +LATEXMK(1L) LATEXMK(1L) -LATEXMK(1L) LATEXMK(1L) + 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 Perl program- + ming language brings into play some special rules for interpolating + variables into strings. People not fluent in Perl will want to avoid + these complications.) - You can do much more complicated things, but for this you will need to + 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 + 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 + 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 + 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, + %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 + %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 + %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. - 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. - - 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 + 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 - 3 February 2011 12 + 21 March 2011 13 @@ -800,90 +882,99 @@ FORMAT OF COMMAND SPECIFICATIONS LATEXMK(1L) LATEXMK(1L) - containing spaces.) In case latexmk's quoting does not work correctly - on your system, you can turn it off -- see the documentation for the + 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. + + 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 $quote_filenames. - 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 + 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 - bibliography file, the setting for the bibtex command should therefore + ument 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 $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. + 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 + 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 + 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 + "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 + 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 + 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 + This will be translated to whatever is appropriate for your operating system. - Notes: (1) In some circumstances, latex will always run a command + 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. + 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 - 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 + 21 March 2011 14 - 3 February 2011 13 +LATEXMK(1L) LATEXMK(1L) -LATEXMK(1L) LATEXMK(1L) + 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'; - (Note about the above example: Forward slashes are equivalent to back- - slashes in filenames under MS-Windows, provided that the filename is - inside double quotes. It is easier to use forward slashes in examples - like the one above, since then one does not have to worry about the - rules for dealing with forward slashes in strings in the Perl lan- + (Note about the above example: Forward slashes are equivalent to back- + slashes in filenames under MS-Windows, provided that the filename is + inside double quotes. It is easier to use forward slashes in examples + like the one above, since then one does not have to worry about the + rules for dealing with forward slashes in strings in the Perl lan- guage.) - Using MS-Windows file associations: A useful trick under modern ver- + Using MS-Windows file associations: A useful trick under modern ver- sions of MS-Windows (e.g., WinXP) is to use just the command 'start' by itself: $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 + program the system has associated with dvi files. (The same applies for a postscript viewer and a pdf viewer.) Not using a certain command: If a command is not to be run, the command @@ -891,47 +982,48 @@ LATEXMK(1L) LATEXMK(1L) $lpr = 'NONE lpr'; - This typically is used when an appropriate command does not exist on + 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 + 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 + 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 + 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'; + $pdflatex = 'pdflatex --shell-escape %O %S; pst2pdf_for_latexmk - 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. + 21 March 2011 15 - 3 February 2011 14 +LATEXMK(1L) LATEXMK(1L) + %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. -LATEXMK(1L) LATEXMK(1L) LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES @@ -939,27 +1031,27 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES $always_view_file_via_temporary [0] Whether ps and pdf files are initially to be made in a temporary - directory and then moved to the final location. (This applies + directory and then moved to the final location. (This applies to dvips, dvipdf, and ps2pdf operations, and the filtering oper- - ators on dvi and ps files. It does not apply to pdflatex, + ators on dvi and ps files. It does not apply to pdflatex, unfortunately.) This use of a temporary file solves a problem that the making of - these files can occupy a substantial time. If a viewer sees - that the file has changed, it reads the new file, and this can + these files can occupy a substantial time. If a viewer sees + that the file has changed, it reads the new file, and this can cause havoc if the program writing the file has not yet finished its work. See the $pvc_view_file_via_temporary variable for a setting that - applies only if preview-continuous mode (-pvc option) is used. + applies only if preview-continuous mode (-pvc option) is used. See $tmpdir for the setting of the directory where the temporary file is created. $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 + 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 @@ -968,7 +1060,7 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES $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 + 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 car- tridge isn't running too low. @@ -977,22 +1069,15 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES 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 + 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. - 3 February 2011 15 + 21 March 2011 16 @@ -1001,7 +1086,14 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES LATEXMK(1L) LATEXMK(1L) - single element list consisting of the current directory is set. + 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: @@ -1011,13 +1103,13 @@ LATEXMK(1L) LATEXMK(1L) @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 + 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 + 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- @@ -1027,7 +1119,7 @@ LATEXMK(1L) LATEXMK(1L) The biber processing program. $biber_silent_switch ["--onlylog"] - Switch(es) for the biber processing program when silent mode is + Switch(es) for the biber processing program when silent mode is on. $bibtex ["bibtex %O %S"] @@ -1039,28 +1131,21 @@ LATEXMK(1L) LATEXMK(1L) $bibtex_use [1] Under what conditions to run BibTeX or biber. When latexmk dis- - covers from the log file that one (or more) BibTeX/biber-gener- - ated bibliographies are used, it can run BibTeX or biber when- - ever it appears necessary to regenerate the bbl file(s) from + covers from the log file that one (or more) BibTeX/biber-gener- + ated bibliographies are used, it can run BibTeX or biber when- + ever it appears necessary to regenerate the bbl file(s) from their source bib database file(s). - But sometimes, the bib file(s) are not available (e.g., for a - document obtained from an external archive), but the bbl files - are provided. In that case use of BibTeX or biber will result - in incorrect overwriting of the precious bbl files. The vari- - able $bibtex_use controls whether this happens. Its possible + But sometimes, the bib file(s) are not available (e.g., for a + document obtained from an external archive), but the bbl files + are provided. In that case use of BibTeX or biber will result + in incorrect overwriting of the precious bbl files. The vari- + able $bibtex_use controls whether this happens. Its possible values are: 0: never use BibTeX or biber. 1: only use BibTeX or - biber if the bib files exist. 2: run BibTeX or biber whenever - it appears necessary to update the bbl files, without testing - for the existence of the bib files. - - $cleanup_includes_cusdep_generated [0] - If nonzero, specifies that cleanup also deletes files that are - generated by custom dependencies. (When doing a clean up, e.g., - 3 February 2011 16 + 21 March 2011 17 @@ -1069,66 +1154,66 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + biber if the bib files exist. 2: run BibTeX or biber whenever + it appears necessary to update the bbl files, without testing + for the existence of the bib files. + + $cleanup_includes_cusdep_generated [0] + If nonzero, specifies that cleanup also deletes files that are + generated by custom dependencies. (When doing a clean up, e.g., by use of the -C option, custom dependencies are those listed in the .fdb_latexmk file from a previous run.) $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 + 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. $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 + 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.) - This variable is equivalent to specifying one of the -c or -C options. + This variable is equivalent to specifying one of the -c 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 or -C) is selected. The value of this - variable is a string containing the extensions separated by + Extra extensions of files for latexmk to remove when any of the + clean-up options (-c or -C) is selected. The value of this + variable is a string containing the extensions separated by spaces. It is also possible to specify a more general pattern of file to - be deleted, by using the place holder %R, as in commands. Thus + be deleted, by using the place holder %R, as in commands. Thus setting $clean_ext = "out %R-blx.bib"; in an initialization file will imply that when a clean-up opera- - tion is specified, not only is the standard set of files - deleted, but also files of the form FOO.out and FOO-blx.bib, - where FOO stands for the basename of the file being processed + tion is specified, not only is the standard set of files + deleted, but also files of the form FOO.out and FOO-blx.bib, + where FOO stands for the basename of the file being processed (as in FOO.tex). $clean_full_ext [""] - Extra extensions of files for latexmk to remove when the -C + 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". + 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 - 3 February 2011 17 + 21 March 2011 18 @@ -1137,8 +1222,15 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - file "latexmkrc" in the current directory). Then if no files - are specified on the command line then the files you specify by + 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: @@ -1149,11 +1241,15 @@ LATEXMK(1L) LATEXMK(1L) @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 + 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. + $dependents_list [0] + Whether to display a list(s) of dependencies at the end of a + run. + $dvi_filter [empty] The dvi file filter to be run on the newly produced dvi file before other processing. Equivalent to specifying the -dF @@ -1182,31 +1278,31 @@ LATEXMK(1L) LATEXMK(1L) $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: + to use the dvipdfm command, which needs its arguments in a - $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 + 21 March 2011 19 - 3 February 2011 18 +LATEXMK(1L) LATEXMK(1L) + different order: -LATEXMK(1L) LATEXMK(1L) + $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". @@ -1253,6 +1349,17 @@ LATEXMK(1L) LATEXMK(1L) variable $dvi_update_method. The default value is the one appropriate for xdvi on a UNIX system. + + + 21 March 2011 20 + + + + + +LATEXMK(1L) LATEXMK(1L) + + $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 @@ -1266,18 +1373,6 @@ LATEXMK(1L) LATEXMK(1L) @generated_exts [( aux , bbl , idx , ind , lof , lot , out , toc , $fdb_ext )] This contains a list of extensions for files that are generated - - - - 3 February 2011 19 - - - - - -LATEXMK(1L) LATEXMK(1L) - - during a LaTeX run and that are read in by LaTeX in later runs, either directly or indirectly. @@ -1322,6 +1417,18 @@ LATEXMK(1L) LATEXMK(1L) time changes, latex sees that the eps file has changed, and therefore reruns latex. This causes an infinite loop, that is only terminated becaues latexmk has a limit on the number of + + + + 21 March 2011 21 + + + + + +LATEXMK(1L) LATEXMK(1L) + + runs to guard against pathological situations. But the changing line has no real effect, since it is a comment. @@ -1337,18 +1444,6 @@ LATEXMK(1L) LATEXMK(1L) 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 - - - - 3 February 2011 20 - - - - - -LATEXMK(1L) LATEXMK(1L) - - extension .eps has changed. There is only one regular expression available for each exten- @@ -1392,6 +1487,18 @@ LATEXMK(1L) LATEXMK(1L) $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 + + + + 21 March 2011 22 + + + + + +LATEXMK(1L) LATEXMK(1L) + + program used, but also specify options to the program. E.g., $latex = "latex --src-specials"; @@ -1409,17 +1516,6 @@ LATEXMK(1L) LATEXMK(1L) specified by the variable %latex_input_extensions. The default extensions are 'tex' and 'eps'. - - - 3 February 2011 21 - - - - - -LATEXMK(1L) LATEXMK(1L) - - (For Perl experts: %latex_input_extensions is a hash whose keys are the extensions. The values are irrelevant.) Two subrou- tines are provided for manipulating this and the related vari- @@ -1461,6 +1557,18 @@ LATEXMK(1L) LATEXMK(1L) example, if you have gsview installed, you could use it with the option "/p": + + + + 21 March 2011 23 + + + + + +LATEXMK(1L) LATEXMK(1L) + + $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p'; If gsview is installed in a different directory, you will need @@ -1479,18 +1587,6 @@ LATEXMK(1L) LATEXMK(1L) The printing program to print pdf files. Under MS-Windows you could set this to use gsview, if it is - - - - 3 February 2011 22 - - - - - -LATEXMK(1L) LATEXMK(1L) - - installed, e.g., $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p'; @@ -1502,6 +1598,10 @@ LATEXMK(1L) LATEXMK(1L) interpreted. + $make ["make"] + The make processing program. + + $makeindex ["makeindex %O -o %D %S"] The index processing program. @@ -1527,6 +1627,18 @@ LATEXMK(1L) LATEXMK(1L) 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 + + + + 21 March 2011 24 + + + + + +LATEXMK(1L) LATEXMK(1L) + + 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 @@ -1551,17 +1663,6 @@ LATEXMK(1L) LATEXMK(1L) specified by the variable %pdflatex_input_extensions. The default extensions are 'tex', 'pdf', 'jpg, and 'png'. - - - 3 February 2011 23 - - - - - -LATEXMK(1L) LATEXMK(1L) - - (For Perl experts: %pdflatex_input_extensions is a hash whose keys are the extensions. The values are irrelevant.) Two sub- routines are provided for manipulating this and the related @@ -1598,6 +1699,18 @@ LATEXMK(1L) LATEXMK(1L) $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, + + + + 21 March 2011 25 + + + + + +LATEXMK(1L) LATEXMK(1L) + + this will cause to be run whatever command the system has asso- ciated with .pdf files.] @@ -1622,17 +1735,6 @@ LATEXMK(1L) LATEXMK(1L) for the value 2, to specify update by signal, the signal is specified by $pdf_update_signal.) - - - 3 February 2011 24 - - - - - -LATEXMK(1L) LATEXMK(1L) - - Note that acroread under MS-Windows (but not UNIX) locks the pdf file, so the default value is then 3. @@ -1669,6 +1771,18 @@ LATEXMK(1L) LATEXMK(1L) If nonzero, generate a postscript version of the document. Equivalent to the -ps option. + + + + 21 March 2011 26 + + + + + +LATEXMK(1L) LATEXMK(1L) + + If some other request is made for which a postscript file is needed, then $postscript_mode will be set to 1. @@ -1693,17 +1807,6 @@ LATEXMK(1L) LATEXMK(1L) Type of file to printout: possibilities are "dvi", "none", "pdf", or "ps". - - - 3 February 2011 25 - - - - - -LATEXMK(1L) LATEXMK(1L) - - $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, @@ -1740,6 +1843,18 @@ LATEXMK(1L) LATEXMK(1L) ferent ways of writing this option. You can configure this variable apppropriately. + + + + 21 March 2011 27 + + + + + +LATEXMK(1L) LATEXMK(1L) + + 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. @@ -1763,18 +1878,6 @@ LATEXMK(1L) LATEXMK(1L) signal, the signal is specified by $ps_update_signal.) - - - - 3 February 2011 26 - - - - - -LATEXMK(1L) LATEXMK(1L) - - $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 @@ -1801,43 +1904,93 @@ LATEXMK(1L) LATEXMK(1L) ing only ensures that such filenames are correctly treated by the oper- ating system in passing arguments to programs.) + $recorder [0] + Whether to use the -recorder option to latex and pdflatex. Use + of this option results in a file of extension .fls containing a + list of the files that these programs have read and written. + Latexmk will then use this file to improve its detection of + source files and generated files after a run of latex or pdfla- + tex. + + It is generally recommended to use this option (or to configure + the $recorder variable to be on.) But it only works if + (pdf)latex supports the -recorder option, which is true for most + + + + 21 March 2011 28 + + + + + +LATEXMK(1L) LATEXMK(1L) + + + current implementations + + Note about the name of the .fls file: Most implementations of + (pdf)latex produce an .fls file with the same basename as the + main document's LaTeX, e.g., for Document.tex, the .fls file is + Document.fls. However, some implementations instead produce + files named for the program, i.e., latex.fls or pdflatex.fls. + In this second case, latexmk copies the latex.fls or pdfla- + tex.fls to a file with the basename of the main LaTeX document, + e.g., Document.fls. + $sleep_time [2] - The time to sleep (in seconds) between checking for source file + The time to sleep (in seconds) between checking for source file changes when running with the -pvc option. This is subject to a - minimum of one second delay, except that zero delay is also + minimum of one second delay, except that zero delay is also allowed. - A value of exactly 0 gives no delay, and typically results in + A value of exactly 0 gives no delay, and typically results in 100% CPU usage, which may not be desirable. $texfile_search [""] - This is an obsolete variable, replaced by the @default_files + 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 + 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 + 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 + 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". + $use_make_for_missing_files [0] + Whether to use make to try and make files that are missing after + a run of latex or pdflatex, and for which a custom dependency + has not been found. This is generally useful only when latexmk + is used as part of a bigger project which is built by using the + make program. + + Note that once a missing file has been made, no further calls to + make will be made on a subsequent run of latexmk to update the + file. Handling this problem is the job of a suitably defined + Makefile. See the section "USING latexmk WITH make" for how to + do this. The intent of calling make from latexmk is merely to + detect dependencies. + $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). - 3 February 2011 27 + 21 March 2011 29 @@ -1846,10 +1999,6 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - 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 @@ -1905,23 +2054,22 @@ CUSTOM DEPENDENCIES 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 - 3 February 2011 28 - + 21 March 2011 30 -LATEXMK(1L) LATEXMK(1L) - 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. +LATEXMK(1L) LATEXMK(1L) - A simple and typical example of code in an initialization rcfile is add_cus_dep( 'fig', 'eps', 0, 'fig2eps' ); sub fig2eps { @@ -1976,24 +2124,24 @@ LATEXMK(1L) LATEXMK(1L) 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 - 3 February 2011 29 + 21 March 2011 31 -LATEXMK(1L) LATEXMK(1L) - } +LATEXMK(1L) LATEXMK(1L) - 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' ); @@ -2046,26 +2194,26 @@ 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 + 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: - 3 February 2011 30 + 21 March 2011 32 -LATEXMK(1L) LATEXMK(1L) - 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. +LATEXMK(1L) LATEXMK(1L) - 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 { @@ -2078,39 +2226,188 @@ LATEXMK(1L) LATEXMK(1L) preferable. + + +USING latexmk WITH make + This section is targeted only at advanced users who use the make pro- + gram for complex projects, as for software development, with the depen- + dencies specified by a Makefile. + + Now the basic task of latexmk is to run the appropriate programs to + make a viewable version of a LaTeX document. However, the usual make + program is not suited to this purpose for at least two reasons. First + is that the use of LaTeX involves circular dependencies (e.g., via .aux + files), and these cannot be handled by the standard make program. Sec- + ond is that in a large document the set of source files can change + quite frequently, particularly with included graphics files; in this + situation keeping a Makefile manually updated is inappropriate and + error-prone, especially when the depedencies can be determined automat- + ically. Latexmk solves both of these problems robustly. + + Thus for many standard LaTeX documents latexmk can be used by itself + without the make program. In a complex project it simply needs to be + suitably configured. A standard configuration would be to define cus- + tom dependencies to make graphics files from their source files (e.g., + as created by the xfig program). Custom dependencies are latexmk's + equivalent of pattern rules in Makefiles. + + Nevertheless there are projects for which a Makefile is appropriate, + and it is useful to know how to use latexmk from a Makefile. A typical + example would be to generate documentation for a software project. + Potentially the interaction with the rest of the rules in the Makefile + could be quite complicated, for example if some of the source files for + a LaTeX document are generated by the project's software. + + In this section, I give a couple of examples of how latexmk can be use- + fully invoked from a Makefile. The examples use specific features of + current versions of GNU make, which is the default on both linux and + OS-X systems. They may need modifications for other versions of make. + + The simplest method is simply to delegate all the relevant tasks to + latexmk, as is suitable for a straightforward LaTeX document. For this + a suitable Makefile is like + + .PHONY : FORCE_MAKE + all : try.pdf + %.pdf : %.tex FORCE_MAKE + latexmk -pdf -dvi- -ps- $< + + (Note: the last line must be introduced by a tab for the Makefile to + function correctly!) Naturally, if making try.pdf from its associated + LaTeX file try.tex were the only task to be performed, a direct use of + + + + 21 March 2011 33 + + + + + +LATEXMK(1L) LATEXMK(1L) + + + latexmk without a Makefile would normally be better. The benefit of + using a Makefile for a LaTeX document would be in a larger project, + where lines such as the above would be only be a small part of a larger + Makefile. + + The above example has a pattern rule for making a .pdf file from a .tex + file, and it is defined to use latexmk in the obvious way. There is a + conventional default target named "all", with a prerequisite of + try.pdf. So when make is invoked, by default it makes try.pdf. The + only complication is that there may be many source files beyond + try.tex, but these aren't specified in the Makefile, so changes in them + will not by themselves cause latexmk to be invoked. Instead, the pat- + tern rule is equipped with a "phony" prerequisite FORCE_MAKE; this has + the effect of causing the rule to be always out-of-date, so that + latexmk is always run. It is latexmk that decides whether any action + is needed, e.g., a rerun of pdflatex. Effectively the Makefile dele- + gates all decisions to latexmk, while make has no knowledge of the list + of source files except for primary LaTeX file for the document. If + there are, for example, graphics files to be made, these must be made + by custom dependencies configured in latexmk. + + But something better is needed in more complicated situations, for + example, when the making of graphics files needs to be specified by + rules in the Makefile. To do this, one can use a Makefile like the + following: + + TARGETS = document1.pdf document2.pdf + DEPS_DIR = .deps + LATEXMK = latexmk -recorder -use-make -deps \ + -e 'warn qq(In Makefile, turn off custom dependencies0;' \ + -e '@cus_dep_list = ();' \ + -e 'show_cus_dep();' + all : $(TARGETS) + $(foreach file,$(TARGETS),$(eval -include $(DEPS_DIR)/$(file)P)) + $(DEPS_DIR) : + mkdir $@ + %.pdf : %.tex + if [ ! -e $(DEPS_DIR) ]; then mkdir $(DEPS_DIR); fi + $(LATEXMK) -pdf -dvi- -ps- -deps-out=$(DEPS_DIR)/$@P $< + %.pdf : %.fig + fig2dev -Lpdf $< $@ + + (Again, the lines containing the commands for the rules should be + started with tabs.) This example was inspired by how GNU automake han- + dles automatic dependency tracking of C source files. + + After each run of latexmk, dependency information is put in a file in + the .deps subdirectory. The Makefile causes these dependency files to + be read by make, which now has the full dependency information for each + target .pdf file. To make things less trivial it is specificed that + two files document1.pdf and document2.pdf are the targets. The depen- + dency files are .deps/document1.pdfP and .deps/document2.pdfP. + + There is now no need for the phony prerequisite for the rule to make + .pdf files from .tex files. But I have added a rule to make .pdf files + from .fig files produced by the xfig program; these are commonly used + for graphics insertions in LaTeX documents. Latexmk is arranged to + output a dependency file after each run. It is given the -recorder + option, which improves its detection of files generated during a run of + pdflatex; such files should not be in the dependency list. The -e + + + + 21 March 2011 34 + + + + + +LATEXMK(1L) LATEXMK(1L) + + + options are used to turn off all custom dependencies, and to document + this. Instead the -use-make is used to delegate the making of missing + files to make itself. + + Suppose in the LaTeX file there is a command \includegraphics{graph}, + and an xfig file "graph.fig" exists. On a first run, pdflatex reports + a missing file, named "graph". Latexmk succeeds in making "graph.pdf" + by calling "make graph.pdf", and after completion of its work, it lists + "fig.pdf" among the dependents of the file latexmk is making. Then let + "fig.fig" be updated, and then let make be run. Make first remakes + "fig.pdf", and only then reruns latexmk. + + Thus we now have a method by which all the subsidiary processing is + delegated to make. + + 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: + 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 - 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 + (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 + 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 + 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.22e). + Current version, by John Collins (username collins at node + phys.psu.edu). (Version 4.23). - Released version can be obtained from CTAN: <http://www.tug.org/tex- + Released version can be obtained from CTAN: <http://www.tug.org/tex- archive/support/latexmk/>, and from the author's website <http://www.phys.psu.edu/~collins/software/latexmk/>. Modifications and enhancements by Evan McLean (Version 2.0) @@ -2121,7 +2418,11 @@ AUTHOR - 3 February 2011 31 + + + + + 21 March 2011 35 @@ -2192,6 +2493,7 @@ LATEXMK(1L) LATEXMK(1L) - 3 February 2011 32 + + 21 March 2011 36 |