INSTALLING latexmk
            ==================
       (Version 3.07, 28 April 2004)

            John Collins
            Physics Department
            Penn State University
            104 Davey Lab, Box 208
            University Park PA 16802
            U.S.A.  

            http://www.phys.psu.edu/~collins/
            http://www.phys.psu.edu/~collins/software/latexmk/
            username collins at node phys.psu.edu
(E-mail address obfuscated to avoid being harvested by worms and spammers)

LatexMk is a "make" tool for building latex documents. It runs latex
and/or pdflatex the appropriate number of times to resolve cross
references, and, if necessary, it also runs makeindex and/or bibtex when
appropriate.  Then it can make postscript files, print the result or
preview it, as request.  It can also be set to run continuously with a
previewer; the latex program, etc, are rerun whenever one of the source
files is modified.

It automatically determines file dependencies from either the LaTeX .log
file or the source .tex file.  Compared with previous versions, the
current version features: a fully reliable algorithm for deciding how
many times to run latex, greatly improved automatic detection of dependent
files, the ability to generate pdf files using pdflatex, and a continuous
preview mode that actually works.

LatexMk can be installed and used on UNIX (including LINUX), and MS
Windows (tested under Win95 and WinME).  It can presumably be used on
other systems with suitable customization.

On all systems, the prequisites are

a.  A working installation of Perl.  (See http://www.cpan.org/ if you
    don't have one.)

b.  A working installation of TeX and LaTeX.  (See http://www.ctan.org/ if
    you don't have one.)



Installing on UNIX/LINUX
========================

1.  Make sure you have working installations of Perl and TeX/LaTeX.

2.  Put the file latexmk.pl in a directory for executable files.  For
    example, for a system-wide installation, you could put it in
    /usr/local/bin.

3.  Rename this file to latexmk.

4.  Make sure latexmk is executable, e.g., by using chmod suitably.

5.  (Optional) Copy the file latexmk.1 to an appropriate directory for man
    pages, e.g., /usr/local/man/man1/.

6.  Check whether the commands used by latexmk for executing latex etc are
    correct.  Normally the only one you have to worry about is $pscmd.
    This runs the command ps and is used in preview_continuous_mode to
    determine whether a previewer is already running.  The format of the
    output of ps is highly system dependent.  Latexmk should get it right
    under LINUX and Solaris.  If latexmk does not get this or another
    command correct, put an override in a startup file.

    a.  For a system-wide installation, the correction should be in the
        system startup file, which is any one of the files
           /opt/local/share/latexmk/LatexMk,
           /usr/local/share/latexmk/LatexMk,
           /usr/local/lib/latexmk/LatexMk.
        (You get to choose which.)

    b.  If you are installing latexmk as an ordinary user, the startup
        file is the user startup file, which is the file .latexmkrc in
        your home directory.

    The startup files are written in perl, so possible overrides are

        $latex = 'unusual_program_to_run_instead_of_normal_latex';

    for changing the program to run latex, and

        $pscmd = 'ps -aeg';
        $pid_position = 1;

    for the ps command.  Here, $pid_position = 1 indicates that the process
    ID number is in the first column of the output of the command ps.

7.  If you need any modifications on the commands for running previewers,
    like gv, note that prefixing a command by start, as in 

        $ps_previewer = 'start gv -watch';

    ensures that the command is run detached, as is normally appropriate
    for a previewer.


Installing on MS-Windows
========================

(Power users can modify these as appropriate.)

1.  Make sure you have working installations of Perl and TeX/LaTeX,
    complete with viewers for dvi and/or postscript files.

2.  If necessary, unpack the distribution.  [Note: It is a good idea to
    unpack the files so that they have the correct line-end characters for
    MS-Windows.  For example, if you use unzip on latexmk.zip, the command
    unzip -a latexmk.zip should do the job.  If you don't do this
    conversion, it probably won't matter, since much software, including
    perl, MikTeX and emacs, handles MS-Windows and UNIX line ends equally
    well.]

3.  Copy the files latexmk.pl and latexmk.bat to a suitable directory
    (your choice).  One possibility is a directory C:\local\bin.  You will
    need to make sure this directory in the search path for executable
    files --- see the next step.   

4.  If the directory in the previous step is NOT already in the search
    path for executable files, arrange for this: 

    a. Suppose this directory is named C:\local\bin, then  
       in Windows 95, 98 and ME, you should add a line 

              PATH %PATH%;C:\local\bin

       to the end of the C:\AUTOEXEC.BAT file.  (The last part of this
       line is the full name of the directory from step 2.)  This change
       will take effect the next time you reboot.
    
    b. In Windows NT, XP, etc, there is an item in the Control Panel
       to achieve the same effect.

5.  (Optional) Copy documentation file(s) to a suitable directory.  The
    only requirement on the directory is your convenience: some convenient
    place to look up documentation. The relevant files are latexmk.txt
    which is a pure ASCII text file, and latexmk.ps which is a postscript
    file.  

6.  Check whether perl is in the search path for executables.  (E.g., from
    the MSDOS command-line prompt, try the command perl --version.) If
    perl is not in the search path, then modify the first line of
    latexmk.bat (which you installed at step 2) by replacing the command
    perl by the full path name for perl, e.g., C:\perl\bin\perl.exe.

7.  Reboot if you made any changes to the path at step 3.  Test out the
    installation at the command-line prompt:

    a. First do

            latexmk --version

       This should show you the version number of latexmk.  If this works
       latexmk is accessible.  If not, you will have to figure out what
       did not work in the previous steps.

    b. Then change to a directory where you have a good LaTeX file.
       Suppose the file is paper.tex.  Delete any pre-existing dvi file,
       so that latexmk is forced to remake the output files.  The
       following commands will check out the main features of latexmk:

            latexmk paper
            latexmk -pv paper
            latexmk -pv -ps paper

       The first command will create the dvi file, running latex a
       suitable number of times, and additionally running bibtex and
       makeindex, but only if needed.  The second command will open a
       viewer of the dvi file.  The third command will create a postscript
       file, and then open a viewer for it.

    c. If the above works, you are done.  If not, you will have to figure
       out what is wrong, and correct it.  FIRST, READ THE DOCUMENTATION!
       The normal problems are that the names for the commands used by
       latexmk are incorrect for your system, or they are not present on
       your system.  See the next item for how to customize latexmk.
       Also LOOK AT THE SECTION NAMED "TRICKY POINTS" below to see some
       hints. 


8.  If the commands used by latexmk are incorrect, see the UNIX
    installation instructions for what to do.  The only changes needed
    from the UNIX instructions are: 

    a.  The system initialization file is C:\latexmk\LatexMk.  

    b.  The user initialization file is .latexmkrc in the directory
        specified by the environment variable HOME.  If there is no HOME
        variable, then the file is in the root directory of the current
        drive. 

       
Other systems
=============

You are on your own.  The instructions for UNIX/LINUX and MS-Windows
should help you to see what to do.  Let me know (username collins at
node phys.psu.edu) what happens, so that I can update these
instructions and possibly latexmk as well.


Tricky points
=============

1.  Finding files in other directories.  Sometimes your source files will
    be somewhere other than the current directory.  This typically occurs
    in a big project, where you want to avoid cluttering your main
    directory with lots of figure files, etc.  Sometimes, latexmk (and
    latex and bibtex for that matter) will fail to find these files.  This
    may result in latex not updating the dvi files when a figure file or a
    bibliography file has changed.  Here are a few pointers:

    a.  Latexmk normally has no problem with finding included tex files,
        since full path information on these is in the log file that LaTeX 
        generates. 

    b.  So the problem is primarily with graphics files input by LaTeX and
        with .bib files read by bibtex (if you use it). 

    c.  The easiest way to handle this is to set the environment variables
        TEXINPUTS and BIBINPUTS.  If you have files in subdirectories, you
        probably already have discovered how to do this, since most
        versions of tex, latex and bibtex use these variables for this
        purpose.  For example if you have figure files in
        a subdirectory figs of the current directory, and bib files in a
        subdirectory bibs, then under csh/tcsh in UNIX you could do

               setenv TEXINPUTS figs:
               setenv BIBINPUTS bibs:

        before running latexmk.  Note the trailing colon, that tells all
        the programs also to look in the default places.  (Latexmk's make
        default place is merely the current directory.)

    d.  Under MSWindows, the separator is a semicolon, not a colon.

    e.  Not all versions of latex and bibtex respond to these environment
        variables. 

2.  BEWARE of filenames with funny extensions, for example, two.part.tex,
    with a double extension.  The behavior of TeX-related software is not
    consistent in this situation.  You may, for example, find a log file
    named two.log or two.part.log, depending on which version of which
    implementation of TeX/LaTeX you use.  Naturally, there is a
    possibility that latexmk will get confused, and not recognize, for
    example, that a dvi file has been generated.  Latexmk has some
    configuration variables to deal with some of the possibilities, so you
    could try playing with them --- see the code.  But it general, it is
    best to avoid such double extensions: they make your files
    non-portable.  Do something like two-part.tex or two_part.tex
    instead. 

3.  The same goes for filenames and directory names with spaces in them.
    Much software interprets spaces as separators between different file
    names or between filenames and other text.  



Credits
=======

The original version of this program was called 'go', and written by David
Musliner.  That version is Copyright 1992 by David J. Musliner and The
University of Michigan.

Version 2 was modified by Evan McLean.

The current version is by John Collins (username collins at node
phys.psu.edu) -- other contact details at the top.  It is copyright
1998-2001 by John Collins, and the previous authors; see the copyright
notice in the latexmk.pl file, which gives permission to use, copy,
modify, and distribute this software and its documentation under the
terms of the GNU Public License.