363 lines
14 KiB
Plaintext
363 lines
14 KiB
Plaintext
@c This is part of the AUCTeX Manual.
|
|
@c Copyright (C) 2003-2007, 2009, 2018, 2021
|
|
@c Free Software Foundation, Inc.
|
|
@c See the file auctex.texi for copying conditions.
|
|
@ifset rawfile
|
|
@include macros.texi
|
|
@end ifset
|
|
|
|
@subheading In a Nutshell
|
|
|
|
The following are brief installation instructions for the impatient. In
|
|
case you don't understand some of this, run into trouble of some sort,
|
|
or need more elaborate information, refer to the detailed instructions
|
|
further below.
|
|
|
|
@enumerate
|
|
@item
|
|
Install the prerequisites, i.e.@: GNU Emacs, MSYS or Cygwin, a @TeX{}
|
|
system, and Ghostscript.
|
|
|
|
@item
|
|
Open the MSYS shell or a Cygwin shell and change to the directory
|
|
containing the unzipped file contents.
|
|
|
|
@item
|
|
Configure @AUCTeX{}:
|
|
|
|
For Emacs: Many people like to install @AUCTeX{} into the pseudo file
|
|
system hierarchy set up by the Emacs installation. Assuming Emacs is
|
|
installed in @file{C:/Program Files/Emacs} and the directory for local
|
|
additions of your @TeX{} system, e.g.@: MiK@TeX{}, is
|
|
@file{C:/localtexmf}, you can do this by typing the following statement
|
|
at the shell prompt:
|
|
|
|
@example
|
|
./configure --prefix='C:/Program Files/Emacs' \
|
|
--infodir='C:/Program Files/Emacs/info' \
|
|
--with-texmf-dir='C:/localtexmf'
|
|
@end example
|
|
|
|
The commands above is example for common usage. More on configuration
|
|
options can be found in the detailed installation instructions below.
|
|
|
|
If the configuration script failed to find all required programs, make
|
|
sure that these programs are in your system path and add directories
|
|
containing the programs to the @env{PATH} environment variable if
|
|
necessary. Here is how to do that in W2000/XP:
|
|
|
|
@enumerate
|
|
@ifclear rawfile
|
|
@cindex Adding to @env{PATH} in Windows
|
|
@cindex @env{PATH} in Windows
|
|
@end ifclear
|
|
@item
|
|
On the desktop, right click ``My Computer'' and select properties.
|
|
@item
|
|
Click on ``Advanced'' in the ``System Properties'' window.
|
|
@item
|
|
Select ``Environment Variables''.
|
|
@item
|
|
Select ``path'' in ``System Variables'' and click ``edit''. Move to the
|
|
front in the line (this might require scrolling) and add the missing
|
|
path including drive letter, ended with a semicolon.
|
|
@end enumerate
|
|
|
|
@item
|
|
If there were no further error messages, type
|
|
|
|
@example
|
|
make
|
|
@end example
|
|
|
|
In case there were, please refer to the detailed description below.
|
|
|
|
@item
|
|
Finish the installation by typing
|
|
|
|
@example
|
|
make install
|
|
@end example
|
|
@end enumerate
|
|
|
|
@subheading Detailed Installation Instructions
|
|
|
|
Installation of @AUCTeX{} under Windows is in itself not more
|
|
complicated than on other platforms. However, meeting the prerequisites
|
|
might require more work than on some other platforms, and feel less
|
|
natural.
|
|
|
|
If you are experiencing any problems, even if you think they are of your
|
|
own making, be sure to report them to @email{auctex-devel@@gnu.org} so
|
|
that we can explain things better in future.
|
|
|
|
Windows is a problematic platform for installation scripts. The main
|
|
problem is that the installation procedure requires consistent file
|
|
names in order to find its way in the directory hierarchy, and Windows
|
|
path names are a mess.
|
|
|
|
The installation procedure tries finding stuff in system search paths
|
|
and in Emacs paths. For that to succeed, you have to use the same
|
|
syntax and spelling and case of paths everywhere: in your system search
|
|
paths, in Emacs' @code{load-path} variable, as argument to the scripts.
|
|
If your path names contain spaces or other `shell-unfriendly'
|
|
characters, most notably backslashes for directory separators, place the
|
|
whole path in @samp{"double quote marks"} whenever you specify it on a
|
|
command line.
|
|
|
|
Avoid `helpful' magic file names like @samp{/cygdrive/c} and
|
|
@samp{C:\PROGRA~1\} like the plague. It is quite unlikely that the
|
|
scripts will be able to identify the actual file names involved. Use
|
|
the full paths, making use of normal Windows drive letters like
|
|
@samp{ 'C:/Program Files/Emacs' } where required, and using the same
|
|
combination of upper- and lowercase letters as in the actual files.
|
|
File names containing shell-special characters like spaces or
|
|
backslashes (if you prefer that syntax) need to get properly quoted to
|
|
the shell: the above example used single quotes for that.
|
|
|
|
Ok, now here are the steps to perform:
|
|
|
|
@enumerate
|
|
@item
|
|
You need to unpack the @AUCTeX{} distribution (which you seemingly have
|
|
done since you are reading this). It must be unpacked in a separate
|
|
installation directory outside of your Emacs file hierarchy: the
|
|
installation will later copy all necessary files to their final
|
|
destination, and you can ultimately remove the directory where you
|
|
unpacked the files.
|
|
|
|
Line endings are a problem under Windows. The distribution contains
|
|
only text files, and theoretically most of the involved tools should get
|
|
along with that. However, the files are processed by various utilities,
|
|
and it is conceivable that not all of them will use the same line ending
|
|
conventions. If you encounter problems, it might help if you try
|
|
unpacking (or checking out) the files in binary mode, if your tools
|
|
allow that.
|
|
|
|
If you don't have a suitable unpacking tool, skip to the next step: this
|
|
should provide you with a working @samp{unzip} command.
|
|
|
|
@item
|
|
The installation of @AUCTeX{} will require the MSYS tool set from
|
|
@uref{http://www.mingw.org/} or the Cygwin tool set from
|
|
@uref{https://cygwin.com/}. The latter is slower and larger (the download
|
|
size of the base system is about 15 MB) but comes with a package manager
|
|
that allows for updating the tool set and installing additional packages
|
|
like, for example, the spell checker @w{aspell}.
|
|
|
|
If Cygwin specific paths like @samp{/cygdrive/c} crop up in the course
|
|
of the installation, using a non-Cygwin Emacs could conceivably cause
|
|
trouble. Using Cygwin either for everything or nothing might save
|
|
headaches, @emph{if} things don't work out.
|
|
|
|
@item
|
|
Install a current version of @w{Emacs} from
|
|
@uref{https://ftp.gnu.org/gnu/emacs/windows/}.
|
|
|
|
@item
|
|
You need a working @TeX{} installation. One popular installation under
|
|
Windows is @uref{https://miktex.org/,MiK@TeX{}}. Another much more
|
|
extensive system is @uref{https://www.tug.org/texlive/,@w{@TeX{} Live}}
|
|
which is rather close to its Unix cousins.
|
|
|
|
@item
|
|
A working copy of @uref{https://www.ghostscript.com/,Ghostscript} is
|
|
required for @previewlatex{} operation. Examining the output from
|
|
@example
|
|
gswin32c -h
|
|
@end example
|
|
on a Windows command line should tell you whether your Ghostscript
|
|
supports the @code{png16m} device needed for @acronym{PNG} support.
|
|
MiK@TeX{} apparently comes with its own Ghostscript called @file{mgs.exe}.
|
|
|
|
@item
|
|
@uref{https://www.perl.org/,Perl} is needed for rebuilding the
|
|
documentation if you are working with a copy from Git or have
|
|
touched documentation source files in the @previewlatex{} part. If the
|
|
line endings of the file @file{preview/latex/preview.dtx} don't
|
|
correspond with what Perl calls @code{\n} when reading text files,
|
|
you'll run into trouble.
|
|
|
|
@item
|
|
Now the fun stuff starts. If you have not yet done so, unpack the
|
|
@AUCTeX{} distribution into a separate directory after rereading the
|
|
instructions for unpacking above.
|
|
|
|
@item
|
|
Ready for takeoff. Start some shell (typically @command{bash}) capable of
|
|
running @command{configure}, change into the installation directory and
|
|
call @command{./configure} with appropriate options.
|
|
|
|
Typical options you'll want to specify will be
|
|
@table @code
|
|
@item --prefix=@var{drive:/path/to/emacs-hierarchy}
|
|
which tells @command{configure} where to perform the installation. It may
|
|
also make @command{configure} find Emacs automatically; if this doesn't
|
|
happen, try @option{--with-emacs} as described below. All automatic
|
|
detection of files and directories restricts itself to directories below
|
|
the @var{prefix} or in the same hierarchy as the program accessing the
|
|
files. Usually, directories like @file{man}, @file{share} and
|
|
@file{bin} will be situated right under @var{prefix}.
|
|
|
|
This option also affects the defaults for placing the Texinfo
|
|
documentation files (see also @option{--infodir} below) and automatically
|
|
generated style hooks.
|
|
|
|
If you have a central directory hierarchy (not untypical with Cygwin)
|
|
for such stuff, you might want to specify its root here. You stand a
|
|
good chance that this will be the only option you need to supply, as
|
|
long as your @TeX{}-related executables are in your system path, which
|
|
they better be for @AUCTeX{}'s operation, anyway.
|
|
|
|
@item --with-emacs
|
|
if you are installing for a version of Emacs. You can use
|
|
@samp{--with-emacs=@var{drive:/path/to/emacs}} to specify the name of the
|
|
installed Emacs executable, complete with its path if necessary (if
|
|
Emacs is not within a directory specified in your @env{PATH} environment
|
|
setting).
|
|
|
|
@item --with-lispdir=@var{drive:/path/to/site-lisp}
|
|
This option tells a place in @code{load-path} below which the
|
|
files are situated. The startup files @file{auctex.el} and
|
|
@file{preview-latex.el} will get installed here unless a subdirectory
|
|
@file{site-start.d} exists which will then be used instead. The other
|
|
files from @AUCTeX{} will be installed in a subdirectory called
|
|
@file{auctex}.
|
|
|
|
If you think that you need a different setup, please refer to the full
|
|
installation instructions in
|
|
@ifset rawfile
|
|
the @file{INSTALL} file.
|
|
@end ifset
|
|
@ifclear rawfile
|
|
@ref{Configure}.
|
|
@end ifclear
|
|
|
|
@item --infodir=@var{drive:/path/to/info/directory}
|
|
If you are installing into an Emacs directory, info files have to be put
|
|
into the @file{info} folder below that directory. The configuration
|
|
script will usually try to install into the folder @file{share/info}, so
|
|
you have to override this by specifying something like
|
|
@samp{--infodir='C:/Program Files/info'} for the configure call.
|
|
|
|
@item --with-auto-dir=@var{drive:/dir}
|
|
Directory containing automatically generated information. You should
|
|
not normally need to set this, as @samp{--prefix} should take care of
|
|
this.
|
|
|
|
@item --disable-preview
|
|
Use this option if your Emacs version is unable to support image
|
|
display.
|
|
|
|
@item --with-texmf-dir=@var{drive:/dir}
|
|
This will specify the directory where your @TeX{} installation sits. If
|
|
your @TeX{} installation does not conform to the @acronym{TDS} (@TeX{} directory
|
|
standard), you may need to specify more options to get everything in
|
|
place.
|
|
@end table
|
|
|
|
For more information about any of the above and additional options, see
|
|
@ifset rawfile
|
|
the `Configure' section in the @file{INSTALL} file.
|
|
@end ifset
|
|
@ifclear rawfile
|
|
@ref{Configure}.
|
|
@end ifclear
|
|
|
|
@c FIXME: It seems this no longer holds.
|
|
@c Calling
|
|
@c @file{./configure --help=recursive}
|
|
@c will tell about other options, but those are almost never required.
|
|
|
|
Some executables might not be found in your path. That is not a good
|
|
idea, but you can get around by specifying environment variables to
|
|
@command{configure}:
|
|
@example
|
|
GS="@var{drive:/path/to/gswin32c.exe}" ./configure @dots{}
|
|
@end example
|
|
should work for this purpose. @file{gswin32c.exe} is the usual name for
|
|
the required @emph{command line} executable under Windows; in contrast,
|
|
@file{gswin32.exe} is likely to fail.
|
|
|
|
As an alternative to specifying variables for the @command{configure} call
|
|
you can add directories containing the required executables to the
|
|
@env{PATH} variable of your Windows system. This is especially a good
|
|
idea if Emacs has trouble finding the respective programs later during
|
|
normal operation.
|
|
|
|
@item
|
|
Run @command{make} in the installation directory.
|
|
|
|
@item
|
|
Run @code{make install} in the installation directory.
|
|
|
|
@item
|
|
With Emacs, activation of @AUCTeX{} and @previewlatex{} depends on a
|
|
working @file{site-start.d} directory or similar setup, since then the
|
|
startup files @file{auctex.el} and @file{preview-latex.el} will have
|
|
been placed there. If this has not been done, you should be able to
|
|
load the startup files manually with
|
|
@lisp
|
|
(load "auctex.el" nil t t)
|
|
(load "preview-latex.el" nil t t)
|
|
@end lisp
|
|
in either a site-wide @file{site-start.el} or your personal startup file
|
|
(usually accessible as @file{~/.emacs} or @file{~/.emacs.d/init.el} from
|
|
within Emacs).
|
|
|
|
@ifclear rawfile
|
|
@cindex @file{tex-mik.el}
|
|
@end ifclear
|
|
The default configuration of @AUCTeX{} is probably not the best fit for
|
|
Windows systems with MiK@TeX{}. You might want to add
|
|
@lisp
|
|
(require 'tex-mik)
|
|
@end lisp
|
|
after loading @file{auctex.el} and @file{preview-latex.el} in order to
|
|
get more appropriate values for some customization options.
|
|
|
|
You can always use
|
|
|
|
@example
|
|
@kbd{M-x customize-group @key{RET} AUCTeX @key{RET}}
|
|
@end example
|
|
|
|
in order to customize more stuff, or use the @samp{Customize} menu.
|
|
|
|
@item
|
|
Load @file{circ.tex} into Emacs and see if you get the @samp{Command}
|
|
menu. Try using it to @LaTeX{} the file.
|
|
|
|
@item
|
|
Check whether the @samp{Preview} menu is available in this file. Use it
|
|
to generate previews for the document.
|
|
|
|
If this barfs and tells you that image type @samp{png} is not supported,
|
|
you can either add @acronym{PNG} support to your Emacs installation or
|
|
choose another image format to be used by @previewlatex{}.
|
|
|
|
Adding support for an image format usually involves the installation of
|
|
a library, e.g.@: from @uref{http://gnuwin32.sf.net/}. If you got your
|
|
Emacs from @uref{https://www.gnu.org/} you might want to check its
|
|
@uref{https://ftp.gnu.org/gnu/emacs/windows/README,README file} for
|
|
details.
|
|
|
|
A different image format can be chosen by setting the variable
|
|
@code{preview-image-type}. While it is recommended to keep the
|
|
@samp{dvipng} or @samp{png} setting, you can temporarily select a
|
|
different format like @samp{pnm} to check if the lack of @acronym{PNG}
|
|
support is the only problem with your Emacs installation.
|
|
|
|
Try adding the line
|
|
|
|
@lisp
|
|
(setq preview-image-type 'pnm)
|
|
@end lisp
|
|
|
|
to your init file for a quick test. You should remove the line after
|
|
the test again, because @acronym{PNM} files take away @strong{vast}
|
|
amounts of disk space, and thus also of load/save time.
|
|
@end enumerate
|
|
|
|
Well, that about is all. Have fun!
|