summaryrefslogtreecommitdiff
path: root/support/latexmk/INSTALL
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/latexmk/INSTALL
Initial commit
Diffstat (limited to 'support/latexmk/INSTALL')
-rw-r--r--support/latexmk/INSTALL414
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.