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.

  1. Install the prerequisites, i.e.  GNU Emacs, MSYS or Cygwin, a TeX
     system, and Ghostscript.

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

  3. 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 'C:/Program Files/Emacs' and the directory for
     local additions of your TeX system, e.g.  MiKTeX, is
     'C:/localtexmf', you can do this by typing the following statement
     at the shell prompt:

          ./configure --prefix='C:/Program Files/Emacs' \
            --infodir='C:/Program Files/Emacs/info' \
            --with-texmf-dir='C:/localtexmf'

     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 'PATH' environment
     variable if necessary.  Here is how to do that in W2000/XP:

       1. On the desktop, right click "My Computer" and select
          properties.
       2. Click on "Advanced" in the "System Properties" window.
       3. Select "Environment Variables".
       4. 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.

  4. If there were no further error messages, type

          make

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

  5. Finish the installation by typing

          make install

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 <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' '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 '"double quote marks"' whenever you specify it on a command line.

   Avoid 'helpful' magic file names like '/cygdrive/c' and
'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 ' '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:

  1. 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 'unzip' command.

  2. The installation of AUCTeX will require the MSYS tool set from
     <http://www.mingw.org/> or the Cygwin tool set from
     <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
     aspell.

     If Cygwin specific paths like '/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, _if_ things don't work out.

  3. Install a current version of Emacs from
     <https://ftp.gnu.org/gnu/emacs/windows/>.

  4. You need a working TeX installation.  One popular installation
     under Windows is MiKTeX (https://miktex.org/).  Another much more
     extensive system is TeX Live (https://www.tug.org/texlive/) which
     is rather close to its Unix cousins.

  5. A working copy of Ghostscript (https://www.ghostscript.com/) is
     required for preview-latex operation.  Examining the output from
          gswin32c -h
     on a Windows command line should tell you whether your Ghostscript
     supports the 'png16m' device needed for PNG support.  MiKTeX
     apparently comes with its own Ghostscript called 'mgs.exe'.

  6. Perl (https://www.perl.org/) is needed for rebuilding the
     documentation if you are working with a copy from Git or have
     touched documentation source files in the preview-latex part.  If
     the line endings of the file 'preview/latex/preview.dtx' don't
     correspond with what Perl calls '\n' when reading text files,
     you'll run into trouble.

  7. 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.

  8. Ready for takeoff.  Start some shell (typically 'bash') capable of
     running 'configure', change into the installation directory and
     call './configure' with appropriate options.

     Typical options you'll want to specify will be
     '--prefix=DRIVE:/PATH/TO/EMACS-HIERARCHY'
          which tells 'configure' where to perform the installation.  It
          may also make 'configure' find Emacs automatically; if this
          doesn't happen, try '--with-emacs' as described below.  All
          automatic detection of files and directories restricts itself
          to directories below the PREFIX or in the same hierarchy as
          the program accessing the files.  Usually, directories like
          'man', 'share' and 'bin' will be situated right under PREFIX.

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

     '--with-emacs'
          if you are installing for a version of Emacs.  You can use
          '--with-emacs=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 'PATH' environment setting).

     '--with-lispdir=DRIVE:/PATH/TO/SITE-LISP'
          This option tells a place in 'load-path' below which the files
          are situated.  The startup files 'auctex.el' and
          'preview-latex.el' will get installed here unless a
          subdirectory 'site-start.d' exists which will then be used
          instead.  The other files from AUCTeX will be installed in a
          subdirectory called 'auctex'.

          If you think that you need a different setup, please refer to
          the full installation instructions in the 'INSTALL' file.

     '--infodir=DRIVE:/PATH/TO/INFO/DIRECTORY'
          If you are installing into an Emacs directory, info files have
          to be put into the 'info' folder below that directory.  The
          configuration script will usually try to install into the
          folder 'share/info', so you have to override this by
          specifying something like '--infodir='C:/Program Files/info''
          for the configure call.

     '--with-auto-dir=DRIVE:/DIR'
          Directory containing automatically generated information.  You
          should not normally need to set this, as '--prefix' should
          take care of this.

     '--disable-preview'
          Use this option if your Emacs version is unable to support
          image display.

     '--with-texmf-dir=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 place.

     For more information about any of the above and additional options,
     see the 'Configure' section in the 'INSTALL' file.

     Calling './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 'configure':
          GS="DRIVE:/PATH/TO/GSWIN32C.EXE" ./configure ...
     should work for this purpose.  'gswin32c.exe' is the usual name for
     the required _command line_ executable under Windows; in contrast,
     'gswin32.exe' is likely to fail.

     As an alternative to specifying variables for the 'configure' call
     you can add directories containing the required executables to the
     'PATH' variable of your Windows system.  This is especially a good
     idea if Emacs has trouble finding the respective programs later
     during normal operation.

  9. Run 'make' in the installation directory.

  10. Run 'make install' in the installation directory.

  11. With Emacs, activation of AUCTeX and preview-latex depends on a
     working 'site-start.d' directory or similar setup, since then the
     startup files 'auctex.el' and '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)
     in either a site-wide 'site-start.el' or your personal startup file
     (usually accessible as '~/.emacs' or '~/.emacs.d/init.el' from
     within Emacs).

     The default configuration of AUCTeX is probably not the best fit
     for Windows systems with MiKTeX.  You might want to add
          (require 'tex-mik)
     after loading 'auctex.el' and 'preview-latex.el' in order to get
     more appropriate values for some customization options.

     You can always use

          M-x customize-group RET AUCTeX RET

     in order to customize more stuff, or use the 'Customize' menu.

  12. Load 'circ.tex' into Emacs and see if you get the 'Command' menu.
     Try using it to LaTeX the file.

  13. Check whether the 'Preview' menu is available in this file.  Use
     it to generate previews for the document.

     If this barfs and tells you that image type 'png' is not supported,
     you can either add PNG support to your Emacs installation or choose
     another image format to be used by preview-latex.

     Adding support for an image format usually involves the
     installation of a library, e.g.  from <http://gnuwin32.sf.net/>.
     If you got your Emacs from <https://www.gnu.org/> you might want to
     check its README file
     (https://ftp.gnu.org/gnu/emacs/windows/README) for details.

     A different image format can be chosen by setting the variable
     'preview-image-type'.  While it is recommended to keep the 'dvipng'
     or 'png' setting, you can temporarily select a different format
     like 'pnm' to check if the lack of PNG support is the only problem
     with your Emacs installation.

     Try adding the line

          (setq preview-image-type 'pnm)

     to your init file for a quick test.  You should remove the line
     after the test again, because PNM files take away *vast* amounts of
     disk space, and thus also of load/save time.

   Well, that about is all.  Have fun!
