AUCTeX ****** This manual may be copied under the conditions spelled out in *note Copying this Manual::. AUCTeX Copying 1 Introduction 1.1 Overview of AUCTeX 1.2 Installing AUCTeX 1.2.1 Prerequisites 1.2.2 Configure 1.2.3 Build/install and uninstall 1.2.4 Loading the package 1.2.5 Providing AUCTeX as a package 1.2.6 Installation for non-privileged users 1.2.6.1 Using AUCTeX from local Git repo 1.2.7 Installation under MS Windows 1.2.8 Customizing 1.3 Quick Start 1.3.1 Functions for editing TeX files 1.3.1.1 Making your TeX code more readable 1.3.1.2 Entering sectioning commands 1.3.1.3 Inserting environments 1.3.1.4 Inserting macros 1.3.1.5 Changing the font 1.3.1.6 Other useful features 1.3.2 Creating and viewing output, debugging 1.3.2.1 One Command for LaTeX, helpers, viewers, and printing 1.3.2.2 Choosing an output format 1.3.2.3 Debugging LaTeX 1.3.2.4 Running LaTeX on parts of your document 2 Editing the Document Source 2.1 Insertion of Quotes, Dollars, and Braces 2.2 Inserting Font Specifiers 2.3 Inserting chapters, sections, etc. 2.4 Inserting Environment Templates 2.4.1 Equations 2.4.2 Floats 2.4.3 Itemize-like Environments 2.4.4 Tabular-like Environments 2.4.5 Customizing Environments 2.5 Entering Mathematics 2.6 Completion 2.7 Marking Environments, Sections, or Texinfo Nodes 2.7.1 LaTeX Commands for Marking Environments and Sections 2.7.2 Texinfo Commands for Marking Environments and Sections 2.8 Commenting 2.9 Indenting 2.10 Filling 3 Controlling Screen Display 3.1 Font Locking 3.1.1 Fontification of macros 3.1.2 Fontification of quotes 3.1.3 Fontification of mathematical constructs 3.1.4 Verbatim macros and environments 3.1.5 Faces used by font-latex 3.1.6 Known fontification problems 3.2 Folding Macros and Environments 3.3 Outlining the Document 3.4 Narrowing 3.5 Prettifying 4 Starting Processors, Viewers and Other Programs 4.1 Executing Commands 4.1.1 Starting a Command on a Document or Region 4.1.2 Selecting and Executing a Command 4.1.3 Options for TeX Processors 4.2 Viewing the Formatted Output 4.2.1 Starting Viewers 4.2.2 Forward and Inverse Search 4.3 Catching the errors 4.3.1 Controlling warnings to be reported 4.3.2 List of all errors and warnings 4.4 Checking for problems 4.5 Controlling the output 4.6 Cleaning intermediate and output files 4.7 Documentation about macros and packages 5 Customization and Extension 5.1 Modes and Hooks 5.2 Multifile Documents 5.3 Automatic Parsing of TeX Files 5.4 Language Support 5.4.1 Using AUCTeX with European Languages 5.4.1.1 Typing and Displaying Non-ASCII Characters 5.4.1.2 Style Files for Different Languages 5.4.2 Using AUCTeX with Japanese TeX 5.5 Automatic Customization 5.5.1 Automatic Customization for the Site 5.5.2 Automatic Customization for a User 5.5.3 Automatic Customization for a Directory 5.6 Writing Your Own Style Support 5.6.1 A Simple Style File 5.6.2 Adding Support for Macros 5.6.3 Adding Support for Environments 5.6.4 Adding or Examining Other Information 5.6.4.1 Adding bibliographies in style hooks 5.6.4.2 Examining Package/Class Options 5.6.4.3 Adding Support for Option Completion 5.6.5 Automatic Extraction of New Things Appendix A Copying, Changes, Development, FAQ, Texinfo Mode A.1 Copying this Manual A.1.1 GNU Free Documentation License A.2 Changes and New Features A.3 Future Development A.3.1 Mid-term Goals A.3.2 Wishlist A.3.3 Bugs A.4 Frequently Asked Questions A.5 Features specific to AUCTeX's Texinfo major mode A.5.1 How AUCTeX and the native mode work together A.5.2 Where the native mode is superseded A.5.3 Where key bindings are mapped to the native mode A.5.4 Which native mode key bindings are missing Indices Key Index Function Index Variable Index Concept Index AUCTeX is an integrated environment for editing LaTeX, ConTeXt, docTeX, Texinfo, and TeX files. Although AUCTeX contains a large number of features, there are no reasons to despair. You can continue to write TeX and LaTeX documents the way you are used to, and only start using the multiple features in small steps. AUCTeX is not monolithic, each feature described in this manual is useful by itself, but together they provide an environment where you will make very few LaTeX errors, and makes it easy to find the errors that may slip through anyway. It is a good idea to make a printout of AUCTeX's reference card ‘tex-ref.tex’ or one of its typeset versions. If you want to make AUCTeX aware of style files and multifile documents right away, insert the following in your init file (usually ‘~/.emacs.d/init.el’). (setq TeX-auto-save t) (setq TeX-parse-self t) (setq-default TeX-master nil) Another thing you should enable is RefTeX, a comprehensive solution for managing cross references, bibliographies, indices, document navigation and a few other things. (*Note (reftex)Installation::.) For detailed information about the preview-latex subsystem of AUCTeX, see *note Introduction: (preview-latex)Top. There is a mailing list for general discussion about AUCTeX: write a mail with "subscribe" in the subject to to join it. Send contributions to . Bug reports should go to , suggestions for new features, and pleas for help should go to either (the AUCTeX developers), or to if they might have general interest. Please use the command ‘M-x TeX-submit-bug-report ’ to report bugs if possible. You can subscribe to a low-volume announcement list by sending "subscribe" in the subject of a mail to . Copying ******* AUCTeX primarily consists of Lisp files for Emacs, but there are also installation scripts and files and TeX support files. All of those are “free”; this means that everyone is free to use them and free to redistribute them on a free basis. The files of AUCTeX are not in the public domain; they are copyrighted and there are restrictions on their distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of these programs that they might get from you. Specifically, we want to make sure that you have the right to give away copies of the files that constitute AUCTeX, that you receive source code or else can get it if you want it, that you can change these files or use pieces of them in new free programs, and that you know you can do these things. To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of parts of AUCTeX, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights. Also, for our own protection, we must make certain that everyone finds out that there is no warranty for AUCTeX. If any parts are modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation. The precise conditions of the licenses for the files currently being distributed as part of AUCTeX are found in the General Public Licenses that accompany them. This manual specifically is covered by the GNU Free Documentation License (*note Copying this Manual::). 1 Introduction ************** 1.1 Overview of AUCTeX ====================== AUCTeX is a comprehensive customizable integrated environment for writing input files for TeX, LaTeX, ConTeXt, Texinfo, and docTeX using Emacs. It supports you in the insertion of macros, environments, and sectioning commands by providing completion alternatives and prompting for parameters. It automatically indents your text as you type it and lets you format a whole file at once. The outlining and folding facilities provide you with a focused and clean view of your text. AUCTeX lets you process your source files by running TeX and related tools (such as output filters, post processors for generating indices and bibliographies, and viewers) from inside Emacs. AUCTeX lets you browse through the errors TeX reported, while it moves the cursor directly to the reported error, and displays some documentation for that particular error. This will even work when the document is spread over several files. One component of AUCTeX that LaTeX users will find attractive is preview-latex, a combination of folding and in-source previewing that provides true "What You See Is What You Get" experience in your sourcebuffer, while letting you retain full control. More detailed information about the features and usage of AUCTeX can be found in the remainder of this manual. AUCTeX is written entirely in Emacs Lisp, and hence you can easily add new features for your own needs. It is a GNU project and distributed under the 'GNU General Public License Version 3'. The most recent version is always available at . WWW users may want to check out the AUCTeX page at . For comprehensive information about how to install AUCTeX *Note Installation::, or *note Installation under MS Windows::, respectively. If you are considering upgrading AUCTeX, the recent changes are described in *note Changes::. If you want to discuss AUCTeX with other users or its developers, there are several mailing lists you can use. Send a mail with the subject "subscribe" to in order to join the general discussion list for AUCTeX. Articles should be sent to . In a similar way, you can subscribe to the list for just getting important announcements about AUCTeX. The list is for bug reports which you should usually file with the ‘M-x TeX-submit-bug-report ’ command. If you want to address the developers of AUCTeX themselves with technical issues, they can be found on the discussion list . 1.2 Installing AUCTeX ===================== The modern and strongly recommended way of installing AUCTeX is by using the Emacs package manager integrated in Emacs 24 and greater (ELPA). Simply do ‘M-x list-packages ’, mark the auctex package for installation with ‘i’, and hit ‘x’ to execute the installation procedure. That's all. ‘use-package’ users can use this simple recipe in their ‘user-init-file’ which essentially does the same as the manual installation explained above. (use-package tex :ensure auctex) Using the ELPA version has several advantages. Besides being platform and OS independent, you will receive intermediate bugfix releases between major AUCTeX releases conveniently. For past ELPA releases, see . Once the installation is completed, you can skip the rest of this section and proceed to *note Quick Start::. The remainder of this section is about installing AUCTeX from a release tarball or from a checkout of the AUCTeX repository. Installing AUCTeX should be simple: merely ‘./configure’, ‘make’, and ‘make install’ for a standard site-wide installation (most other installations can be done by specifying a ‘--prefix=...’ option). On many systems, this will already activate the package, making its modes the default instead of the built-in modes of Emacs. If this is not the case, consult *note Loading the package::. Please read through this document fully before installing anything. The installation procedure has changed as compared to earlier versions. Users of MS Windows are asked to consult *Note Installation under MS Windows::. 1.2.1 Prerequisites ------------------- • GNU Emacs 26.1 or higher Using preview-latex requires a version of Emacs compiled with image support. Windows Precompiled versions are available from . macOS For an overview of precompiled versions of Emacs for macOS see for example . GNU/Linux Most GNU/Linux distributions nowadays provide a recent variant of Emacs via their package repositories. Self-compiled Compiling Emacs yourself requires a C compiler and a number of tools and development libraries. Details are beyond the scope of this manual. Instructions for checking out the source code can be found at . • A working TeX installation Well, AUCTeX would be pointless without that. Processing documentation requires TeX, LaTeX and Texinfo during installation. preview-latex requires Dvips or ‘dvipng’ for its operation in DVI mode. The default configuration of AUCTeX is tailored for TeX Live-based distributions, but can be adapted easily. • A recent Ghostscript This is needed for operation of preview-latex in both DVI and PDF mode. Ghostscript version 7.07 or newer is required. • GNU make Recent AUCTeX uses GNU make specific capabilities in the Makefiles. If your OS's default ‘make’ command is not GNU make, you have to obtain it in order to build AUCTeX by yourself. GNU make is sometimes provided under the name ‘gmake’ in your OS's binary package system. • The Texinfo package Strictly speaking, you can get away without it if you are building from the distribution tarball, have not modified any files and don't need a printed version of the manual: the pregenerated info file is included in the tarball. At least version 4.0 is required. For some known issues with various software, see *note (preview-latex)Known problems::. 1.2.2 Configure --------------- The first step is to configure the source code, telling it where various files will be. To do so, run ./configure OPTIONS (Note: if you have fetched AUCTeX from Git rather than a regular release, you will have to first follow the instructions in ‘README.GIT’). On many machines, you will not need to specify any options, but if ‘configure’ cannot determine something on its own, you'll need to help it out with one of these options: ‘--prefix=PREFIX’ All automatic placements for package components will be chosen from sensible existing hierarchies below this: directories like ‘man’, ‘share’ and ‘bin’ are supposed to be directly below PREFIX. Only if no workable placement can be found there, in some cases an alternative search will be made in a prefix deduced from a suitable binary. ‘/usr/local’ is the default PREFIX, intended to be suitable for a site-wide installation. If you are packaging this as an operating system component for distribution, the setting ‘/usr’ will probably be the right choice. See *note Advice for package providers:: for detail. If you are planning to install the package as a single non-priviledged user, you will typically set PREFIX to your home directory. Consult *note Advice for non-privileged users:: for additional instructions. ‘--with-emacs=/PATH/TO/EMACS’ If you are using a pretest which isn't in your ‘PATH’, or ‘configure’ is not finding the right Emacs executable, you can specify it with this option. ‘--with-lispdir=LISPDIR’ This option specifies the location of the ‘site-lisp’ directory within ‘load-path’ under which the files will get installed (the bulk will get installed in a subdirectory). ‘./configure’ should figure this out by itself. ‘--with-auctexstartfile=auctex.el’ ‘--with-previewstartfile=preview-latex.el’ This is the name of the respective startup files. If LISPDIR contains a subdirectory ‘site-start.d’, the start files are placed there, and ‘site-start.el’ should load them automatically. Please be aware that you must not move the start files after installation since other files are found _relative_ to them. ‘--with-packagelispdir=auctex’ This is the directory where the bulk of the package gets located. The startfile adds this into ‘load-path’. ‘--with-auto-dir=/DIR’ You can use this option to specify the directory containing automatically generated information by ‘M-x TeX-auto-generate-global ’. It is not necessary for most TeX installs, but may be used if you don't like the directory that configure is suggesting. ‘--help’ This is not an option specific to AUCTeX. A number of standard options to ‘configure’ exist, and we do not have the room to describe them here; a short description of each is available, using ‘--help’. ‘--disable-preview’ This disables configuration and installation of preview-latex. This option is not actually recommended. If your Emacs does not support images, you should really upgrade to a newer version. Distributors should, if possible, refrain from distributing AUCTeX and preview-latex separately in order to avoid confusion and upgrade hassles if users install partial packages on their own. ‘--with-texmf-dir=/DIR’ ‘--without-texmf-dir’ This option is used for specifying a TDS-compliant directory hierarchy. Using ‘--with-texmf-dir=/DIR’ you can specify where the TeX TDS directory hierarchy resides, and the TeX files will get installed in ‘/DIR/tex/latex/preview/’. If you use the ‘--without-texmf-dir’ option, the TeX-related files will be kept in the Emacs Lisp tree, and at runtime the ‘TEXINPUTS’ environment variable will be made to point there. You can install those files into your own TeX tree at some later time with ‘M-x preview-install-styles ’. ‘--with-tex-dir=/DIR’ If you want to specify an exact directory for the preview TeX files, use ‘--with-tex-dir=/DIR’. In this case, the files will be placed in ‘/DIR’, and you'll also need the following option: ‘--with-doc-dir=/DIR’ This option may be used to specify where the TeX documentation goes. It is to be used when you are using ‘--with-tex-dir=/DIR’, but is normally not necessary otherwise. 1.2.3 Build/install and uninstall --------------------------------- Once ‘configure’ has been run, simply enter make at the prompt to byte-compile the lisp files, extract the TeX files and build the documentation files. To install the files into the locations chosen earlier, type make install You may need special privileges to install, e.g., if you are installing into system directories. Should you want to completely remove the installed package, in the same directory you built AUCTeX run make uninstall You will need administration privileges if you installed the package into system directories. 1.2.4 Loading the package ------------------------- You can detect the successful activation of AUCTeX and preview-latex in the menus after loading a LaTeX file like ‘circ.tex’: AUCTeX then gives you a ‘Command’ menu, and preview-latex gives you a ‘Preview’ menu. With Emacs (or if you explicitly disabled use of the package system), the startup files ‘auctex.el’ and ‘preview-latex.el’ may already be in a directory of the ‘site-start.d/’ variety if your Emacs installation provides it. In that case they should be automatically loaded on startup and nothing else needs to be done. If not, they should at least have been placed somewhere in your ‘load-path’. You can then load them by placing the lines (load "auctex.el" nil t t) (load "preview-latex.el" nil t t) into your init file such as ‘init.el’ or ‘.emacs’. If you explicitly used ‘--with-lispdir’, you may need to add the specified directory into Emacs' ‘load-path’ variable by adding something like (add-to-list 'load-path "~/elisp") before the above lines into your Emacs startup file. For site-wide activation in GNU Emacs, see *Note Advice for package providers::. Once activated, the modes provided by AUCTeX are used per default for all supported file types. If you want to change the modes for which it is operative instead of the default, use M-x customize-option TeX-modes If you want to remove a preinstalled AUCTeX completely before any of its modes have been used, (unload-feature 'tex-site) should accomplish that. 1.2.5 Providing AUCTeX as a package ----------------------------------- As a package provider, you should make sure that your users will be served best according to their intentions, and keep in mind that a system might be used by more than one user, with different preferences. There are people that prefer the built-in Emacs modes for editing TeX files, in particular plain TeX users. There are various ways to tell AUCTeX even after auto-activation that it should not get used, and they are described in *note Introduction to AUCTeX: Introduction. So if you have users that don't want to use the preinstalled AUCTeX, they can easily get rid of it. Activating AUCTeX by default is therefore a good choice. If the installation procedure did not achieve this already by placing ‘auctex.el’ and ‘preview-latex.el’ into a possibly existing ‘site-start.d’ directory, you can do this by placing (load "auctex.el" nil t t) (load "preview-latex.el" nil t t) in the system-wide ‘site-start.el’. The ‘--without-texmf-dir’ option can be convenient for systems that are intended to support more than a single TeX distribution. Since more often than not TeX packages for operating system distributions are either much more outdated or much less complete than separately provided systems like TeX Live, this method may be generally preferable when providing packages. The following package structure would be adequate for a typical fully supported Unix-like installation: ‘preview-tetex’ Style files and documentation for ‘preview.sty’, placed into a TeX tree where it is accessible from the teTeX executables usually delivered with a system. If there are other commonly used TeX system packages, it might be appropriate to provide separate packages for those. ‘auctex-emacs-tetex’ This package will require the installation of ‘preview-tetex’ and will record in ‘TeX-macro-global’ where to find the TeX tree. It is also a good idea to run emacs -batch -f TeX-auto-generate-global when either AUCTeX or teTeX get installed or upgraded. If your users might want to work with a different TeX distribution (nowadays pretty common), instead consider the following: ‘auctex-emacs’ This package will be compiled with ‘--without-texmf-dir’ and will consequently contain the ‘preview’ style files in its private directory. It will probably not be possible to initialize ‘TeX-macro-global’ to a sensible value, so running ‘TeX-auto-generate-global’ does not appear useful. This package would neither conflict with nor provide ‘preview-tetex’. 1.2.6 Installation for non-privileged users ------------------------------------------- Often people without system administration privileges want to install software for their private use. In that case you need to pass more options to the ‘configure’ script. The main expedient is using the ‘--prefix’ option to the ‘configure’ script, and let it point to the personal home directory. In that way, resulting binaries will be installed under the ‘bin’ subdirectory of your home directory, manual pages under ‘man’ and so on. It is reasonably easy to maintain a bunch of personal software, since the prefix argument is supported by most ‘configure’ scripts. You often need to specify ‘--with-lispdir’ option as well. If you haven't installed Emacs under your home directory and use Emacs installed in system directories, the ‘configure’ script might not be able to figure out suitable place to install lisp files under your home directory. In that case, the ‘configure’ script would silently choose, by default, the ‘site-lisp’ directory within ‘load-path’ for the place, where administration privileges are usually required to put relevant files. Thus you will have to tell the ‘configure’ script explicitly where to put those files by, e.g., ‘--with-lispdir=‘/home/myself/share/emacs/site-lisp’’. You'll have to add something like ‘/home/myself/share/emacs/site-lisp’ to your ‘load-path’ variable, if it isn't there already. In addition, you will have to tell ‘configure’ script where to install TeX-related files such as ‘preview.sty’ if preview-latex isn't disabled. It is enough to specify ‘--with-texmf-dir=$HOME/texmf’ for most typical cases, but you have to create the direcotry ‘$HOME/texmf’ in advance if it doesn't exist. If this prescription doesn't work, consider using one or more of the options ‘--with-texmf-dir=/DIR’, ‘--without-texmf-dir’, ‘--with-tex-dir=/DIR’ and ‘--with-doc-dir=/DIR’. See *note Configure:: for detail of these options. Now here is another thing to ponder: perhaps you want to make it easy for other users to share parts of your personal Emacs configuration. In general, you can do this by writing ‘~myself/’ anywhere where you specify paths to something installed in your personal subdirectories, not merely ‘~/’, since the latter, when used by other users, will point to non-existent files. For yourself, it will do to manipulate environment variables in your ‘.profile’ resp. ‘.login’ files. But if people will be copying just Elisp files, their copies will not work. While it would in general be preferable if the added components where available from a shell level, too (like when you call the standalone info reader, or try using ‘preview.sty’ for functionality besides of Emacs previews), it will be a big help already if things work from inside of Emacs. Here is how to do the various parts: Making the Elisp available .......................... In GNU Emacs, it should be sufficient if people just do (load "~myself/share/emacs/site-lisp/auctex.el" nil t t) (load "~myself/share/emacs/site-lisp/preview-latex.el" nil t t) where the path points to your personal installation. The rest of the package should be found relative from there without further ado. Making the Info files available ............................... For making the info files accessible from within Elisp, something like the following might be convenient to add into your or other people's startup files: (eval-after-load 'info '(add-to-list 'Info-directory-list "~myself/info")) Making the LaTeX style available ................................ If you want others to be able to share your installation, you should configure it using ‘--without-texmf-dir’, in which case things should work as well for them as for you. 1.2.6.1 Using AUCTeX from local Git repo ........................................ With the techniques described above, it is also possible to use AUCTeX directly from a local Git repository. Let's assume you have your Git repositories under ‘~/development/’. First, you have to fetch a copy of the AUCTeX Git repository. In a shell, change directory to ‘~/development/’ and do: git clone https://git.savannah.gnu.org/git/auctex.git Now change directory to ‘~/development/auctex’ and run ‘./autogen.sh’. Next thing is to run ‘configure’ like this: ./configure --without-texmf-dir --with-lispdir=. When finished, simply enter make and you're finished. Note that the ‘make install’ step is not necessary. Now you have to tell Emacs about the plan. The following variables must be set in your init file because their normal values are only correct when AUCTeX is installed: (setq TeX-data-directory "~/development/auctex" TeX-lisp-directory TeX-data-directory) The info files will be available with this: (eval-after-load 'info '(add-to-list 'Info-additional-directory-list "~/development/auctex/doc")) Now you're ready to load ‘auctex.el’ and ‘preview-latex.el’ out of this directory: (load "~/development/auctex/auctex.el" nil t t) (load "~/development/auctex/preview-latex.el" nil t t) 1.2.7 Installation under MS Windows ----------------------------------- 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 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 or the Cygwin tool set from . 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 . 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 *note Configure::. ‘--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 *note Configure::. 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 AUCTeX 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 . If you got your Emacs from 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! 1.2.8 Customizing ----------------- Most of the site-specific customization should already have happened during configuration of AUCTeX. Any further customization can be done with customization buffers directly in Emacs. Just type ‘M-x customize-group AUCTeX ’ to open the customization group for AUCTeX or use the menu entries provided in the mode menus. Editing the file ‘tex-site.el’ as suggested in former versions of AUCTeX should not be done anymore because the installation routine will overwrite those changes. You might check some options with a special significance. They are accessible directly by typing ‘M-x customize-option