INSTALLING latexmk ================== (Version 4.05, 11 April 2008) 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 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.) b. A working installation of TeX and LaTeX. (See http://www.ctan.org/ if you don't have one.) Installing on UNIX/LINUX ======================== (Power users can modify these as appropriate.) 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. 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 very system dependent location. The program /usr/bin/env is suppposed to be 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 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 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, 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. 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 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; See step 6 for the locations of these files (under UNIX-like systems). This change is likely to be particularly for Mac OS-X. 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, 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.ps 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 ============= 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 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. 2. 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. 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 system 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-2009 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.