diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/latexmk/latexmk.txt')
-rw-r--r-- | Master/texmf-dist/doc/support/latexmk/latexmk.txt | 337 |
1 files changed, 180 insertions, 157 deletions
diff --git a/Master/texmf-dist/doc/support/latexmk/latexmk.txt b/Master/texmf-dist/doc/support/latexmk/latexmk.txt index 84914dde566..f8d83547723 100644 --- a/Master/texmf-dist/doc/support/latexmk/latexmk.txt +++ b/Master/texmf-dist/doc/support/latexmk/latexmk.txt @@ -127,7 +127,7 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE - 18 May 2010 2 + 27 July 2010 2 @@ -193,7 +193,7 @@ LATEXMK(1L) LATEXMK(1L) - 18 May 2010 3 + 27 July 2010 3 @@ -259,7 +259,7 @@ LATEXMK(1L) LATEXMK(1L) - 18 May 2010 4 + 27 July 2010 4 @@ -270,8 +270,8 @@ LATEXMK(1L) LATEXMK(1L) -diagnostics Print detailed diagnostics during a run. This may help for - debugging problems or to understand .latexmk's behavior in dif- - ficult situations. + debugging problems or to understand latexmk's behavior in diffi- + cult situations. -dvi Generate dvi version of document. @@ -325,7 +325,7 @@ LATEXMK(1L) LATEXMK(1L) - 18 May 2010 5 + 27 July 2010 5 @@ -391,7 +391,7 @@ LATEXMK(1L) LATEXMK(1L) - 18 May 2010 6 + 27 July 2010 6 @@ -457,7 +457,7 @@ LATEXMK(1L) LATEXMK(1L) - 18 May 2010 7 + 27 July 2010 7 @@ -492,7 +492,11 @@ LATEXMK(1L) LATEXMK(1L) can only work with one file. So in this case you will normally only specify one filename on the command line. It is also incompatible with the -p and -pv options, so it turns these - options off + options off. + + The -pvc option also turns off force mode (-f), as is normally + best for continuous preview mode. If you really want force + mode, use the options in the order -pvc -f. With a good previewer the display will be automatically updated. (Under some but not all versions of UNIX/Linux "gv -watch" does @@ -516,14 +520,10 @@ LATEXMK(1L) LATEXMK(1L) "forked" previewer will continue to run. Successive invocations with the -pvc option will not fork new previewers, but latexmk will normally use the existing previewer. (At least this will - happen when latexmk is running under an operating system where - it knows how to determine whether an existing previewer is run- - ning.) - - 18 May 2010 8 + 27 July 2010 8 @@ -532,6 +532,10 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + happen when latexmk is running under an operating system where + it knows how to determine whether an existing previewer is run- + ning.) + -pvc- Turn off -pvc. -quiet Same as -silent @@ -583,13 +587,10 @@ LATEXMK(1L) LATEXMK(1L) -view=default, -view=dvi, -view=ps, -view=pdf Set the kind of file used when previewing is requested (e.g., by the -pv or -pvc switches). The default is to view the "highest" - kind of requested file (in the order dvi, ps, pdf). - - The preview-continuous option -pvc can only work with one file. So in - 18 May 2010 9 + 27 July 2010 9 @@ -598,6 +599,9 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + kind of requested file (in the order dvi, ps, pdf). + + The preview-continuous option -pvc can only work with one file. So in this case you will normally only specify one filename on the command line. @@ -650,12 +654,10 @@ CONFIGURATION/INITIALIZATION (RC) FILES the user may choose to set it. 3) The RC file in the current working directory. This file can be - named either "latexmkrc" or ".latexmkrc", and the first of these to be - found is used, if any. - 18 May 2010 10 + 27 July 2010 10 @@ -664,6 +666,9 @@ CONFIGURATION/INITIALIZATION (RC) FILES LATEXMK(1L) LATEXMK(1L) + named either "latexmkrc" or ".latexmkrc", and the first of these to be + found is used, if any. + 4) Any RC file(s) specified on the command line with the -r option. Each RC file is a sequence of Perl commands. Naturally, a user can use @@ -716,13 +721,10 @@ HOW TO SET VARIABLES IN INITIALIZATION FILES -FORMAT OF COMMAND SPECIFICATIONS - Some of the variables set the commands that latexmk uses for carrying - out its work, for example to generate a dvi file from a tex file or to - 18 May 2010 11 + 27 July 2010 11 @@ -731,6 +733,9 @@ FORMAT OF COMMAND SPECIFICATIONS LATEXMK(1L) LATEXMK(1L) +FORMAT OF COMMAND SPECIFICATIONS + Some of the variables set the commands that latexmk uses for carrying + out its work, for example to generate a dvi file from a tex file or to view a postscript file. This section describes some important features of how the commands are specified. @@ -783,13 +788,10 @@ 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 - 18 May 2010 12 + 27 July 2010 12 @@ -798,6 +800,9 @@ LATEXMK(1L) LATEXMK(1L) 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 bibliography file, the setting for the bibtex command should therefore be @@ -840,31 +845,39 @@ LATEXMK(1L) LATEXMK(1L) Command names containing spaces: Under MS-Windows it is common that the name of a command includes spaces, since software is often installed in - a subdirectory of "C:Program Files". Such command names should be + a subdirectory of "C:\Program Files". Such command names should be enclosed in double quotes, as in $lpr_pdf = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p %S'; - Using MS-Windows file associations: A useful trick under modern ver- - sions of MS-Windows (e.g., WinXP) is to use just the command + (Note about the above example: Forward slashes are equivalent to back- + slashes in filenames under MS-Windows, provided that the filename is + inside double quotes. It is easier to use forward slashes in examples + like the one above, since then one does not have to worry about the - $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 + 27 July 2010 13 - 18 May 2010 13 +LATEXMK(1L) LATEXMK(1L) -LATEXMK(1L) LATEXMK(1L) + rules for dealing with forward slashes in strings in the Perl lan- + guage.) + Using MS-Windows file associations: A useful trick under modern ver- + sions of MS-Windows (e.g., WinXP) is to use just the command 'start' by + itself: + $dvi_previewer = 'start %S'; + + Under recent versions of MS-Windows, this will cause to be run whatever + program the system has associated with dvi files. (The same applies for a postscript viewer and a pdf viewer.) Not using a certain command: If a command is not to be run, the command @@ -910,27 +923,27 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES $always_view_file_via_temporary [0] Whether ps and pdf files are initially to be made in a temporary directory and then moved to the final location. (This applies - to dvips, dvipdf, and ps2pdf operations, and the filtering oper- - ators on dvi and ps files. It does not apply to pdflatex, - unfortunately.) - This use of a temporary file solves a problem that the making of - these files can occupy a substantial time. If a viewer sees - that the file has changed, it reads the new file, and this can - cause havoc if the program writing the file has not yet finished - its work. + 27 July 2010 14 - 18 May 2010 14 +LATEXMK(1L) LATEXMK(1L) -LATEXMK(1L) LATEXMK(1L) + to dvips, dvipdf, and ps2pdf operations, and the filtering oper- + ators on dvi and ps files. It does not apply to pdflatex, + unfortunately.) + This use of a temporary file solves a problem that the making of + these files can occupy a substantial time. If a viewer sees + that the file has changed, it reads the new file, and this can + cause havoc if the program writing the file has not yet finished + its work. See the $pvc_view_file_via_temporary variable for a setting that applies only if preview-continuous mode (-pvc option) is used. @@ -978,26 +991,26 @@ LATEXMK(1L) LATEXMK(1L) @BIBINPUTS = ( ".", "C:\bibfiles" ); @BIBINPUTS = ( ".", "\\server\bibfiles" ); @BIBINPUTS = ( ".", "C:/bibfiles" ); - @BIBINPUTS = ( ".", "//server/bibfiles" ); - @BIBINPUTS = ( ".", "/usr/local/texmf/bibtex/bib" ); - Note that under MS Windows, either a forward slash "/" or a - backward slash "\" can be used to separate pathname components, - so the first two and the second two examples are equivalent. - Each backward slash should be doubled to avoid running afoul of - Perl's rules for writing strings. + 27 July 2010 15 - 18 May 2010 15 +LATEXMK(1L) LATEXMK(1L) -LATEXMK(1L) LATEXMK(1L) + @BIBINPUTS = ( ".", "//server/bibfiles" ); + @BIBINPUTS = ( ".", "/usr/local/texmf/bibtex/bib" ); + Note that under MS Windows, either a forward slash "/" or a + backward slash "\" can be used to separate pathname components, + so the first two and the second two examples are equivalent. + Each backward slash should be doubled to avoid running afoul of + Perl's rules for writing strings. Important note: This variable is now mostly obsolete in the current version of latexmk, since it has a better method of searching for files @@ -1048,16 +1061,10 @@ LATEXMK(1L) LATEXMK(1L) $clean_ext [""] Extra extensions of files for latexmk to remove when any of the clean-up options (-c, -c1, or -C) is selected. The value of - this variable is a string containing the extensions separated by - spaces. - - $clean_full_ext [""] - Extra extensions of files for latexmk to remove when the -C - option is selected, i.e., extensions of files to remove when the - 18 May 2010 16 + 27 July 2010 16 @@ -1066,6 +1073,12 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + this variable is a string containing the extensions separated by + spaces. + + $clean_full_ext [""] + Extra extensions of files for latexmk to remove when the -C + option is selected, i.e., extensions of files to remove when the .dvi, etc files are to be cleaned-up. @cus_dep_list [()] @@ -1118,13 +1131,10 @@ LATEXMK(1L) LATEXMK(1L) will cause to be run whatever command the system has associated with .dvi files.] - $dvi_previewer_landscape ["start xdvi %O %S"] - The command to invoke a dvi-previewer in landscape mode. - [Default is "start" under MS-WINDOWS; under more recent versions - 18 May 2010 17 + 27 July 2010 17 @@ -1133,6 +1143,9 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) + $dvi_previewer_landscape ["start xdvi %O %S"] + The command to invoke a dvi-previewer in landscape mode. + [Default is "start" under MS-WINDOWS; under more recent versions of Windows, this will cause to be run whatever command the sys- tem has associated with .dvi files.] @@ -1191,7 +1204,7 @@ LATEXMK(1L) LATEXMK(1L) - 18 May 2010 18 + 27 July 2010 18 @@ -1257,10 +1270,11 @@ LATEXMK(1L) LATEXMK(1L) %hash_calc_ignore_pattern !!!This variable is for experts only!!! + The general rule latexmk uses for determining when an extra run - 18 May 2010 19 + 27 July 2010 19 @@ -1269,7 +1283,6 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - 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 @@ -1323,13 +1336,15 @@ LATEXMK(1L) LATEXMK(1L) 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. + 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 - 18 May 2010 20 + 27 July 2010 20 @@ -1338,10 +1353,9 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - 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 + extensions are 'tex' and 'eps'. (For Perl experts: %latex_input_extensions is a hash whose keys are the extensions. The values are irrelevant.) Two subrou- @@ -1395,10 +1409,13 @@ LATEXMK(1L) LATEXMK(1L) sary because one part of the command name ("Program Files") con- tains a space which would otherwise be misinterpreted. + $lpr_dvi ["NONE lpr_dvi"] + The printing program to print dvi files. + - 18 May 2010 21 + 27 July 2010 21 @@ -1407,9 +1424,6 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - $lpr_dvi ["NONE lpr_dvi"] - The printing program to print dvi files. - $lpr_pdf ["NONE lpr_pdf"] The printing program to print pdf files. @@ -1464,27 +1478,27 @@ 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 + 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. - 18 May 2010 22 + 27 July 2010 22 -LATEXMK(1L) LATEXMK(1L) +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 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 + 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 sub- @@ -1535,10 +1549,15 @@ LATEXMK(1L) LATEXMK(1L) $pdf_update_command [""] When the pdf previewer is set to be updated by running a com- mand, this is the command that is run. See the information for + the variable $pdf_update_method. + + $pdf_update_method [1 under UNIX, 3 under MS-Windows] + How the pdf viewer updates its display when the pdf file has + changed. See the information on the variable $dvi_update_method - 18 May 2010 23 + 27 July 2010 23 @@ -1547,11 +1566,6 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - the variable $pdf_update_method. - - $pdf_update_method [1 under UNIX, 3 under MS-Windows] - How the pdf viewer updates its display when the pdf file has - changed. See the information on the variable $dvi_update_method for the codes. (Note that information needs be changed slightly so that for the value 4, to run a command to do the update, the command is specified by the variable $pdf_update_command, and @@ -1606,10 +1620,16 @@ LATEXMK(1L) LATEXMK(1L) $preview_mode [0] If nonzero, run a previewer to preview the document. Equivalent to the -pv option. Which previewer is run depends on the other + settings, see the command line options -view=, and the variable + $view. + $printout_mode [0] + If nonzero, print the document using lpr. Equivalent to the -p + option. This is recommended not to be set from an RC file, - 18 May 2010 24 + + 27 July 2010 24 @@ -1618,13 +1638,7 @@ LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) LATEXMK(1L) - settings, see the command line options -view=, and the variable - $view. - - $printout_mode [0] - If nonzero, print the document using lpr. Equivalent to the -p - option. This is recommended not to be set from an RC file, oth- - erwise you could waste lots of paper. + otherwise you could waste lots of paper. $print_type = ["ps"] Type of file to printout: possibilities are "dvi", "none", @@ -1677,25 +1691,25 @@ LATEXMK(1L) LATEXMK(1L) $ps_update_command [""] When the postscript previewer is set to be updated by running a command, this is the command that is run. See the information + for the variable $ps_update_method. + $ps_update_method [0 under UNIX, 1 under MS-Windows] + How the postscript viewer updates its display when the ps file + has changed. See the information on the variable + $dvi_update_method for the codes. (Note that information needs + be changed slightly so that for the value 4, to run a command to - 18 May 2010 25 + 27 July 2010 25 -LATEXMK(1L) LATEXMK(1L) +LATEXMK(1L) LATEXMK(1L) - for the variable $ps_update_method. - $ps_update_method [0 under UNIX, 1 under MS-Windows] - How the postscript viewer updates its display when the ps file - has changed. See the information on the variable - $dvi_update_method for the codes. (Note that information needs - be changed slightly so that for the value 4, to run a command to do the update, the command is specified by the variable $ps_update_command, and for the value 2, to specify update by signal, the signal is specified by $ps_update_signal.) @@ -1749,9 +1763,17 @@ LATEXMK(1L) LATEXMK(1L) Directory to store temporary files that latexmk may generate while running. + The default under MSWindows (including cygwin), is to set + $tmpdir to the value of the first of whichever of the system + environment variables TMPDIR or TEMP exists, otherwise to the + current directory. Under other operating systems (expected to + be UNIX/Linux, including OS-X), the default is the value of the + system environment variable TMPDIR if it exists, otherwise + "/tmp". + - 18 May 2010 26 + 27 July 2010 26 @@ -1760,14 +1782,6 @@ LATEXMK(1L) LATEXMK(1L) 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 - current directory. Under other operating systems (expected to - be UNIX/Linux, including OS-X), the default is the value of the - system environment variable TMPDIR if it exists, otherwise - "/tmp". - $view ["default"] Which kind of file is to be previewed if a previewer is used. The possible values are "default", "dvi", "ps", "pdf". The @@ -1819,10 +1833,19 @@ CUSTOM DEPENDENCIES needs to read a file, like a graphics file, whose extension is the to- extension of a custom dependency. Then latexmk examines whether a file exists with the same name, but with the corresponding from-extension, + as specified in the custom-dependency rule. If it does, then whenever + the destination file (the one with the to-extension) is out-of-date + with respect to the corresponding source file. + + To make the new destination file, the Perl subroutine specified in the + rule is invoked, with an argument that is the base name of the files in + question. Simple cases just involve a subroutine invoking an external + program; this can be done by following the templates below, even by + those without knowledge of the Perl programming language. Of course, - 18 May 2010 27 + 27 July 2010 27 @@ -1831,15 +1854,6 @@ CUSTOM DEPENDENCIES LATEXMK(1L) LATEXMK(1L) - as specified in the custom-dependency rule. If it does, then whenever - the destination file (the one with the to-extension) is out-of-date - with respect to the corresponding source file. - - To make the new destination file, the Perl subroutine specified in the - rule is invoked, with an argument that is the base name of the files in - question. Simple cases just involve a subroutine invoking an external - program; this can be done by following the templates below, even by - those without knowledge of the Perl programming language. Of course, experts could do something much more elaborate. One other item in each custom-dependency rule labelled "must" above @@ -1890,28 +1904,28 @@ 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 { - 18 May 2010 28 + 27 July 2010 28 -LATEXMK(1L) LATEXMK(1L) - 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. +LATEXMK(1L) LATEXMK(1L) - If you use pdflatex instead of latex, then you will probably prefer to - convert your graphics files to pdf format, in which case you would - replace the above code in an initialization file by - add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' ); - sub fig2pdf { system("fig2dev -Lpdf $_[0].fig $_[0].pdf"); } @@ -1961,30 +1975,30 @@ LATEXMK(1L) LATEXMK(1L) 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. - 18 May 2010 29 +OLD METHOD OF DEFINING CUSTOM DEPENDENCIES + In previous versions of latexmk, the only method of defining custom + dependencies was to directly manipulate the table of custom dependen- + cies. This is contained in the @cus_dep_list array. It is an array of + strings, and each string in the array has four items in it, each + 27 July 2010 29 -LATEXMK(1L) LATEXMK(1L) - For real experts: See the %hash_cal_ignore_pattern if you have to deal - with such problems. - Glossaries can be dealt with similarly. +LATEXMK(1L) LATEXMK(1L) -OLD METHOD OF DEFINING CUSTOM DEPENDENCIES - In previous versions of latexmk, the only method of defining custom - dependencies was to directly manipulate the table of custom dependen- - cies. This is contained in the @cus_dep_list array. It is an array of - strings, and each string in the array has four items in it, each sepa- - rated by a space, the from-extension, the to-extension, the "must" + separated by a space, the from-extension, the to-extension, the "must" item, and the name of the subroutine for the custom dependency. These were all defined above. @@ -2033,11 +2047,21 @@ THANKS TO AUTHOR Current version, by John Collins (username collins at node - phys.psu.edu). (Version 4.16a). + phys.psu.edu). (Version 4.17). + + 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) + + + - 18 May 2010 30 + + 27 July 2010 30 @@ -2046,11 +2070,6 @@ AUTHOR LATEXMK(1L) LATEXMK(1L) - 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) @@ -2110,6 +2129,10 @@ LATEXMK(1L) LATEXMK(1L) - 18 May 2010 31 + + + + + 27 July 2010 31 |