From becff06c71d277647eda4378203d03ab36e141eb Mon Sep 17 00:00:00 2001 From: mattkae Date: Tue, 17 May 2022 07:07:37 -0400 Subject: Evil mode and latex support --- elpa/auctex-13.1.3/auctex.info | 9633 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 9633 insertions(+) create mode 100644 elpa/auctex-13.1.3/auctex.info (limited to 'elpa/auctex-13.1.3/auctex.info') diff --git a/elpa/auctex-13.1.3/auctex.info b/elpa/auctex-13.1.3/auctex.info new file mode 100644 index 0000000..b9ac9ee --- /dev/null +++ b/elpa/auctex-13.1.3/auctex.info @@ -0,0 +1,9633 @@ +This is auctex.info, produced by makeinfo version 6.8 from auctex.texi. + +This manual is for AUCTeX (version 13.1.3 from 2022-04-16), a +sophisticated TeX environment for Emacs. + + Copyright (C) 1992-1995, 2001, 2002, 2004-2022 Free Software +Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts and no + Back-Cover Texts. A copy of the license is included in the section + entitled "GNU Free Documentation License." +INFO-DIR-SECTION Emacs +START-INFO-DIR-ENTRY +* AUCTeX: (auctex). A sophisticated TeX environment for Emacs. +END-INFO-DIR-ENTRY + +INFO-DIR-SECTION TeX +START-INFO-DIR-ENTRY +* AUCTeX: (auctex). A sophisticated TeX environment for Emacs. +END-INFO-DIR-ENTRY + + +File: auctex.info, Node: Top, Next: Copying, Up: (dir) + +AUCTeX +****** + +This manual may be copied under the conditions spelled out in *note +Copying this Manual::. + + 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 +. + +* Menu: + +* Copying:: Copying +* Introduction:: Introduction to AUCTeX +* Editing:: Editing the Document Source +* Display:: Controlling Screen Display +* Processing:: Starting Processors, Viewers and Other Programs +* Customization:: Customization and Extension +* Appendices:: Copying, Changes, Development, FAQ, Texinfo mode +* Indices:: Indices + + -- The Detailed Node Listing -- + +Introduction + +* Summary:: Overview of AUCTeX +* Installation:: Installing AUCTeX +* Quick Start:: Quick Start + +Editing the Document Source + +* Quotes:: Inserting double quotes +* Font Specifiers:: Inserting Font Specifiers +* Sectioning:: Inserting chapters, sections, etc. +* Environments:: Inserting Environment Templates +* Mathematics:: Entering Mathematics +* Completion:: Completion of macros +* Commenting:: Commenting text +* Indenting:: Reflecting syntactic constructs with whitespace +* Filling:: Automatic and manual line breaking + +Inserting Environment Templates + +* Equations:: Equations +* Floats:: Floats +* Itemize-like:: Itemize-like Environments +* Tabular-like:: Tabular-like Environments +* Customizing Environments:: Customizing Environments + +Controlling Screen Display + +* Font Locking:: Font Locking +* Folding:: Folding Macros and Environments +* Outline:: Outlining the Document +* Narrowing:: Restricting display and editing to a portion of the buffer +* Prettifying:: Displaying Greek and math macros as Unicode characters + +Font Locking + +* Fontification of macros:: Fontification of macros +* Fontification of quotes:: Fontification of quotes +* Fontification of math:: Fontification of math constructs +* Verbatim content:: Verbatim macros and environments +* Faces:: Faces used by font-latex +* Known problems:: Known fontification problems + +Starting Processors, Viewers and Other Programs + +* Commands:: Invoking external commands. +* Viewing:: Invoking external viewers. +* Debugging:: Debugging TeX and LaTeX output. +* Checking:: Checking the document. +* Control:: Controlling the processes. +* Cleaning:: Cleaning intermediate and output files. +* Documentation:: Documentation about macros and packages. + +Viewing the Formatted Output + +* Starting Viewers:: Starting viewers +* I/O Correlation:: Forward and inverse search + +Catching the errors + +* Ignoring warnings:: Controlling warnings to be reported +* Error overview:: List of all errors and warnings + +Customization and Extension + +* Multifile:: Multifile Documents +* Parsing Files:: Automatic Parsing of TeX Files +* Internationalization:: Language Support +* Automatic:: Automatic Customization +* Style Files:: Writing Your Own Style Support + +Language Support + +* European:: Using AUCTeX with European Languages +* Japanese:: Using AUCTeX with Japanese + +Automatic Customization + +* Automatic Global:: Automatic Customization for the Site +* Automatic Private:: Automatic Customization for a User +* Automatic Local:: Automatic Customization for a Directory + +Writing Your Own Style Support + +* Simple Style:: A Simple Style File +* Adding Macros:: Adding Support for Macros +* Adding Environments:: Adding Support for Environments +* Adding Other:: Adding or Examining Other Information +* Hacking the Parser:: Automatic Extraction of New Things + +Copying, Changes, Development, FAQ + +* Copying this Manual:: +* Changes:: +* Development:: +* FAQ:: +* Texinfo mode:: + +Copying this Manual + +* GNU Free Documentation License:: License for copying this manual. + +Indices + +* Key Index:: +* Function Index:: +* Variable Index:: +* Concept Index:: + + + +File: auctex.info, Node: Copying, Next: Introduction, Prev: Top, Up: Top + +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::). + + +File: auctex.info, Node: Introduction, Next: Editing, Prev: Copying, Up: Top + +1 Introduction +************** + +* Menu: + +* Summary:: Overview of AUCTeX +* Installation:: Installing AUCTeX +* Quick Start:: Quick Start + + +File: auctex.info, Node: Summary, Next: Installation, Up: 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 . + + +File: auctex.info, Node: Installation, Next: Quick Start, Prev: Summary, Up: Introduction + +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::. + +* Menu: + +* Prerequisites:: +* Configure:: +* Build/install and uninstall:: +* Loading the package:: +* Advice for package providers:: +* Advice for non-privileged users:: +* Installation under MS Windows:: +* Customizing:: + + +File: auctex.info, Node: Prerequisites, Next: Configure, Up: Installation + +1.2.1 Prerequisites +------------------- + + * GNU Emacs 25.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::. + + +File: auctex.info, Node: Configure, Next: Build/install and uninstall, Prev: Prerequisites, Up: Installation + +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 + addtional 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. + + +File: auctex.info, Node: Build/install and uninstall, Next: Loading the package, Prev: Configure, Up: Installation + +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. + + +File: auctex.info, Node: Loading the package, Next: Advice for package providers, Prev: Build/install and uninstall, Up: Installation + +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. + + +File: auctex.info, Node: Advice for package providers, Next: Advice for non-privileged users, Prev: Loading the package, Up: Installation + +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'. + + +File: auctex.info, Node: Advice for non-privileged users, Next: Installation under MS Windows, Prev: Advice for package providers, Up: Installation + +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) + + +File: auctex.info, Node: Installation under MS Windows, Next: Customizing, Prev: Advice for non-privileged users, Up: Installation + +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! + + +File: auctex.info, Node: Customizing, Prev: Installation under MS Windows, Up: Installation + +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