auctex / texi / wininstall.texi

Full commit
@include macros.texi

Installation of @AUCTeX{} is a bit more complicated, but we are working
to resolve the issues involved. Please report success/failure to us at
@samp{}. Here are the steps to perform:

The installation of @AUCTeX{} will require the MSYS tool set from
@uref{}. If you have the Cygwin tool set from
@uref{} installed, that should do just fine as well,
but it is quite larger and slower.

If you are installing @AUCTeX{} with one of those sets for an Emacs
compiled in a different one, you should try to avoid tool-specific path
names like @file{/cygwin/c}.  Instead, use the @file{c:} syntax.  It
might also help to use forward slashes instead of the backward slashes
more typical for @w{MS Windows}: while backward slashes are supposed to
work if properly escaped in the shell, this is one area easily
overlooked by the developers.  The same holds for file or directory
names with spaces in them.  Of course, we want to hear about any
problems in that area.

Compiling Emacs is outside of the scope of this manual.  @AUCTeX{}
itself does not require a @w{C compiler} for installation.

Install GNU Emacs from @uref{}
or XEmacs from @uref{}.

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.

Now the fun stuff starts. Unpack the @AUCTeX{} distribution into some
installation directory. @strong{Do not} unpack it right into your Emacs'
own directories: the installation will copy the material that needs to
be placed there. Keep the installation directory separate: you can
remove its contents after installation completes. Since you are reading
this, you probably have already unpacked @AUCTeX{}, but it should still
be easy to move it elsewhere now.

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-directory}
which makes sure that (1) the AUCTeX manual will be installed in the
@file{info/} directory of your Emacs installation and (2) the
automatically generated global style hooks will be installed in the
@file{var/} directory of your Emacs installation.  If you are collecting
stuff like that in a central directory hierarchy (not untypical with
Cygwin), you might want to specify that here instead.  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 Emacs. You can use
@samp{--with-emacs=@var{/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 @var{PATH} environment

@item --with-xemacs
If you are using XEmacs, of course use @samp{--with-xemacs} in the same
manner.  It may also be necessary to specify this option if a copy of
Emacs is in your path, but you would like to install @AUCTeX{} for
XEmacs, too.

@item --with-lispdir=@var{/dir}
This may be needed for GNU Emacs installation, but hopefully
@command{configure} should figure this out by itself. Don't use this for
XEmacs, rather use

@item --with-packagedir=@var{/dir}
which gives the location of the package directory for XEmacs where stuff
should be installed. Again, hopefully this is not necessary to specify.

@item --with-tex-input-dirs=@var{/dir-1/;/dir-2/;...;/dir-N/}
This option allows to specify the directories to be used for file
searches, e.g. for completion of LaTeX or BibTeX style file names.  They
will be used in the variable @code{TeX-macro-global}.

@command{configure} will usually figure out the right value for this option
but will only succeed if it finds the necessary programs of the @TeX{}
system in the system path.  Which should be there for running @AUCTeX{},

@item --with-auto-dir=@var{/dir}
Directory containing automatically generated information.  You should
not normally need to set this, as @samp{--prefix} should take care of
@end table

Some additional information about the above options may be found in
@ifset rawfile
the `Configure' section in the @file{INSTALL} file.
@end ifset
@ifclear rawfile
@end ifclear

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{/path/to/GhostScript}" ./configure @dots{}
@end example
should work for this purpose.
@end ignore

If you need to use the prebuilt documentation (see above), now is the
time to unpack it over the rest of the installation directory.

Run @command{make} in the installation directory (we have had one report
that Emacs did not manage to byte compile the Elisp files, and that had
to be done by hand.  No idea about what might have gone wrong there).
Run @code{make install} in the installation directory.

For GNU Emacs, the recommended way to activate @AUCTeX{} is to add the
following line to your @file{.emacs} file:

(require 'tex-site)
@end example

The configuration for Windows systems is probably not quite fitting.
Instead of loading @file{tex-site.el} in that manner, you might want to
load @file{tex-mik.el} (for Mik@TeX{}) or @file{tex-fptex} (for
fp@TeX{}) instead.  Those will lead to somewhat more appropriate values
for your system.  You can always use

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

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

Load a @file{.tex} file Emacs or XEmacs and see if you get the
@samp{Command} menu. Try using that to @LaTeX{} the file.

@end enumerate
Well, that about is all.  Have fun!