diff options
Diffstat (limited to 'Master/texmf')
| -rw-r--r-- | Master/texmf/doc/man/man1/latexmk.1 | 271 | ||||
| -rw-r--r-- | Master/texmf/doc/man/man1/latexmk.man1.pdf | bin | 94122 -> 108188 bytes |
2 files changed, 265 insertions, 6 deletions
diff --git a/Master/texmf/doc/man/man1/latexmk.1 b/Master/texmf/doc/man/man1/latexmk.1 index f41863fcfcc..a36817826f4 100644 --- a/Master/texmf/doc/man/man1/latexmk.1 +++ b/Master/texmf/doc/man/man1/latexmk.1 @@ -1,4 +1,4 @@ -.TH LATEXMK 1L "3 February 2011" "" +.TH LATEXMK 1L "21 March 2011" "" .SH NAME latexmk \- generate LaTeX document .SH SYNOPSIS @@ -23,7 +23,11 @@ one of the source files is modified, and the previewer automatically updates the on-screen view of the compiled document. .PP \fILatexmk\fR determines which are the source files by examining the -log file. When \fIlatexmk\fR is run, it examines properties of the +log file. (Optionally, it also examines the list of input and output +files generated by the \fI-recorder\fR option of modern versions of +\fIlatex\fR and \fIpdflatex\fR. See the documentation for the +\fI-recorder\fR option of \fIlatexmk\fR below.) +When \fIlatexmk\fR is run, it examines properties of the source files, and if any have been changed since the last document generation, \fIlatexmk\fR will run the various LaTeX processing programs as necessary. In particular, it will repeat the run of LaTeX @@ -202,8 +206,8 @@ files are considered as including those generated by custom dependencies and are also deleted. Otherwise these files are not deleted. .TP .B -CA -Clean up (remove) absolutely all regeneratable files. It is now -equivalent to the \fB-C\fR option. See that option for details. +(Obsolete). Now equivalent to the \fB-C\fR option. See that option +for details. .TP .B -CF Remove the file containing the database of source file information, @@ -221,6 +225,43 @@ specifying: Note that if the \fB-d\fR option is specified, the \fB-ps\fR option is assumed. .TP +.B -deps +Show a list of dependent files after processing. This is in the form +of a dependency list of the form used by the \fImake\fR 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 +\fIlatexmk\fR 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 output). +But you can set the filename where the list is sent by the +\fI-deps-out=\fR option. + +See the section "USING \fIlatexmk\fR WITH \fImake\fR" for +an example of how to use a dependency list with \fImake\fR. + +Users familiar with GNU \fIautomake\fR and \fIgcc\fR will find that +the \fI-deps\fR option is very similar in its purpose and results to +the \fI-M\fR option to \fIgcc\fR. +.TP +.B -dependents +Equivalent to \fI-deps\fR. +.TP +.B -deps- +Do not show a list of dependent files after processing. (This is the +default.) +.TP +.B -dependents- +Equivalent to \fI-deps-\fR. +.TP +.B -deps-out=FILENAME +Set the filename to which the list of dependent files is written. If +the FILENAME argument is omitted or set to '-', then the output is +sent to stdout. + +Use of this option also turns on the output of the list of dependent +files after processing. +.TP .B -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 @@ -310,7 +351,7 @@ Turn off \fB-g\fR. .TP .B -gg "Super go mode" or "clean make": clean out generated files as if -\fB-CA\fR had been given, and then do a regular make. +\fB-C\fR had been given, and then do a regular make. .TP .B -h, -help Print help information. @@ -496,6 +537,27 @@ error results in \fIlatexmk\fR stopping. Multiple instances of the \fB-r\fR and \fB-e\fR options can be used, and they are executed in the order they appear on the command line. .TP +.B -recorder +Use the -recorder option with \fIlatex\fR and \fIpdflatex\fR. In +(most) modern versions of these programs, this results in a file of +extension \fI.fls\fR containing a list of the files that these +programs have read and written. \fILatexmk\fR will then use this file +to improve its detection of source files and generated files after a +run of \fIlatex\fR or \fIpdflatex\fR. + +For further information, see the documentation for the \fI$recorder\fR +configuration variable. +.TP +.B -recorder- +Do not use the -recorder option with \fIlatex\fR and \fIpdflatex\fR. +.TP +.B -rules +Show a list of \fIlatemk\fR's rules and dependencies after processing. +.TP +.B -rules- +Do not show a list of \fIlatexmk\fR's rules and dependencies after +processing. (This is the default.) +.TP .B -silent Run commands silently, i.e., with options that reduce the amount of diagnostics generated. For example, with the default settings, the @@ -511,6 +573,27 @@ variables, the relevant ones being \fI$bibtex_silent_switch\fR, \fI$dvips_silent_switch\fR, \fI$latex_silent_switch\fR, and \fI$pdflatex_silent_switch\fR. .TP +.B -use-make +When after a run of \fIlatex\fR or \fIpdflatex\fR, there are warnings +about missing files (e.g., as requested by the LaTeX \\input, \\include, +and \\includgraphics), \fIlatexmk\fR tries to make them by a custom +dependency. If no relevant custom dependency with an appropriate +source file is found, and if the -use-make option is set, then +\fIlatexmk\fR will try as a resort using the make program to try to +make the missing files. + +Note that the filename may be specified without an extension, e.g., +by \\includegraphics{drawing} in a LaTeX file. In that case, +\fIlatexmk\fR will try making drawing.ext with ext set in turn to the +possible extensions that are relevant for \fIlatex\fR (or as +appropriate \fIpdflatex\fR). + +See also the documentation for the \fI$use_make_for_missing_files\fR +configuration variable. +.TP +.B -use-make- +Do not use the make program to try to make missing files. (Default.) +.TP .B -v, -version Print version number of \fIlatexmk\fR. .TP @@ -980,6 +1063,9 @@ is ".tex". Wild cards are allowed. The parentheses are because \fI@default_files\fR is an array variable, i.e., a sequence of filename specifications is possible. .TP +.B $dependents_list [0] +Whether to display a list(s) of dependencies at the end of a run. +.TP .B $dvi_filter [empty] The dvi file filter to be run on the newly produced dvi file before other processing. Equivalent to specifying the \fB-dF\fR option. @@ -1260,6 +1346,10 @@ is necessary because one part of the command name ("Program Files") contains a space which would otherwise be misinterpreted. .TP +.B $make ["make"] +The make processing program. + +.TP .B $makeindex ["makeindex %O -o %D %S"] The index processing program. .TP @@ -1508,6 +1598,27 @@ correctly deal with TeX files whose names contain spaces. Latexmk's quoting only ensures that such filenames are correctly treated by the operating system in passing arguments to programs.) .TP +.B $recorder [0] +Whether to use the \fI-recorder\fR option to \fIlatex\fR and +\fIpdflatex\fR. Use of this option results in a file of extension +\fI.fls\fR containing a list of the files that these programs have +read and written. \fILatexmk\fR will then use this file to improve +its detection of source files and generated files after a run of +\fIlatex\fR or \fIpdflatex\fR. + +It is generally recommended to use this option (or to configure the +\fI$recorder\fR variable to be on.) But it only works if +\fI(pdf)latex\fR supports the -recorder option, which is true for most +current implementations + +\fINote about the name of the .fls file:\fR Most implementations of +\fI(pdf)latex\fR produce an .fls file with the same basename as the +main document's LaTeX, e.g., for Document.tex, the .fls file is +Document.fls. However, some implementations instead produce files +named for the program, i.e., latex.fls or pdflatex.fls. In this +second case, \fIlatexmk\fR copies the latex.fls or pdflatex.fls to a +file with the basename of the main LaTeX document, e.g., Document.fls. +.TP .B $sleep_time [2] The time to sleep (in seconds) between checking for source file changes when running with the \fB-pvc\fR option. This is subject to a @@ -1536,6 +1647,20 @@ 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". .TP +.B $use_make_for_missing_files [0] +Whether to use \fImake\fR to try and make files that are missing after +a run of \fIlatex\fR or \fIpdflatex\fR, and for which a custom +dependency has not been found. This is generally useful only when +\fIlatexmk\fR is used as part of a bigger project which is built by +using the \fImake\fR program. + +Note that once a missing file has been made, no further calls to +\fImake\fR will be made on a subsequent run of \fIlatexmk\fR to update +the file. Handling this problem is the job of a suitably defined +Makefile. See the section "USING \fIlatexmk\fR WITH \fImake\fR" for +how to do this. The intent of calling \fImake\fR from \fIlatexmk\fR +is merely to detect dependencies. +.TP .B $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 @@ -1737,6 +1862,140 @@ 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. + + +.SH USING \fIlatexmk\fR WITH \fImake\fR + +This section is targeted only at advanced users who use the \fImake\fR +program for complex projects, as for software development, with the +dependencies specified by a Makefile. + +Now the basic task of \fIlatexmk\fR is to run the appropriate programs +to make a viewable version of a LaTeX document. However, the usual +\fImake\fR 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 \fImake\fR program. Second 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 automatically. \fILatexmk\fR solves +both of these problems robustly. + +Thus for many standard LaTeX documents \fIlatexmk\fR can be used by +itself without the \fImake\fR program. In a complex project it simply +needs to be suitably configured. A standard configuration would be to +define custom dependencies to make graphics files from their source +files (e.g., as created by the \fIxfig\fR program). Custom +dependencies are \fIlatexmk\fR's equivalent of pattern rules in +Makefiles. + +Nevertheless there are projects for which a Makefile is appropriate, +and it is useful to know how to use \fIlatexmk\fR from a Makefile. A +typical example would be to generate documentation for a software +project. Potentially the interaction with the rest of the rules in +the Makefile could be quite complicated, for example if some of the +source files for a LaTeX document are generated by the project's +software. + +In this section, I give a couple of examples of how \fIlatexmk\fR can +be usefully invoked from a Makefile. The examples use specific +features of current versions of GNU \fImake\fR, which is the default +on both linux and OS-X systems. They may need modifications for other +versions of \fImake\fR. + +The simplest method is simply to delegate all the relevant tasks to +\fIlatexmk\fR, as is suitable for a straightforward LaTeX document. +For this a suitable Makefile is like + + .PHONY : FORCE_MAKE + all : try.pdf + %.pdf : %.tex FORCE_MAKE + latexmk -pdf -dvi- -ps- $< + +(Note: the last line must be introduced by a tab for the Makefile to +function correctly!) Naturally, if making try.pdf from its associated +LaTeX file try.tex were the only task to be performed, a direct use of +\fIlatexmk\fR 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 \fImake\fR 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 \fIlatexmk\fR to be +invoked. Instead, the pattern 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 \fIlatexmk\fR is always run. It is +\fIlatexmk\fR that decides whether any action is needed, e.g., a rerun +of \fIpdflatex\fR. Effectively the Makefile delegates all decisions +to \fIlatexmk\fR, while \fImake\fR 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 \fIlatexmk\fR. + +But something better is needed in more complicated situations, for +example, when the making of graphics files needs to be specified by +rules in the Makefile. To do this, one can use a Makefile like the +following: + + TARGETS = document1.pdf document2.pdf + DEPS_DIR = .deps + LATEXMK = latexmk -recorder -use-make -deps \\ + -e 'warn qq(In Makefile, turn off custom dependencies\n);' \\ + -e '@cus_dep_list = ();' \\ + -e 'show_cus_dep();' + all : $(TARGETS) + $(foreach file,$(TARGETS),$(eval -include $(DEPS_DIR)/$(file)P)) + $(DEPS_DIR) : + mkdir $@ + %.pdf : %.tex + if [ ! -e $(DEPS_DIR) ]; then mkdir $(DEPS_DIR); fi + $(LATEXMK) -pdf -dvi- -ps- -deps-out=$(DEPS_DIR)/$@P $< + %.pdf : %.fig + fig2dev -Lpdf $< $@ + +(Again, the lines containing the commands for the rules should be +started with tabs.) This example was inspired by how GNU +\fIautomake\fR handles automatic dependency tracking of C source +files. + +After each run of latexmk, dependency information is put in a file +in the .deps subdirectory. The Makefile causes these dependency files +to be read by \fImake\fR, 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 dependency files are .deps/document1.pdfP +and .deps/document2.pdfP. + +There is now no need for the phony prerequisite for the rule to +make .pdf files from .tex files. But I have added a rule to +make .pdf files from .fig files produced by the \fIxfig\fR program; +these are commonly used for graphics insertions in LaTeX documents. +\fILatexmk\fR is arranged to output a dependency file after each run. +It is given the \fI-recorder\fR option, which improves its detection +of files generated during a run of \fIpdflatex\fR; such files should +not be in the dependency list. The \fI-e\fR options are used to turn +off all custom dependencies, and to document this. Instead the +\fI-use-make\fR is used to delegate the making of missing files to +\fImake\fR itself. + +Suppose in the LaTeX file there is a command \\includegraphics{graph}, +and an \fIxfig\fR file "graph.fig" exists. On a first run, +\fIpdflatex\fR reports a missing file, named "graph". \fILatexmk\fR +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 \fIlatexmk\fR is making. Then let "fig.fig" be updated, and then +let \fImake\fR be run. \fIMake\fR first remakes "fig.pdf", and only +then reruns \fIlatexmk\fR. + +Thus we now have a method by which all the subsidiary processing is +delegated to \fImake\fR. + .SH SEE ALSO latex(1), bibtex(1). .SH BUGS @@ -1768,7 +2027,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.22e). +(Version 4.23). Released version can be obtained from CTAN: <http://www.tug.org/tex-archive/support/latexmk/>, and from the diff --git a/Master/texmf/doc/man/man1/latexmk.man1.pdf b/Master/texmf/doc/man/man1/latexmk.man1.pdf Binary files differindex 6a024ce3886..d14a4071a41 100644 --- a/Master/texmf/doc/man/man1/latexmk.man1.pdf +++ b/Master/texmf/doc/man/man1/latexmk.man1.pdf |