auctex / doc / wininstall.texi

Full commit
@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.

Install the prerequisites, i.e. GNU Emacs or XEmacs, MSYS or Cygwin, a
@TeX{} system, and Ghostscript.

Open the MSYS shell or a Cygwin shell and change to the directory
containing the unzipped file contents.

Configure @AUCTeX{}:

For GNU 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:

./configure --prefix='C:/Program Files/Emacs' \
@end example

For XEmacs: You can install @AUCTeX{} as an XEmacs package.  Assuming
XEmacs is installed in @file{C:/Program Files/XEmacs} 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 command at
the shell prompt:

./configure --with-xemacs='C:/Program Files/XEmacs/bin/xemacs' \
@end example

The commands above are examples 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:

@cindex Adding to @env{PATH} in Windows
@cindex @env{PATH} in Windows
On the desktop, right click ``My Computer'' and select properties.
Click on ``Advanced'' in the ``System Properties'' window.
Select ``Environment Variables''.
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

If there were no further error messages, type

@end example

In case there were, please refer to the detailed description below.

Finish the installation by typing

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

If you are experiencing any problems, even if you think they are of your
own making, be sure to report them to @email{} 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:

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.

The installation of @AUCTeX{} will require the MSYS tool set from
@uref{} or the Cygwin tool set from
@uref{}.  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.

Install a current version of XEmacs from @uref{} or
try getting and compiling a developer version of @w{Emacs 22} from
@uref{,Savannah}.  Compiling
Emacs is outside of the scope of this manual.  Precompiled versions are
available from @uref{} (including
@AUCTeX{}) and @uref{}.

If you don't want to use a developer version and @w{Emacs 22} has not
yet been released, it is also possible to use an @w{Emacs 21} binary
from @uref{}, but then you
should disable the installation of @previewlatex{} (it will not work).
Since the developer version has seen quite a few improvements relevant
also for other features of @AUCTeX{}, we really recommend you give it a

You need a working @TeX{} installation.  One popular installation under
Windows is @uref{,MiK@TeX{}}.  Another much more
extensive system is @uref{,@w{@TeX{} Live}}
which is rather close to its Unix cousins.

A working copy of @uref{,Ghostscript} is
required for @previewlatex{} operation.  Examining the output from
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.
MiKTeX apparently comes with its own Ghostscript called @samp{mgs.exe}.

@uref{,Perl} is needed for rebuilding the
documentation if you are working with a copy from @acronym{CVS} 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.

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.

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 @file{configure} where to perform the installation. It may
also make @file{configure} find Emacs or XEmacs automatically; if this
doesn't happen, try one of @samp{--with-emacs} or @samp{--with-xemacs}
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

This option also affects the defaults for placing the Texinfo
documentation files 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

@item --with-xemacs
if you are installing for a version of XEmacs.  Again, you can use
@samp{--with-xemacs=@var{drive:/path/to/xemacs}} to specify the name of the
installed XEmacs executable complete with its path if necessary.  It may
also be necessary to specify this option if a copy of Emacs is found in
your @env{PATH} environment setting, but you still would like to install
a copy of @AUCTeX{} for XEmacs.

@item --with-packagedir=@var{drive:/dir}
is an XEmacs-only option giving the location of the package directory.
This will install and activate the package.  Emacs uses a different
installation scheme:

@item --with-lispdir=@var{drive:/path/to/site-lisp}
This Emacs-only 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

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
@end ifclear

@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

@item --disable-preview
Use this option if your Emacs version is unable to support image
display.  This will be the case if you are using a native variant of
@w{Emacs 21}.

@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 TDS (@TeX{} directory
standard), you may need to specify more options to get everything in
@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
@end ifclear

@file{./configure --help=recursive}
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
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 @file{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.

Run @command{make} in the installation directory.
Run @code{make install} in the installation directory.

With XEmacs, @AUCTeX{} and @previewlatex{} should now be active by
default.  With Emacs, activation 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
(load "auctex.el" nil t t)
(load "preview-latex.el" nil t t)
@end example
in either a site-wide @file{site-start.el} or your personal startup file
(usually accessible as @file{~/.emacs} from within Emacs and
@file{~/.xemacs/init.el} from within XEmacs).

The default configuration of @AUCTeX{} is probably not the best fit for
Windows systems.  You might want to additionally use
(require 'tex-mik)
@end example
(require 'tex-fptex)
@end example
in order to get more appropriate values for MiK@TeX{} and fp@TeX{},

You can always use

@kbd{M-x customize-group RET AUCTeX RET}
@end example

in order to customize more stuff, or use the @samp{Customize} menu.

Load @file{preview/circ.tex} into Emacs or XEmacs and see if you get the
@samp{Command} menu. Try using it to @LaTeX{} the file.

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, try adding the line

(setq preview-image-type 'pnm)
@end example

at the end of your installed version of @file{preview-latex.el}.  If
this helps, complain to wherever you got your Emacs from: all current
Emacs/XEmacs versions capable of running @previewlatex{} by now can be
compiled to support @acronym{PNG} images.  Which is important, 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!