diff options
| author | Karl Berry <karl@freefriends.org> | 2009-04-11 22:45:11 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2009-04-11 22:45:11 +0000 |
| commit | 34d005dca21a959191bb56ff1b4b70cc022edb2a (patch) | |
| tree | ece0e335ce6f8eeedc38e8950c5122e5757064fb /Master/texmf-dist/doc/support | |
| parent | 32f195b8cc3e111152dac092ced8c20ba6ba3fb3 (diff) | |
latexmk update (11apr)
git-svn-id: svn://tug.org/texlive/trunk@12697 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support')
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/README | 4 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/latexmk.1 | 83 | ||||
| -rwxr-xr-x | Master/texmf-dist/doc/support/latexmk/latexmk.bat | 10 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/latexmk.pdf | bin | 148039 -> 155123 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/support/latexmk/latexmk.txt | 636 |
5 files changed, 452 insertions, 281 deletions
diff --git a/Master/texmf-dist/doc/support/latexmk/README b/Master/texmf-dist/doc/support/latexmk/README index aa1cc45a7e4..7a3b07a87c4 100644 --- a/Master/texmf-dist/doc/support/latexmk/README +++ b/Master/texmf-dist/doc/support/latexmk/README @@ -1,4 +1,4 @@ -Hi, and thanks for checking out latexmk. (Version 4.01, 24 September 2008) +Hi, and thanks for checking out latexmk. (Version 4.05, 10 April 2009) Latexmk completely automates the process of generating a LaTeX document. Essentially, it is a highly specialized cousin of the general make @@ -88,7 +88,7 @@ I hope you find this useful. John Collins ---------------------------- "latexmk -h" ---------------------------- -Latexmk 4.03: Automatic LaTeX document generation routine +Latexmk 4.05: Automatic LaTeX document generation routine Usage: latexmk [latexmk_options] [filename ...] diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.1 b/Master/texmf-dist/doc/support/latexmk/latexmk.1 index 25132b0cfee..c50258b3f28 100644 --- a/Master/texmf-dist/doc/support/latexmk/latexmk.1 +++ b/Master/texmf-dist/doc/support/latexmk/latexmk.1 @@ -1,4 +1,4 @@ -.TH LATEXMK 1L "22 December 2008" "" +.TH LATEXMK 1L "10 April 2009" "" .SH NAME latexmk \- generate LaTeX document .SH SYNOPSIS @@ -14,6 +14,9 @@ source file for a document, and it issues the appropriate sequence of commands to generate a .dvi, .ps, .pdf and/or hardcopy version of the document. .PP +By default \fIlatexmk\fR will run the commands necessary to generate a +.dvi file. +.PP \fILatexmk\fR can also be set to run continuously with a suitable previewer. In that case the LaTeX program, etc, are rerun whenever one of the source files is modified, and the previewer automatically @@ -808,9 +811,14 @@ filename specifications is possible. The dvi file filter to be run on the newly produced dvi file before other processing. Equivalent to specifying the \fB-dF\fR option. .TP -.B $dvi_mode [0] +.B $dvi_mode [See below for default] If nonzero, generate a dvi version of the document. Equivalent to the \fB-dvi\fR option. +.PP +The variable $dvi_mode defaults to 0, but if no explicit requests are +made for other types of file (postscript, pdf), then $dvi_mode will be +set to 1. In addition, if a request for a file for which a .dvi file +is a prerequisite, then $dvi_mode will be set to 1. .TP .B $dvi_previewer ["start xdvi %O %S" under UNIX] The command to invoke a dvi-previewer. @@ -979,6 +987,39 @@ but also specify options to the program. E.g., $latex = "latex --src-specials"; .TP +.B %latex_input_extensions +This variable specifies the extensions tried by latexmk when it finds +that a LaTeX run resulted in an error that a file has not been found, +and the file is given without an extension. This typically happens when +LaTeX commands of the form \input{file} or \includegraphics{figure}, +when the relevant source file does not exist. + +In this situation, latexmk searches for custom dependencies to make +the missing file(s), but restricts it to the extensions specified by +the variable %latex_input_extensions. The default extensions are +'tex' and 'eps'. + +(For Perl experts: %latex_input_extensions is a hash whose keys are +the extensions. The values are irrelevant.) Two subroutines are +provided for manipulating this and the related variable +%pdflatex_input_extensions, add_input_ext and remove_input_ext. They +are used as in the following examples are possible lines in an +initialization file: + + remove_input_ext( 'latex', 'tex' ); + +removes the extension 'tex' from latex_input_extensions + + add_input_ext( 'latex', 'asdf' ); + +add the extension 'asdf to latex_input_extensions. (Naturally with +such an extension, you should have made an appropriate custom +dependency for latexmk, and should also have done the appropriate +programming in the LaTeX source file to enable the file to be read. +The standard extensions are handled by LaTeX and its graphics/graphicx +packages. + +.TP .B $latex_silent_switch ["-interaction=batchmode"] Switch(es) for the LaTeX processing program when silent mode is on. Under MS-Windows, the default value is changed to @@ -1054,6 +1095,39 @@ Equivalent to the \fB-pdf-\fR, \fB-pdf\fR, \fB-pdfdvi\fR, The LaTeX processing program in the version that makes a pdf file instead of a dvi file. .TP +.B %pdflatex_input_extensions +This variable specifies the extensions tried by latexmk when it finds +that a pdfLaTeX run resulted in an error that a file has not been found, +and the file is given without an extension. This typically happens when +LaTeX commands of the form \input{file} or \includegraphics{figure}, +when the relevant source file does not exist. + +In this situation, latexmk searches for custom dependencies to make +the missing file(s), but restricts it to the extensions specified by +the variable %pdflatex_input_extensions. The default extensions are +'tex', 'pdf', 'jpg, and 'png'. + +(For Perl experts: %pdflatex_input_extensions is a hash whose keys are +the extensions. The values are irrelevant.) Two subroutines are +provided for manipulating this and the related variable +%latex_input_extensions, add_input_ext and remove_input_ext. They +are used as in the following examples are possible lines in an +initialization file: + + remove_input_ext( 'pdflatex', 'tex' ); + +removes the extension 'tex' from pdflatex_input_extensions + + add_input_ext( 'pdflatex', 'asdf' ); + +add the extension 'asdf to pdflatex_input_extensions. (Naturally with +such an extension, you should have made an appropriate custom +dependency for latexmk, and should also have done the appropriate +programming in the LaTeX source file to enable the file to be read. +The standard extensions are handled by pdflatex and its graphics/graphicx +packages.) + +.TP .B $pdflatex_silent_switch ["-interaction=batchmode"] Switch(es) for the pdflatex program (specified in the variable \fI$pdflatex\fR when silent mode is on. @@ -1121,6 +1195,9 @@ corresponds to the process ID. The first word in the line is numbered .B $postscript_mode [0] If nonzero, generate a postscript version of the document. Equivalent to the \fB-ps\fR option. +.PP +If some other request is made for which a postscript file is needed, +then $postscript_mode will be set to 1. .TP .B $preview_continuous_mode [0] If nonzero, run a previewer to view the document, and @@ -1462,7 +1539,7 @@ e-mail addresses are not written in their standard form to avoid being harvested by worms and viruses.) .SH AUTHOR Current version, by John Collins (username collins at node phys.psu.edu). -(Version 4.03). +(Version 4.05). Released version can be obtained from CTAN: <http://www.tug.org/tex-archive/support/latexmk/>, and from the diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.bat b/Master/texmf-dist/doc/support/latexmk/latexmk.bat index 48e01d6e5e1..f119082adac 100755 --- a/Master/texmf-dist/doc/support/latexmk/latexmk.bat +++ b/Master/texmf-dist/doc/support/latexmk/latexmk.bat @@ -1,5 +1,5 @@ -Rem Execute latexmk.pl, searching for it in the PATH -Rem Assume perl is in the PATH. If not, you should replace 'perl' by -Rem the full pathname of the perl executable, e.g., 'C:\perl\bin\perl.exe' - -perl -S latexmk.pl %1 %2 %3 %4 %5 %6 %7 %8 %9 +Rem Execute latexmk.pl, searching for it in the PATH
+Rem Assume perl is in the PATH. If not, you should replace 'perl' by
+Rem the full pathname of the perl executable, e.g., 'C:\perl\bin\perl.exe'
+
+perl -S latexmk.pl %1 %2 %3 %4 %5 %6 %7 %8 %9
diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.pdf b/Master/texmf-dist/doc/support/latexmk/latexmk.pdf Binary files differindex 1220cb0574e..d804f857a68 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 1e67ad04111..2248a598c3e 100644 --- a/Master/texmf-dist/doc/support/latexmk/latexmk.txt +++ b/Master/texmf-dist/doc/support/latexmk/latexmk.txt @@ -14,6 +14,8 @@ DESCRIPTION and it issues the appropriate sequence of commands to generate a .dvi, .ps, .pdf and/or hardcopy version of the document. + By default latexmk will run the commands necessary to generate a + Latexmk can also be set to run continuously with a suitable previewer. In that case the LaTeX program, etc, are rerun whenever one of the source files is modified, and the previewer automatically updates the @@ -56,8 +58,6 @@ DESCRIPTION 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. - @@ -70,6 +70,8 @@ DESCRIPTION LATEXMK(1L) LATEXMK(1L) + 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 @@ -122,12 +124,10 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE -bi <intensity> How dark to print the banner message. A decimal number between 0 and 1. 0 is black and 1 is white. The default is 0.95, which - is OK unless your toner cartridge is getting low. - - 22 December 2008 2 + 10 April 2009 2 @@ -136,6 +136,8 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE LATEXMK(1L) LATEXMK(1L) + 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 @@ -189,11 +191,10 @@ LATEXMK(1L) LATEXMK(1L) -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, - 22 December 2008 3 + 10 April 2009 3 @@ -202,6 +203,7 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + ".dviF". All extra processing (e.g. conversion to postscript, preview, printing) will then be performed on this filtered dvi file. @@ -259,7 +261,7 @@ LATEXMK(1L) LATEXMK(1L) - 22 December 2008 4 + 10 April 2009 4 @@ -322,10 +324,11 @@ LATEXMK(1L) LATEXMK(1L) $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 - 22 December 2008 5 + 10 April 2009 5 @@ -334,7 +337,6 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - This option is incompatible with the -pv and -pvc options, so it turns them off. -pdf Generate pdf version of document using pdflatex. @@ -388,19 +390,19 @@ LATEXMK(1L) LATEXMK(1L) viewer will be used. This option is incompatible with the -p and -pvc options, so it turns them off. + -pv- Turn off -pv. - 22 December 2008 6 + 10 April 2009 6 -LATEXMK(1L) LATEXMK(1L) +LATEXMK(1L) LATEXMK(1L) - -pv- Turn off -pv. -pvc Run a file previewer and continually update the .dvi, .ps, and/or .pdf files whenever changes are made to source files (see @@ -454,21 +456,21 @@ LATEXMK(1L) LATEXMK(1L) 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 - 22 December 2008 7 + 10 April 2009 7 -LATEXMK(1L) LATEXMK(1L) +LATEXMK(1L) LATEXMK(1L) - 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 statements); they are executed when the -r option is encountered during latexmk's parsing of its command line. See the -e option @@ -521,20 +523,19 @@ EXAMPLES keep running, watching for source file changes. + % latexmk -c # remove .aux, .log, .bbl, .blg, .dvi, + .pdf, .ps & .bbl files - 22 December 2008 8 - + 10 April 2009 8 -LATEXMK(1L) LATEXMK(1L) - % latexmk -c # remove .aux, .log, .bbl, .blg, .dvi, - .pdf, .ps & .bbl files +LATEXMK(1L) LATEXMK(1L) CONFIGURATION/INITIALIZATION (RC) FILES @@ -587,21 +588,22 @@ HOW TO SET VARIABLES IN INITIALIZATION FILES for the setting of a numeric variable, and + @default_files = ('paper', 'paper1'); + for the setting of an array of strings. It is possible to append an + item to an array variable as follows: - 22 December 2008 9 + 10 April 2009 9 -LATEXMK(1L) LATEXMK(1L) - @default_files = ('paper', 'paper1'); - for the setting of an array of strings. It is possible to append an - item to an array variable as follows: +LATEXMK(1L) LATEXMK(1L) + push @default_files, 'paper2'; @@ -653,10 +655,15 @@ FORMAT OF COMMAND SPECIFICATIONS %T The name of the primary tex file. + The distinction between %B and %R needs a bit of care, since they are + often the same, but not always. For example on a simple document, the + basename of a bibtex run is the same as for the texfile. But in a doc- + ument with several bibliographies, the bibliography files will have a + variety of names. Since bibtex is invoked with the basename of the - 22 December 2008 10 + 10 April 2009 10 @@ -665,11 +672,6 @@ FORMAT OF COMMAND SPECIFICATIONS 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 - 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 be @@ -721,21 +723,22 @@ LATEXMK(1L) LATEXMK(1L) Using MS-Windows file associations: A useful trick under modern ver- sions of MS-Windows (e.g., WinXP) is to use just the command + $dvi_previewer = 'start %S'; + Under recent versions of MS-Windows, this will cause to be run whatever + program the system has associated with dvi files. (The same applies - 22 December 2008 11 + 10 April 2009 11 -LATEXMK(1L) LATEXMK(1L) - $dvi_previewer = 'start %S'; +LATEXMK(1L) LATEXMK(1L) + - Under recent versions of MS-Windows, this will cause to be run whatever - program the system has associated with dvi files. (The same applies for a postscript viewer and a pdf viewer.) Not using a certain command: If a command is not to be run, the command @@ -788,9 +791,13 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES and the postscript file is always generated, even if it is newer than the dvi file. + $banner_intensity [0.95] + Equivalent to the -bi option, this is a decimal number between 0 + and 1 that specifies how dark to print the banner message. 0 is - 22 December 2008 12 + + 10 April 2009 12 @@ -799,9 +806,6 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES LATEXMK(1L) LATEXMK(1L) - $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 black, 1 is white. The default is just right if your toner car- tridge isn't running too low. @@ -854,20 +858,20 @@ LATEXMK(1L) LATEXMK(1L) $cleanup_includes_generated [0] If nonzero, specifies that cleanup also deletes files that are detected in log file as being generated (see the \openout lines + in the log file). It will also include files made from these + first generation generated files. - 22 December 2008 13 + 10 April 2009 13 -LATEXMK(1L) LATEXMK(1L) +LATEXMK(1L) LATEXMK(1L) - 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 @@ -921,10 +925,13 @@ LATEXMK(1L) LATEXMK(1L) are because @default_files is an array variable, i.e., a sequence of filename specifications is possible. + $dvi_filter [empty] + The dvi file filter to be run on the newly produced dvi file + before other processing. Equivalent to specifying the -dF - 22 December 2008 14 + 10 April 2009 14 @@ -933,65 +940,65 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - $dvi_filter [empty] - The dvi file filter to be run on the newly produced dvi file - before other processing. Equivalent to specifying the -dF option. - $dvi_mode [0] + $dvi_mode [See below for default] If nonzero, generate a dvi version of the document. Equivalent to the -dvi option. + The variable $dvi_mode defaults to 0, but if no explicit requests are + made for other types of file (postscript, pdf), then $dvi_mode will be + set to 1. In addition, if a request for a file for which a .dvi file + is a prerequisite, then $dvi_mode will be set to 1. + $dvi_previewer ["start xdvi %O %S" under UNIX] - The command to invoke a dvi-previewer. [Default is "start" - under MS-WINDOWS; under more recent versions of Windows, this - will cause to be run whatever command the system has associated + The command to invoke a dvi-previewer. [Default is "start" + under MS-WINDOWS; under more recent versions of Windows, this + will cause to be run whatever command the system has associated with .dvi files.] $dvi_previewer_landscape ["start xdvi %O %S"] The command to invoke a dvi-previewer in landscape mode. [Default is "start" under MS-WINDOWS; under more recent versions - of Windows, this will cause to be run whatever command the sys- + of Windows, this will cause to be run whatever command the sys- tem has associated with .dvi files.] $dvipdf ["dvipdf %O %S %D"] Command to convert dvi to pdf file. A common reconfiguration is - to use the dvipdfm command, which needs its arguments in a dif- + to use the dvipdfm command, which needs its arguments in a dif- ferent order: $dvipdf = "dvipdfm %O -o %D %S"; - WARNING: The default dvipdf script generates pdf files with + 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 + 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 + The program to used as a filter to convert a .dvi file to a .ps + file. If pdf is going to be generated from pdf, then the value of the $dvips_pdf_switch -- see below -- will be included in the options substituted for "%O". $dvips_landscape ["dvips -tlandscape %O -o %D %S"] - The program to used as a filter to convert a .dvi file to a .ps + The program to used as a filter to convert a .dvi file to a .ps file in landscape mode. $dvips_pdf_switch ["-P pdf"] - Switch(es) for dvips program when pdf file is to be generated + Switch(es) for dvips program when pdf file is to be generated from ps file. $dvips_silent_switch ["-q"] Switch(es) for dvips program when silent mode is on. $dvi_update_command [""] - When the dvi previewer is set to be updated by running a com- - mand, this is the command that is run. See the information for - the variable $dvi_update_method for further information, and see - information on the variable $pdf_update_method for an example + When the dvi previewer is set to be updated by running a com- + mand, this is the command that is run. See the information for - 22 December 2008 15 + 10 April 2009 15 @@ -1000,65 +1007,65 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + the variable $dvi_update_method for further information, and see + information on the variable $pdf_update_method for an example for the analogous case of a pdf previewer. $dvi_update_method [2 under UNIX, 1 under MS-Windows] - How the dvi viewer updates its display when the dvi file has - changed. The values here apply equally to the + How the dvi viewer updates its display when the dvi file has + changed. The values here apply equally to the $pdf_update_method and to the $ps_update_method variables. 0 => update is automatic, 1=> manual update by user, which may only mean a mouse click on the viewer's window or may mean a more serious action. - 2 => Send the signal, whose number is in the variable - $dvi_update_signal. The default value under UNIX is suitable + 2 => Send the signal, whose number is in the variable + $dvi_update_signal. The default value under UNIX is suitable for xdvi. - 3 => Viewer cannot do an update, because it locks the file. + 3 => Viewer cannot do an update, because it locks the file. (As with acroread under MS-Windows.) - 4 => run a command to do the update. The command is speci- + 4 => run a command to do the update. The command is speci- fied by the variable $dvi_update_command. - See information on the variable $pdf_update_method for an exam- + See information on the variable $pdf_update_method for an exam- ple of updating by command. - $dvi_update_signal [Under UNIX: SIGUSR1, which is a system-dependent + $dvi_update_signal [Under UNIX: SIGUSR1, which is a system-dependent value] - The number of the signal that is sent to the dvi viewer when it - is updated by sending a signal -- see the information on the - variable $dvi_update_method. The default value is the one + The number of the signal that is sent to the dvi viewer when it + is updated by sending a signal -- see the information on the + variable $dvi_update_method. The default value is the one appropriate for xdvi on a UNIX system. $fdb_ext ["fdb_latexmk"] - The extension of the file which latexmk generates to contain a - database of information on source files. You will not normally + The extension of the file which latexmk generates to contain a + database of information on source files. You will not normally need to change this. $force_mode [0] - If nonzero, continue processing past minor latex errors includ- + If nonzero, continue processing past minor latex errors includ- ing unrecognized cross references. Equivalent to specifying the -f option. - @generated_exts [( aux , bbl , idx , ind , lof , lot , out , toc , + @generated_exts [( aux , bbl , idx , ind , lof , lot , out , toc , $fdb_ext )] - This contains a list of extensions for files that are generated - during a LaTeX run and that are read in by LaTeX in later runs, + This contains a list of extensions for files that are generated + during a LaTeX run and that are read in by LaTeX in later runs, either directly or indirectly. - This list has two uses: (a) to set the kinds of file to be + This list has two uses: (a) to set the kinds of file to be deleted in a cleanup operation (with the -c, -C, -CA, -g and -gg - options), and (b) in the determination of whether a rerun of + options), and (b) in the determination of whether a rerun of (pdf)LaTeX is needed after a run that gives an error. (Normally, a change of a source file during a run should provoke - a rerun. This includes a file generated by LaTeX, e.g., an aux - file, that is read in on subsequent runs. But after a run that - results in an error, a new run should occur until the user has - made a change in the files. But the user may have corrected an - error in a source .tex file during the run. So latexmk needs to - distinguish user-generated and automatically generated files; it + a rerun. This includes a file generated by LaTeX, e.g., an aux + file, that is read in on subsequent runs. But after a run that + results in an error, a new run should occur until the user has + made a change in the files. But the user may have corrected an - 22 December 2008 16 + 10 April 2009 16 @@ -1067,35 +1074,37 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - determines the automatically generated files as those with + error in a source .tex file during the run. So latexmk needs to + distinguish user-generated and automatically generated files; it + determines the automatically generated files as those with extensions in the list in @generated_exts.) - A convenient way to add an extra extension to the list, without - losing the already defined ones is to use a push command in the + A convenient way to add an extra extension to the list, without + losing the already defined ones is to use a push command in the line in an RC file. E.g., push @generated_exts, "end"; - adds the extension "end" to the list of predefined generated - extensions. (This extension is used by the RevTeX package, for + adds the extension "end" to the list of predefined generated + extensions. (This extension is used by the RevTeX package, for example.) $go_mode [0] - If nonzero, process files regardless of timestamps, and is then + If nonzero, process files regardless of timestamps, and is then equivalent to the -g option. %hash_calc_ignore_pattern !!!This variable is for experts only!!! - The general rule latexmk uses for determining when an extra run - of some program is needed is that one of the source files has - changed. But consider for example a latex package that causes - an encapsulated postscript file (an "eps" file) to be made that - is to be read in on the next run. The file contains a comment - line giving its creation date and time. On the next run the - time changes, latex sees that the eps file has changed, and - therefore reruns latex. This causes an infinite loop, only - exited becaues latexmk has a limit on the number of runs to + The general rule latexmk uses for determining when an extra run + of some program is needed is that one of the source files has + changed. But consider for example a latex package that causes + an encapsulated postscript file (an "eps" file) to be made that + is to be read in on the next run. The file contains a comment + line giving its creation date and time. On the next run the + time changes, latex sees that the eps file has changed, and + therefore reruns latex. This causes an infinite loop, only + exited becaues latexmk has a limit on the number of runs to guard against pathological situations. But the changing line has no real effect, since it is a comment. @@ -1104,28 +1113,26 @@ LATEXMK(1L) LATEXMK(1L) $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: '; This creates a rule for files with extension .eps about lines to - ignore. The left-hand side is a Perl idiom for setting an item - in a hash. Note that the file extension is specified without a + ignore. The left-hand side is a Perl idiom for setting an item + in a hash. Note that the file extension is specified without a period. The value, on the right-hand side, is a string contain- - ing a regular expresssion. (See documentation on Perl for how - they are to be specified in general.) This particular regular - expression specifies that lines beginning with "%%CreationDate: - " are to be ignored in deciding whether a file of the given + ing a regular expresssion. (See documentation on Perl for how + they are to be specified in general.) This particular regular + expression specifies that lines beginning with "%%CreationDate: + " are to be ignored in deciding whether a file of the given extension .eps has changed. $kpsewhich ["kpsewhich %S"] - The program called to locate a source file when the name alone - is not sufficient. Most filenames used by latexmk have suffi- - cient path information to be found directly. But sometimes, - notably when the file, but not its path is known. The program + The program called to locate a source file when the name alone + is not sufficient. Most filenames used by latexmk have suffi- + cient path information to be found directly. But sometimes, + notably when the file, but not its path is known. The program specified by $kpsewhich is used to find it. - See also the @BIBINPUTS variable for another way that latexmk - also uses to try to locate files; it applies only in the case of - 22 December 2008 17 + 10 April 2009 17 @@ -1134,41 +1141,89 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + See also the @BIBINPUTS variable for another way that latexmk + also uses to try to locate files; it applies only in the case of .bib files. $landscape_mode [0] If nonzero, run in landscape mode, using the landscape mode pre- - viewers and dvi to postscript converters. Equivalent to the -l + viewers and dvi to postscript converters. Equivalent to the -l option. Normally not needed with current previewers. $latex ["latex %O %S"] The LaTeX processing program. Note that as with other programs, - you can use this variable not just to change the name of the + you can use this variable not just to change the name of the program used, but also specify options to the program. E.g., $latex = "latex --src-specials"; + %latex_input_extensions + This variable specifies the extensions tried by latexmk when it + finds that a LaTeX run resulted in an error that a file has not + been found, and the file is given without an extension. This + typically happens when LaTeX commands of the form input{file} or + includegraphics{figure}, when the relevant source file does not + exist. + + In this situation, latexmk searches for custom dependencies to + make the missing file(s), but restricts it to the extensions + specified by the variable %latex_input_extensions. The default + extensions are + + (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- + able %pdflatex_input_extensions, add_input_ext and + remove_input_ext. They are used as in the following examples + are possible lines in an initialization file: + + remove_input_ext( 'latex', 'tex' ); + + removes the extension 'tex' from latex_input_extensions + + add_input_ext( 'latex', 'asdf' ); + + add the extension 'asdf to latex_input_extensions. (Naturally + with such an extension, you should have made an appropriate cus- + tom dependency for latexmk, and should also have done the appro- + priate programming in the LaTeX source file to enable the file + to be read. The standard extensions are handled by LaTeX and + its graphics/graphicx packages. + + $latex_silent_switch ["-interaction=batchmode"] - Switch(es) for the LaTeX processing program when silent mode is - on. Under MS-Windows, the default value is changed to "-inter- - action=batchmode -c-style-errors", as used by MikTeX and fpTeX. + Switch(es) for the LaTeX processing program when silent mode is + on. Under MS-Windows, the default value is changed to "-inter- + action=batchmode -c-style-errors", as used by MikTeX and fpTeX. + + + + + 10 April 2009 18 + + + + + +LATEXMK(1L) LATEXMK(1L) + $lpr ["lpr %O %S" under UNIX/LINUX, "NONE lpr" under MS-WINDOWS] The command to print postscript files. - Under MS-Windows (unlike UNIX/LINUX), there is no standard pro- + Under MS-Windows (unlike UNIX/LINUX), there is no standard pro- gram for printing files. But there are ways you can do it. For example, if you have gsview installed, you could use it with the option "/p": $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p'; - If gsview is installed in a different directory, you will need - to make the appropriate change. Note the combination of single - and double quotes around the name. The single quotes specify - that this is a string to be assigned to the configuration vari- - able $lpr. The double quotes are part of the string passed to - the operating system to get the command obeyed; this is neces- + If gsview is installed in a different directory, you will need + to make the appropriate change. Note the combination of single + and double quotes around the name. The single quotes specify + that this is a string to be assigned to the configuration vari- + able $lpr. The double quotes are part of the string passed to + the operating system to get the command obeyed; this is neces- sary because one part of the command name ("Program Files") con- tains a space which would otherwise be misinterpreted. @@ -1178,108 +1233,143 @@ LATEXMK(1L) LATEXMK(1L) $lpr_pdf ["NONE lpr_pdf"] The printing program to print pdf files. - Under MS-Windows you could set this to use gsview, if it is + Under MS-Windows you could set this to use gsview, if it is installed, e.g., $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p'; - If gsview is installed in a different directory, you will need - to make the appropriate change. Note the double quotes around + If gsview is installed in a different directory, you will need + to make the appropriate change. Note the double quotes around the name: this is necessary because one part of the command name ("Program Files") contains a space which would otherwise be mis- interpreted. + $makeindex ["makeindex %O -o %D %S"] + The index processing program. + $max_repeat [5] + The maximum number of times latexmk will run latex/pdflatex + before deciding that there may be an infinite loop and that it + needs to bail out, rather than rerunning latex/pdflatex again to + resolve cross-references, etc. The default value covers all + normal cases. - 22 December 2008 18 + (Note that the "etc" covers a lot of cases where one run of + latex/pdflatex generates files to be read in on a later run.) + $new_viewer_always [0] + This variable applies to latexmk only in continuous-preview + mode. If $new_viewer_always is 0, latexmk will check for a pre- + viously running previewer on the same file, and if one is run- + ning will not start a new one. If $new_viewer_always is non- + 10 April 2009 19 -LATEXMK(1L) LATEXMK(1L) - $makeindex ["makeindex %O -o %D %S"] - The index processing program. - $max_repeat [5] - The maximum number of times latexmk will run latex/pdflatex - before deciding that there may be an infinite loop and that it - needs to bail out, rather than rerunning latex/pdflatex again to - resolve cross-references, etc. The default value covers all - normal cases. - (Note that the "etc" covers a lot of cases where one run of - latex/pdflatex generates files to be read in on a later run.) +LATEXMK(1L) LATEXMK(1L) - $new_viewer_always [0] - This variable applies to latexmk only in continuous-preview - mode. If $new_viewer_always is 0, latexmk will check for a pre- - viously running previewer on the same file, and if one is run- - ning will not start a new one. If $new_viewer_always is non- - zero, this check will be skipped, and latexmk will behave as if + + zero, this check will be skipped, and latexmk will behave as if no viewer is running. $pdf_mode [0] - If zero, do NOT generate a pdf version of the document. If - equal to 1, generate a pdf version of the document using pdfla- + If zero, do NOT generate a pdf version of the document. If + equal to 1, generate a pdf version of the document using pdfla- tex. If equal to 2, generate a pdf version of the document from the ps file, by using the command specified by the $ps2pdf vari- - able. If equal to 3, generate a pdf version of the document + able. If equal to 3, generate a pdf version of the document from the dvi file, by using the command specified by the $dvipdf variable. Equivalent to the -pdf-, -pdf, -pdfdvi, -pdfps options. $pdflatex ["pdflatex %O %S"] - The LaTeX processing program in the version that makes a pdf + The LaTeX processing program in the version that makes a pdf file instead of a dvi file. + %pdflatex_input_extensions + This variable specifies the extensions tried by latexmk when it + finds that a pdfLaTeX run resulted in an error that a file has + not been found, and the file is given without an extension. + This typically happens when LaTeX commands of the form + input{file} or includegraphics{figure}, when the relevant source + file does not exist. + + In this situation, latexmk searches for custom dependencies to + make the missing file(s), but restricts it to the extensions + specified by the variable %pdflatex_input_extensions. The + default extensions are + + (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 + variable %latex_input_extensions, add_input_ext and + remove_input_ext. They are used as in the following examples + are possible lines in an initialization file: + + remove_input_ext( 'pdflatex', 'tex' ); + + removes the extension 'tex' from pdflatex_input_extensions + + add_input_ext( 'pdflatex', 'asdf' ); + + add the extension 'asdf to pdflatex_input_extensions. (Natu- + rally with such an extension, you should have made an appropri- + ate custom dependency for latexmk, and should also have done the + appropriate programming in the LaTeX source file to enable the + file to be read. The standard extensions are handled by pdfla- + tex and its graphics/graphicx packages.) + + $pdflatex_silent_switch ["-interaction=batchmode"] - Switch(es) for the pdflatex program (specified in the variable + Switch(es) for the pdflatex program (specified in the variable $pdflatex when silent mode is on. Under MS-Windows, the default - value is changed to "-interaction=batchmode -c-style-errors", as - used by MikTeX and fpTeX. - $pdf_previewer ["start acroread %O %S"] - The command to invoke a pdf-previewer. [Default is changed to - "start" on MS-WINDOWS; under more recent versions of Windows, - this will cause to be run whatever command the system has asso- - ciated with .pdf files.] - WARNING: Potential problem under MS-Windows: if acroread is used - as the pdf previewer, and it is actually viewing a pdf file, the - pdf file cannot be updated. Thus makes acroread a bad choice of - previewer if you use latexmk's previous-continuous mode (option - -pvc) under MS-windows. This problem does not occur if - ghostview, gv or gsview is used to view pdf files. + 10 April 2009 20 - 22 December 2008 19 +LATEXMK(1L) LATEXMK(1L) + value is changed to "-interaction=batchmode -c-style-errors", as + used by MikTeX and fpTeX. -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, + this will cause to be run whatever command the system has asso- + ciated with .pdf files.] + WARNING: Potential problem under MS-Windows: if acroread is used + as the pdf previewer, and it is actually viewing a pdf file, the + pdf file cannot be updated. Thus makes acroread a bad choice of + previewer if you use latexmk's previous-continuous mode (option + -pvc) under MS-windows. This problem does not occur if + ghostview, gv or gsview is used to view pdf files. $pdf_update_command [""] - When the pdf previewer is set to be updated by running a com- - mand, this is the command that is run. See the information for + When the pdf previewer is set to be updated by running a com- + mand, this is the command that is run. See the information for the variable $pdf_update_method. $pdf_update_method [1 under UNIX, 3 under MS-Windows] - How the pdf viewer updates its display when the pdf file has - changed. See the information on the variable $dvi_update_method + How the pdf viewer updates its display when the pdf file has + changed. See the information on the variable $dvi_update_method for the codes. (Note that information needs be changed slightly - so that for the value 4, to run a command to do the update, the - command is specified by the variable $pdf_update_command, and - for the value 2, to specify update by signal, the signal is + so that for the value 4, to run a command to do the update, the + command is specified by the variable $pdf_update_command, and + for the value 2, to specify update by signal, the signal is specified by $pdf_update_signal.) Note that acroread under MS-Windows (but not UNIX) locks the pdf @@ -1292,48 +1382,52 @@ LATEXMK(1L) LATEXMK(1L) $pdf_update_method = 4; $pdf_update_command = "xpdf -remote %R -reload"; - The first setting arranges for the xpdf program to be used in - its "remote server mode", with the server name specified as the - rootname of the TeX file. The second setting arranges for + The first setting arranges for the xpdf program to be used in + its "remote server mode", with the server name specified as the + rootname of the TeX file. The second setting arranges for updating to be done in response to a command, and the third set- ting sets the update command. - $pdf_update_signal [Under UNIX: SIGHUP, which is a system-dependent + $pdf_update_signal [Under UNIX: SIGHUP, which is a system-dependent value] - The number of the signal that is sent to the pdf viewer when it - is updated by sending a signal -- see the information on the - variable $pdf_update_method. The default value is the one + The number of the signal that is sent to the pdf viewer when it + is updated by sending a signal -- see the information on the + variable $pdf_update_method. The default value is the one appropriate for gv on a UNIX system. $pid_position[1 under UNIX, -1 under MS-Windows] - The variable $pid_position is used to specify which word in - lines of the output from $pscmd corresponds to the process ID. - The first word in the line is numbered 0. The default value of - 1 (2nd word in line) is correct for Solaris 2.6 and Linux. Set- - ting the variable to -1 is used to indicate that $pscmd is not - to be used. + The variable $pid_position is used to specify which word in + lines of the output from $pscmd corresponds to the process ID. - $postscript_mode [0] - If nonzero, generate a postscript version of the document. - Equivalent to the -ps option. - $preview_continuous_mode [0] - If nonzero, run a previewer to view the document, and continue - running latexmk to keep .dvi up-to-date. Equivalent to the -pvc - option. Which previewer is run depends on the other settings, - see the command line options -view=, and the variable $view. + 10 April 2009 21 - 22 December 2008 20 +LATEXMK(1L) LATEXMK(1L) -LATEXMK(1L) LATEXMK(1L) + The first word in the line is numbered 0. The default value of + 1 (2nd word in line) is correct for Solaris 2.6 and Linux. Set- + ting the variable to -1 is used to indicate that $pscmd is not + to be used. + $postscript_mode [0] + If nonzero, generate a postscript version of the document. + Equivalent to the -ps option. + + If some other request is made for which a postscript file is needed, + then $postscript_mode will be set to 1. + + $preview_continuous_mode [0] + If nonzero, run a previewer to view the document, and continue + running latexmk to keep .dvi up-to-date. Equivalent to the -pvc + option. Which previewer is run depends on the other settings, + see the command line options -view=, and the variable $view. $preview_mode [0] If nonzero, run a previewer to preview the document. Equivalent @@ -1375,6 +1469,17 @@ LATEXMK(1L) LATEXMK(1L) postscript file before other processing. Equivalent to specify- ing the -pF option. + + + 10 April 2009 22 + + + + + +LATEXMK(1L) LATEXMK(1L) + + $ps_previewer ["start gv %O %S", but "start %O %S" under MS-WINDOWS] The command to invoke a ps-previewer. (The default under MS- WINDOWS will cause to be run whatever command the system has @@ -1390,18 +1495,6 @@ LATEXMK(1L) LATEXMK(1L) of gv under different names, e.g., ggv, kghostview, etc, but perhaps not one called gv. - - - - 22 December 2008 21 - - - - - -LATEXMK(1L) LATEXMK(1L) - - $ps_previewer_landscape ["start gv -swap %O %S", but "start %O %S" under MS-WINDOWS] The command to invoke a ps-previewer in landscape mode. @@ -1444,6 +1537,18 @@ LATEXMK(1L) LATEXMK(1L) Directory to store temporary files that latexmk may generate while running. + + + + 10 April 2009 23 + + + + + +LATEXMK(1L) LATEXMK(1L) + + 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 @@ -1459,16 +1564,6 @@ LATEXMK(1L) LATEXMK(1L) generated is to be used (among dvi, ps and pdf). - - 22 December 2008 22 - - - - - -LATEXMK(1L) LATEXMK(1L) - - 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 @@ -1511,6 +1606,18 @@ CUSTOM DEPENDENCIES 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- + + + + 10 April 2009 24 + + + + + +LATEXMK(1L) LATEXMK(1L) + + 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 @@ -1524,18 +1631,6 @@ CUSTOM DEPENDENCIES those without knowledge of the Perl programming language. Of course, experts could do something much more elaborate. - - - - 22 December 2008 23 - - - - - -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. @@ -1581,27 +1676,27 @@ LATEXMK(1L) LATEXMK(1L) system("fig2dev -Lps '$_[0].fig' '$_[0].eps'"); } - This causes the invocation of the fig2dev program to have quoted file- - names; it should therefore work with filenames containing spaces. How- - ever, not all software deals correctly with filenames that contain - spaces. Moreover, the rules, if any, for quoting filenames vary - between operating systems, command shells and individual pieces of - software, so this code may not always work. - If you use pdflatex instead of latex, then you will probably prefer to - convert your graphics files to pdf format, in which case you would - replace the above code in an initialization file by + 10 April 2009 25 - 22 December 2008 24 +LATEXMK(1L) LATEXMK(1L) -LATEXMK(1L) LATEXMK(1L) + This causes the invocation of the fig2dev program to have quoted file- + names; it should therefore work with filenames containing spaces. How- + ever, not all software deals correctly with filenames that contain + spaces. Moreover, the rules, if any, for quoting filenames vary + between operating systems, command shells and individual pieces of + software, so this code may not always work. + If you use pdflatex instead of latex, then you will probably prefer to + convert your graphics files to pdf format, in which case you would + replace the above code in an initialization file by add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' ); sub fig2pdf { @@ -1649,25 +1744,27 @@ LATEXMK(1L) LATEXMK(1L) be perpetually out-of-date. This situation, of circular dependencies, is endemic to latex, and latexmk in its current version works correctly with circular dependencies. It examines the contents of the files (by - use of an md5 checksum), and only does a remake when the file contents - have actually changed. - Of course if you choose to write random data to the .nnd (or and .aux - file, etc) that changes on each new run, then you will have a problem. - For real experts: See the %hash_cal_ignore_pattern if you have to deal - with such problems. - Glossaries can be dealt with similarly. + 10 April 2009 26 - 22 December 2008 25 +LATEXMK(1L) LATEXMK(1L) -LATEXMK(1L) LATEXMK(1L) + use of an md5 checksum), and only does a remake when the file contents + have actually changed. + + Of course if you choose to write random data to the .nnd (or and .aux + file, etc) that changes on each new run, then you will have a problem. + For real experts: See the %hash_cal_ignore_pattern if you have to deal + with such problems. + + Glossaries can be dealt with similarly. OLD METHOD OF DEFINING CUSTOM DEPENDENCIES @@ -1718,17 +1815,10 @@ BUGS 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.03). - 22 December 2008 26 + 10 April 2009 27 @@ -1737,6 +1827,14 @@ AUTHOR LATEXMK(1L) LATEXMK(1L) + 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.05). + 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/>. @@ -1791,10 +1889,6 @@ LATEXMK(1L) LATEXMK(1L) - - - - - 22 December 2008 27 + 10 April 2009 28 |