diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/latexmk/INSTALL')
-rw-r--r-- | Master/texmf-dist/doc/support/latexmk/INSTALL | 271 |
1 files changed, 271 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/latexmk/INSTALL b/Master/texmf-dist/doc/support/latexmk/INSTALL new file mode 100644 index 00000000000..225e1c6e6b5 --- /dev/null +++ b/Master/texmf-dist/doc/support/latexmk/INSTALL @@ -0,0 +1,271 @@ + INSTALLING latexmk + ================== + (Version 4.00, 12 March 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 +======================== + +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 like + + $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, 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 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. 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. + + 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. 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-2008 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. |