path: root/obsolete/support/latexmk/latexmk.1

.TH LATEXMK 1L "27 Jan 1995" ""
.SH NAME
latexmk \- generate LaTeX document
.SH SYNOPSIS
.B latexmk
[-bm message] [-bs scale] [-bi intensity] [-c] [-C] [-d] [-dF filter] [-f] [-F] [-g] [-h] [-i] [-I] [-l] [-p] [-ps] [-pF filter] [-pv] [-pvc] [-r rcfile] [-s] [file ...]
.SH DESCRIPTION
.I LatexMk
completely automates the process of generating a LaTeX document.
Essentially, it is a highly specialized relative of the general
\fImake\fR utility.  Given the source files for a document,
\fIlatexmk\fR issues the appropriate sequence of commands to generate
a .dvi, .ps or hardcopy version of the document.
.PP
\fILatexmk\fR recognizes the commands that are unique to SliTeX
documents; slide mode is automatically turn on when it finds a
\\colorslides or \\blackandwhite include command.
.PP
\fILatexmk\fR will scan source files for all included files, placing
the resulting dependency information into a dependency file with the
same name as the root file with the extension \fB.dep\fR.  This option
allows the user to essentially leave all the work to \fIlatexmk\fR.
The program will find all LaTeX \\include, \\input, \\psfig, \\epsfbox,
\\blackandwhite, and \\colorslides commands which input other source
files.  When \fIlatexmk\fR is run, it will examine the timestamps on
those files and run the various LaTeX processing programs as necessary,
if any of the source files have been changed since the last document
generation.  If the dependencies of the document are changed (e.g., by
adding or removing a \\include command), an additional pass of
\fIlatexmk -i\fR or \fIlatexmk -I\fR will update the dependency file.
.PP
By default, if no dependency exists, the source files are scanned and the
dependency file generated.  If the dependency file exists, it is read
instead (even if the root file is newer than the dependency file (see
-\fBi\fR option))
.PP
\fILatexMk\fR has two different previewing options.  In the simple
\fB-pv\fR option, a postscript or dvi previewer is automatically run
after generating the postscript or dvi version of the document.  The
type of viewer is selected automatically depending on the \fB-ps\fR
option.  When a document is reaching the final stages of editing, the
user frequently wants to make small changes to the source files and
examine the effects in a previewer; for this phase, \fIlatexmk\fR
provides the powerful \fB-pvc\fR option (mnemonic:  "preview
continuously").  With this option, \fIlatexmk\fR forks a child process
to run an \fIxtex\fR (or other specified) previewer on the document,
and then \fIlatexmk\fR repeatedly monitors the source files of the
document to see if any changes have been made since the last .dvi file
was produced.  When changes are detected, \fIlatexmk\fR runs the
appropriate LaTeX commands to regenerate the .dvi file, and then sends
a signal to \fIxtex\fR job, indicating that the previewer should update
its display.  Thus the user can simply edit a file and, when the
changes are written to disk, \fIlatexmk\fR completely automates the
cycle of updating the .dvi and refreshing the previewer's display.
It's not quite WYSIWYG, but LaTeX has never been closer.
.PP
\fILatexMk\fR has the ability to print a banner in gray diagonally across
each page when making the postscript file.
.SH LATEXMK OPTIONS
.TP
.B file
One or more files can be specified.  If no files are specified,
\fIlatexmk\fR will run on all files in the current working directory
with a ".tex" extention and any files that match any file masks
specified in the \fI$texfile_search\fR variable.

If a file specified does exist, and does not have an ".tex" extention, then
the ".tex" extention is automatically added.  (e.g.  If you specify:

latexmk foo

and the file "foo" does not exist, then \fIlatexmk\fR will try to operate
on the file "foo.tex".
.TP
.B -bm <message>
A banner message to print diagonally accross each page when converting
the dvi file to postscript.  The message must be a single argument on
the command line so be careful with quoting spaces and such.

Note that if the \fB-bm\fR option is specified, the \fB-ps\fR option is
assumed and the postscript file is always generated, even if it is newer
than the dvi file.
.TP
.B -bi <intensity>
How dark to print the banner message.  A decimal number between 0 and 1.
0 is black and 1 is white, default is 0.95 which is ok unless your
toner cartridge is getting low.
.TP
.B -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.  Default is 220.0
which is just right for 5 character messages.
.TP 
.B -c
Clean up (remove) all unnecessary files generated by \fIlatex\fR and
\fIbibtex\fR except dvi and postscript.
.TP 
.B -C
Clean up (remove) all unnecessary files generated by \fIlatex\fR and
\fIbibtex\fR including dvi and postscript.
.TP
.B -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 \fI-bs\fR and \fI-bi\fR options.  The \fI-bm\fR
option will override this option as this is really just a short way of
specifying:

latexmk -bm DRAFT

Note that if the \fB-d\fR option is specified, the \fB-ps\fR option is
assumed and the postscript file is always generated, even if it is newer
than the dvi file.
.TP
.B -dF
Dvi file filtering.  The argument to this option is a filter which will
generate a filtered dvi file with the extention ".dviF".  All extra
processing (e.g. conversion to postscript, preview, printing) will then
be performed on this filtered dvi file.

Exampe usage: Use dviselect to select only the even pages of the dvi file:

latexmk -dF 'dviselect even' foo.tex
.TP
.B -f
Force \fIlatexmk\fR to continue document processing despite errors.
Normally, when \fIlatexmk\fR detects that \fIlatex\fR has found an error
which will not be resolved by further processing, the program terminates.
.TP
.B -F
Force \fIlatexmk\fR to include files that don't exist when generating
dependency files.  A warning is produced instead of an error message and
the program terminating.  If the file name is not an absolute path, it
is assumed to be relative to the current working directory.
.TP
.B -g
Force \fIlatexmk\fR to process document, disregarding the timestamps of the 
source files.
This option is particularly useful when updating style files, which are not
included in the file dependency information.
.TP
.B -h
Print help information.
.TP
.B -i
Scan source files and generate new dependency file if root file is newer
than dependency file or dependency file does not exist.
.TP
.B -I
Always scan source files and generate new dependency file, even if newer
dependency file exists.  This forces a scan.
.TP
.B -l
Run in landscape mode, using the landscape mode previewers and dvi to
postscript converters.
.TP
.B -p
Print out the file using lpr after generating the postscript version.
.TP
.B -ps
Generate postscript version of document.
.TP
.B -pF
Postscript file filtering.  The argument to this option is a filter
which will generate a filtered postscript file with the extention
".psF".  All extra processing (e.g. preview, printing) will then be
performed on this filtered postscript file.

Exampe usage: Use psnup to print two pages on the one page:

latexmk -ps -pF 'psnup -2' foo.tex
.TP
.B -pv
Run file previewer if \fB-ps\fR specified, will run postscript previewer,
otherwise runs dvi previewer.
.TP
.B -pvc
Run a dvi-previewer and continually update the .dvi file whenever changes
are made to source files (see the Description above).
Note that if \fIlatexmk\fR dies because it encounters an error, 
the forked previewer will continue to run.  Successive invocations with
the \fB-pvc\fR option will not fork new previewers, but will find
the existing previewer and send it the signals indicating the .dvi has
been updated.
.TP
.B -r <rcfile>
Read specified RC file before processing.  The contents of the RC file my
override options specified before the \fB-r\fR option, therefore it is
a good idea have the habit of specifying the -r option first.
.TP
.B -s
Set slide mode.
.TP
.B -v
Print version number of \fILatexMk\fR.
.PP
If \fI-ps\fR or \fI-s\fR are specified when the dependency file is created
or updated, then these options are stored in the dependency file.  This
means that these options will automatically be activated without having
to be explicitly specified on the command line in future runs.  Of coarse,
if the dependency file is updated or deleted, these automatic settings will
be lost.
.PP
Options \fI-pv\fR and \fI-pvc\fR require one and only one filename specified
on the command line.
.PP
Options \fI-p\fR, \fI-pv\fR and \fI-pvc\fR are mutually exclusive.
.SH EXAMPLES
.nf
.ta 2i
% \fBlatexmk thesis\fR		\fI# scan for includes, setup thesis.dep
				     if thesis.tex is does not exist\fR

% \fBlatexmk -i thesis\fR	\fI# scan for includes, setup thesis.dep
				     if thesis.tex is newer\fR

% \fBlatexmk -I thesis\fR	\fI# scan for includes, setup thesis.dep\fR

% \fBlatexmk -c\fR		\fI# remove .aux, .log, .bbl, .blg, .dep,
				     .dvi, .ps & .bbe files\fR
.SH RC FILE
.PP
There are four RC files that latexmk can read at startup:
.PP
1) The system RC file "/usr/local/lib/latexmk/LatexMk".
.PP
2) The user's RC file in "$HOME/.latexmkrc".
.PP
3) The RC file in the current working directory called "latexmkrc".
.PP
4) The RC file specified on the command line with the \fB-r\fR option.
.PP
The available variables that can be set are shown below.  Syntax is of the
form:
.PP
$bibtex='bibtex';
.SH RC VARIABLES
.PP
Default values are indicated in brackets.
.TP
.B $banner [0]
If nonzero, the banner message is printed across each page when converting
the dvi file to postscript.  Without modifying $banner_message, this is
equivalent to specifing the \fB-d\fR option.

Note that if \fB$banner\fR is nonzero, the \fB$postscript_mode\fR is
assumed and the postscript file is always generated, even if it is newer
than the dvi file.
.TP
.B $banner_intensity [0.95]
Equivalent to the \fB-bi\fR 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 cartridge isn't
running too low.
.TP
.B $banner_message ['DRAFT']
The banner message to print across each page when converting the dvi
file to postscript.  This is equivalent to the \fB-bm\fR option.
.TP
.B $banner_scale [220.0]
A decimal number that specifies how large the banner message will be
printed.  Experimentation is necessary to get the right scale for your
message, as a rule of thumb the scale should be about equal to 1100
divided by the number of characters in the message.  The Default is
just right for 5 character messages.  This is equivalent to the
\fB-bs\fR option.
.TP
.B $bibtex ['bibtex']
The BibTeX processing program.
.TP
.B $bibtex_mode [0]
If nonzero, the document has a bibtex bibliography.  Set by the \fB-i\fR
and \fB-I\fR options and saved in the dependency file.  Should not need
to set this in an RC file.
.TP
.B $cleanup_mode [0]
If nonzero, specifies cleanup mode.  All other options ignored.
Equivalent to specifying the \fB-c\fR option.  Recommend that this is
not set from an RC file.
.TP
.B $clean_ext ['']
Extra extensions of files for latexmk to remove when the \fB-c\fR option
is selected.
.TP
.B $clean_full_ext ['']
Extra extensions of files for latexmk to remove when the \fB-C\fR option
is selected.
.TP
.B $cus_dep_list [empty]
Custom dependency list (see below).
.TP
.B $dvi_cont_previewer ['xtex']
The dvi-previewer to run with the \fB-pvc\fR option.
.TP
.B $dvi_cont_previewer_landscape ['xtex']
The dvi-previewer to run with the \fB-pvc\fR option in landscape mode.
.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.
.TP
.B $dvi_previewer ['xdvi -s 4']
The dvi-previewer to run with the \fB-pv\fR option.
.TP
.B $dvi_previewer_landscape ['xdvi -s 4 -paper a4r']
The dvi-previewer to run with the \fB-pv\fR option in landscape mode.
.TP
.B $dvips ['dvips']
The program to used as a filter to convert a .dvi file to a .ps file.
.TP
.B $dvips_landscape ['dvips -tlandscape']
The program to used as a filter to convert a .dvi file to a .ps file
in landscape mode.
.TP
.B $force_generate_and_save_includes [0]
If nonzero, specifies that the dependency file should always be
generated.  Equivalent to specifying the \fB-I\fR option.
.TP
.B $force_mode [0]
If nonzero, continue processing past minor \fIlatex\fR errors 
including unrecognized cross references.  Equivalent to specifying the
\fB-f\fR option.
.TP
.B $force_include_mode [0]
If nonzero, force \fIlatexmk\fR to include files that don't exist when
generating dependency files.  A warning is produced instead of an error
message and the program terminating.  If the file name is not an
absolute path, it is assumed to be relative to the current working
directory.  Equivalent to specifying the \fB-F\fR option.
.TP
.B $gererate_and_save_includes [0]
If nonzero, generates dependency file if it does not exist or is older
than the root file (the base .tex file).  Equivalent to specifying
the \fB-i\fR option.
.TP
.B $go_mode [0]
If nonzero, process files regardless of timestamps.  Equivalent to the
\fB-g\fR option.
.TP
.B $index_mode [0]
If nonzero, run \fImakeindex\fR to produce index of document.  Set by
the \fB-i\fR and \fB-I\fR options and saved in the dependency file.
Should not need to set this in an RC file.
.TP
.B $landscape_mode [0]
If nonzero, run in landscape mode, using the landscape mode previewers and
dvi to postscript converters.  Equivalent to the \fB-l\fR option.
.TP
.B $latex ['latex']
The LaTeX processing program.
.TP
.B $lpr ['lpr']
The printing program.
.TP
.B $makeindex ['makeindex']
The index processing program.
.TP
.B $postscript_mode [0]
If nonzero, generate a postscript version of the document.  
Set by the \fB-i\fR and \fB-I\fR options if $slide_mode is set.
Equivalent to the \fB-ps\fR option and is stored in the dependency file
if generated.
.TP
.B $preview_continuous_mode [0]
If nonzero, run the \fB$dvi_previewer\fR to preview the document, and
continue running \fIlatexmk\fR to keep .dvi up-to-date.  Equivalent to
the \fB-pvc\fR option.
.TP
.B $preview_mode [0]
If nonzero, run the \fB$ps_previewer\fR to preview the document.
Equivalent to the \fB-pv\fR option.  
.TP
.B $printout_mode [0]
If nonzero, print the document using \fIlpr\fR.  Equivalent to the
\fB-p\fR option.  Recommend that this is not set from an RC file or
you could waste lots of paper.
.TP
.B $pscmd ['ps -x']
Command used to get all the processes currently run by the user.  This
is used by the -pvc option to try and reattach itself to the already
existing previewer from a previous run with -pvc on the same file.
The default works for SunOS (BSD UNIX?).  For Solaris (System V?) try 'ps'
in the LatexMk RC file.
.TP
.B $ps_filter [empty]
The postscript file filter to be run on the newly produced postscript
file before other processing.  Equivalent to specifying the \fB-pF\fR
option.
.TP
.B $ps_previewer ['gs']
The postscript previewer to run with the \fB-pv\fR option.
.TP
.B $ps_previewer_landscape ['gs -swap']
The postscript previewer to run with the \fB-pv\fR option in landscape mode.
.TP
.B $sleep_time [2]
The time to sleep (in seconds) between checking for source file 
changes when running the \fB-pvc\fR option.
.TP
.B $slide_mode [0]
If nonzero, document is a Slitex document.  Set by the \fB-i\fR
and \fB-I\fR options or the \fB-s\fR option.  Saved in the
dependency file if generated.
.TP
.B $slitex ['slitex']
The SLiTeX processing program for slides.
.TP
.B $texfile_search ['']
If no files were specified on the command line, then \fIlatexmk\fR will
search for and files in the current working directory that end with a
".tex" extention or match the file mask specifed in this variable.

e.g.: $texfile_search = "$texfile_search *.ftex *.c.tex";
.TP
.B $tmpdir ['/usr/tmp']
Directory to store very small temporary files that \fIlatexmk\fR generates
while running.
.SH CUSTOM DEPENDENCIES
.PP
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 \fIlatexmk\fR to convert a \fI.fig\fR file to
\fI.eps\fR to be included in the \fI.tex\fR file.  A table of custom
dependencies are set up by using the \fB@cus_dep_list\fR array.  Each
string in the array has four arguments, separated by a space:
.TP
.B from extention:
The extension of the file we are converting from (e.g. "fig").
.TP
.B to extention:
The extension of the file we are converting to (e.g. "eps").
.TP
.B must:
If non-zero, the file we are converting from \fBmust\fR exist, if it
doesn't exist \fIlatexmk\fR will give an error message and exit unless
the \fB-f\fR option is specified.  If \fImust\fR is zero and the file
we are converting from doesn't exist, then no action is taken.
.TP
.B function:
The name of the subroutine that \fIlatexmk\fR 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 \fIperl\fR.
.PP
Example in an RC file to convert a \fI.fig\fR file to a \fI.eps\fR file:

@cus_dep_list = (@cus_dep_list, "fig eps 0 fig2eps");

sub fig2eps
{
  system("fig2dev -Lps $_[0].fig $_[0].eps");
}

The subroutine \fIfig2eps\fR will only be called if the \fI.fig\fR file
was modified more recently then the \fI.eps\fR file, or the \fI.eps\fR
file does not exist.

If the return value of the subroutine is non-zero, then \fIlatexmk\fR
will assume an error occurred during the execution of the subroutine.

.SH SEE ALSO
latex(1), bibtex(1).
.SH BUGS
If you use macros for generating input file names in your document,
latexmk will not be able to figure out what the name should be when
trying to generate a dependency file.  Using the \fI-F\fR option will
make latexmk ignore these, but latexmk will also obviously not have
a complete dependency list.
.SH IDENTIFICATION
Modifications and enhancements by Evan McLean (Version 2.0)
.br
Original script called "go" by David J. Musliner (RCS Version 3.2)