path: root/Master/texmf-dist/doc/support/latexmk/INSTALL

            INSTALLING latexmk
            ==================
      (Version 4.22e, 3 February 2011)

            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/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 etc, and, if necessary, it also runs makeindex and/or
bibtex (or biber) and other programs when appropriate.  Then it can
make postscript or pdf files, print the result or preview it, as
requested.  It can also be set to run continuously with a previewer;
the latex program, etc, are then rerun whenever one of the source
files is modified.  Latexmk automatically determines file dependencies
from the LaTeX .log file.

Latexmk can be installed and used on UNIX (including LINUX and OS-X),
and MS Windows (tested under WinXP).  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.  Modern UNIX-like systems, particularly linux and
    OS-X, normally have perl installed by default.  As for MSWindows,
    the TeXLive distribution (2009 or later) includes Perl, and also
    includes latexmk.)

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


!!!!  IMPORTANT NOTE:  !!!!
===========================

If you have installed a modern distribution of TeX and friends, you
may find that latexmk is already installed on your computer.  If not,
you may be able to install it by using your distribution's package
manager.

This is definitely the case for TeXLive 2009 or later, which is also
an essential component of MacTeX.  I have also read that another major
distribution MiKTeX also includes latexmk, but I have not checked this
for myself.

You can test whether latexmk is already installed by trying the
command "latexmk -v" from the command line.  If this succeeds, then
latexmk is already installed.  Otherwise, if you are using TeXLive or
MacTeX, then you can simply use its package manager to get latexmk
installed, the same as for any other missing package.

If you are on MS-Windows and you are using TeXLive (2009, or later),
this distribution also includes a distribution of Perl sufficient to
run latexmk.pl, so you don't need to install Perl separately.  It also
includes an executable file latexmk.exe that runs latexmk, so you
don't have to use the latexmk.bat that is part of the latexmk
distribution.




Installing on UNIX/LINUX/OS-X
=============================

(Power users can modify these as appropriate.)

NOTE: If you are using TeXLive 2009 or later, you can install latexmk
simply by using the TeXLive package manager.  In fact, depending on
how much of TeXLive you have already installed, latexmk may already
have been installed.  In that case you don't normally need to bother
with the manual installation explained below.  

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.  But if you are an ordinary user, you can put the
    file somewhere where you have access, and ensure that the PATH
    environment variable includes the directory where latexmk is
    installed.  

3.  Rename this file to latexmk.

4.  Make sure latexmk is executable, e.g., by using chmod suitably.
        [Special case, which you probably don't have to be concerned
        with: You may also find it necessary to change the first line
        of the script so that perl can be found to execute latexmk.
        Currently the first line is #!/usr/bin/env perl, which uses
        the program /usr/bin/env to find perl, provided only that the
        perl executable can be found in the PATH for executables.
        This insulates latexmk from the fact that the perl executable
        has a system-dependent location. The program /usr/bin/env is
        present on almost all modern UNIX/Linux systems.]

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.  The ones you particularly have to worry about are
    those for previewing files ($pdf_previewer, $ps_previewer, and
    $dvi_previwer), and most importantly $pscmd, and its associated
    variable $pid_position --- see below.  The command $pscmd is the
    least obvious: it 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 OS-X.
    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, but only one.  If none of these
        directories is appropriate you'll need to modify latexmk.pl.)

    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 like

        $latex = 'unusual_program_to_run_instead_of_normal_latex %O %S';

    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.  See the latexmk.pl file for some examples.

    To determine what commands latexmk currently uses run the
    following: 

        latexmk --commands


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 %O %S';

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

    (In the examples above, there appear the strings %O and %S.  See
    the documenation for details.  They are placeholders used when
    latexmk constructs the command line.  %O denotes any options
    latexmk wants to add to the command invocation, and %S denotes the
    source file.)

8.  You may also want to change the defaults on what kinds of output
    file latexmk makes.  By default latexmk makes dvi files, but not
    postscript or pdf files.  If you (or people on your system)
    generally make pdf files using pdflatex, it would be a good idea
    to put the following in an appropriate initialization file:

            $pdf_mode = 1;
            $postscript_mode = 0;
            $dvi_mode = 0;

    This change is particularly useful for Mac OS-X.  See step 6 for
    the locations of the initialization/configuration files (under
    UNIX-like systems), where you should put this lines.


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

(Power users can modify these as appropriate.)

NOTE: If you are using TeXLive 2009 or later, you can install latexmk
simply by using the TeXLive package manager.  In fact, depending on
how much of TeXLive you have already installed, latexmk may already
have been installed.  In that case you don't normally need to bother
with the manual installation explained below.  

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, by adjusting the
    environment variable PATH suitably.  Suppose the latexmk directory
    is C:\local\bin.   

    a. In Windows XP, there is an item in the Control Panel to adjust
       the environment: normally Control Panel -> Performance and
       Maintenance -> System.  The pick the tab Advanced and click on
       Environment Variables.  

       (i) If you are a REGULAR user, examine the User variables.  If
           there is already an entry for PATH, append a semicolon and
           then the name of latexmk's directory (e.g., C:\local\bin).
           If not, then make a new variable named PATH with the value
           %PATH%;C:\local\bin  

       (ii) If you are an administrator, examine the System variables,
            and adjust the entry to PATH, as above.

    b. ONLY in Windows 95, 98 and ME: you will need to add a line to
       the end of the C:\AUTOEXEC.BAT file.  Suppose the directory for
       latexmk is named C:\local\bin, then the line you add is

              PATH %PATH%;C:\local\bin
      
       This change will take effect the next time you reboot.
    
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.pdf which is a postscript
    file.  

6.  Check whether perl is in the search path for executables.  (E.g.,
    from the MS-Windows 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.  You may need to reboot, or at least logoff and log back in, 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.  (If
        this is not suitable for some reason, you'll need to change
        the latexmk.pl file where this filename appears.)

    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 directory specified by the
        environment variable USERPROFILE, which should have been set
        by the MS-Windows operating system at login.


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

For 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.  BEWARE of filenames with double extensions, for example,
    two.part.tex.  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 in this situation that latexmk will get confused, and
    not recognize, for example, that a dvi file has been generated.
    Latexmk has 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.

2.  The same goes for filenames and directory names with spaces in them.
    Much software interprets spaces as separators between different
    filenames or between filenames and other text.  This can cause
    problems in some of the programs called by latexmk.  It can also
    cause problems when latexmk parses a .log file to determine
    dependency information.  Latexmk does try to correctly treat
    filenames with spaces, as do current implementations of the TeX
    program.

3.  If you need to remake documentation files, e.g., latexmk.pdf or
    latexmk.txt, from the man page file latexmk.1, the following
    commands work (on my linux and OS-X systems at least):

    Postscript file from latexmk.1:

        groff -Tps -man-old -rcR=0 latexmk.1 > latexmk.ps

    Pdf file from postscript:

        ps2pdf latexmk.ps latexmk.pdf

    Text file:

        groff -Tascii -man-old -rcR=0 latexmk.1 > latexmk.txt



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-2011 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.