diff options
| author | Karl Berry <karl@freefriends.org> | 2011-12-11 22:30:30 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2011-12-11 22:30:30 +0000 |
| commit | bca3b6017c5eda5d6c5d67bb266062fb7f363b5b (patch) | |
| tree | 4982edcfc2080e1c96ac6d3d3a7b83655c273393 /Master/texmf-dist/doc/support/latexmk | |
| parent | 66913a012bff67aeac726ca83cbaffcafbae1118 (diff) | |
latexmk 4.30a (10dec11)
git-svn-id: svn://tug.org/texlive/trunk@24819 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support/latexmk')
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/CHANGES | 22 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/INSTALL | 2 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/README | 6 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/example_rcfiles/mpost_latexmkrc | 26 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/latexmk.pdf | bin | 102990 -> 104938 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/latexmk.txt | 1374 |
6 files changed, 783 insertions, 647 deletions
diff --git a/Master/texmf-dist/doc/support/latexmk/CHANGES b/Master/texmf-dist/doc/support/latexmk/CHANGES index a9a05979adc..5d8952a7e71 100644 --- a/Master/texmf-dist/doc/support/latexmk/CHANGES +++ b/Master/texmf-dist/doc/support/latexmk/CHANGES @@ -291,3 +291,25 @@ From v. 4.28a to 4.28c can continue normally. Latexmk now parses correctly error messages from biber v. 0.9.7. +From v. 4.28c to 4.29a + Latexmk now works with the feynmp package and mpost, + provided a suitable custom dependency is defined. (See the + example latexmkrc fragment mpost_latexmkrc in the + example_rcfiles directory in the latexmk distribution.) + If output directory is set, arrange that dvips can find files + there. + In searching for cus-deps that can make a missing file, look in + $out_dir. + Solves problem that sometimes dvips and dvipdf weren't run when + they should have been. (The problem only arose with certain + changes in eps files being made within a minute of the previous + run.) + +From v. 4.29a to 4.30a + Fix use of bibtex so that it works correctly when $aux_dir and/or + $out_dir are set. + Use OS-dependent search path separator when when manipulating + TEXINPUTS, etc. Then use of -output-directory and + -aux-directory options should work on MSWin systems. + Documentation of $search_path_separator variable. + diff --git a/Master/texmf-dist/doc/support/latexmk/INSTALL b/Master/texmf-dist/doc/support/latexmk/INSTALL index 7de5cc93524..ab2a0147194 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.28c, 1 December 2011) + (Version 4.30, 9 December 2011) John Collins Physics Department diff --git a/Master/texmf-dist/doc/support/latexmk/README b/Master/texmf-dist/doc/support/latexmk/README index 715b1b080fc..7c538ad51ff 100644 --- a/Master/texmf-dist/doc/support/latexmk/README +++ b/Master/texmf-dist/doc/support/latexmk/README @@ -1,5 +1,5 @@ -Latexmk, version 4.28c, 1 December 2011 ---------------------------------------- +Latexmk, version 4.30, 9 December 2011 +-------------------------------------- Latexmk completely automates the process of generating a LaTeX document. Essentially, it is a highly specialized cousin of the @@ -92,7 +92,7 @@ NOTES:- John Collins ---------------------------- "latexmk -h" ---------------------------- -Latexmk 4.28c: Automatic LaTeX document generation routine +Latexmk 4.30a: Automatic LaTeX document generation routine Usage: latexmk [latexmk_options] [filename ...] diff --git a/Master/texmf-dist/doc/support/latexmk/example_rcfiles/mpost_latexmkrc b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/mpost_latexmkrc new file mode 100644 index 00000000000..d77cdc41c13 --- /dev/null +++ b/Master/texmf-dist/doc/support/latexmk/example_rcfiles/mpost_latexmkrc @@ -0,0 +1,26 @@ +# This shows how to use mpost, as used by the feynmp package. +# The feynmp package writes files with extension .mp, e.g., foo.mp, +# and these are to be converted by mpost to make postscript files, +# e.g., foo.1, which are later read in by dvips. +# +# A more complicated custom dependency is needed than normal, because: +# if the output directory ($out_dir) or the auxiliary directory +# ($out_dir) is set, mpost doesn't put its output in the correct +# place. + +add_cus_dep('mp', '1', 0, 'mpost'); + + +sub mpost { + my $file = $_[0]; + my ($name, $path) = fileparse( $file ); + my $return = system "mpost $file"; + # Fix the problem that mpost puts its output and log files + # in the current directory, not in the auxiliary directory + # (which is often the same as the output directory): + if ( ($path ne '') && ($path ne '.\') ) { + foreach ( "$name.1", "$name.log" ) { move $_, $aux_dir; } + } + return $return; +} + diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.pdf b/Master/texmf-dist/doc/support/latexmk/latexmk.pdf Binary files differindex 4dac1c4082f..577b9f417b2 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 475e43b765b..921658628de 100644 --- a/Master/texmf-dist/doc/support/latexmk/latexmk.txt +++ b/Master/texmf-dist/doc/support/latexmk/latexmk.txt @@ -123,11 +123,11 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE tory option of (pdf)latex, which currently is only implemented on the MiKTeX version of (pdf)latex. - See also the -outdir/-output-directory options, and the $aux_dir + See also the -outdir/-output-directory options, and the - 1 December 2011 2 + 9 December 2011 2 @@ -136,7 +136,8 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE LATEXMK(1L) LATEXMK(1L) - and $out_dir configuration variables of latexmk. + $aux_dir, $out_dir, and $search_path_separator configuration + variables of latexmk. @@ -144,58 +145,55 @@ LATEXMK(1L) LATEXMK(1L) 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 - 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 - 1 December 2011 3 + 9 December 2011 3 @@ -204,8 +202,11 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - 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 + -bs <scale> + A decimal number that specifies how large the banner message + will be printed. Experimentation is necessary to get the right + scale for your message, as a rule of thumb the scale should be + about equal to 1100 divided by the number of characters in the message. The default is 220.0 which is just right for 5 charac- ter messages. @@ -215,55 +216,51 @@ 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 - in the @generated_exts configuration variable. In addition, - files with extensions by the $clean_ext configuration variable + a combination of log files, aux files, latexmk's database file + of source file information, and those with extensions specified + 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 (Obsolete). Now equivalent to the -C option. See that option + -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 - intensity can be modified with the -bs and -bi options. The -bm - option will override this option as this is really just a short - way of specifying: - + -d Set draft mode. This prints the banner message "DRAFT" across + your page when converting the dvi file to postscript. Size and - 1 December 2011 4 + 9 December 2011 4 @@ -272,50 +269,54 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + intensity can be modified with the -bs and -bi options. The -bm + option will override this option as this is really just a short + way of specifying: + latexmk -bm DRAFT - Note that if the -d option is specified, the -ps option is + Note that if the -d option is specified, the -ps option is assumed. -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, + 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., - normally to the screen unless you've redirected latexmk's out- - put). But you can set the filename where the list is sent by + By default the list of dependent files is sent to stdout (i.e., + 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 + 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 + 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 + -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 + 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 + 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 + -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 @@ -323,15 +324,10 @@ LATEXMK(1L) LATEXMK(1L) latexmk -dF 'dviselect even' foo.tex - -diagnostics - Print detailed diagnostics during a run. This may help for - debugging problems or to understand latexmk's behavior in diffi- - cult situations. - - 1 December 2011 5 + 9 December 2011 5 @@ -340,45 +336,50 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + -diagnostics + 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- + 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 + 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 + 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 + 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 + 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 @@ -387,20 +388,13 @@ LATEXMK(1L) LATEXMK(1L) 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. - 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 - 1 December 2011 6 + 9 December 2011 6 @@ -409,12 +403,19 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - configuration file. + -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- + 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. @@ -426,50 +427,41 @@ LATEXMK(1L) LATEXMK(1L) 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. -latex='command' This sets the string specifying the command to run latex, and is - typically used to add desired options. Since the string nor- + typically used to add desired options. Since the string nor- mally contains spaces, it should be quoted, e.g., latex -latex='latex --shell-escape %O %S' foo.tex - The specification of the contents of the string are the same as - for the $latex configuration variable. Depending on your oper- - ating system and the command-line shell you are using, you may - need to change the single quotes to double quotes (or something + The specification of the contents of the string are the same as + for the $latex configuration variable. Depending on your oper- + ating system and the command-line shell you are using, you may + need to change the single quotes to double quotes (or something else). To set the command for running pdflatex (rather than the command for latex) see the -pdflatex option. - Note that the effect of this option can also be achieved by + Note that the effect of this option can also be achieved by using the -e option with a suitable line of Perl code to set the $latex variable. See the explanation of the -e option. -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 - option turns off the default behavior. - - -new-viewer- - The inverse of the -new-viewer option. It puts latexmk in its - normal behavior that in preview-continuous mode it checks for an - already-running previewer. - 1 December 2011 7 + 9 December 2011 7 @@ -478,34 +470,45 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + running. However, its test sometimes fails (notably if there is + an already-running previewer that is viewing a file of the same + name as the current file, but in a different directory). This + option turns off the default behavior. + + -new-viewer- + The inverse of the -new-viewer option. It puts latexmk in its + normal behavior that in preview-continuous mode it checks for an + already-running previewer. + -nobibtex Never run bibtex or biber. - 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 + 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. -norc Turn off the automatic reading of initialization (rc) files. - N.B. Normally the initialization files are read and obeyed, and - then command line options are obeyed in the order they are - encountered. Then -norc is an exception to this rule: it is + N.B. Normally the initialization files are read and obeyed, and + then command line options are obeyed in the order they are + encountered. Then -norc is an exception to this rule: it is acted on first, no matter where is occurs on the command line. -outdir=FOO or -output-directory=FOO - Sets the directory for the output files of (pdf)latex. This - achieves its effect by the -output-directory option of - (pdf)latex, which currently (Oct. 2011) is implemented on the + Sets the directory for the output files of (pdf)latex. This + achieves its effect by the -output-directory option of + (pdf)latex, which currently (Dec. 2011) is implemented on the common versions of (pdf)latex, i.e., MiKTeX and TeXLive. It may not be present in other versions. - See also the -auxdir/-aux-directory options, and the $aux_dir - and $out_dir configuration variables of latexmk. + See also the -auxdir/-aux-directory options, and the $aux_dir, + $out_dir, and $search_path_separator configuration variables of + latexmk. @@ -522,6 +525,18 @@ LATEXMK(1L) LATEXMK(1L) 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 + + + + 9 December 2011 8 + + + + + +LATEXMK(1L) LATEXMK(1L) + + $lpr_pdf configuration variables to see how to set the commands for printing. @@ -537,17 +552,6 @@ LATEXMK(1L) LATEXMK(1L) -pdfps Generate pdf version of document from the ps file, by default using ps2pdf. - - - 1 December 2011 8 - - - - - -LATEXMK(1L) LATEXMK(1L) - - -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 @@ -588,6 +592,18 @@ LATEXMK(1L) LATEXMK(1L) -pF Postscript file filtering. The argument to this option is a filter which will generate a filtered postscript file with the + + + + 9 December 2011 9 + + + + + +LATEXMK(1L) LATEXMK(1L) + + extension ".psF". All extra processing (e.g. preview, printing) will then be performed on this filtered postscript file. @@ -606,18 +622,6 @@ LATEXMK(1L) LATEXMK(1L) -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 - - - - 1 December 2011 9 - - - - - -LATEXMK(1L) LATEXMK(1L) - - 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 @@ -655,6 +659,18 @@ LATEXMK(1L) LATEXMK(1L) There are some other methods for arranging an update, notably useful for many versions of xdvi and xpdf. These are best set + + + + 9 December 2011 10 + + + + + +LATEXMK(1L) LATEXMK(1L) + + in latexmk's configuration; see below. Note that if latexmk dies or is stopped by the user, the @@ -676,18 +692,6 @@ LATEXMK(1L) LATEXMK(1L) 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 - - - - 1 December 2011 10 - - - - - -LATEXMK(1L) LATEXMK(1L) - - 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 @@ -724,6 +728,17 @@ LATEXMK(1L) LATEXMK(1L) Do not show a list of latexmk's rules and dependencies after processing. (This is the default.) + + + 9 December 2011 11 + + + + + +LATEXMK(1L) LATEXMK(1L) + + -silent Run commands silently, i.e., with options that reduce the amount of diagnostics generated. For example, with the default set- @@ -746,18 +761,6 @@ LATEXMK(1L) LATEXMK(1L) 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 - - - - 1 December 2011 11 - - - - - -LATEXMK(1L) LATEXMK(1L) - - make the missing files. Note that the filename may be specified without an extension, @@ -792,6 +795,18 @@ LATEXMK(1L) LATEXMK(1L) options turns the others off. + + + + 9 December 2011 12 + + + + + +LATEXMK(1L) LATEXMK(1L) + + EXAMPLES % latexmk thesis # run latex enough times to resolve cross-references @@ -817,17 +832,6 @@ CONFIGURATION/INITIALIZATION (RC) FILES Latexmk can be customized using initialization files, which are read at startup in the following order: - - - 1 December 2011 12 - - - - - -LATEXMK(1L) LATEXMK(1L) - - 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: @@ -860,12 +864,27 @@ LATEXMK(1L) LATEXMK(1L) knowledge of the Perl language by using the examples in this document as templates. Comment lines are introduced by the "#" character. + + + 9 December 2011 13 + + + + + +LATEXMK(1L) LATEXMK(1L) + + Note that command line options are obeyed in the order in which they are written; thus any RC file specified on the command line with the -r option can override previous options but can be itself overridden by later options on the command line. There is also the -e option, which allows initialization code to be specified in latexmk's command line. + For possible examples of code for in an RC file, see the directory + example_rcfiles in the distribution of latexmk (e.g., at + http://ctan.tug.org/tex-archive/support/latexmk/example_rcfiles). + HOW TO SET VARIABLES IN INITIALIZATION FILES The important variables that can be configured are described in the @@ -887,17 +906,6 @@ HOW TO SET VARIABLES IN INITIALIZATION FILES push @default_files, 'paper2'; - - - 1 December 2011 13 - - - - - -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. @@ -923,6 +931,18 @@ FORMAT OF COMMAND SPECIFICATIONS 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 + + + + 9 December 2011 14 + + + + + +LATEXMK(1L) LATEXMK(1L) + + the following setting: $latex = 'elatex --shell-escape %O %S'; @@ -956,18 +976,6 @@ FORMAT OF COMMAND SPECIFICATIONS is non-empty and does not end in a suitable character, with suitable characters being those appropriate to UNIX and MS-Win- dows, i.e., ':', '/' and '\'. %Z Name of directory for output - - - - 1 December 2011 14 - - - - - -LATEXMK(1L) LATEXMK(1L) - - files (see the configuration variable $out_dir). A directory separation character ('/') is appended if $out_dir is non-empty and does not end in a suitable character, with suitable charac- @@ -991,6 +999,18 @@ LATEXMK(1L) LATEXMK(1L) 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 + + + + 9 December 2011 15 + + + + + +LATEXMK(1L) LATEXMK(1L) + + 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 @@ -1026,18 +1046,6 @@ LATEXMK(1L) LATEXMK(1L) Notes: (1) In some circumstances, latex will always run a command detached. This is the case for a previewer in preview continuous mode, - - - - 1 December 2011 15 - - - - - -LATEXMK(1L) LATEXMK(1L) - - 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 @@ -1059,6 +1067,18 @@ LATEXMK(1L) LATEXMK(1L) traPDF.exe" %O %S'; + + + + 9 December 2011 16 + + + + + +LATEXMK(1L) LATEXMK(1L) + + (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 @@ -1096,18 +1116,6 @@ LATEXMK(1L) LATEXMK(1L) This typically is used when an appropriate command does not exist on your system. The string after the "NONE" is effectively a comment. - - - - 1 December 2011 16 - - - - - -LATEXMK(1L) LATEXMK(1L) - - 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 @@ -1128,6 +1136,17 @@ LATEXMK(1L) LATEXMK(1L) file you need to run another program after pdflatex to perform some extra processing, you could do something like: + + + 9 December 2011 17 + + + + + +LATEXMK(1L) LATEXMK(1L) + + $pdflatex = 'pdflatex --shell-escape %O %S; pst2pdf_for_latexmk %B'; @@ -1167,22 +1186,11 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES turn this setting off, i.e., it could set $auto_rc_use to zero to prevent automatic reading of the later RC files. - - - 1 December 2011 17 - - - - - -LATEXMK(1L) LATEXMK(1L) - - This variable does not affect the reading of RC files specified on the command line by the -r option. - $aux_dir [''] + $aux_dir [""] The directory in which auxiliary files (aux, log, etc) are to be written by a run of (pdf)latex. If this variable is not set, but $out_dir is set, then $aux_dir is set to $out_dir, which is @@ -1190,13 +1198,25 @@ LATEXMK(1L) LATEXMK(1L) Important note. The effect of $aux_dir, if different from $out_dir, is achieved by given (pdf)latex the -aux-directory. - Currently (Oct. 2011) this only works on the MiKTeX version of + Currently (Dec. 2011) this only works on the MiKTeX version of (pdf)latex. $banner [0] If nonzero, the banner message is printed across each page when converting the dvi file to postscript. Without modifying the + + + + 9 December 2011 18 + + + + + +LATEXMK(1L) LATEXMK(1L) + + variable $banner_message, this is equivalent to specifying the -d option. @@ -1237,17 +1257,6 @@ LATEXMK(1L) LATEXMK(1L) @BIBINPUTS = ( ".", "//server/bibfiles" ); @BIBINPUTS = ( ".", "/usr/local/texmf/bibtex/bib" ); - - - 1 December 2011 18 - - - - - -LATEXMK(1L) LATEXMK(1L) - - 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. @@ -1267,6 +1276,17 @@ LATEXMK(1L) LATEXMK(1L) Switch(es) for the biber processing program when silent mode is on. + + + 9 December 2011 19 + + + + + +LATEXMK(1L) LATEXMK(1L) + + $bibtex ["bibtex %O %S"] The BibTeX processing program. @@ -1306,18 +1326,6 @@ LATEXMK(1L) LATEXMK(1L) $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 - - - - 1 December 2011 19 - - - - - -LATEXMK(1L) LATEXMK(1L) - - for dep and aux files. (There is also extra cleaning as speci- fied by the $clean_ext, $clean_full_ext and @generated_exts variables.) @@ -1337,6 +1345,18 @@ LATEXMK(1L) LATEXMK(1L) $clean_ext = "out %R-blx.bib"; + + + + 9 December 2011 20 + + + + + +LATEXMK(1L) LATEXMK(1L) + + 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, @@ -1376,18 +1396,6 @@ LATEXMK(1L) LATEXMK(1L) Note that more than file may be given, and that the default extension is ".tex". Wild cards are allowed. The parentheses - - - - 1 December 2011 20 - - - - - -LATEXMK(1L) LATEXMK(1L) - - are because @default_files is an array variable, i.e., a sequence of filename specifications is possible. @@ -1407,6 +1415,18 @@ LATEXMK(1L) LATEXMK(1L) The variable $dvi_mode defaults to 0, but if no explicit requests are made for other types of file (postscript, pdf), then $dvi_mode will be set to 1. In addition, if a request for a file for which a .dvi file + + + + 9 December 2011 21 + + + + + +LATEXMK(1L) LATEXMK(1L) + + is a prerequisite, then $dvi_mode will be set to 1. $dvi_previewer ["start xdvi %O %S" under UNIX] @@ -1447,17 +1467,6 @@ LATEXMK(1L) LATEXMK(1L) Switch(es) for dvips program when pdf file is to be generated from ps file. - - - 1 December 2011 21 - - - - - -LATEXMK(1L) LATEXMK(1L) - - $dvips_silent_switch ["-q"] Switch(es) for dvips program when silent mode is on. @@ -1476,6 +1485,18 @@ LATEXMK(1L) LATEXMK(1L) 1=> manual update by user, which may only mean a mouse click on the viewer's window or may mean a more serious action. 2 => Send the signal, whose number is in the variable + + + + 9 December 2011 22 + + + + + +LATEXMK(1L) LATEXMK(1L) + + $dvi_update_signal. The default value under UNIX is suitable for xdvi. 3 => Viewer cannot do an update, because it locks the file. @@ -1516,18 +1537,6 @@ LATEXMK(1L) LATEXMK(1L) (Normally, a change of a source file during a run should provoke a rerun. This includes a file generated by LaTeX, e.g., an aux - - - - 1 December 2011 22 - - - - - -LATEXMK(1L) LATEXMK(1L) - - file, that is read in on subsequent runs. But after a run that results in an error, a new run should occur until the user has made a change in the files. But the user may have corrected an @@ -1546,6 +1555,18 @@ LATEXMK(1L) LATEXMK(1L) extensions. (This extension is used by the RevTeX package, for example.) + + + + 9 December 2011 23 + + + + + +LATEXMK(1L) LATEXMK(1L) + + $go_mode [0] If nonzero, process files regardless of timestamps, and is then equivalent to the -g option. @@ -1586,18 +1607,6 @@ LATEXMK(1L) LATEXMK(1L) ple patterns by a vertical bar character (indicating "alterna- tion" in the jargon of regular expressions). For example, - - - - 1 December 2011 23 - - - - - -LATEXMK(1L) LATEXMK(1L) - - $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: |^%%Title: '; @@ -1616,6 +1625,18 @@ LATEXMK(1L) LATEXMK(1L) The program called to locate a source file when the name alone is not sufficient. Most filenames used by latexmk have suffi- cient path information to be found directly. But sometimes, + + + + 9 December 2011 24 + + + + + +LATEXMK(1L) LATEXMK(1L) + + notably when .bib files are found from the log file of a bibtex or biber run, the name of the file, but not its path is known. The program specified by $kpsewhich is used to find it. @@ -1656,18 +1677,6 @@ LATEXMK(1L) LATEXMK(1L) remove_input_ext. They are used as in the following examples are possible lines in an initialization file: - - - - 1 December 2011 24 - - - - - -LATEXMK(1L) LATEXMK(1L) - - remove_input_ext( 'latex', 'tex' ); removes the extension 'tex' from latex_input_extensions @@ -1686,6 +1695,18 @@ LATEXMK(1L) LATEXMK(1L) Switch(es) for the LaTeX processing program when silent mode is on. + + + + 9 December 2011 25 + + + + + +LATEXMK(1L) LATEXMK(1L) + + If you use MikTeX, you may prefer the results if you configure the options to include -c-style-errors, e.g., by the following line in an initialization file @@ -1726,18 +1747,6 @@ LATEXMK(1L) LATEXMK(1L) If gsview is installed in a different directory, you will need to make the appropriate change. Note the double quotes around - - - - 1 December 2011 25 - - - - - -LATEXMK(1L) LATEXMK(1L) - - the name: this is necessary because one part of the command name ("Program Files") contains a space which would otherwise be mis- interpreted. @@ -1757,6 +1766,17 @@ LATEXMK(1L) LATEXMK(1L) resolve cross-references, etc. The default value covers all normal cases. + + + 9 December 2011 26 + + + + + +LATEXMK(1L) LATEXMK(1L) + + (Note that the "etc" covers a lot of cases where one run of latex/pdflatex generates files to be read in on a later run.) @@ -1769,13 +1789,13 @@ LATEXMK(1L) LATEXMK(1L) no viewer is running. - $out_dir [''] + $out_dir [""] The directory in which output files are to be written by a run of (pdf)latex. See also the variable $aux_dir. The effect of this variable is achieved by using the -output- directory option of (pdf)latex. This exists in the usual cur- - rent (Oct. 2011) implementations, i.e., MiKTeX and TeXLive. But + rent (Dec. 2011) implementations, i.e., MiKTeX and TeXLive. But it may not be present in other versions. @@ -1798,18 +1818,6 @@ LATEXMK(1L) LATEXMK(1L) %pdflatex_input_extensions This variable specifies the extensions tried by latexmk when it finds that a pdfLaTeX run resulted in an error that a file has - - - - 1 December 2011 26 - - - - - -LATEXMK(1L) LATEXMK(1L) - - not been found, and the file is given without an extension. This typically happens when LaTeX commands of the form \input{file} or \includegraphics{figure}, when the relevant @@ -1827,6 +1835,18 @@ LATEXMK(1L) LATEXMK(1L) remove_input_ext. They are used as in the following examples are possible lines in an initialization file: + + + + 9 December 2011 27 + + + + + +LATEXMK(1L) LATEXMK(1L) + + remove_input_ext( 'pdflatex', 'tex' ); removes the extension 'tex' from pdflatex_input_extensions @@ -1871,17 +1891,6 @@ LATEXMK(1L) LATEXMK(1L) mand, this is the command that is run. See the information for the variable $pdf_update_method. - - - 1 December 2011 27 - - - - - -LATEXMK(1L) LATEXMK(1L) - - $pdf_update_method [1 under UNIX, 3 under MS-Windows] How the pdf viewer updates its display when the pdf file has changed. See the information on the variable $dvi_update_method @@ -1897,6 +1906,17 @@ LATEXMK(1L) LATEXMK(1L) Arranging to use a command to get a previewer explicitly updated requires three variables to be set. For example: + + + 9 December 2011 28 + + + + + +LATEXMK(1L) LATEXMK(1L) + + $pdf_previewer = "start xpdf -remote %R %O %S"; $pdf_update_method = 4; $pdf_update_command = "xpdf -remote %R -reload"; @@ -1942,18 +1962,6 @@ LATEXMK(1L) LATEXMK(1L) settings, see the command line options -view=, and the variable $view. - - - - 1 December 2011 28 - - - - - -LATEXMK(1L) LATEXMK(1L) - - $printout_mode [0] If nonzero, print the document using lpr. Equivalent to the -p option. This is recommended not to be set from an RC file, oth- @@ -1967,6 +1975,18 @@ LATEXMK(1L) LATEXMK(1L) The -pvc option uses the command specified by the variable $pscmd to determine if there is an already running previewer, and to find the process ID (needed if latexmk needs to signal + + + + 9 December 2011 29 + + + + + +LATEXMK(1L) LATEXMK(1L) + + the previewer about file changes). Each line of the output of this command is assumed to correspond @@ -2015,28 +2035,28 @@ LATEXMK(1L) LATEXMK(1L) $ps_update_method [0 under UNIX, 1 under MS-Windows] How the postscript viewer updates its display when the ps file has changed. See the information on the variable + $dvi_update_method for the codes. (Note that information needs + be changed slightly so that for the value 4, to run a command to + do the update, the command is specified by the variable + $ps_update_command, and for the value 2, to specify update by + signal, the signal is specified by $ps_update_signal.) + $ps_update_signal [Under UNIX: SIGHUP, which is a system-dependent + value] + The number of the signal that is sent to the pdf viewer when it - 1 December 2011 29 + 9 December 2011 30 -LATEXMK(1L) LATEXMK(1L) - $dvi_update_method for the codes. (Note that information needs - be changed slightly so that for the value 4, to run a command to - do the update, the command is specified by the variable - $ps_update_command, and for the value 2, to specify update by - signal, the signal is specified by $ps_update_signal.) +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 is updated by sending a signal -- see $ps_update_method. The default value is the one appropriate for gv on a UNIX system. @@ -2082,16 +2102,23 @@ LATEXMK(1L) LATEXMK(1L) 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 - changes when running with the -pvc option. This is subject to a - minimum of one second delay, except that zero delay is also - allowed. + $search_path_separator [See below for default] + The character separating paths in the environment variables TEX- + INPUTS, BIBINPUTS, and BSTINPUTS. This variable is mainly used + by latexmk when the -outdir, -output-directory, -auxdir, and/or + -aux-directory options are used. In that case latexmk needs to + communicate appropriately modified search paths to $bibtex, + dvipdf, dvips, and (pdf)latex. + [Comment to technically savvy readers: (pdf)latex doesn't actu- + ally need the modified search path, because it corrects it + internally. But, surprisingly, dvipdf and dvips do, because + sometimes graphics files get generated in the output or aux - 1 December 2011 30 + + 9 December 2011 31 @@ -2100,168 +2127,187 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - A value of exactly 0 gives no delay, and typically results in + directories.] + + The default under MSWin and Cygwin is ';' and under UNIX-like + operating systems (including Linux and OS-X) is ':'. Normally + the defaults give correct behavior. But there can be difficul- + ties if your operating system is of one kind, but some of your + software is running under an emulator for the other kind of + operating system; in that case you'll need to find out what is + needed, and set $search_path_separator explicitly. (The same + goes, of course, for unusual operating systems that are not in + the MSWin, Linux, OS-X, Unix collection.) + + + $sleep_time [2] + 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 + allowed. + + 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 + 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 + 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). + Which kind of file is to be previewed if a previewer is used. + The possible values are "default", "dvi", "ps", "pdf". The -CUSTOM DEPENDENCIES - In any RC file a set of custom dependencies can be set up to convert a - file with one extension to a file with another. An example use of this - would be to allow latexmk to convert a .fig file to .eps to be included - in the .tex file. - The old method of configuring latexmk was to directly manipulate the - @cus_dep_list array that contains information defining the custom - dependencies. This method still works. But now there are subroutines - that allow convenient manipulations of the custom dependency list. - These are + 9 December 2011 32 - add_cus_dep( fromextension, toextension, must, subroutine ) - remove_cus_dep( fromextension, toextension ) - show_cus_dep() - 1 December 2011 31 +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 + would be to allow latexmk to convert a .fig file to .eps to be included + in the .tex file. -LATEXMK(1L) LATEXMK(1L) + The old method of configuring latexmk was to directly manipulate the + @cus_dep_list array that contains information defining the custom + dependencies. This method still works. But now there are subroutines + that allow convenient manipulations of the custom dependency list. + These are + add_cus_dep( fromextension, toextension, must, subroutine ) + remove_cus_dep( fromextension, toextension ) + show_cus_dep() The custom dependency is a list of rules, each of which is specified as follow: from extension: - The extension of the file we are converting from (e.g. "fig"). + The extension of the file we are converting from (e.g. "fig"). It is specified without a period. to extension: The extension of the file we are converting to (e.g. "eps"). It is specified without a period. - must: If non-zero, the file from which we are converting must exist, - if it doesn't exist latexmk will give an error message and exit + must: If non-zero, the file from which we are converting must exist, + if it doesn't exist latexmk will give an error message and exit unless the -f option is specified. If must is zero and the file we are converting from doesn't exist, then no action is taken. function: - The name of the subroutine that latexmk should call to perform - the file conversion. The first argument to the subroutine is + The name of the subroutine that latexmk should call to perform + the file conversion. The first argument to the subroutine is the base name of the file to be converted without any extension. - The subroutines are declared in the syntax of Perl. The func- - tion should return 0 if it was successful and a nonzero number + The subroutines are declared in the syntax of Perl. The func- + tion should return 0 if it was successful and a nonzero number if it failed. - It is invoked whenever latexmk detects that a run of latex/pdflatex - needs to read a file, like a graphics file, whose extension is the to- + It is invoked whenever latexmk detects that a run of latex/pdflatex + needs to read a file, like a graphics file, whose extension is the to- extension of a custom dependency. Then latexmk examines whether a file - exists with the same name, but with the corresponding from-extension, - as specified in the custom-dependency rule. If it does, then whenever - the destination file (the one with the to-extension) is out-of-date + exists with the same name, but with the corresponding from-extension, + as specified in the custom-dependency rule. If it does, then whenever + the destination file (the one with the to-extension) is out-of-date with respect to the corresponding source file. - To make the new destination file, the Perl subroutine specified in the + To make the new destination file, the Perl subroutine specified in the rule is invoked, with an argument that is the base name of the files in - question. Simple cases just involve a subroutine invoking an external - program; this can be done by following the templates below, even by - those without knowledge of the Perl programming language. Of course, + question. Simple cases just involve a subroutine invoking an external + program; this can be done by following the templates below, even by + those without knowledge of the Perl programming language. Of course, experts could do something much more elaborate. - One other item in each custom-dependency rule labelled "must" above - specifies how the rule should be applied when the source file fails to - exist. + One other item in each custom-dependency rule labelled "must" above - A simple and typical example of code in an initialization rcfile is - add_cus_dep( 'fig', 'eps', 0, 'fig2eps' ); - sub fig2eps { - system("fig2dev -Leps $_[0].fig $_[0].eps"); - } - The first line adds a custom dependency that converts a file with - extension "fig", as created by the xfig program, to an encapsulated - postscript file, with extension "eps". The remaining lines define a - subroutine that carries out the conversion. If a rule for converting - "fig" to "eps" files already exists (e.g., from a previously read-in - initialization file), the latexmk will delete this rule before making - the new one. + 9 December 2011 33 - Suppose latexmk is using this rule to convert a file "figure.fig" to - "figure.eps". Then it will invoke the fig2eps subroutine defined in - the above code with a single argument "figure", which is the basename - 1 December 2011 32 +LATEXMK(1L) LATEXMK(1L) + 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 -LATEXMK(1L) LATEXMK(1L) + add_cus_dep( 'fig', 'eps', 0, 'fig2eps' ); + sub fig2eps { + system("fig2dev -Leps $_[0].fig $_[0].eps"); + } + The first line adds a custom dependency that converts a file with + extension "fig", as created by the xfig program, to an encapsulated + postscript file, with extension "eps". The remaining lines define a + subroutine that carries out the conversion. If a rule for converting + "fig" to "eps" files already exists (e.g., from a previously read-in + initialization file), the latexmk will delete this rule before making + the new one. - of each of the files (possibly with a path component). This argument - is referred to by Perl as $_[0]. In the example above, the subroutine + Suppose latexmk is using this rule to convert a file "figure.fig" to + "figure.eps". Then it will invoke the fig2eps subroutine defined in + the above code with a single argument "figure", which is the basename + of each of the files (possibly with a path component). This argument + is referred to by Perl as $_[0]. In the example above, the subroutine uses the Perl command system to invoke the program fig2dev. The double quotes around the string are a Perl idiom that signify that each string - of the form of a variable name, $_[0] in this case, is to be substi- + of the form of a variable name, $_[0] in this case, is to be substi- tuted by its value. - If the return value of the subroutine is non-zero, then latexmk will - assume an error occurred during the execution of the subroutine. In - the above example, no explicit return value is given, and instead the - return value is the value returned by the last (and only) statement, + If the return value of the subroutine is non-zero, then latexmk will + assume an error occurred during the execution of the subroutine. In + the above example, no explicit return value is given, and instead the + return value is the value returned by the last (and only) statement, i.e., the invocation of system, which returns the value 0 on success. - If you use filenames with spaces in them, and if your LaTeX system and - all other relevant software correctly handle such filenames, then you - could put single quotes around filenames in the command line that is + If you use filenames with spaces in them, and if your LaTeX system and + all other relevant software correctly handle such filenames, then you + could put single quotes around filenames in the command line that is executed: add_cus_dep( 'fig', 'eps', 0, 'fig2eps' ); @@ -2269,15 +2315,15 @@ LATEXMK(1L) LATEXMK(1L) system("fig2dev -Lps '$_[0].fig' '$_[0].eps'"); } - This causes the invocation of the fig2dev program to have quoted file- + This causes the invocation of the fig2dev program to have quoted file- names; it should therefore work with filenames containing spaces. How- - ever, not all software deals correctly with filenames that contain - spaces. Moreover, the rules, if any, for quoting filenames vary - between operating systems, command shells and individual pieces of + ever, not all software deals correctly with filenames that contain + spaces. Moreover, the rules, if any, for quoting filenames vary + between operating systems, command shells and individual pieces of software, so this code may not always work. - If you use pdflatex instead of latex, then you will probably prefer to - convert your graphics files to pdf format, in which case you would + If you use pdflatex instead of latex, then you will probably prefer to + convert your graphics files to pdf format, in which case you would replace the above code in an initialization file by add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' ); @@ -2285,43 +2331,43 @@ LATEXMK(1L) LATEXMK(1L) system("fig2dev -Lpdf $_[0].fig $_[0].pdf"); } - If you have some general custom dependencies defined in the system or - user initialization file, you may find that for a particular project - they are undesirable. So you might want to delete the unneeded ones. - For example, you remove any "fig" to "eps" rule by the line - remove_cus_dep( 'fig', 'eps' ); - If you have complicated sets of custom dependencies, you may want to - get a listing of the custom dependencies. This is done by using the - line - show_cus_dep(); + 9 December 2011 34 - in an initialization file. - Another example of a custom dependency overcomes a limitation of - latexmk concerning index files. The only index-file conversion built- - in to latexmk is from an ".idx" file written on one run of latex/pdfla- - tex to an ".ind" file to be read in on a subsequent run. But with the - index.sty package you can create extra indexes with extensions that you - configure. Latexmk does not know how to deduce the extensions from the - information it has. But you can easily write a custom dependency. For - 1 December 2011 33 +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' ); + If you have complicated sets of custom dependencies, you may want to + get a listing of the custom dependencies. This is done by using the + line -LATEXMK(1L) LATEXMK(1L) + show_cus_dep(); + in an initialization file. - example if your latex file uses the command "\newindex{spe- + Another example of a custom dependency overcomes a limitation of + latexmk concerning index files. The only index-file conversion built- + in to latexmk is from an ".idx" file written on one run of latex/pdfla- + tex to an ".ind" file to be read in on a subsequent run. But with the + index.sty package you can create extra indexes with extensions that you + configure. Latexmk does not know how to deduce the extensions from the + information it has. But you can easily write a custom dependency. For + example if your latex file uses the command "\newindex{spe- cial}{ndx}{nnd}{Special index}" you will need to convert files with the - extension .ndx to .nnd. The following lines in an initialization RC + extension .ndx to .nnd. The following lines in an initialization RC file will cause this to happen: add_cus_dep('ndx', 'nnd', 0, 'makendx2nnd'); @@ -2329,37 +2375,48 @@ LATEXMK(1L) LATEXMK(1L) system("makeindex -o $_[0].nnd $_[0].ndx"); } - (You will need to modify this code if you use filenames with spaces in + (You will need to modify this code if you use filenames with spaces in them, to provide correct quoting of the filenames.) - Those of you with experience with Makefiles, will undoubtedly be con- + Those of you with experience with Makefiles, will undoubtedly be con- cerned that the .ndx file is written during a run of latex/pdflatex and - is always later than the .nnd last read in. Thus the .nnd appears to - be perpetually out-of-date. This situation, of circular dependencies, + is always later than the .nnd last read in. Thus the .nnd appears to + be perpetually out-of-date. This situation, of circular dependencies, is endemic to latex, and latexmk in its current version works correctly - with circular dependencies. It examines the contents of the files (by - use of an md5 checksum), and only does a remake when the file contents + with circular dependencies. It examines the contents of the files (by + use of an md5 checksum), and only does a remake when the file contents have actually changed. - Of course if you choose to write random data to the .nnd (or and .aux - file, etc) that changes on each new run, then you will have a problem. - For real experts: See the %hash_cal_ignore_pattern if you have to deal + Of course if you choose to write random data to the .nnd (or and .aux + file, etc) that changes on each new run, then you will have a problem. + For real experts: See the %hash_cal_ignore_pattern if you have to deal with such problems. Glossaries can be dealt with similarly. OLD METHOD OF DEFINING CUSTOM DEPENDENCIES - In previous versions of latexmk, the only method of defining custom - dependencies was to directly manipulate the table of custom dependen- + In previous versions of latexmk, the only method of defining custom + dependencies was to directly manipulate the table of custom dependen- cies. This is contained in the @cus_dep_list array. It is an array of - strings, and each string in the array has four items in it, each sepa- - rated by a space, the from-extension, the to-extension, the "must" - item, and the name of the subroutine for the custom dependency. These + 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. + + + 9 December 2011 35 + + + + + +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 + 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"; @@ -2367,62 +2424,50 @@ OLD METHOD OF DEFINING CUSTOM DEPENDENCIES system("fig2dev -Lps $_[0].fig $_[0].eps"); } - This method still works, and is equivalent to the earlier code using - the add_cus_dep subroutine, except that it doesn't delete any previous - custom-dependency for the same conversion. So the new method is + This method still works, and is equivalent to the earlier code using + the add_cus_dep subroutine, except that it doesn't delete any previous + custom-dependency for the same conversion. So the new method is preferable. USING latexmk WITH make - This section is targeted only at advanced users who use the make pro- + 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. - - - - 1 December 2011 34 - - - - - -LATEXMK(1L) LATEXMK(1L) - - - 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 + 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 + 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 + 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, + 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 + 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. + 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 + 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 @@ -2431,32 +2476,9 @@ LATEXMK(1L) LATEXMK(1L) %.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 - 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 - - 1 December 2011 35 + 9 December 2011 36 @@ -2465,11 +2487,33 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + (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 + 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 + 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 @@ -2488,37 +2532,49 @@ LATEXMK(1L) LATEXMK(1L) %.pdf : %.fig fig2dev -Lpdf $< $@ - (Again, the lines containing the commands for the rules should be + (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 + 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- + 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 + 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 + from .fig files produced by the xfig program; these are commonly used + for graphics insertions in LaTeX documents. Latexmk is arranged to + + + + 9 December 2011 37 + + + + + +LATEXMK(1L) LATEXMK(1L) + + + 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 - 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 + pdflatex; such files should not be in the dependency list. The -e + 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" + 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.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 + Thus we now have a method by which all the subsidiary processing is delegated to make. @@ -2527,11 +2583,46 @@ SEE ALSO 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 + instead.) + +THANKS TO + Authors of previous versions. Many users with their feedback, and + especially David Coppit (username david at node coppit.org) who made + many useful suggestions that contributed to version 3, and Herbert + Schulz. (Please note that the e-mail addresses are not written in + their standard form to avoid being harvested by worms and viruses.) + +AUTHOR + Current version, by John Collins (username collins at node + phys.psu.edu). (Version 4.30). + + 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) + Original script called "go" by David J. Musliner (RCS Version 3.2) - 1 December 2011 36 + + + + + 9 December 2011 38 @@ -2540,37 +2631,10 @@ BUGS LATEXMK(1L) LATEXMK(1L) - 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 - instead.) -THANKS TO - Authors of previous versions. Many users with their feedback, and - especially David Coppit (username david at node coppit.org) who made - many useful suggestions that contributed to version 3, and Herbert - Schulz. (Please note that the e-mail addresses are not written in - their standard form to avoid being harvested by worms and viruses.) -AUTHOR - Current version, by John Collins (username collins at node - phys.psu.edu). (Version 4.28c). - 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) - Original script called "go" by David J. Musliner (RCS Version 3.2) @@ -2606,6 +2670,30 @@ AUTHOR - 1 December 2011 37 + + + + + + + + + + + + + + + + + + + + + + + + + 9 December 2011 39 |