diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/latexmk/INSTALL |
Initial commit
Diffstat (limited to 'support/latexmk/INSTALL')
-rw-r--r-- | support/latexmk/INSTALL | 414 |
1 files changed, 414 insertions, 0 deletions
diff --git a/support/latexmk/INSTALL b/support/latexmk/INSTALL new file mode 100644 index 0000000000..9cb537bfcc --- /dev/null +++ b/support/latexmk/INSTALL @@ -0,0 +1,414 @@ + INSTALLING latexmk + ================== + (Version 4.65, 18 June 2019) + + John Collins + Physics Department + Penn State University + 104 Davey Lab, Box 208 + University Park PA 16802 + U.S.A. + + http://www.personal.psu.edu/jcc8/ + http://www.personal.psu.edu/jcc8/latexmk/ + username jcc8 at node psu.edu + +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 and .fls files. + +Latexmk can be installed and used on UNIX (including LINUX and OS-X), +and MS Windows (tested under WinXP and some later versions). 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.) + +c. In addition, the installation of TeX and LaTex should, of course, + contain the packages etc that are needed for your specific + documents to be compiled and processed. + + +!!!! IMPORTANT NOTE: !!!! +=========================== + +If you have installed a modern distribution of TeX and friends, you +may find that latexmk is already installed on your computer. This is +true for full installations of TeXLive 2009 or later on the operating +systems it supports. (Note that MacTeX on OS-X incorporates TeXLive, +so anything said about TeXLive also applies to MacTeX.) If you have +only installed a subset of packages, e.g., because you installed +BasicTeX, then the subset may not include latexmk; in that case you +should be able to use your distribution's package manager to install +latexmk. This is generally the recommended method; only use the +manual installation method below if you have a special need for it. +However, you should still examine the information on configuration +here and in the main documentation to get latexmk working exactly as +you want it. + +You can test whether latexmk is already properly 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. + +In the case of MiKTeX, the other standard distribution for MS-Windows, +the main difference from TeXLive as regards latexmk is that you may +need to install a distribution of Perl. A standard default +installation of Perl should enable latexmk to work. + + +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 (that includes users of +MacTeX on OS-X). 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. Still you may need to examine the configuration +instructions. + +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/. + + Alternatively, or in addition, put the file latexmk.pdf in a + suitable place for pdf files for documentation. + +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, + /opt/local/share/latexmk/latexmkrc, + /usr/local/share/latexmk/latexmkrc, + /usr/local/lib/latexmk/latexmkrc. + (You get to choose which, but only one. If none of these + directories is appropriate you'll need to modify latexmk.pl.) + + Those directories apply to Unix-like operating systems + (including linux and OS-X). On MS-Windows, the system + start-up file is one of C:\latexmk\LatexMk + C:\latexmk\latexmkrc (If you happen to use Cygwin, latexmk + combines both the MS-Windows and the Unix possibilities.) + + 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. + + (Under normal circumstances, latexmk's definition of home + directory under Unix-like operating systems is the usual one, + i.e., the value in the environment variable HOME. Under + MS-Windows, a user's home directory is normally the directory + of the user profile, as given in the environment variable + USERPROFILE. In general, latexmk takes a user's home + directory to be the directory specified in the first of the + environment variables HOME and USERPROFILE that is non-empty.) + + 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 more 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. + +Similarly if you have MiKTeX, you can install latexmk by using +MiKTeX's package manager. But to allow latexmk to work, you will also +need to install a distribution of Perl if you haven't done so already. + +1. Make sure you have working installations of Perl and TeX/LaTeX, + complete with viewers for dvi and/or postscript files. You will + also need whatever packages your document needs. + +2. If necessary, unpack the latexmk 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. (Warning: the exact details of the instructions + below are subject to change as new versions of MS-Windows come out, + so you may need to do some exploration to find the equivalents of + the instructions under other versions; the principles remain + unchanged.) + + 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. OBSOLETE: 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 jcc8 at node 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 tends to interpret 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. Beware also of files and directories whose names contain non-ASCII + characters. There are some tricky problems because of mismatches + between character codings as used by different software and + operating systems. Latexmk tries to do its best, but problems can + arise. + +4. 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 jcc8 at node +psu.edu) -- other contact details at the top. It is copyright +1998-2019 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 v. 2. |