summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexmk/INSTALL
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/support/latexmk/INSTALL')
-rw-r--r--Master/texmf-dist/doc/support/latexmk/INSTALL271
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.