1 This is auctex.info, produced by makeinfo version 4.13 from auctex.texi.
3 This manual is for AUCTeX (version 11.86 from 2010-02-21), a
4 sophisticated TeX environment for Emacs.
6 Copyright (C) 1992, 1993, 1994, 1995, 2001, 2002, 2004, 2005, 2006,
7 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
9 Permission is granted to copy, distribute and/or modify this
10 document under the terms of the GNU Free Documentation License,
11 Version 1.3 or any later version published by the Free Software
12 Foundation; with no Invariant Sections, no Front-Cover Texts and
13 no Back-Cover Texts. A copy of the license is included in the
14 section entitled "GNU Free Documentation License."
16 INFO-DIR-SECTION Emacs
18 * AUCTeX: (auctex). A sophisticated TeX environment for Emacs.
22 * AUCTeX: (auctex). A sophisticated TeX environment for Emacs.
26 File: auctex.info, Node: Top, Next: Copying, Up: (dir)
31 This manual may be copied under the conditions spelled out in *note
32 Copying this Manual::.
34 AUCTeX is an integrated environment for editing LaTeX, ConTeXt,
35 docTeX, Texinfo, and TeX files.
37 Although AUCTeX contains a large number of features, there are no
38 reasons to despair. You can continue to write TeX and LaTeX documents
39 the way you are used to, and only start using the multiple features in
40 small steps. AUCTeX is not monolithic, each feature described in this
41 manual is useful by itself, but together they provide an environment
42 where you will make very few LaTeX errors, and makes it easy to find
43 the errors that may slip through anyway.
45 It is a good idea to make a printout of AUCTeX's reference card
46 `tex-ref.tex' or one of its typeset versions.
48 If you want to make AUCTeX aware of style files and multi-file
49 documents right away, insert the following in your `.emacs' file.
51 (setq TeX-auto-save t)
52 (setq TeX-parse-self t)
53 (setq-default TeX-master nil)
55 Another thing you should enable is RefTeX, a comprehensive solution
56 for managing cross references, bibliographies, indices, document
57 navigation and a few other things. (*note Installation:
58 (reftex)Installation.)
60 For detailed information about the preview-latex subsystem of
61 AUCTeX, see *note Introduction: (preview-latex)Top.
63 There is a mailing list for general discussion about AUCTeX: write a
64 mail with "subscribe" in the subject to <auctex-request@gnu.org> to
65 join it. Send contributions to <auctex@gnu.org>.
67 Bug reports should go to <bug-auctex@gnu.org>, suggestions for new
68 features, and pleas for help should go to either <auctex-devel@gnu.org>
69 (the AUCTeX developers), or to <auctex@gnu.org> if they might have
70 general interest. Please use the command `M-x TeX-submit-bug-report
71 RET' to report bugs if possible. You can subscribe to a low-volume
72 announcement list by sending "subscribe" in the subject of a mail to
73 <info-auctex-request@gnu.org>.
78 * Introduction:: Introduction to AUCTeX
79 * Editing:: Editing the Document Source
80 * Display:: Controlling Screen Display
81 * Processing:: Starting Processors, Viewers and Other Programs
82 * Customization:: Customization and Extension
83 * Appendices:: Copying, Changes, Development, FAQ
86 --- The Detailed Node Listing ---
90 * Summary:: Overview of AUCTeX
91 * Installation:: Installing AUCTeX
92 * Quick Start:: Quick Start
94 Editing the Document Source
96 * Quotes:: Inserting double quotes
97 * Font Specifiers:: Inserting Font Specifiers
98 * Sectioning:: Inserting chapters, sections, etc.
99 * Environments:: Inserting Environment Templates
100 * Mathematics:: Entering Mathematics
101 * Completion:: Completion of macros
102 * Commenting:: Commenting text
103 * Indenting:: Reflecting syntactic constructs with whitespace
104 * Filling:: Automatic and manual line breaking
106 Inserting Environment Templates
108 * Equations:: Equations
110 * Itemize-like:: Itemize-like Environments
111 * Tabular-like:: Tabular-like Environments
112 * Customizing Environments:: Customizing Environments
114 Controlling Screen Display
116 * Font Locking:: Font Locking
117 * Folding:: Folding Macros and Environments
118 * Outline:: Outlining the Document
122 * Fontification of macros:: Fontification of macros
123 * Fontification of quotes:: Fontification of quotes
124 * Fontification of math:: Fontification of math constructs
125 * Verbatim content:: Verbatim macros and environments
126 * Faces:: Faces used by font-latex
128 Starting Processors, Viewers and Other Programs
130 * Commands:: Invoking external commands.
131 * Viewing:: Invoking external viewers.
132 * Debugging:: Debugging TeX and LaTeX output.
133 * Checking:: Checking the document.
134 * Control:: Controlling the processes.
135 * Cleaning:: Cleaning intermediate and output files.
136 * Documentation:: Documentation about macros and packages.
138 Viewing the Formatted Output
140 * Starting Viewers:: Starting viewers
141 * I/O Correlation:: Forward and inverse search
143 Customization and Extension
145 * Multifile:: Multifile Documents
146 * Parsing Files:: Automatic Parsing of TeX Files
147 * Internationalization:: Language Support
148 * Automatic:: Automatic Customization
149 * Style Files:: Writing Your Own Style Support
153 * European:: Using AUCTeX with European Languages
154 * Japanese:: Using AUCTeX with Japanese
156 Automatic Customization
158 * Automatic Global:: Automatic Customization for the Site
159 * Automatic Private:: Automatic Customization for a User
160 * Automatic Local:: Automatic Customization for a Directory
162 Writing Your Own Style Support
164 * Simple Style:: A Simple Style File
165 * Adding Macros:: Adding Support for Macros
166 * Adding Environments:: Adding Support for Environments
167 * Adding Other:: Adding Other Information
168 * Hacking the Parser:: Automatic Extraction of New Things
170 Copying, Changes, Development, FAQ
172 * Copying this Manual::
179 * GNU Free Documentation License:: License for copying this manual.
189 File: auctex.info, Node: Copying, Next: Introduction, Prev: Top, Up: Top
194 AUCTeX primarily consists of Lisp files for Emacs (and XEmacs), but
195 there are also installation scripts and files and TeX support files.
196 All of those are "free"; this means that everyone is free to use them
197 and free to redistribute them on a free basis. The files of AUCTeX are
198 not in the public domain; they are copyrighted and there are
199 restrictions on their distribution, but these restrictions are designed
200 to permit everything that a good cooperating citizen would want to do.
201 What is not allowed is to try to prevent others from further sharing
202 any version of these programs that they might get from you.
204 Specifically, we want to make sure that you have the right to give
205 away copies of the files that constitute AUCTeX, that you receive source
206 code or else can get it if you want it, that you can change these files
207 or use pieces of them in new free programs, and that you know you can do
210 To make sure that everyone has such rights, we have to forbid you to
211 deprive anyone else of these rights. For example, if you distribute
212 copies of parts of AUCTeX, you must give the recipients all the rights
213 that you have. You must make sure that they, too, receive or can get
214 the source code. And you must tell them their rights.
216 Also, for our own protection, we must make certain that everyone
217 finds out that there is no warranty for AUCTeX. If any parts are
218 modified by someone else and passed on, we want their recipients to
219 know that what they have is not what we distributed, so that any
220 problems introduced by others will not reflect on our reputation.
222 The precise conditions of the licenses for the files currently being
223 distributed as part of AUCTeX are found in the General Public Licenses
224 that accompany them. This manual specifically is covered by the GNU
225 Free Documentation License (*note Copying this Manual::).
228 File: auctex.info, Node: Introduction, Next: Editing, Prev: Copying, Up: Top
235 * Summary:: Overview of AUCTeX
236 * Installation:: Installing AUCTeX
237 * Quick Start:: Quick Start
240 File: auctex.info, Node: Summary, Next: Installation, Up: Introduction
242 1.1 Overview of AUCTeX
243 ======================
245 AUCTeX is a comprehensive customizable integrated environment for
246 writing input files for TeX, LaTeX, ConTeXt, Texinfo, and docTeX using
249 It supports you in the insertion of macros, environments, and
250 sectioning commands by providing completion alternatives and prompting
251 for parameters. It automatically indents your text as you type it and
252 lets you format a whole file at once. The outlining and folding
253 facilities provide you with a focused and clean view of your text.
255 AUCTeX lets you process your source files by running TeX and related
256 tools (such as output filters, post processors for generating indices
257 and bibliographies, and viewers) from inside Emacs. AUCTeX lets you
258 browse through the errors TeX reported, while it moves the cursor
259 directly to the reported error, and displays some documentation for
260 that particular error. This will even work when the document is spread
263 One component of AUCTeX that LaTeX users will find attractive is
264 preview-latex, a combination of folding and in-source previewing that
265 provides true "What You See Is What You Get" experience in your
266 sourcebuffer, while letting you retain full control.
268 More detailed information about the features and usage of AUCTeX can
269 be found in the remainder of this manual.
271 AUCTeX is written entirely in Emacs Lisp, and hence you can easily
272 add new features for your own needs. It is a GNU project and
273 distributed under the `GNU General Public License Version 3'.
275 The most recent version is always available at
276 `http://ftp.gnu.org/pub/gnu/auctex/'.
278 WWW users may want to check out the AUCTeX page at
279 `http://www.gnu.org/software/auctex/'.
281 For comprehensive information about how to install AUCTeX *Note
282 Installation::, or *note Installation under MS Windows::, respectively.
284 If you are considering upgrading AUCTeX, the recent changes are
285 described in *note Changes::.
287 If you want to discuss AUCTeX with other users or its developers,
288 there are several mailing lists you can use.
290 Send a mail with the subject "subscribe" to <auctex-request@gnu.org>
291 in order to join the general discussion list for AUCTeX. Articles
292 should be sent to <auctex@gnu.org>. In a similar way, you can
293 subscribe to the <info-auctex@gnu.org> list for just getting important
294 announcements about AUCTeX. The list <bug-auctex@gnu.org> is for bug
295 reports which you should usually file with the `M-x
296 TeX-submit-bug-report <RET>' command. If you want to address the
297 developers of AUCTeX themselves with technical issues, they can be
298 found on the discussion list <auctex-devel@gnu.org>.
301 File: auctex.info, Node: Installation, Next: Quick Start, Prev: Summary, Up: Introduction
303 1.2 Installing AUCTeX
304 =====================
306 Installing AUCTeX should be simple: merely `./configure', `make',
307 and `make install' for a standard site-wide installation (most other
308 installations can be done by specifying a `--prefix=...' option).
310 On many systems, this will already activate the package, making its
311 modes the default instead of the built-in modes of Emacs. If this is
312 not the case, consult *note Loading the package::. Please read through
313 this document fully before installing anything. The installation
314 procedure has changed as compared to earlier versions. Users of
315 MS Windows are asked to consult *Note Installation under MS Windows::.
322 * Loading the package::
323 * Advice for package providers::
324 * Advice for non-privileged users::
325 * Installation under MS Windows::
329 File: auctex.info, Node: Prerequisites, Next: Configure, Up: Installation
334 * A recent version of Emacs, alternatively XEmacs
336 Emacs 20 is no longer supported, and neither is XEmacs with a
337 version of `xemacs-base' older than 1.84 (released in sumo from
338 02/02/2004). Using preview-latex requires a version of Emacs
339 compiled with image support. While the X11 version of Emacs 21
340 will likely work, Emacs 22 and later is the preferred platform.
343 Precompiled versions are available from
344 `ftp://ftp.gnu.org/gnu/emacs/windows/'.
347 For an overview of precompiled versions of Emacs for Mac OS X
349 `http://www.emacswiki.org/cgi-bin/wiki/EmacsForMacOS'.
352 Most GNU/Linux distributions nowadays provide a variant of
353 Emacs 22 or later via their package repositories.
356 Compiling Emacs yourself requires a C compiler and a number
357 of tools and development libraries. Details are beyond the
358 scope of this manual. Instructions for checking out the
359 source code can be found at
360 `https://savannah.gnu.org/bzr/?group=emacs'.
362 If you really need to use Emacs 21 on platforms where this implies
363 missing image support, you should disable the installation of
364 preview-latex (see below).
366 While XEmacs (version 21.4.15, 21.4.17 or later) is supported,
367 doing this in a satisfactory manner has proven to be difficult.
368 This is mostly due to technical shortcomings and differing API's
369 which are hard to come by. If AUCTeX is your main application for
370 XEmacs, you are likely to get better results and support by
371 switching to Emacs. Of course, you can improve support for your
372 favorite editor by giving feedback in case you encounter bugs.
374 * A working TeX installation
376 Well, AUCTeX would be pointless without that. Processing
377 documentation requires TeX, LaTeX and Texinfo during installation.
378 preview-latex requires Dvips for its operation in DVI mode. The
379 default configuration of AUCTeX is tailored for teTeX or
380 TeXlive-based distributions, but can be adapted easily.
382 * A recent Ghostscript
384 This is needed for operation of preview-latex in both DVI and PDF
385 mode. Most versions of Ghostscript nowadays in use should work
386 fine (version 7.0 and newer). If you encounter problems, check
387 *note Problems with Ghostscript: (preview-latex)Problems with
390 * The `texinfo' package
392 Strictly speaking, you can get away without it if you are building
393 from the distribution tarball, have not modified any files and
394 don't need a printed version of the manual: the pregenerated info
395 file is included in the tarball. At least version 4.0 is required.
398 For some known issues with various software, see *note Known
399 problems: (preview-latex)Known problems.
402 File: auctex.info, Node: Configure, Next: Build/install, Prev: Prerequisites, Up: Installation
407 The first step is to configure the source code, telling it where
408 various files will be. To do so, run
412 (Note: if you have fetched AUCTeX from CVS rather than a regular
413 release, you will have to first follow the instructions in
416 On many machines, you will not need to specify any options, but if
417 `configure' cannot determine something on its own, you'll need to help
418 it out with one of these options:
420 `--prefix=`/usr/local''
421 All automatic placements for package components will be chosen from
422 sensible existing hierarchies below this: directories like `man',
423 `share' and `bin' are supposed to be directly below PREFIX.
425 Only if no workable placement can be found there, in some cases an
426 alternative search will be made in a prefix deduced from a suitable
429 `/usr/local' is the default PREFIX, intended to be suitable for a
430 site-wide installation. If you are packaging this as an operating
431 system component for distribution, the setting `/usr' will
432 probably be the right choice. If you are planning to install the
433 package as a single non-priviledged user, you will typically set
434 PREFIX to your home directory.
436 `--with-emacs[=/PATH/TO/EMACS]'
437 If you are using a pretest which isn't in your `$PATH', or
438 `configure' is not finding the right Emacs executable, you can
439 specify it with this option.
441 `--with-xemacs[=/PATH/TO/XEMACS]'
442 Configure for generation under XEmacs (Emacs is the default).
443 Again, the name of the right XEmacs executable can be specified,
444 complete with path if necessary.
446 `--with-packagedir=/DIR'
447 This XEmacs-only option configures the directory for XEmacs
448 packages. A typical user-local setting would be
449 `~/.xemacs/xemacs-packages'. If this directory exists and is
450 below PREFIX, it should be detected automatically. This will
451 install and activate the package.
453 `--without-packagedir'
454 This XEmacs-only option switches the detection of a package
455 directory and corresponding installation off. Consequently, the
456 Emacs installation scheme will be used. This might be appropriate
457 if you are using a different package system/installer than the
458 XEmacs one and want to avoid conflicts.
460 The Emacs installation scheme has the following options:
462 `--with-lispdir=/DIR'
463 This Emacs-only option specifies the location of the `site-lisp'
464 directory within `load-path' under which the files will get
465 installed (the bulk will get installed in a subdirectory).
466 `./configure' should figure this out by itself.
468 `--with-auctexstartfile=`auctex.el''
469 `--with-previewstartfile=`preview-latex.el''
470 This is the name of the respective startup files. If LISPDIR
471 contains a subdirectory `site-start.d', the start files are placed
472 there, and `site-start.el' should load them automatically. Please
473 be aware that you must not move the start files after installation
474 since other files are found _relative_ to them.
476 `--with-packagelispdir=`auctex''
477 This is the directory where the bulk of the package gets located.
478 The startfile adds this into LOAD-PATH.
480 `--with-auto-dir=/DIR'
481 You can use this option to specify the directory containing
482 automatically generated information. It is not necessary for most
483 TeX installs, but may be used if you don't like the directory that
484 configure is suggesting.
487 This is not an option specific to AUCTeX. A number of standard
488 options to `configure' exist, and we do not have the room to
489 describe them here; a short description of each is available, using
490 `--help'. If you use `--help=recursive', then also
491 preview-latex-specific options will get listed.
494 This disables configuration and installation of preview-latex.
495 This option is not actually recommended. If your Emacs does not
496 support images, you should really upgrade to a newer version.
497 Distributors should, if possible, refrain from distributing AUCTeX
498 and preview-latex separately in order to avoid confusion and
499 upgrade hassles if users install partial packages on their own.
501 `--with-texmf-dir=/DIR
503 This option is used for specifying a TDS-compliant directory
504 hierarchy. Using `--with-texmf-dir=/DIR' you can specify where
505 the TeX TDS directory hierarchy resides, and the TeX files will
506 get installed in `/DIR/tex/latex/preview/'.
508 If you use the `--without-texmf-dir' option, the TeX-related files
509 will be kept in the Emacs Lisp tree, and at runtime the
510 `TEXINPUTS' environment variable will be made to point there. You
511 can install those files into your own TeX tree at some later time
512 with `M-x preview-install-styles RET'.
514 `--with-tex-dir=/DIR'
515 If you want to specify an exact directory for the preview TeX
516 files, use `--with-tex-dir=/DIR'. In this case, the files will be
517 placed in `/DIR', and you'll also need the following option:
519 `--with-doc-dir=/DIR'
520 This option may be used to specify where the TeX documentation
521 goes. It is to be used when you are using `--with-tex-dir=/DIR',
522 but is normally not necessary otherwise.
525 File: auctex.info, Node: Build/install, Next: Loading the package, Prev: Configure, Up: Installation
530 Once `configure' has been run, simply enter
534 at the prompt to byte-compile the lisp files, extract the TeX files and
535 build the documentation files. To install the files into the locations
540 You may need special privileges to install, e.g., if you are
541 installing into system directories.
544 File: auctex.info, Node: Loading the package, Next: Advice for package providers, Prev: Build/install, Up: Installation
546 1.2.4 Loading the package
547 -------------------------
549 You can detect the successful activation of AUCTeX and preview-latex in
550 the menus after loading a LaTeX file like `preview/circ.tex': AUCTeX
551 then gives you a `Command' menu, and preview-latex gives you a
554 For XEmacs, if the installation occured into a valid package
555 directory (which is the default), then this should work out of the box.
557 With Emacs (or if you explicitly disabled use of the package system),
558 the startup files `auctex.el' and `preview-latex.el' may already be in
559 a directory of the `site-start.d/' variety if your Emacs installation
560 provides it. In that case they should be automatically loaded on
561 startup and nothing else needs to be done. If not, they should at
562 least have been placed somewhere in your `load-path'. You can then
563 load them by placing the lines
565 (load "auctex.el" nil t t)
566 (load "preview-latex.el" nil t t)
570 If you explicitly used `--with-lispdir', you may need to add the
571 specified directory into Emacs' `load-path' variable by adding
574 (add-to-list 'load-path "~/elisp")
576 before the above lines into your Emacs startup file.
578 For site-wide activation in GNU Emacs, see *Note Advice for package
581 Once activated, the modes provided by AUCTeX are used per default for
582 all supported file types. If you want to change the modes for which it
583 is operative instead of the default, use
584 M-x customize-variable <RET> TeX-modes <RET>
586 If you want to remove a preinstalled AUCTeX completely before any of
587 its modes have been used,
588 (unload-feature 'tex-site)
589 should accomplish that.
592 File: auctex.info, Node: Advice for package providers, Next: Advice for non-privileged users, Prev: Loading the package, Up: Installation
594 1.2.5 Providing AUCTeX as a package
595 -----------------------------------
597 As a package provider, you should make sure that your users will be
598 served best according to their intentions, and keep in mind that a
599 system might be used by more than one user, with different preferences.
601 There are people that prefer the built-in Emacs modes for editing
602 TeX files, in particular plain TeX users. There are various ways to
603 tell AUCTeX even after auto-activation that it should not get used, and
604 they are described in *note Introduction to AUCTeX: Introduction.
606 So if you have users that don't want to use the preinstalled AUCTeX,
607 they can easily get rid of it. Activating AUCTeX by default is
608 therefore a good choice.
610 If the installation procedure did not achieve this already by placing
611 `auctex.el' and `preview-latex.el' into a possibly existing
612 `site-start.d' directory, you can do this by placing
614 (load "auctex.el" nil t t)
615 (load "preview-latex.el" nil t t)
617 in the system-wide `site-start.el'.
619 If your package is intended as an XEmacs package or to accompany a
620 precompiled version of Emacs, you might not know which TeX system will
621 be available when preview-latex gets used. In this case you should
622 build using the `--without-texmf-dir' option described previously.
623 This can also be convenient for systems that are intended to support
624 more than a single TeX distribution. Since more often than not TeX
625 packages for operating system distributions are either much more
626 outdated or much less complete than separately provided systems like
627 TeX Live, this method may be generally preferable when providing
630 The following package structure would be adequate for a typical fully
631 supported Unix-like installation:
634 Style files and documentation for `preview.sty', placed into a TeX
635 tree where it is accessible from the teTeX executables usually
636 delivered with a system. If there are other commonly used TeX
637 system packages, it might be appropriate to provide separate
641 This package will require the installation of `preview-tetex' and
642 will record in `TeX-macro-global' where to find the TeX tree. It
643 is also a good idea to run
644 emacs -batch -f TeX-auto-generate-global
645 when either AUCTeX or teTeX get installed or upgraded. If your
646 users might want to work with a different TeX distribution
647 (nowadays pretty common), instead consider the following:
650 This package will be compiled with `--without-texmf-dir' and will
651 consequently contain the `preview' style files in its private
652 directory. It will probably not be possible to initialize
653 `TeX-macro-global' to a sensible value, so running
654 `TeX-auto-generate-global' does not appear useful. This package
655 would neither conflict with nor provide `preview-tetex'.
657 `auctex-xemacs-tetex'
659 Those are the obvious XEmacs equivalents. For XEmacs, there is the
660 additional problem that the XEmacs sumo package tree already
661 possibly provides its own version of AUCTeX, and the user might
662 even have used the XEmacs package manager to updating this
663 package, or even installing a private AUCTeX version. So you
664 should make sure that such a package will not conflict with
665 existing XEmacs packages and will be at an appropriate place in
666 the load order (after site-wide and user-specific locations, but
667 before a distribution-specific sumo package tree). Using the
668 `--without-packagedir' option might be one idea to avoid
669 conflicts. Another might be to refrain from providing an XEmacs
670 package and just rely on the user or system administrator to
671 instead use the XEmacs package system.
674 File: auctex.info, Node: Advice for non-privileged users, Next: Installation under MS Windows, Prev: Advice for package providers, Up: Installation
676 1.2.6 Installation for non-privileged users
677 -------------------------------------------
679 Often people without system administration privileges want to install
680 software for their private use. In that case you need to pass more
681 options to the `configure' script. For XEmacs users, this is fairly
682 easy, because the XEmacs package system has been designed to make this
683 sort of thing practical: but GNU Emacs users (and XEmacs users for whom
684 the package system is for some reason misbehaving) may need to do a
687 The main expedient is using the `--prefix' option to the `configure'
688 script, and let it point to the personal home directory. In that way,
689 resulting binaries will be installed under the `bin' subdirectory of
690 your home directory, manual pages under `man' and so on. It is
691 reasonably easy to maintain a bunch of personal software, since the
692 prefix argument is supported by most `configure' scripts.
694 You'll have to add something like
695 `/home/myself/share/emacs/site-lisp' to your `load-path' variable, if
696 it isn't there already.
698 XEmacs users can achieve the same end by pointing `configure' at an
699 appropriate package directory (normally
700 `--with-packagedir=~/.xemacs/xemacs-packages' will serve). The package
701 directory stands a good chance at being detected automatically as long
702 as it is in a subtree of the specified PREFIX.
704 Now here is another thing to ponder: perhaps you want to make it easy
705 for other users to share parts of your personal Emacs configuration. In
706 general, you can do this by writing `~myself/' anywhere where you
707 specify paths to something installed in your personal subdirectories,
708 not merely `~/', since the latter, when used by other users, will point
709 to non-existent files.
711 For yourself, it will do to manipulate environment variables in your
712 `.profile' resp. `.login' files. But if people will be copying just
713 Elisp files, their copies will not work. While it would in general be
714 preferable if the added components where available from a shell level,
715 too (like when you call the standalone info reader, or try using
716 `preview.sty' for functionality besides of Emacs previews), it will be
717 a big help already if things work from inside of Emacs.
719 Here is how to do the various parts:
721 Making the Elisp available
722 ..........................
724 In GNU Emacs, it should be sufficient if people just do
726 (load "~myself/share/emacs/site-lisp/auctex.el" nil t t)
727 (load "~myself/share/emacs/site-lisp/preview-latex.el" nil t t)
729 where the path points to your personal installation. The rest of the
730 package should be found relative from there without further ado.
732 In XEmacs, you should ask the other users to add symbolic links in
733 the subdirectories `lisp', `info' and `etc' of their
734 `~/.xemacs/xemacs-packages/' directory. (Alas, there is presently no
735 easy programmatic way to do this, except to have a script do the
736 symlinking for them.)
738 Making the Info files available
739 ...............................
741 For making the info files accessible from within Elisp, something like
742 the following might be convenient to add into your or other people's
745 (eval-after-load 'info
746 '(add-to-list 'Info-directory-list "~myself/info"))
748 In XEmacs, as long as XEmacs can see the package, there should be no
749 need to do anything at all; the info files should be immediately
750 visible. However, you might want to set `INFOPATH' anyway, for the
751 sake of standalone readers outside of XEmacs. (The info files in XEmacs
752 are normally in `~/.xemacs/xemacs-packages/info'.)
754 Making the LaTeX style available
755 ................................
757 If you want others to be able to share your installation, you should
758 configure it using `--without-texmf-dir', in which case things should
759 work as well for them as for you.
762 File: auctex.info, Node: Installation under MS Windows, Next: Customizing, Prev: Advice for non-privileged users, Up: Installation
764 1.2.7 Installation under MS Windows
765 -----------------------------------
770 The following are brief installation instructions for the impatient. In
771 case you don't understand some of this, run into trouble of some sort,
772 or need more elaborate information, refer to the detailed instructions
775 1. Install the prerequisites, i.e. Emacs or XEmacs, MSYS or Cygwin, a
776 TeX system, and Ghostscript.
778 2. Open the MSYS shell or a Cygwin shell and change to the directory
779 containing the unzipped file contents.
783 For Emacs: Many people like to install AUCTeX into the pseudo file
784 system hierarchy set up by the Emacs installation. Assuming Emacs
785 is installed in `C:/Program Files/Emacs' and the directory for
786 local additions of your TeX system, e.g. MiKTeX, is
787 `C:/localtexmf', you can do this by typing the following statement
790 ./configure --prefix='C:/Program Files/Emacs' \
791 --infodir='C:/Program Files/Emacs/info' \
792 --with-texmf-dir='C:/localtexmf'
794 For XEmacs: You can install AUCTeX as an XEmacs package. Assuming
795 XEmacs is installed in `C:/Program Files/XEmacs' and the directory
796 for local additions of your TeX system, e.g. MiKTeX, is
797 `C:/localtexmf', you can do this by typing the following command at
800 ./configure --with-xemacs='C:/Program Files/XEmacs/bin/xemacs' \
801 --with-texmf-dir='C:/localtexmf'
803 The commands above are examples for common usage. More on
804 configuration options can be found in the detailed installation
807 If the configuration script failed to find all required programs,
808 make sure that these programs are in your system path and add
809 directories containing the programs to the `PATH' environment
810 variable if necessary. Here is how to do that in W2000/XP:
812 1. On the desktop, right click "My Computer" and select
815 2. Click on "Advanced" in the "System Properties" window.
817 3. Select "Environment Variables".
819 4. Select "path" in "System Variables" and click "edit". Move
820 to the front in the line (this might require scrolling) and
821 add the missing path including drive letter, ended with a
824 4. If there were no further error messages, type
828 In case there were, please refer to the detailed description below.
830 5. Finish the installation by typing
834 Detailed Installation Instructions
835 ..................................
837 Installation of AUCTeX under Windows is in itself not more complicated
838 than on other platforms. However, meeting the prerequisites might
839 require more work than on some other platforms, and feel less natural.
841 If you are experiencing any problems, even if you think they are of
842 your own making, be sure to report them to <auctex-devel@gnu.org> so
843 that we can explain things better in future.
845 Windows is a problematic platform for installation scripts. The main
846 problem is that the installation procedure requires consistent file
847 names in order to find its way in the directory hierarchy, and Windows
848 path names are a mess.
850 The installation procedure tries finding stuff in system search paths
851 and in Emacs paths. For that to succeed, you have to use the same
852 syntax and spelling and case of paths everywhere: in your system search
853 paths, in Emacs' `load-path' variable, as argument to the scripts. If
854 your path names contain spaces or other `shell-unfriendly' characters,
855 most notably backslashes for directory separators, place the whole path
856 in `"double quote marks"' whenever you specify it on a command line.
858 Avoid `helpful' magic file names like `/cygdrive/c' and
859 `C:\PROGRA~1\' like the plague. It is quite unlikely that the scripts
860 will be able to identify the actual file names involved. Use the full
861 paths, making use of normal Windows drive letters like ` 'C:/Program
862 Files/Emacs' ' where required, and using the same combination of upper-
863 and lowercase letters as in the actual files. File names containing
864 shell-special characters like spaces or backslashes (if you prefer that
865 syntax) need to get properly quoted to the shell: the above example
866 used single quotes for that.
868 Ok, now here are the steps to perform:
870 1. You need to unpack the AUCTeX distribution (which you seemingly
871 have done since you are reading this). It must be unpacked in a
872 separate installation directory outside of your Emacs file
873 hierarchy: the installation will later copy all necessary files to
874 their final destination, and you can ultimately remove the
875 directory where you unpacked the files.
877 Line endings are a problem under Windows. The distribution
878 contains only text files, and theoretically most of the involved
879 tools should get along with that. However, the files are
880 processed by various utilities, and it is conceivable that not all
881 of them will use the same line ending conventions. If you
882 encounter problems, it might help if you try unpacking (or
883 checking out) the files in binary mode, if your tools allow that.
885 If you don't have a suitable unpacking tool, skip to the next
886 step: this should provide you with a working `unzip' command.
888 2. The installation of AUCTeX will require the MSYS tool set from
889 `http://www.mingw.org/' or the Cygwin tool set from
890 `http://cygwin.com/'. The latter is slower and larger (the
891 download size of the base system is about 15 MB) but comes with a
892 package manager that allows for updating the tool set and
893 installing additional packages like, for example, the spell
896 If Cygwin specific paths like `/cygdrive/c' crop up in the course
897 of the installation, using a non-Cygwin Emacs could conceivably
898 cause trouble. Using Cygwin either for everything or nothing
899 might save headaches, _if_ things don't work out.
901 3. Install a current version of XEmacs from `http://www.xemacs.org/'
902 or Emacs from `ftp://ftp.gnu.org/gnu/emacs/windows/'. Emacs is
903 the recommended choice because it is currently the primary
904 platform for AUCTeX development.
906 4. You need a working TeX installation. One popular installation
907 under Windows is MiKTeX (http://www.miktex.org). Another much more
908 extensive system is TeX Live (http://www.tug.org/texlive) which is
909 rather close to its Unix cousins.
911 5. A working copy of Ghostscript (http://www.cs.wisc.edu/~ghost/) is
912 required for preview-latex operation. Examining the output from
914 on a Windows command line should tell you whether your Ghostscript
915 supports the `png16m' device needed for PNG support. MiKTeX
916 apparently comes with its own Ghostscript called `mgs.exe'.
918 6. Perl (http://www.perl.org) is needed for rebuilding the
919 documentation if you are working with a copy from CVS or have
920 touched documentation source files in the preview-latex part. If
921 the line endings of the file `preview/latex/preview.dtx' don't
922 correspond with what Perl calls `\n' when reading text files,
923 you'll run into trouble.
925 7. Now the fun stuff starts. If you have not yet done so, unpack the
926 AUCTeX distribution into a separate directory after rereading the
927 instructions for unpacking above.
929 8. Ready for takeoff. Start some shell (typically `bash') capable of
930 running `configure', change into the installation directory and
931 call `./configure' with appropriate options.
933 Typical options you'll want to specify will be
934 `--prefix=DRIVE:/PATH/TO/EMACS-HIERARCHY'
935 which tells `configure' where to perform the installation. It
936 may also make `configure' find Emacs or XEmacs automatically;
937 if this doesn't happen, try one of `--with-emacs' or
938 `--with-xemacs' as described below. All automatic detection
939 of files and directories restricts itself to directories
940 below the PREFIX or in the same hierarchy as the program
941 accessing the files. Usually, directories like `man',
942 `share' and `bin' will be situated right under PREFIX.
944 This option also affects the defaults for placing the Texinfo
945 documentation files (see also `--infodir' below) and
946 automatically generated style hooks.
948 If you have a central directory hierarchy (not untypical with
949 Cygwin) for such stuff, you might want to specify its root
950 here. You stand a good chance that this will be the only
951 option you need to supply, as long as your TeX-related
952 executables are in your system path, which they better be for
953 AUCTeX's operation, anyway.
956 if you are installing for a version of Emacs. You can use
957 `--with-emacs=DRIVE:/PATH/TO/EMACS' to specify the name of the
958 installed Emacs executable, complete with its path if
959 necessary (if Emacs is not within a directory specified in
960 your `PATH' environment setting).
963 if you are installing for a version of XEmacs. Again, you
964 can use `--with-xemacs=DRIVE:/PATH/TO/XEMACS' to specify the
965 name of the installed XEmacs executable complete with its
966 path if necessary. It may also be necessary to specify this
967 option if a copy of Emacs is found in your `PATH' environment
968 setting, but you still would like to install a copy of AUCTeX
971 `--with-packagedir=DRIVE:/DIR'
972 is an XEmacs-only option giving the location of the package
973 directory. This will install and activate the package.
974 Emacs uses a different installation scheme:
976 `--with-lispdir=DRIVE:/PATH/TO/SITE-LISP'
977 This Emacs-only option tells a place in `load-path' below
978 which the files are situated. The startup files `auctex.el'
979 and `preview-latex.el' will get installed here unless a
980 subdirectory `site-start.d' exists which will then be used
981 instead. The other files from AUCTeX will be installed in a
982 subdirectory called `auctex'.
984 If you think that you need a different setup, please refer to
985 the full installation instructions in *note Configure::.
987 `--infodir=DRIVE:/PATH/TO/INFO/DIRECTORY'
988 If you are installing into an Emacs directory, info files
989 have to be put into the `info' folder below that directory.
990 The configuration script will usually try to install into the
991 folder `share/info', so you have to override this by
992 specifying something like `--infodir='C:/Program Files/info''
993 for the configure call.
995 `--with-auto-dir=DRIVE:/DIR'
996 Directory containing automatically generated information.
997 You should not normally need to set this, as `--prefix'
998 should take care of this.
1001 Use this option if your Emacs version is unable to support
1002 image display. This will be the case if you are using a
1003 native variant of Emacs 21.
1005 `--with-texmf-dir=DRIVE:/DIR'
1006 This will specify the directory where your TeX installation
1007 sits. If your TeX installation does not conform to the TDS
1008 (TeX directory standard), you may need to specify more
1009 options to get everything in place.
1011 For more information about any of the above and additional
1012 options, see *note Configure::.
1014 Calling `./configure --help=recursive' will tell about other
1015 options, but those are almost never required.
1017 Some executables might not be found in your path. That is not a
1018 good idea, but you can get around by specifying environment
1019 variables to `configure':
1020 GS="DRIVE:/PATH/TO/GSWIN32C.EXE" ./configure ...
1021 should work for this purpose. `gswin32c.exe' is the usual name for
1022 the required _command line_ executable under Windows; in contrast,
1023 `gswin32.exe' is likely to fail.
1025 As an alternative to specifying variables for the `configure' call
1026 you can add directories containing the required executables to the
1027 `PATH' variable of your Windows system. This is especially a good
1028 idea if Emacs has trouble finding the respective programs later
1029 during normal operation.
1031 9. Run `make' in the installation directory.
1033 10. Run `make install' in the installation directory.
1035 11. With XEmacs, AUCTeX and preview-latex should now be active by
1036 default. With Emacs, activation depends on a working
1037 `site-start.d' directory or similar setup, since then the startup
1038 files `auctex.el' and `preview-latex.el' will have been placed
1039 there. If this has not been done, you should be able to load the
1040 startup files manually with
1041 (load "auctex.el" nil t t)
1042 (load "preview-latex.el" nil t t)
1043 in either a site-wide `site-start.el' or your personal startup file
1044 (usually accessible as `~/.emacs' from within Emacs and
1045 `~/.xemacs/init.el' from within XEmacs).
1047 The default configuration of AUCTeX is probably not the best fit
1048 for Windows systems. You might want to add
1051 (require 'tex-fptex)
1052 in order to get more appropriate values for MiKTeX and fpTeX,
1053 respectively after loading `auctex.el' and `preview-latex.el'.
1057 M-x customize-group RET AUCTeX RET
1059 in order to customize more stuff, or use the `Customize' menu.
1061 12. Load `preview/circ.tex' into Emacs or XEmacs and see if you get the
1062 `Command' menu. Try using it to LaTeX the file.
1064 13. Check whether the `Preview' menu is available in this file. Use it
1065 to generate previews for the document.
1067 If this barfs and tells you that image type `png' is not supported,
1068 you can either add PNG support to your Emacs installation or
1069 choose another image format to be used by preview-latex.
1071 Adding support for an image format usually involves the
1072 installation of a library, e.g. from `http://gnuwin32.sf.net/'.
1073 If you got your Emacs from `gnu.org' you might want to check its
1074 README file (ftp://ftp.gnu.org/gnu/emacs/windows/README) for
1077 A different image format can be chosen by setting the variable
1078 `preview-image-type'. While it is recommended to keep the
1079 `dvipng' or `png' setting, you can temporarily select a different
1080 format like `pnm' to check if the lack of PNG support is the only
1081 problem with your Emacs installation.
1085 (setq preview-image-type 'pnm)
1087 to your init file for a quick test. You should remove the line
1088 after the test again, because PNM files take away *vast* amounts
1089 of disk space, and thus also of load/save time.
1091 Well, that about is all. Have fun!
1094 File: auctex.info, Node: Customizing, Prev: Installation under MS Windows, Up: Installation
1099 Most of the site-specific customization should already have happened
1100 during configuration of AUCTeX. Any further customization can be done
1101 with customization buffers directly in Emacs. Just type `M-x
1102 customize-group RET AUCTeX RET' to open the customization group for
1103 AUCTeX or use the menu entries provided in the mode menus. Editing the
1104 file `tex-site.el' as suggested in former versions of AUCTeX should not
1105 be done anymore because the installation routine will overwrite those
1108 You might check some variables with a special significance. They are
1109 accessible directly by typing `M-x customize-variable RET <variable>
1112 -- User Option: TeX-macro-global
1113 Directories containing the site's TeX style files.
1115 Normally, AUCTeX will only allow you to complete macros and
1116 environments which are built-in, specified in AUCTeX style files or
1117 defined by yourself. If you issue the `M-x TeX-auto-generate-global'
1118 command after loading AUCTeX, you will be able to complete on all
1119 macros available in the standard style files used by your document. To
1120 do this, you must set this variable to a list of directories where the
1121 standard style files are located. The directories will be searched
1122 recursively, so there is no reason to list subdirectories explicitly.
1123 Automatic configuration will already have set the variable for you if
1124 it could use the program `kpsewhich'. In this case you normally don't
1125 have to alter anything.
1128 File: auctex.info, Node: Quick Start, Prev: Installation, Up: Introduction
1133 AUCTeX is a powerful program offering many features and configuration
1134 options. If you are new to AUCTeX this might be deterrent.
1135 Fortunately you do not have to learn everything at once. This Quick
1136 Start Guide will give you the knowledge of the most important commands
1137 and enable you to prepare your first LaTeX document with AUCTeX after
1138 only a few minutes of reading.
1140 In this introduction, we assume that AUCTeX is already installed on
1141 your system. If this is not the case, you should read the file
1142 `INSTALL' in the base directory of the unpacked distribution tarball.
1143 These installation instructions are available in this manual as well,
1144 *note Installation::. We also assume that you are familiar with the
1145 way keystrokes are written in Emacs manuals. If not, have a look at
1146 the Emacs Tutorial in the Help menu.
1148 If AUCTeX is installed, you might still need to activate it, by
1151 (load "auctex.el" nil t t)
1153 in your user init file.(1) In order to get support for many of the
1154 LaTeX packages you will use in your documents, you should enable
1155 document parsing as well, which can be achieved by putting
1157 (setq TeX-auto-save t)
1158 (setq TeX-parse-self t)
1160 into your init file. Finally, if you often use `\include' or
1161 `\input', you should make AUCTeX aware of the multi-file document
1162 structure. You can do this by inserting
1164 (setq-default TeX-master nil)
1166 into your init file. Each time you open a new file, AUCTeX will then
1167 ask you for a master file.
1171 * Editing Facilities:: Functions for editing TeX files
1172 * Processing Facilities:: Creating and viewing output, debugging
1174 ---------- Footnotes ----------
1176 (1) This usually is a file in your home directory called `.emacs' if
1177 you are utilizing GNU Emacs or `.xemacs/init.el' if you are using
1181 File: auctex.info, Node: Editing Facilities, Next: Processing Facilities, Up: Quick Start
1183 1.3.1 Functions for editing TeX files
1184 -------------------------------------
1186 1.3.1.1 Making your TeX code more readable
1187 ..........................................
1189 AUCTeX can do syntax highlighting of your source code, that means
1190 commands will get special colors or fonts. You can enable it locally by
1191 typing `M-x font-lock-mode RET'. If you want to have font locking
1192 activated generally, enable `global-font-lock-mode', e.g. with `M-x
1193 customize-variable RET global-font-lock-mode RET'.
1195 AUCTeX will indent new lines to indicate their syntactical
1196 relationship to the surrounding text. For example, the text of a
1197 `\footnote' or text inside of an environment will be indented relative
1198 to the text around it. If the indenting has gotten wrong after adding
1199 or deleting some characters, use <TAB> to reindent the line, `M-q' for
1200 the whole paragraph, or `M-x LaTeX-fill-buffer RET' for the whole
1203 1.3.1.2 Entering sectioning commands
1204 ....................................
1206 Insertion of sectioning macros, that is `\chapter', `\section',
1207 `\subsection', etc. and accompanying `\label' commands may be eased by
1208 using `C-c C-s'. You will be asked for the section level. As nearly
1209 everywhere in AUCTeX, you can use the <TAB> or <SPC> key to get a list
1210 of available level names, and to auto-complete what you started typing.
1211 Next, you will be asked for the printed title of the section, and last
1212 you will be asked for a label to be associated with the section.
1214 1.3.1.3 Inserting environments
1215 ..............................
1217 Similarly, you can insert environments, that is `\begin{}'-`\end{}'
1218 pairs: Type `C-c C-e', and select an environment type. Again, you can
1219 use <TAB> or <SPC> to get a list, and to complete what you type.
1220 Actually, the list will not only provide standard LaTeX environments,
1221 but also take your `\documentclass' and `\usepackage' commands into
1222 account if you have parsing enabled by setting `TeX-parse-self' to `t'.
1223 If you use a couple of environments frequently, you can use the up and
1224 down arrow keys (or `M-p' and `M-n') in the minibuffer to get back to
1225 the previously inserted commands.
1227 Some environments need additional arguments. Often, AUCTeX knows
1228 about this and asks you to enter a value.
1230 1.3.1.4 Inserting macros
1231 ........................
1233 `C-c C-m', or simply `C-c RET' will give you a prompt that asks you for
1234 a LaTeX macro. You can use <TAB> for completion, or the up/down arrow
1235 keys (or `M-p' and `M-n') to browse the command history. In many
1236 cases, AUCTeX knows which arguments a macro needs and will ask you for
1237 that. It even can differentiate between mandatory and optional
1238 arguments--for details, see *note Completion::.
1240 An additional help for inserting macros is provided by the
1241 possibility to complete macros right in the buffer. With point at the
1242 end of a partially written macro, you can complete it by typing `M-TAB'.
1244 1.3.1.5 Changing the font
1245 .........................
1247 AUCTeX provides convenient keyboard shortcuts for inserting macros
1248 which specify the font to be used for typesetting certain parts of the
1249 text. They start with `C-c C-f', and the last `C-' combination tells
1250 AUCTeX which font you want:
1253 Insert bold face `\textbf{-!-}' text.
1256 Insert italics `\textit{-!-}' text.
1259 Insert emphasized `\emph{-!-}' text.
1262 Insert slanted `\textsl{-!-}' text.
1265 Insert roman \textrm{-!-} text.
1268 Insert sans serif `\textsf{-!-}' text.
1271 Insert typewriter `\texttt{-!-}' text.
1274 Insert SMALL CAPS `\textsc{-!-}' text.
1277 Delete the innermost font specification containing point.
1280 If you want to change font attributes of existing text, mark it as a
1281 region, and then invoke the commands. If no region is selected, the
1282 command will be inserted with empty braces, and you can start typing the
1285 Most of those commands will also work in math mode, but then macros
1286 like `\mathbf' will be inserted.
1288 1.3.1.6 Other useful features
1289 .............................
1291 AUCTeX also tries to help you when inserting the right "quote" signs
1292 for your language, dollar signs to typeset math, or pairs of braces.
1293 It offers shortcuts for commenting out text (`C-c ;' for the current
1294 region or `C-c %' for the paragraph you are in). The same keystrokes
1295 will remove the % signs, if the region or paragraph is commented out
1296 yet. With `TeX-fold-mode', you can hide certain parts (like footnotes,
1297 references etc.) that you do not edit currently. Support for Emacs'
1298 outline mode is provided as well. And there's more, but this is beyond
1299 the scope of this Quick Start Guide.
1302 File: auctex.info, Node: Processing Facilities, Prev: Editing Facilities, Up: Quick Start
1304 1.3.2 Creating and viewing output, debugging
1305 --------------------------------------------
1307 1.3.2.1 One Command for LaTeX, helpers, viewers, and printing
1308 .............................................................
1310 If you have typed some text and want to run LaTeX (or TeX, or other
1311 programs--see below) on it, type `C-c C-c'. If applicable, you will be
1312 asked whether you want to save changes, and which program you want to
1313 invoke. In many cases, the choice that AUCTeX suggests will be just
1314 what you want: first `latex', then a viewer. If a `latex' run produces
1315 or changes input files for `makeindex', the next suggestion will be to
1316 run that program, and AUCTeX knows that you need to run `latex' again
1317 afterwards--the same holds for BibTeX.
1319 When no processor invocation is necessary anymore, AUCTeX will
1320 suggest to run a viewer, or you can chose to create a PostScript file
1321 using `dvips', or to directly print it.
1323 At this place, a warning needs to be given: First, although AUCTeX is
1324 really good in detecting the standard situations when an additional
1325 `latex' run is necessary, it cannot detect it always. Second, the
1326 creation of PostScript files or direct printing currently only works
1327 when your output file is a DVI file, not a PDF file.
1329 Ah, you didn't know you can do both? That brings us to the next
1332 1.3.2.2 Choosing an output format
1333 .................................
1335 From a LaTeX file, you can produce DVI output, or a PDF file directly
1336 via `pdflatex'. You can switch on source specials for easier
1337 navigation in the output file, or tell `latex' to stop after an error
1338 (usually `\noninteractive' is used, to allow you to detect all errors
1341 These options are controlled by toggles, the keystrokes should be
1345 This command toggles between DVI and PDF output
1348 toggles interactive mode
1351 toggles source specials support
1354 toggles usage of Omega/lambda.
1357 1.3.2.3 Debugging LaTeX
1358 .......................
1360 When AUCTeX runs a program, it creates an output buffer in which it
1361 displays the output of the command. If there is a syntactical error in
1362 your file, `latex' will not complete successfully. AUCTeX will tell you
1363 that, and you can get to the place where the first error occured by
1364 pressing `C-c `' (the last character is a backtick). The view will be
1365 split in two windows, the output will be displayed in the lower buffer,
1366 and both buffers will be centered around the place where the error
1367 ocurred. You can then try to fix it in the document buffer, and use
1368 the same keystrokes to get to the next error. This procedure may be
1369 repeated until all errors have been dealt with. By pressing `C-c C-w'
1370 (`TeX-toggle-debug-boxes') you can toggle whether AUCTeX should notify
1371 you of overfull and underfull boxes in addition to regular errors.
1373 If a command got stuck in a seemingly infinite loop, or you want to
1374 stop execution for other reasons, you can use `C-c C-k' (for "kill").
1375 Similar to `C-l', which centers the buffer you are in around your
1376 current position, `C-c C-l' centers the output buffer so that the last
1377 lines added at the bottom become visible.
1379 1.3.2.4 Running LaTeX on parts of your document
1380 ...............................................
1382 If you want to check how some part of your text looks like, and do not
1383 want to wait until the whole document has been typeset, then mark it as
1384 a region and use `C-c C-r'. It behaves just like `C-c C-c', but it
1385 only uses the document preamble and the region you marked.
1387 If you are using `\include' or `\input' to structure your document,
1388 try `C-c C-b' while you are editing one of the included files. It will
1389 run `latex' only on the current buffer, using the preamble from the
1393 File: auctex.info, Node: Editing, Next: Display, Prev: Introduction, Up: Top
1395 2 Editing the Document Source
1396 *****************************
1398 The most commonly used commands/macros of AUCTeX are those which simply
1399 insert templates for often used TeX, LaTeX, or ConTeXt constructs, like
1400 font changes, handling of environments, etc. These features are very
1401 simple, and easy to learn, and help you avoid mistakes like mismatched
1402 braces, or `\begin{}'-`\end{}' pairs.
1404 Apart from that this chapter contains a description of some features
1405 for entering more specialized sorts of text, for formatting the source
1406 by indenting and filling and for navigating through the document.
1410 * Quotes:: Inserting double quotes
1411 * Font Specifiers:: Inserting Font Specifiers
1412 * Sectioning:: Inserting chapters, sections, etc.
1413 * Environments:: Inserting Environment Templates
1414 * Mathematics:: Entering Mathematics
1415 * Completion:: Completion of macros
1416 * Commenting:: Commenting text
1417 * Indenting:: Reflecting syntactic constructs with whitespace
1418 * Filling:: Automatic and manual line breaking
1421 File: auctex.info, Node: Quotes, Next: Font Specifiers, Up: Editing
1423 2.1 Insertion of Quotes, Dollars, and Braces
1424 ============================================
1429 In TeX, literal double quotes `"like this"' are seldom used, instead
1430 two single quotes are used ```like this'''. To help you insert these
1431 efficiently, AUCTeX allows you to continue to press `"' to insert two
1432 single quotes. To get a literal double quote, press `"' twice.
1434 -- Command: TeX-insert-quote COUNT
1435 (`"') Insert the appropriate quote marks for TeX.
1437 Inserts the value of `TeX-open-quote' (normally ```') or
1438 `TeX-close-quote' (normally `''') depending on the context. With
1439 prefix argument, always inserts `"' characters.
1441 -- User Option: TeX-open-quote
1442 String inserted by typing `"' to open a quotation. (*Note
1443 European::, for language-specific quotation mark insertion.)
1445 -- User Option: TeX-close-quote
1446 String inserted by typing `"' to close a quotation. (*Note
1447 European::, for language-specific quotation mark insertion.)
1449 -- User Option: TeX-quote-after-quote
1450 Determines the behavior of `"'. If it is non-nil, typing `"' will
1451 insert a literal double quote. The respective values of
1452 `TeX-open-quote' and `TeX-close-quote' will be inserted after
1453 typing `"' once again.
1455 The `babel' package provides special support for the requirements of
1456 typesetting quotation marks in many different languages. If you use
1457 this package, either directly or by loading a language-specific style
1458 file, you should also use the special commands for quote insertion
1459 instead of the standard quotes shown above. AUCTeX is able to
1460 recognize several of these languages and will change quote insertion
1461 accordingly. *Note European::, for details about this feature and how
1464 In case you are using the `csquotes' package, you should customize
1465 `LaTeX-csquotes-open-quote', `LaTeX-csquotes-close-quote' and
1466 `LaTeX-csquotes-quote-after-quote'. The quotation characters will only
1467 be used if both variables--`LaTeX-csquotes-open-quote' and
1468 `LaTeX-csquotes-close-quote'--are non-empty strings. But then the
1469 `csquotes'-related values will take precedence over the
1470 language-specific ones.
1475 In AUCTeX, dollar signs should match like they do in TeX. This has
1476 been partially implemented, we assume dollar signs always match within
1477 a paragraph. The first `$' you insert in a paragraph will do nothing
1478 special. The second `$' will match the first. This will be indicated
1479 by moving the cursor temporarily over the first dollar sign.
1481 -- Command: TeX-insert-dollar ARG
1482 (`$') Insert dollar sign.
1484 Show matching dollar sign if this dollar sign end the TeX math
1485 mode. Ensure double dollar signs match up correctly by inserting
1486 extra dollar signs when needed if `TeX-math-close-double-dollar'
1489 With optional ARG, insert that many dollar signs.
1491 -- User Option: TeX-math-close-double-dollar
1492 Control the insertion of double dollar signs for delimiting display
1493 math. (Note that you should not use double dollar signs in LaTeX
1494 because this practice can lead to wrong spacing in typeset
1495 documents.) If the variable is non-nil and you enter a dollar
1496 sign that matches a double dollar sign `$$' AUCTeX will
1497 automatically insert two dollar signs.
1502 To avoid unbalanced braces, it is useful to insert them pairwise. You
1503 can do this by typing `C-c {'.
1505 -- Command: TeX-insert-braces
1506 (`C-c {') Make a pair of braces and position the cursor to type
1507 inside of them. If there is an active region, put braces around
1508 it and leave point after the closing brace.
1511 File: auctex.info, Node: Font Specifiers, Next: Sectioning, Prev: Quotes, Up: Editing
1513 2.2 Inserting Font Specifiers
1514 =============================
1516 Perhaps the most used keyboard commands of AUCTeX are the short-cuts
1517 available for easy insertion of font changing macros.
1519 If you give an argument (that is, type `C-u') to the font command,
1520 the innermost font will be replaced, i.e. the font in the TeX group
1521 around point will be changed. The following table shows the available
1522 commands, with `-!-' indicating the position where the text will be
1526 Insert bold face `\textbf{-!-}' text.
1529 Insert italics `\textit{-!-}' text.
1532 Insert emphasized `\emph{-!-}' text.
1535 Insert slanted `\textsl{-!-}' text.
1538 Insert roman \textrm{-!-} text.
1541 Insert sans serif `\textsf{-!-}' text.
1544 Insert typewriter `\texttt{-!-}' text.
1547 Insert SMALL CAPS `\textsc{-!-}' text.
1550 Delete the innermost font specification containing point.
1553 -- Command: TeX-font replace what
1554 (`C-c C-f') Insert template for font change command.
1556 If REPLACE is not nil, replace current font. WHAT determines the
1557 font to use, as specified by `TeX-font-list'.
1559 -- User Option: TeX-font-list
1560 List of fonts used by `TeX-font'.
1562 Each entry is a list with three elements. The first element is the
1563 key to activate the font. The second element is the string to
1564 insert before point, and the third element is the string to insert
1565 after point. An optional fourth element means always replace if
1568 -- User Option: LaTeX-font-list
1569 List of fonts used by `TeX-font' in LaTeX mode. It has the same
1570 structure as `TeX-font-list'.
1573 File: auctex.info, Node: Sectioning, Next: Environments, Prev: Font Specifiers, Up: Editing
1575 2.3 Inserting chapters, sections, etc.
1576 ======================================
1578 Insertion of sectioning macros, that is `\chapter', `\section',
1579 `\subsection', etc. and accompanying `\label''s may be eased by using
1580 `C-c C-s'. This command is highly customizable, the following
1581 describes the default behavior.
1583 When invoking you will be asked for a section macro to insert. An
1584 appropriate default is automatically selected by AUCTeX, that is
1585 either: at the top of the document; the top level sectioning for that
1586 document style, and any other place: The same as the last occurring
1589 Next, you will be asked for the actual name of that section, and
1590 last you will be asked for a label to be associated with that section.
1591 The label will be prefixed by the value specified in
1592 `LaTeX-section-hook'.
1594 -- Command: LaTeX-section ARG
1595 (`C-c C-s') Insert a sectioning command.
1597 Determine the type of section to be inserted, by the argument ARG.
1599 * If ARG is nil or missing, use the current level.
1601 * If ARG is a list (selected by C-u), go downward one level.
1603 * If ARG is negative, go up that many levels.
1605 * If ARG is positive or zero, use absolute level:
1620 The following variables can be set to customize the function.
1622 `LaTeX-section-hook'
1623 Hooks to be run when inserting a section.
1625 `LaTeX-section-label'
1626 Prefix to all section references.
1629 The precise behavior of `LaTeX-section' is defined by the contents
1630 of `LaTeX-section-hook'.
1632 -- User Option: LaTeX-section-hook
1633 List of hooks to run when a new section is inserted.
1635 The following variables are set before the hooks are run
1638 Numeric section level, default set by prefix arg to
1642 Name of the sectioning command, derived from LEVEL.
1645 The title of the section, default to an empty string.
1648 Entry for the table of contents list, default nil.
1651 Position of point afterwards, default nil meaning after the
1654 A number of hooks are already defined. Most likely, you will be
1655 able to get the desired functionality by choosing from these hooks.
1657 `LaTeX-section-heading'
1658 Query the user about the name of the sectioning command.
1659 Modifies LEVEL and NAME.
1661 `LaTeX-section-title'
1662 Query the user about the title of the section. Modifies TITLE.
1665 Query the user for the toc entry. Modifies TOC.
1667 `LaTeX-section-section'
1668 Insert LaTeX section command according to NAME, TITLE, and
1669 TOC. If TOC is nil, no toc entry is inserted. If TOC or
1670 TITLE are empty strings, DONE-MARK will be placed at the
1671 point they should be inserted.
1673 `LaTeX-section-label'
1674 Insert a label after the section command. Controlled by the
1675 variable `LaTeX-section-label'.
1677 To get a full featured `LaTeX-section' command, insert
1679 (setq LaTeX-section-hook
1680 '(LaTeX-section-heading
1683 LaTeX-section-section
1684 LaTeX-section-label))
1686 in your `.emacs' file.
1688 The behavior of `LaTeX-section-label' is determined by the variable
1689 `LaTeX-section-label'.
1691 -- User Option: LaTeX-section-label
1692 Default prefix when asking for a label.
1694 If it is a string, it is used unchanged for all kinds of sections.
1695 If it is nil, no label is inserted. If it is a list, the list is
1696 searched for a member whose car is equal to the name of the
1697 sectioning command being inserted. The cdr is then used as the
1698 prefix. If the name is not found, or if the cdr is nil, no label
1701 By default, chapters have a prefix of `cha:' while sections and
1702 subsections have a prefix of `sec:'. Labels are not automatically
1703 inserted for other types of sections.
1706 File: auctex.info, Node: Environments, Next: Mathematics, Prev: Sectioning, Up: Editing
1708 2.4 Inserting Environment Templates
1709 ===================================
1711 A large apparatus is available that supports insertions of environments,
1712 that is `\begin{}' -- `\end{}' pairs.
1714 AUCTeX is aware of most of the actual environments available in a
1715 specific document. This is achieved by examining your `\documentclass'
1716 command, and consulting a precompiled list of environments available in
1717 a large number of styles.
1719 You insert an environment with `C-c C-e', and select an environment
1720 type. Depending on the environment, AUCTeX may ask more questions
1721 about the optional parts of the selected environment type. With `C-u
1722 C-c C-e' you will change the current environment.
1724 -- Command: LaTeX-environment ARG
1725 (`C-c C-e') AUCTeX will prompt you for an environment to insert.
1726 At this prompt, you may press <TAB> or <SPC> to complete a
1727 partially written name, and/or to get a list of available
1728 environments. After selection of a specific environment AUCTeX may
1729 prompt you for further specifications.
1731 If the optional argument ARG is not-nil (i.e. you have given a
1732 prefix argument), the current environment is modified and no new
1733 environment is inserted.
1735 As a default selection, AUCTeX will suggest the environment last
1736 inserted or, as the first choice the value of the variable
1737 `LaTeX-default-environment'.
1739 -- User Option: LaTeX-default-environment
1740 Default environment to insert when invoking `LaTeX-environment'
1743 If the document is empty, or the cursor is placed at the top of the
1744 document, AUCTeX will default to insert a `document' environment.
1746 Most of these are described further in the following sections, and
1747 you may easily specify more. *Note Customizing Environments::.
1751 * Equations:: Equations
1753 * Itemize-like:: Itemize-like Environments
1754 * Tabular-like:: Tabular-like Environments
1755 * Customizing Environments:: Customizing Environments
1757 You can close the current environment with `C-c ]', but we suggest
1758 that you use `C-c C-e' to insert complete environments instead.
1760 -- Command: LaTeX-close-environment
1761 (`C-c ]') Insert an `\end' that matches the current environment.
1764 File: auctex.info, Node: Equations, Next: Floats, Up: Environments
1769 When inserting equation-like environments, the `\label' will have a
1770 default prefix, which is controlled by the following variables:
1772 -- User Option: LaTeX-equation-label
1773 Prefix to use for `equation' labels.
1775 -- User Option: LaTeX-eqnarray-label
1776 Prefix to use for `eqnarray' labels.
1778 -- User Option: LaTeX-amsmath-label
1779 Prefix to use for amsmath equation labels. Amsmath equations
1780 include `align', `alignat', `xalignat', `aligned', `flalign' and
1784 File: auctex.info, Node: Floats, Next: Itemize-like, Prev: Equations, Up: Environments
1789 Figures and tables (i.e., floats) may also be inserted using AUCTeX.
1790 After choosing either `figure' or `table' in the environment list
1791 described above, you will be prompted for a number of additional things.
1794 This is the optional argument of float environments that controls
1795 how they are placed in the final document. In LaTeX this is a
1796 sequence of the letters `htbp' as described in the LaTeX manual.
1797 The value will default to the value of `LaTeX-float'.
1800 This is the caption of the float. The default is to insert the
1801 caption at the bottom of the float. You can specify floats where
1802 the caption should be placed at the top with
1803 `LaTeX-top-caption-list'.
1806 The label of this float. The label will have a default prefix,
1807 which is controlled by the variables `LaTeX-figure-label' and
1808 `LaTeX-table-label'.
1810 Moreover, you will be asked if you want the contents of the float
1811 environment to be horizontally centered. Upon a positive answer a
1812 `\centering' macro will be inserted at the beginning of the float
1815 -- User Option: LaTeX-float
1816 Default placement for floats.
1818 -- User Option: LaTeX-figure-label
1819 Prefix to use for figure labels.
1821 -- User Option: LaTeX-table-label
1822 Prefix to use for table labels.
1824 -- User Option: LaTeX-top-caption-list
1825 List of float environments with top caption.
1828 File: auctex.info, Node: Itemize-like, Next: Tabular-like, Prev: Floats, Up: Environments
1830 2.4.3 Itemize-like Environments
1831 -------------------------------
1833 In an itemize-like environment, nodes (i.e., `\item's) may be inserted
1836 -- Command: LaTeX-insert-item
1837 (`C-c <LFD>') Close the current item, move to the next line and
1838 insert an appropriate `\item' for the current environment. That is,
1839 `itemize' and `enumerate' will have `\item ' inserted, while
1840 `description' will have `\item[]' inserted.
1843 File: auctex.info, Node: Tabular-like, Next: Customizing Environments, Prev: Itemize-like, Up: Environments
1845 2.4.4 Tabular-like Environments
1846 -------------------------------
1848 When inserting Tabular-like environments, that is, `tabular' `array'
1849 etc., you will be prompted for a template for that environment.
1852 -- User Option: LaTeX-default-format
1853 Default format string for array and tabular environments.
1855 -- User Option: LaTeX-default-position
1856 Default position string for array and tabular environments. If
1857 nil, act like the empty string is given, but don't prompt for a
1861 File: auctex.info, Node: Customizing Environments, Prev: Tabular-like, Up: Environments
1863 2.4.5 Customizing Environments
1864 ------------------------------
1866 *Note Adding Environments::, for how to customize the list of known
1870 File: auctex.info, Node: Mathematics, Next: Completion, Prev: Environments, Up: Editing
1872 2.5 Entering Mathematics
1873 ========================
1875 TeX is written by a mathematician, and has always contained good
1876 support for formatting mathematical text. AUCTeX supports this
1877 tradition, by offering a special minor mode for entering text with many
1878 mathematical symbols. You can enter this mode by typing `C-c ~'.
1880 -- Command: LaTeX-math-mode
1881 (`C-c ~') Toggle LaTeX Math mode. This is a minor mode rebinding
1882 the key `LaTeX-math-abbrev-prefix' to allow easy typing of
1883 mathematical symbols. ``' will read a character from the keyboard,
1884 and insert the symbol as specified in `LaTeX-math-default' and
1885 `LaTeX-math-list'. If given a prefix argument, the symbol will be
1886 surrounded by dollar signs.
1888 You can use another prefix key (instead of ``') by setting the
1889 variable `LaTeX-math-abbrev-prefix'.
1891 To enable LaTeX Math mode by default, add the following in your
1893 (add-hook 'LaTeX-mode-hook 'LaTeX-math-mode)
1895 -- User Option: LaTeX-math-abbrev-prefix
1896 A string containing the prefix of `LaTeX-math-mode' commands; This
1897 value defaults to ``'.
1899 The string has to be a key or key sequence in a format understood
1900 by the `kbd' macro. This corresponds to the syntax usually used
1901 in the manuals for Emacs Emacs Lisp.
1903 The variable `LaTeX-math-list' allows you to add your own mappings.
1905 -- User Option: LaTeX-math-list
1906 A list containing user-defined keys and commands to be used in
1907 LaTeX Math mode. Each entry should be a list of two to four
1910 First, the key to be used after `LaTeX-math-abbrev-prefix' for
1911 macro insertion. If it is nil, the symbol has no associated
1912 keystroke (it is available in the menu, though).
1914 Second, a string representing the name of the macro (without a
1917 Third, a string representing the name of a submenu the command
1918 should be added to. Use a list of strings in case of nested menus.
1920 Fourth, the position of a Unicode character to be displayed in the
1921 menu alongside the macro name. This is an integer value.
1923 -- User Option: LaTeX-math-menu-unicode
1924 Whether the LaTeX menu should try using Unicode for effect. Your
1925 Emacs built must be able to display include Unicode characters in
1926 menus for this feature.
1928 AUCTeX's reference card `tex-ref.tex' includes a list of all math
1931 AUCTeX can help you write subscripts and superscripts in math
1932 constructs by automatically inserting a pair of braces after typing <_>
1933 or <^> respectively and putting point between the braces. In order to
1934 enable this feature, set the variable
1935 `TeX-electric-sub-and-superscript' to a non-nil value.
1937 -- User Option: TeX-electric-sub-and-superscript
1938 If non-nil, insert braces after typing <^> and <_> in math mode.
1941 File: auctex.info, Node: Completion, Next: Commenting, Prev: Mathematics, Up: Editing
1946 Emacs lisp programmers probably know the `lisp-complete-symbol'
1947 command, usually bound to `M-<TAB>'. Users of the wonderful ispell
1948 mode know and love the `ispell-complete-word' command from that
1949 package. Similarly, AUCTeX has a `TeX-complete-symbol' command, by
1950 default bound to `M-<TAB>' which is equivalent to `M-C-i'. Using
1951 `TeX-complete-symbol' makes it easier to type and remember the names of
1954 In order to use `TeX-complete-symbol', you should write a backslash
1955 and the start of the macro. Typing `M-<TAB>' will now complete as much
1956 of the macro, as it unambiguously can. For example, if you type
1957 ``\renewc'' and then `M-<TAB>', it will expand to ``\renewcommand''.
1959 -- Command: TeX-complete-symbol
1960 (`M-<TAB>') Complete TeX symbol before point.
1962 A more direct way to insert a macro is with `TeX-insert-macro',
1963 bound to `C-c C-m' which is equivalent to `C-c <RET>'. It has the
1964 advantage over completion that it knows about the argument of most
1965 standard LaTeX macros, and will prompt for them. It also knows about
1966 the type of the arguments, so it will for example give completion for
1967 the argument to `\include'. Some examples are listed below.
1969 -- Command: TeX-insert-macro
1970 (`C-c C-m' or `C-c <RET>') Prompt (with completion) for the name
1971 of a TeX macro, and if AUCTeX knows the macro, prompt for each
1974 As a default selection, AUCTeX will suggest the macro last inserted
1975 or, as the first choice the value of the variable `TeX-default-macro'.
1977 -- User Option: TeX-insert-macro-default-style
1978 Specifies whether `TeX-insert-macro' will ask for all optional
1981 If set to the symbol `show-optional-args', `TeX-insert-macro' asks
1982 for optional arguments of TeX macros. If set to
1983 `mandatory-args-only', `TeX-insert-macro' asks only for mandatory
1984 arguments. When `TeX-insert-macro' is called with prefix argument
1985 (`C-u'), it's the other way round.
1987 Note that for some macros, there are special mechanisms, e.g.
1988 `LaTeX-includegraphics-options-alist'.
1991 -- User Option: TeX-default-macro
1992 Default macro to insert when invoking `TeX-insert-macro' first
1995 A faster alternative is to bind the function `TeX-electric-macro' to
1996 `\'. This can be done by setting the variable `TeX-electric-escape'
1998 -- User Option: TeX-electric-escape
1999 If this is non-nil when AUCTeX is loaded, the TeX escape character
2000 `\' will be bound to `TeX-electric-macro'
2002 The difference between `TeX-insert-macro' and `TeX-electric-macro'
2003 is that space will complete and exit from the minibuffer in
2004 `TeX-electric-macro'. Use <TAB> if you merely want to complete.
2006 -- Command: TeX-electric-macro
2007 Prompt (with completion) for the name of a TeX macro, and if
2008 AUCTeX knows the macro, prompt for each argument. Space will
2011 By default AUCTeX will put an empty set braces `{}' after a macro
2012 with no arguments to stop it from eating the next whitespace. This can
2013 be stopped by entering `LaTeX-math-mode', *note Mathematics::, or by
2014 setting `TeX-insert-braces' to nil.
2016 -- User Option: TeX-insert-braces
2017 If non-nil, append a empty pair of braces after inserting a macro.
2019 Completions work because AUCTeX can analyze TeX files, and store
2020 symbols in Emacs Lisp files for later retrieval. *Note Automatic::, for
2023 AUCTeX will also make completion for many macro arguments, for
2024 example existing labels when you enter a `\ref' macro with
2025 `TeX-insert-macro' or `TeX-electric-macro', and BibTeX entries when you
2026 enter a `\cite' macro. For this kind of completion to work, parsing
2027 must be enabled as described in *note Parsing Files::. For `\cite' you
2028 must also make sure that the BibTeX files have been saved at least once
2029 after you enabled automatic parsing on save, and that the basename of
2030 the BibTeX file does not conflict with the basename of one of TeX files.
2033 File: auctex.info, Node: Commenting, Next: Indenting, Prev: Completion, Up: Editing
2038 It is often necessary to comment out temporarily a region of TeX or
2039 LaTeX code. This can be done with the commands `C-c ;' and `C-c %'.
2040 `C-c ;' will comment out all lines in the current region, while `C-c %'
2041 will comment out the current paragraph. Type `C-c ;' again to
2042 uncomment all lines of a commented region, or `C-c %' again to
2043 uncomment all comment lines around point. These commands will insert
2044 or remove a single `%' respectively.
2046 -- Command: TeX-comment-or-uncomment-region
2047 (`C-c ;') Add or remove `%' from the beginning of each line in the
2048 current region. Uncommenting works only if the region encloses
2049 solely commented lines. If AUCTeX should not try to guess if the
2050 region should be commented or uncommented the commands
2051 `TeX-comment-region' and `TeX-uncomment-region' can be used to
2052 explicitly comment or uncomment the region in concern.
2054 -- Command: TeX-comment-or-uncomment-paragraph
2055 (`C-c %') Add or remove `%' from the beginning of each line in the
2056 current paragraph. When removing `%' characters the paragraph is
2057 considered to consist of all preceding and succeeding lines
2058 starting with a `%', until the first non-comment line.
2061 File: auctex.info, Node: Indenting, Next: Filling, Prev: Commenting, Up: Editing
2066 Indentation means the addition of whitespace at the beginning of lines
2067 to reflect special syntactical constructs. This makes it easier to see
2068 the structure of the document, and to catch errors such as a missing
2069 closing brace. Thus, the indentation is done for precisely the same
2070 reasons that you would indent ordinary computer programs.
2072 Indentation is done by LaTeX environments and by TeX groups, that is
2073 the body of an environment is indented by the value of
2074 `LaTeX-indent-level' (default 2). Also, items of an `itemize-like'
2075 environment are indented by the value of `LaTeX-item-indent', default
2076 -2. (Items are identified with the help of `LaTeX-item-regexp'.) If
2077 more environments are nested, they are indented `accumulated' just like
2078 most programming languages usually are seen indented in nested
2081 You can explicitely indent single lines, usually by pressing <TAB>,
2082 or marked regions by calling `indent-region' on it. If you have
2083 `auto-fill-mode' enabled and a line is broken while you type it, Emacs
2084 automatically cares about the indentation in the following line. If
2085 you want to have a similar behavior upon typing <RET>, you can
2086 customize the variable `TeX-newline-function' and change the default of
2087 `newline' which does no indentation to `newline-and-indent' which
2088 indents the new line or `reindent-then-newline-and-indent' which
2089 indents both the current and the new line.
2091 There are certain LaTeX environments which should be indented in a
2092 special way, like `tabular' or `verbatim'. Those environments may be
2093 specified in the variable `LaTeX-indent-environment-list' together with
2094 their special indentation functions. Taking the `verbatim' environment
2095 as an example you can see that `current-indentation' is used as the
2096 indentation function. This will stop AUCTeX from doing any indentation
2097 in the environment if you hit <TAB> for example.
2099 There are environments in `LaTeX-indent-environment-list' which do
2100 not bring a special indentation function with them. This is due to the
2101 fact that first the respective functions are not implemented yet and
2102 second that filling will be disabled for the specified environments.
2103 This shall prevent the source code from being messed up by accidently
2104 filling those environments with the standard filling routine. If you
2105 think that providing special filling routines for such environments
2106 would be an appropriate and challenging task for you, you are invited to
2107 contribute. (*Note Filling::, for further information about the filling
2110 The check for the indentation function may be enabled or disabled by
2111 customizing the variable `LaTeX-indent-environment-check'.
2113 As a side note with regard to formatting special environments: Newer
2114 Emacsen include `align.el' and therefore provide some support for
2115 formatting `tabular' and `tabbing' environments with the function
2116 `align-current' which will nicely align columns in the source code.
2118 AUCTeX is able to format commented parts of your code just as any
2119 other part. This means LaTeX environments and TeX groups in comments
2120 will be indented syntactically correct if the variable
2121 `LaTeX-syntactic-comments' is set to t. If you disable it, comments
2122 will be filled like normal text and no syntactic indentation will be
2125 Following you will find a list of most commands and variables related
2126 to indenting with a small summary in each case:
2129 `LaTeX-indent-line' will indent the current line.
2132 `newline-and-indent' inserts a new line (much like <RET>) and
2133 moves the cursor to an appropriate position by the left margin.
2135 Most keyboards nowadays lack a linefeed key and `C-j' may be
2136 tedious to type. Therefore you can customize AUCTeX to perform
2137 indentation upon typing <RET> as well. The respective option is
2138 called `TeX-newline-function'.
2143 -- User Option: LaTeX-indent-environment-list
2144 List of environments with special indentation. The second element
2145 in each entry is the function to calculate the indentation level in
2148 The filling code currently cannot handle tabular-like environments
2149 which will be completely messed-up if you try to format them.
2150 This is why most of these environments are included in this
2151 customization option without a special indentation function. This
2152 will prevent that they get filled.
2154 -- User Option: LaTeX-indent-level
2155 Number of spaces to add to the indentation for each `\begin' not
2156 matched by a `\end'.
2158 -- User Option: LaTeX-item-indent
2159 Number of spaces to add to the indentation for `\item''s in list
2162 -- User Option: TeX-brace-indent-level
2163 Number of spaces to add to the indentation for each `{' not
2166 -- User Option: LaTeX-syntactic-comments
2167 If non-nil comments will be filled and indented according to LaTeX
2168 syntax. Otherwise they will be filled like normal text.
2170 -- User Option: TeX-newline-function
2171 Used to specify the function which is called when <RET> is pressed.
2172 This will normally be `newline' which simply inserts a new line.
2173 In case you want to have AUCTeX do indentation as well when you
2174 press <RET>, use the built-in functions `newline-and-indent' or
2175 `reindent-then-newline-and-indent'. The former inserts a new line
2176 and indents the following line, i.e. it moves the cursor to the
2177 right position and therefore acts as if you pressed <LFD>. The
2178 latter function additionally indents the current line. If you
2179 choose `Other', you can specify your own fancy function to be
2180 called when <RET> is pressed.
2183 File: auctex.info, Node: Filling, Prev: Indenting, Up: Editing
2188 Filling deals with the insertion of line breaks to prevent lines from
2189 becoming wider than what is specified in `fill-column'. The linebreaks
2190 will be inserted automatically if `auto-fill-mode' is enabled. In this
2191 case the source is not only filled but also indented automatically as
2194 `auto-fill-mode' can be enabled for AUCTeX by calling
2195 `turn-on-auto-fill' in one of the hooks AUCTeX is running. *Note Modes
2196 and Hooks::. As an example, if you want to enable `auto-fill-mode' in
2197 `LaTeX-mode', put the following into your init file:
2199 (add-hook 'LaTeX-mode-hook 'turn-on-auto-fill)
2201 You can manually fill explicitely marked regions, paragraphs,
2202 environments, complete sections, or the whole buffer. (Note that manual
2203 filling in AUCTeX will indent the start of the region to be filled in
2204 contrast to many other Emacs modes.)
2206 There are some syntactical constructs which are handled specially
2207 with regard to filling. These are so-called code comments and paragraph
2210 Code comments are comments preceded by code or text in the same line.
2211 Upon filling a region, code comments themselves will not get filled.
2212 Filling is done from the start of the region to the line with the code
2213 comment and continues after it. In order to prevent overfull lines in
2214 the source code, a linebreak will be inserted before the last
2215 non-comment word by default. This can be changed by customizing
2216 `LaTeX-fill-break-before-code-comments'. If you have overfull lines
2217 with code comments you can fill those explicitely by calling
2218 `LaTeX-fill-paragraph' or pressing `M-q' with the cursor positioned on
2219 them. This will add linebreaks in the comment and indent subsequent
2220 comment lines to the column of the comment in the first line of the
2221 code comment. In this special case `M-q' only acts on the current line
2222 and not on the whole paragraph.
2224 Lines with `\par' are treated similarly to code comments, i.e.
2225 `\par' will be treated as paragraph boundary which should not be
2226 followed by other code or text. But it is not treated as a real
2227 paragraph boundary like an empty line where filling a paragraph would
2230 Paragraph commands like `\section' or `\noindent' (the list of
2231 commands is defined by `LaTeX-paragraph-commands') are often to be
2232 placed in their own line(s). This means they should not be consecuted
2233 with any preceding or following adjacent lines of text. AUCTeX will
2234 prevent this from happening if you do not put any text except another
2235 macro after the end of the last brace of the respective macro. If
2236 there is other text after the macro, AUCTeX regards this as a sign that
2237 the macro is part of the following paragraph.
2239 Here are some examples:
2244 \begin{quote}\label{foo}
2247 If you press `M-q' on the first line in both examples, nothing will
2248 change. But if you write
2253 and press `M-q', you will get
2255 \begin{quote} text text text text text
2257 Besides code comments and paragraph commands, another speciality of
2258 filling in AUCTeX involves commented lines. You should be aware that
2259 these comments are treated as islands in the rest of the LaTeX code if
2260 syntactic filling is enabled. This means, for example, if you try to
2261 fill an environment with `LaTeX-fill-environment' and have the cursor
2262 placed on a commented line which does not have a surrounding
2263 environment inside the comment, AUCTeX will report an error.
2265 The relevant commands and variables with regard to filling are:
2268 `LaTeX-fill-paragraph' will fill and indent the current paragraph.
2271 Alias for `C-c C-q C-p'
2274 `LaTeX-fill-environment' will fill and indent the current
2275 environment. This may e.g. be the `document' environment, in
2276 which case the entire document will be formatted.
2279 `LaTeX-fill-section' will fill and indent the current logical
2283 `LaTeX-fill-region' will fill and indent the current region.
2285 -- User Option: LaTeX-fill-break-at-separators
2286 List of separators before or after which respectively linebreaks
2287 will be inserted if they do not fit into one line. The separators
2288 can be curly braces, brackets, switches for inline math (`$', `\(',
2289 `\)') and switches for display math (`\[', `\]'). Such formatting
2290 can be useful to make macros and math more visible or to prevent
2291 overfull lines in the LaTeX source in case a package for
2292 displaying formatted TeX output inside the Emacs buffer, like
2293 preview-latex, is used.
2295 -- User Option: LaTeX-fill-break-before-code-comments
2296 Code comments are comments preceded by some other text in the same
2297 line. When a paragraph containing such a comment is to be filled,
2298 the comment start will be seen as a border after which no line
2299 breaks will be inserted in the same line. If the option
2300 `LaTeX-fill-break-before-code-comments' is enabled (which is the
2301 default) and the comment does not fit into the line, a line break
2302 will be inserted before the last non-comment word to minimize the
2303 chance that the line becomes overfull.
2306 File: auctex.info, Node: Display, Next: Processing, Prev: Editing, Up: Top
2308 3 Controlling Screen Display
2309 ****************************
2311 It is often desirable to get visual help of what markup code in a text
2312 actually does whithout having to decipher it explicitely. For this
2313 purpose Emacs and AUCTeX provide font locking (also known as syntax
2314 highlighting) which visually sets off markup code like macros or
2315 environments by using different colors or fonts. For example text to be
2316 typeset in italics can be displayed with an italic font in the editor as
2317 well, or labels and references get their own distinct color.
2319 While font locking helps you grasp the purpose of markup code and
2320 separate markup from content, the markup code can still be distracting.
2321 AUCTeX lets you hide those parts and show them again at request with
2322 its built-in support for hiding macros and environments which we call
2325 Besides folding of macros and environments, AUCTeX provides support
2326 for Emacs' outline mode which lets you narrow the buffer content to
2327 certain sections of your text by hiding the parts not belonging to these
2332 * Font Locking:: Font Locking
2333 * Folding:: Folding Macros and Environments
2334 * Outline:: Outlining the Document
2337 File: auctex.info, Node: Font Locking, Next: Folding, Up: Display
2342 Font locking is supposed to improve readability of the source code by
2343 highlighting certain keywords with different colors or fonts. It
2344 thereby lets you recognize the function of markup code to a certain
2345 extent without having to read the markup command. For general
2346 information on controlling font locking with Emacs' Font Lock mode, see
2347 *note Font Lock Mode: (emacs)Font Lock.
2349 -- User Option: TeX-install-font-lock
2350 Once font locking is enabled globally or for the major modes
2351 provided by AUCTeX, the font locking patterns and functionality of
2352 font-latex are activated by default. You can switch to a
2353 different font locking scheme or disable font locking in AUCTeX by
2354 customizing the variable `TeX-install-font-lock'.
2356 Besides font-latex AUCTeX ships with a scheme which is derived
2357 from Emacs' default LaTeX mode and activated by choosing
2358 `tex-font-setup'. Be aware that this scheme is not coupled with
2359 AUCTeX's style system and not the focus of development. Therefore
2360 and due to font-latex being much more feature-rich the following
2361 explanations will only cover font-latex.
2363 In case you want to hook in your own fontification scheme, you can
2364 choose `other' and insert the name of the function which sets up
2365 your font locking patterns. If you want to disable fontification
2366 in AUCTeX completely, choose `ignore'.
2368 font-latex provides many options for customization which are
2369 accessible with `M-x customize-group RET font-latex RET'. For this
2370 description the various options are explained in conceptional groups.
2374 * Fontification of macros:: Fontification of macros
2375 * Fontification of quotes:: Fontification of quotes
2376 * Fontification of math:: Fontification of math constructs
2377 * Verbatim content:: Verbatim macros and environments
2378 * Faces:: Faces used by font-latex
2379 * Known problems:: Known fontification problems
2382 File: auctex.info, Node: Fontification of macros, Next: Fontification of quotes, Up: Font Locking
2384 3.1.1 Fontification of macros
2385 -----------------------------
2387 Highlighting of macros can be customized by adapting keyword lists which
2388 can be found in the customization group `font-latex-keywords'.
2390 Three types of macros can be handled differently with respect to
2393 1. Commands of the form `\foo[bar]{baz}' which consist of the macro
2394 itself, optional arguments in square brackets and mandatory
2395 arguments in curly braces. For the command itself the face
2396 `font-lock-keyword-face' will be used and for the optional
2397 arguments the face `font-lock-variable-name-face'. The face
2398 applied to the mandatory argument depends on the macro class
2399 represented by the respective built-in variables.
2401 2. Declaration macros of the form `{\foo text}' which consist of the
2402 macro which may be enclosed in a TeX group together with text to be
2403 affected by the macro. In case a TeX group is present, the macro
2404 will get the face `font-lock-keyword-face' and the text will get
2405 the face configured for the respective macro class. If no TeX
2406 group is present, the latter face will be applied to the macro
2409 3. Simple macros of the form `\foo' which do not have any arguments or
2410 groupings. The respective face will be applied to the macro
2413 Customization variables for `\foo[bar]{baz}' type macros allow both
2414 the macro name and the sequence of arguments to be specified. The
2415 latter is done with a string which can contain the characters
2417 indicating the existence of a starred variant for the macro,
2420 for optional arguments in brackets,
2423 for mandatory arguments in braces,
2426 for mandatory arguments consisting of a single macro and
2429 as a prefix indicating that two alternatives are following.
2430 For example the specifier for `\documentclass' would be `[{' because
2431 the macro has one optional followed by one mandatory argument. The
2432 specifier for `\newcommand' would be `*|{\[[{' because there is a
2433 starred variant, the mandatory argument following the macro name can be
2434 a macro or a TeX group which can be followed by two optional arguments
2435 and the last token is a mandatory argument in braces.
2437 Customization variables for the `{\foo text}' and `\foo' types are
2438 simple lists of strings where each entry is a macro name (without the
2441 General macro classes
2442 ---------------------
2444 font-latex provides keyword lists for different macro classes which are
2445 described in the following table:
2447 `font-latex-match-function-keywords'
2448 Keywords for macros defining or related to functions, like
2450 Type: `\macro[...]{...}'
2451 Face: `font-lock-function-name-face'
2453 `font-latex-match-reference-keywords'
2454 Keywords for macros defining or related to references, like `\ref'.
2455 Type: `\macro[...]{...}'
2456 Face: `font-lock-constant-face'
2458 `font-latex-match-textual-keywords'
2459 Keywords for macros specifying textual content, like `\caption'.
2460 Type: `\macro[...]{...}'
2461 Face: `font-lock-type-face'
2463 `font-latex-match-variable-keywords'
2464 Keywords for macros defining or related to variables, like
2466 Type: `\macro[...]{...}'
2467 Face: `font-lock-variable-name-face'
2469 `font-latex-match-warning-keywords'
2470 Keywords for important macros, e.g. affecting line or page break,
2473 Face: `font-latex-warning-face'
2478 Sectioning commands are macros like `\chapter' or `\section'. For
2479 these commands there are two fontification schemes which may be
2480 selected by customizing the variable `font-latex-fontify-sectioning'.
2482 -- User Option: font-latex-fontify-sectioning
2483 Per default sectioning commands will be shown in a larger,
2484 proportional font, which corresponds to a number for this
2485 variable. The font size varies with the sectioning level, e.g.
2486 `\part' (`font-latex-sectioning-0-face') has a larger font than
2487 `\paragraph' (`font-latex-sectioning-5-face'). Typically, values
2488 from 1.05 to 1.3 for `font-latex-fontify-sectioning' give best
2489 results, depending on your font setup. If you rather like to use
2490 the base font and a different color, set the variable to the symbol
2491 `color'. In this case the face `font-lock-type-face' will be used
2492 to fontify the argument of the sectioning commands.
2494 You can make font-latex aware of your own sectioning commands be
2495 adding them to the keyword lists:
2496 `font-latex-match-sectioning-0-keywords'
2497 (`font-latex-sectioning-0-face') ...
2498 `font-latex-match-sectioning-5-keywords'
2499 (`font-latex-sectioning-5-face').
2501 Related to sectioning there is special support for slide titles which
2502 may be fontified with the face `font-latex-slide-title-face'. You can
2503 add macros which should appear in this face by customizing the variable
2504 `font-latex-match-slide-title-keywords'.
2506 Commands for changing fonts
2507 ---------------------------
2509 LaTeX provides various macros for changing fonts or font attributes.
2510 For example, you can select an italic font with `\textit{...}' or bold
2511 with `\textbf{...}'. An alternative way to specify these fonts is to
2512 use special macros in TeX groups, like `{\itshape ...}' for italics and
2513 `{\bfseries ...}' for bold. As mentioned above, we call the former
2514 variants commands and the latter declarations.
2516 Besides the macros for changing fonts provided by LaTeX there is an
2517 infinite number of other macros--either defined by yourself for logical
2518 markup or defined by macro packages--which affect the font in the
2519 typeset text. While LaTeX's built-in macros and macros of packages
2520 known by AUCTeX are already handled by font-latex, different keyword
2521 lists per type style and macro type are provided for entering your own
2522 macros which are listed in the table below.
2524 `font-latex-match-bold-command-keywords'
2525 Keywords for commands specifying a bold type style.
2526 Face: `font-latex-bold-face'
2528 `font-latex-match-italic-command-keywords'
2529 Keywords for commands specifying an italic font.
2530 Face: `font-latex-italic-face'
2532 `font-latex-match-math-command-keywords'
2533 Keywords for commands specifying a math font.
2534 Face: `font-latex-math-face'
2536 `font-latex-match-type-command-keywords'
2537 Keywords for commands specifying a typewriter font.
2538 Face: `font-lock-type-face'
2540 `font-latex-match-bold-declaration-keywords'
2541 Keywords for declarations specifying a bold type style.
2542 Face: `font-latex-bold-face'
2544 `font-latex-match-italic-declaration-keywords'
2545 Keywords for declarations specifying an italic font.
2546 Face: `font-latex-italic-face'
2548 `font-latex-match-type-declaration-keywords'
2549 Keywords for declarations specifying a typewriter font.
2550 Face: `font-latex-type-face'
2552 Deactivating defaults of built-in keyword classes
2553 -------------------------------------------------
2555 font-latex ships with predefined lists of keywords for the classes
2556 described above. You can disable these defaults per class by
2557 customizing the variable `font-latex-deactivated-keyword-classes'.
2558 This is a list of strings for keyword classes to be deactivated. Valid
2559 entries are "warning", "variable", "reference", "function" ,
2560 "sectioning-0", "sectioning-1", "sectioning-2", "sectioning-3",
2561 "sectioning-4", "sectioning-5", "textual", "bold-command",
2562 "italic-command", "math-command", "type-command", "bold-declaration",
2563 "italic-declaration", "type-declaration".
2565 You can also get rid of certain keywords only. For example if you
2566 want to remove highlighting of footnotes as references you can put the
2567 following stanza into your init file:
2569 (eval-after-load "font-latex"
2571 font-latex-match-reference-keywords-local
2572 (remove "footnote" font-latex-match-reference-keywords-local)))
2574 But note that this means fiddling with font-latex's internals and is
2575 not guaranteed to work in future versions of font-latex.
2577 User-defined keyword classes
2578 ----------------------------
2580 In case the customization options explained above do not suffice for
2581 your needs, you can specify your own keyword classes by customizing the
2582 variable `font-latex-user-keyword-classes'.
2584 -- User Option: font-latex-user-keyword-classes
2585 Every keyword class consists of four parts, a name, a list of
2586 keywords, a face and a specifier for the type of macros to be
2589 When adding new entries, you have to use unique values for the
2590 class names, i.e. they must not clash with names of the built-in
2591 keyword classes or other names given by you. Additionally the
2592 names must not contain spaces.
2594 The list of keywords defines which commands and declarations
2595 should be covered by the keyword class. A keyword can either be a
2596 simple command name omitting the leading backslash or a list
2597 consisting of the command name and a string specifying the
2598 sequence of arguments for the command.
2600 The face argument can either be an existing face or font
2601 specifications made by you. (The latter option is not available
2604 There are three alternatives for the type of keywords--"Command
2605 with arguments", "Declaration inside TeX group" and "Command
2606 without arguments"--which correspond with the macro types
2610 File: auctex.info, Node: Fontification of quotes, Next: Fontification of math, Prev: Fontification of macros, Up: Font Locking
2612 3.1.2 Fontification of quotes
2613 -----------------------------
2615 Text in quotation marks is displayed with the face
2616 `font-latex-string-face'. Besides the various forms of opening and
2617 closing double and single quotation marks, so-called guillemets (<<, >>)
2618 can be used for quoting. Because there are two styles of using
2619 them--French style: << text >>; German style: >>text<<--you can
2620 customize the variable `font-latex-quotes' to tell font-latex which
2621 type you are using if the correct value cannot be derived from document
2624 -- User Option: font-latex-quotes
2625 The default value of `font-latex-quotes' is `auto' which means
2626 that font-latex will try to derive the correct type of quotation
2627 mark matching from document properties like the language option
2628 supplied to the babel LaTeX package.
2630 If the automatic detection fails for you and you mostly use one
2631 specific style you can set it to a specific language-dependent
2632 value as well. Set the value to `german' if you are using
2633 >>German quotes<< and to `french' if you are using << French
2634 quotes >>. font-latex will recognize the different ways these
2635 quotes can be given in your source code, i.e. (`"<', `">'), (`<<',
2636 `>>') and the respective 8-bit variants.
2638 If you set `font-latex-quotes' to nil, quoted content will not be
2642 File: auctex.info, Node: Fontification of math, Next: Verbatim content, Prev: Fontification of quotes, Up: Font Locking
2644 3.1.3 Fontification of mathematical constructs
2645 ----------------------------------------------
2647 In LaTeX mathematics can be indicated by a variety of different
2648 methods: toggles (like dollar signs), macros and environments. Math
2649 constructs known by font-latex are displayed with the face
2650 `font-latex-math-face'. Support for dollar signs and shorthands like
2651 `\(...\)' or `\[...\]' is built-in and not customizable. Support for
2652 other math macros and environments can be adapted by customizing the
2653 variables `font-latex-match-math-command-keywords' and
2654 `font-latex-math-environments' respectively.
2656 In order to make math constructs more readable, font-latex displays
2657 subscript and superscript parts in a smaller font and raised or lowered
2658 respectively. This fontification feature can be controlled with the
2659 variables `font-latex-fontify-script' and `font-latex-script-display'.
2661 -- User Option: font-latex-fontify-script
2662 If non-nil, fontify subscript and superscript strings.
2664 Note that this feature is not available on XEmacs, for which it is
2665 disabled per default. In GNU Emacs raising and lowering is not
2666 enabled for versions 21.3 and before due to it working not
2669 -- User Option: font-latex-script-display
2670 Display specification for subscript and superscript content. The
2671 car is used for subscript, the cdr is used for superscript. The
2672 feature is implemented using so-called display properties. For
2673 information on what exactly to specify for the values, see *note
2674 Other Display Specifications: (elisp)Other Display Specs.
2677 File: auctex.info, Node: Verbatim content, Next: Faces, Prev: Fontification of math, Up: Font Locking
2679 3.1.4 Verbatim macros and environments
2680 --------------------------------------
2682 Usually it is not desirable to have content to be typeset verbatim
2683 highlighted according to LaTeX syntax. Therefore this content will be
2684 fontified uniformly with the face `font-latex-verbatim-face'.
2686 font-latex differentiates three different types of verbatim
2687 constructs for fontification. Macros with special characters like | as
2688 delimiters, macros with braces, and environments. Which macros and
2689 environments are recognized is controlled by the variables
2690 `LaTeX-verbatim-macros-with-delims',
2691 `LaTeX-verbatim-macros-with-braces', and `LaTeX-verbatim-environments'
2695 File: auctex.info, Node: Faces, Next: Known problems, Prev: Verbatim content, Up: Font Locking
2697 3.1.5 Faces used by font-latex
2698 ------------------------------
2700 In case you want to change the colors and fonts used by font-latex
2701 please refer to the faces mentioned in the explanations above and use
2702 `M-x customize-face RET <face> RET'. All faces defined by font-latex
2703 are accessible through a customization group by typing `M-x
2704 customize-group RET font-latex-highlighting-faces RET'.
2707 File: auctex.info, Node: Known problems, Prev: Faces, Up: Font Locking
2709 3.1.6 Known fontification problems
2710 ----------------------------------
2712 In certain cases the fontification machinery fails to interpret buffer
2713 contents correctly. This can lead to color bleed, i.e. large parts of a
2714 buffer get fontified with an inappropriate face. A typical situation
2715 for this to happen is the use of a dollar sign (`$') in a verbatim
2716 macro or environment. If font-latex is not aware of the verbatim
2717 construct, it assumes the dollar sign to be a toggle for mathematics and
2718 fontifies the following buffer content with the respective face until it
2719 finds a closing dollar sign or till the end of the buffer.
2721 As a remedy you can make the verbatim construct known to font-latex,
2722 *note Verbatim content::. If this is not possible, you can insert a
2723 commented dollar sign (`%$') at the next suitable end of line as a
2727 File: auctex.info, Node: Folding, Next: Outline, Prev: Font Locking, Up: Display
2729 3.2 Folding Macros and Environments
2730 ===================================
2732 A popular complaint about markup languages like TeX and LaTeX is that
2733 there is too much clutter in the source text and that one cannot focus
2734 well on the content. There are macros where you are only interested in
2735 the content they are enclosing, like font specifiers where the content
2736 might already be fontified in a special way by font locking. Or macros
2737 the content of which you only want to see when actually editing it,
2738 like footnotes or citations. Similarly you might find certain
2739 environments or comments distracting when trying to concentrate on the
2740 body of your document.
2742 With AUCTeX's folding functionality you can collapse those items and
2743 replace them by a fixed string, the content of one of their arguments,
2744 or a mixture of both. If you want to make the original text visible
2745 again in order to view or edit it, move point sideways onto the
2746 placeholder (also called display string) or left-click with the mouse
2747 pointer on it. (The latter is currently only supported on Emacs.) The
2748 macro or environment will unfold automatically, stay open as long as
2749 point is inside of it and collapse again once you move point out of it.
2750 (Note that folding of environments currently does not work in every
2753 In order to use this feature, you have to activate `TeX-fold-mode'
2754 which will activate the auto-reveal feature and the necessary commands
2755 to hide and show macros and environments. You can activate the mode in
2756 a certain buffer by typing the command `M-x TeX-fold-mode RET' or using
2757 the keyboard shortcut `C-c C-o C-f'. If you want to use it every time
2758 you edit a LaTeX document, add it to a hook:
2760 (add-hook 'LaTeX-mode-hook (lambda ()
2763 If it should be activated in all AUCTeX modes, use `TeX-mode-hook'
2764 instead of `LaTeX-mode-hook'.
2766 Once the mode is active there are several commands available to hide
2767 and show macros, environments and comments:
2769 -- Command: TeX-fold-buffer
2770 (`C-c C-o C-b') Hide all foldable items in the current buffer
2771 according to the setting of `TeX-fold-type-list'.
2773 If you want to have this done automatically every time you open a
2774 file, add it to a hook and make sure the function is called after
2775 font locking is set up for the buffer. The following code should
2778 (add-hook 'find-file-hook 'TeX-fold-buffer t)
2780 The command can be used any time to refresh the whole buffer and
2781 fold any new macros and environments which were inserted after the
2782 last invocation of the command.
2784 -- User Option: TeX-fold-type-list
2785 List of symbols determining the item classes to consider for
2786 folding. This can be macros, environments and comments. Per
2787 default only macros and environments are folded.
2789 -- User Option: TeX-fold-force-fontify
2790 In order for all folded content to get the right faces, the whole
2791 buffer has to be fontified before folding is carried out.
2792 `TeX-fold-buffer' therefore will force fontification of unfontified
2793 regions. As this will prolong the time folding takes, you can
2794 prevent forced fontification by customizing the variable
2795 `TeX-fold-force-fontify'.
2797 -- User Option: TeX-fold-preserve-comments
2798 By default items found in comments will be folded. If your
2799 comments often contain unfinished code this might lead to
2800 problems. Give this variable a non-nil value and foldable items
2801 in your comments will be left alone.
2803 -- Command: TeX-fold-region
2804 (`C-c C-o C-r') Hide all configured macros in the marked region.
2806 -- Command: TeX-fold-paragraph
2807 (`C-c C-o C-p') Hide all configured macros in the paragraph
2810 -- Command: TeX-fold-macro
2811 (`C-c C-o C-m') Hide the macro on which point currently is located.
2812 If the name of the macro is found in `TeX-fold-macro-spec-list',
2813 the respective display string will be shown instead. If it is not
2814 found, the name of the macro in sqare brackets or the default
2815 string for unspecified macros
2816 (`TeX-fold-unspec-macro-display-string') will be shown, depending
2817 on the value of the variable `TeX-fold-unspec-use-name'.
2819 -- Command: TeX-fold-env
2820 (`C-c C-o C-e') Hide the environment on which point currently is
2821 located. The behavior regarding the display string is analogous to
2822 `TeX-fold-macro' and determined by the variables
2823 `TeX-fold-env-spec-list' and `TeX-fold-unspec-env-display-string'
2826 -- Command: TeX-fold-math
2827 Hide the math macro on which point currently is located. If the
2828 name of the macro is found in `TeX-fold-math-spec-list', the
2829 respective display string will be shown instead. If it is not
2830 found, the name of the macro in sqare brackets or the default
2831 string for unspecified macros
2832 (`TeX-fold-unspec-macro-display-string') will be shown, depending
2833 on the value of the variable `TeX-fold-unspec-use-name'.
2835 -- Command: TeX-fold-comment
2836 (`C-c C-o C-c') Hide the comment point is located on.
2838 -- Command: TeX-fold-clearout-buffer
2839 (`C-c C-o b') Permanently unfold all macros and environments in the
2842 -- Command: TeX-fold-clearout-region
2843 (`C-c C-o r') Permanently unfold all macros and environments in the
2846 -- Command: TeX-fold-clearout-paragraph
2847 (`C-c C-o p') Permanently unfold all macros and environments in the
2848 paragraph containing point.
2850 -- Command: TeX-fold-clearout-item
2851 (`C-c C-o i') Permanently show the macro or environment on which
2852 point currently is located. In contrast to temporarily opening the
2853 macro when point is moved sideways onto it, the macro will be
2854 permanently unfolded and will not collapse again once point is
2857 -- Command: TeX-fold-dwim
2858 (`C-c C-o C-o') Hide or show items according to the current
2859 context. If there is folded content, unfold it. If there is a
2860 marked region, fold all configured content in this region. If
2861 there is no folded content but a macro or environment, fold it.
2863 In case you want to use a different prefix than `C-c C-o' for these
2864 commands you can customize the variable `TeX-fold-command-prefix'.
2865 (Note that this will not change the key binding for activating the
2868 The commands above will only take macros or environments into
2869 consideration which are specified in the variables
2870 `TeX-fold-macro-spec-list' or `TeX-fold-env-spec-list' respectively.
2872 -- User Option: TeX-fold-macro-spec-list
2873 List of replacement specifiers and macros to fold. The specifier
2874 can be a string, an integer or a function symbol.
2876 If you specify a string, it will be used as a display replacement
2877 for the whole macro. Numbers in braces, brackets, parens or angle
2878 brackets will be replaced by the respective macro argument. For
2879 example `{1}' will be replaced by the first mandatory argument of
2880 the macro. One can also define alternatives within the specifier
2881 which are used if an argument is not found. Alternatives are
2882 separated by `||'. They are most useful with optional arguments.
2883 As an example, the default specifier for `\item' is `[1]:||*' which
2884 means that if there is an optional argument, its value is shown
2885 followed by a colon. If there is no optional argument, only an
2886 asterisk is used as the display string.
2888 If you specify a number as the first element, the content of the
2889 respective mandatory argument of a LaTeX macro will be used as the
2892 If the first element is a function symbol, the function will be
2893 called with all mandatory arguments of the macro and the result of
2894 the function call will be used as a replacement for the macro.
2896 The placeholder is made by copying the text from the buffer
2897 together with its properties, i.e. its face as well. If
2898 fontification has not happened when this is done (e.g. because of
2899 lazy font locking) the intended fontification will not show up.
2900 As a workaround you can leave Emacs idle a few seconds and wait
2901 for stealth font locking to finish before you fold the buffer. Or
2902 you just re-fold the buffer with `TeX-fold-buffer' when you notice
2903 a wrong fontification.
2905 -- User Option: TeX-fold-env-spec-list
2906 List of display strings or argument numbers and environments to
2907 fold. Argument numbers refer to the `\begin' statement. That
2908 means if you have e.g. `\begin{tabularx}{\linewidth}{XXX} ...
2909 \end{tabularx}' and specify 3 as the argument number, the resulting
2910 display string will be "XXX".
2912 -- User Option: TeX-fold-math-spec-list
2913 List of display strings and math macros to fold.
2915 The variables `TeX-fold-macro-spec-list', `TeX-fold-env-spec-list',
2916 and `TeX-fold-math-spec-list' apply to any AUCTeX mode. If you want to
2917 make settings which are only applied to LaTeX mode, you can use the
2918 mode-specific variables `LaTeX-fold-macro-spec-list',
2919 `LaTeX-fold-env-spec-list', and `LaTeX-fold-math-spec-list'
2921 -- User Option: TeX-fold-unspec-macro-display-string
2922 Default display string for macros which are not specified in
2923 `TeX-fold-macro-spec-list'.
2925 -- User Option: TeX-fold-unspec-env-display-string
2926 Default display string for environments which are not specified in
2927 `TeX-fold-env-spec-list'.
2929 -- User Option: TeX-fold-unspec-use-name
2930 If non-nil the name of the macro or environment surrounded by
2931 square brackets is used as display string, otherwise the defaults
2932 specified in `TeX-fold-unspec-macro-display-string' or
2933 `TeX-fold-unspec-env-display-string' respectively.
2935 When you hover with the mouse pointer over folded content, its
2936 original text will be shown in a tooltip or the echo area depending on
2937 Tooltip mode being activate. In order to avoid exorbitantly big
2938 tooltips and to cater for the limited space in the echo area the
2939 content will be cropped after a certain amount of characters defined by
2940 the variable `TeX-fold-help-echo-max-length'.
2942 -- User Option: TeX-fold-help-echo-max-length
2943 Maximum length of original text displayed in a tooltip or the echo
2944 area for folded content. Set it to zero in order to disable this
2948 File: auctex.info, Node: Outline, Prev: Folding, Up: Display
2950 3.3 Outlining the Document
2951 ==========================
2953 AUCTeX supports the standard outline minor mode using LaTeX/ConTeXt
2954 sectioning commands as header lines. *Note Outline Mode:
2955 (emacs)Outline Mode.
2957 You can add your own headings by setting the variable
2958 `TeX-outline-extra'.
2960 -- Variable: TeX-outline-extra
2961 List of extra TeX outline levels.
2963 Each element is a list with two entries. The first entry is the
2964 regular expression matching a header, and the second is the level
2965 of the header. A `^' is automatically prepended to the regular
2966 expressions in the list, so they must match text at the beginning
2969 See `LaTeX-section-list' or `ConTeXt-INTERFACE-section-list' for
2970 existing header levels.
2972 The following example add `\item' and `\bibliography' headers, with
2973 `\bibliography' at the same outline level as `\section', and `\item'
2974 being below `\subparagraph'.
2976 (setq TeX-outline-extra
2977 '(("[ \t]*\\\\\\(bib\\)?item\\b" 7)
2978 ("\\\\bibliography\\b" 2)))
2980 You may want to check out the unbundled `out-xtra' package for even
2981 better outline support. It is available from your favorite emacs lisp
2985 File: auctex.info, Node: Processing, Next: Customization, Prev: Display, Up: Top
2987 4 Starting Processors, Viewers and Other Programs
2988 *************************************************
2990 The most powerful features of AUCTeX may be those allowing you to run
2991 TeX, LaTeX, ConTeXt and other external commands like BibTeX and
2992 `makeindex' from within Emacs, viewing and printing the results, and
2993 moreover allowing you to _debug_ your documents.
2995 AUCTeX comes with a special tool bar for TeX and LaTeX which
2996 provides buttons for the most important commands. You can enable or
2997 disable it by customizing the options `plain-TeX-enable-toolbar' and
2998 `LaTeX-enable-toolbar' in the `TeX-tool-bar' customization group.
3002 * Commands:: Invoking external commands.
3003 * Viewing:: Invoking external viewers.
3004 * Debugging:: Debugging TeX and LaTeX output.
3005 * Checking:: Checking the document.
3006 * Control:: Controlling the processes.
3007 * Cleaning:: Cleaning intermediate and output files.
3008 * Documentation:: Documentation about macros and packages.
3011 File: auctex.info, Node: Commands, Next: Viewing, Up: Processing
3013 4.1 Executing Commands
3014 ======================
3016 Formatting the document with TeX, LaTeX or ConTeXt, viewing with a
3017 previewer, printing the document, running BibTeX, making an index, or
3018 checking the document with `lacheck' or `chktex' all require running an
3023 * Starting a Command:: Starting a Command on a Document or Region
3024 * Selecting a Command:: Selecting and Executing a Command
3025 * Processor Options:: Options for TeX Processors
3028 File: auctex.info, Node: Starting a Command, Next: Selecting a Command, Up: Commands
3030 4.1.1 Starting a Command on a Document or Region
3031 ------------------------------------------------
3033 There are two ways to run an external command, you can either run it on
3034 the current document with `TeX-command-master', or on the current
3035 region with `TeX-command-region'. A special case of running TeX on a
3036 region is `TeX-command-buffer' which differs from `TeX-command-master'
3037 if the current buffer is not its own master file.
3039 -- Command: TeX-command-master
3040 (`C-c C-c') Query the user for a command, and run it on the master
3041 file associated with the current buffer. The name of the master
3042 file is controlled by the variable `TeX-master'. The available
3043 commands are controlled by the variable `TeX-command-list'.
3045 -- Command: TeX-command-region
3046 (`C-c C-r') Query the user for a command, and run it on the
3047 contents of the selected region. The region contents are written
3048 into the region file, after extracting the header and trailer from
3049 the master file. If mark is inactive (which can happen with
3050 Transient Mark mode), use the old region. See also the command
3051 `TeX-pin-region' about how to fix a region.
3053 The name of the region file is controlled by the variable
3054 `TeX-region'. The name of the master file is controlled by the
3055 variable `TeX-master'. The header is all text up to the line
3056 matching the regular expression `TeX-header-end'. The trailer is
3057 all text from the line matching the regular expression
3058 `TeX-trailer-start'. The available commands are controlled by the
3059 variable `TeX-command-list'.
3061 -- Command: TeX-command-buffer
3062 (`C-c C-b') Query the user for a command, and apply it to the
3063 contents of the current buffer. The buffer contents are written
3064 into the region file, after extracting the header and trailer from
3065 the master file. The command is then actually run on the region
3066 file. See above for details.
3068 -- User Option: TeX-region
3069 The name of the file for temporarily storing the text when
3070 formatting the current region.
3072 -- User Option: TeX-header-end
3073 A regular expression matching the end of the header. By default,
3074 this is `\begin{document}' in LaTeX mode and `%**end of header' in
3077 -- User Option: TeX-trailer-start
3078 A regular expression matching the start of the trailer. By
3079 default, this is `\end{document}' in LaTeX mode and `\bye' in TeX
3082 If you want to change the values of `TeX-header-end' and
3083 `TeX-trailer-start' you can do this for all files by setting the
3084 variables in a mode hook or per file by specifying them as file
3085 variables (*note File Variables: (emacs)File Variables.).
3087 -- Command: TeX-pin-region
3088 (`C-c C-t C-r') If you don't have a mode like Transient Mark mode
3089 active, where marks get disabled automatically, the region would
3090 need to get properly set before each call to `TeX-command-region'.
3091 If you fix the current region with `C-c C-t C-r', then it will get
3092 used for more commands even though mark and point may change. An
3093 explicitly activated mark, however, will always define a new
3094 region when calling `TeX-command-region'.
3096 AUCTeX will allow one process for each document, plus one process
3097 for the region file to be active at the same time. Thus, if you are
3098 editing N different documents, you can have N plus one processes
3099 running at the same time. If the last process you started was on the
3100 region, the commands described in *note Debugging:: and *note Control::
3101 will work on that process, otherwise they will work on the process
3102 associated with the current document.
3105 File: auctex.info, Node: Selecting a Command, Next: Processor Options, Prev: Starting a Command, Up: Commands
3107 4.1.2 Selecting and Executing a Command
3108 ---------------------------------------
3110 Once you started the command selection with `C-c C-c', `C-c C-s' or
3111 `C-c C-b' you will be prompted for the type of command. AUCTeX will
3112 try to guess which command is appropriate in the given situation and
3113 propose it as default. Usually this is a processor like `TeX' or
3114 `LaTeX' if the document was changed or a viewer if the document was
3115 just typeset. Other commands can be selected in the minibuffer with
3116 completion support by typing <TAB>.
3118 The available commands are defined by the variable
3119 `TeX-command-list'. Per default it includes commands for typesetting
3120 the document (e.g. `LaTeX'), for viewing the output (`View'), for
3121 printing (`Print'), for generating an index (`Index') or for spell
3122 checking (`Spell') to name but a few. You can also add your own
3123 commands by adding entries to `TeX-command-list'. Refer to its doc
3124 string for information about its syntax. You might also want to look
3125 at `TeX-expand-list' to learn about the expanders you can use in
3128 Note that the default of the variable occasionally changes.
3129 Therefore it is advisable to add to the list rather than overwriting
3130 it. You can do this with a call to `add-to-list' in your init file.
3131 For example, if you wanted to add a command for running a program called
3132 `foo' on the master or region file, you could do this with the
3135 (eval-after-load "tex"
3136 '(add-to-list 'TeX-command-list
3137 '("Foo" "foo %s" TeX-run-command t t :help "Run foo") t))
3139 As mentioned before, AUCTeX will try to guess what command you want
3140 to invoke. If you want to use another command than `TeX', `LaTeX' or
3141 whatever processor AUCTeX thinks is appropriate for the current mode,
3142 set the variable `TeX-command-default'. You can do this for all files
3143 by setting it in a mode hook or per file by specifying it as a file
3144 variable (*note File Variables: (emacs)File Variables.).
3146 -- User Option: TeX-command-default
3147 The default command to run in this buffer. Must be an entry in
3150 After confirming a command to execute, AUCTeX will try to save any
3151 buffers related to the document, and check if the document needs to be
3152 reformatted. If the variable `TeX-save-query' is non-nil, AUCTeX will
3153 query before saving each file. By default AUCTeX will check emacs
3154 buffers associated with files in the current directory, in one of the
3155 `TeX-macro-private' directories, and in the `TeX-macro-global'
3156 directories. You can change this by setting the variable
3159 -- User Option: TeX-check-path
3160 Directory path to search for dependencies.
3162 If nil, just check the current file. Used when checking if any
3166 File: auctex.info, Node: Processor Options, Prev: Selecting a Command, Up: Commands
3168 4.1.3 Options for TeX Processors
3169 --------------------------------
3171 There are some options you can customize affecting which processors are
3172 invoked or the way this is done and which output they produce as a
3173 result. These options control if DVI or PDF output should be produced,
3174 if TeX should be started in interactive or nonstop mode, if source
3175 specials or a SyncTeX file should be produced for making inverse and
3176 forward search possible or which TeX engine should be used instead of
3177 regular TeX, like PDFTeX, Omega or XeTeX.
3179 -- Command: TeX-PDF-mode
3180 (`C-c C-t C-p') This command toggles the PDF mode of AUCTeX, a
3181 buffer-local minor mode. You can customize `TeX-PDF-mode' to give
3182 it a different default. The default is used when AUCTeX does not
3183 have additional clue about what a document might want. This
3184 option usually results in calling either PDFTeX or ordinary TeX.
3186 -- User Option: TeX-DVI-via-PDFTeX
3187 If this is set, DVI will also be produced by calling PDFTeX,
3188 setting `\pdfoutput=0'. This makes it possible to use PDFTeX
3189 features like character protrusion even when producing DVI files.
3190 Contemporary TeX distributions do this anyway, so that you need
3191 not enable the option within AUCTeX.
3193 -- Command: TeX-interactive-mode
3194 (`C-c C-t C-i') This command toggles the interactive mode of
3195 AUCTeX, a global minor mode. You can customize
3196 `TeX-interactive-mode' to give it a different default. In
3197 interactive mode, TeX will pause with an error prompt when errors
3198 are encountered and wait for the user to type something.
3200 -- Command: TeX-source-correlate-mode
3201 (`C-c C-t C-s') Toggles support for forward and inverse search.
3202 Forward search refers to jumping to the place in the previewed
3203 document corresponding to where point is located in the document
3204 source and inverse search to the other way round. *Note I/O
3207 You can permanently activate `TeX-source-correlate-mode' by
3208 customizing the variable `TeX-source-correlate-mode'. There is a
3209 bunch of customization options for the mode, use `M-x
3210 customize-group <RET> TeX-view <RET>' to find out more.
3212 AUCTeX is aware of three different means to do I/O correlation:
3213 source specials (only DVI output), the pdfsync LaTeX package (only
3214 PDF output) and SyncTeX. The choice between source specials and
3215 SyncTeX can be controlled with the variable
3216 `TeX-source-correlate-method'.
3218 Should you use source specials it has to be stressed _very_
3219 strongly however, that source specials can cause differences in
3220 page breaks and spacing, can seriously interfere with various
3221 packages and should thus _never_ be used for the final version of
3222 a document. In particular, fine-tuning the page breaks should be
3223 done with source specials switched off.
3225 AUCTeX also allows you to easily select different TeX engines for
3226 processing, either by using the entries in the `TeXing Options' submenu
3227 below the `Command' menu or by calling the function `TeX-engine-set'.
3228 These eventually set the variable `TeX-engine' which you can also
3231 -- User Option: TeX-engine
3232 This variable allows you to choose which TeX engine should be used
3233 for typesetting the document, i.e. the executables which will be
3234 used when you invoke the `TeX' or `LaTeX' commands. The value
3235 should be one of the symbols defined in `TeX-engine-alist-builtin'
3236 or `TeX-engine-alist'. The symbols `default', `xetex', `luatex'
3237 and `omega' are available from the built-in list.
3239 Note that `TeX-engine' is buffer-local, so setting the variable
3240 directly or via the above mentioned menu or function will not take
3241 effect in other buffers. If you want to activate an engine for all
3242 AUCTeX modes, set `TeX-engine' in your init file, e.g. by using `M-x
3243 customize-variable <RET>'. If you want to activate it for a certain
3244 AUCTeX mode only, set the variable in the respective mode hook. If you
3245 want to activate it for certain files, set it through file variables
3246 (*note File Variables: (emacs)File Variables.).
3248 Should you need to change the executable names related to the
3249 different engine settings, there are some variables you can tweak.
3250 Those are `TeX-command', `LaTeX-command', `TeX-Omega-command',
3251 `LaTeX-Omega-command', `ConTeXt-engine' and `ConTeXt-Omega-engine'.
3252 The rest of the executables is defined directly in
3253 `TeX-engine-alist-builtin'. If you want to override an entry from
3254 that, add an entry to `TeX-engine-alist' that starts with the same
3255 symbol as that the entry in the built-in list and specify the
3256 executables you want to use instead. You can also add entries to
3257 `TeX-engine-alist' in order to add support for engines not covered per
3260 -- User Option: TeX-engine-alist
3261 Alist of TeX engines and associated commands. Each entry is a
3262 list with a maximum of five elements. The first element is a
3263 symbol used to identify the engine. The second is a string
3264 describing the engine. The third is the command to be used for
3265 plain TeX. The fourth is the command to be used for LaTeX. The
3266 fifth is the command to be used for the `--engine' parameter of
3267 ConTeXt's `texexec' program. Each command can either be a
3268 variable or a string. An empty string or nil means there is no
3271 You can customize AUCTeX to show the processor output as it is
3274 -- User Option: TeX-show-compilation
3275 If non-nil, the output of TeX compilation is shown in another
3279 File: auctex.info, Node: Viewing, Next: Debugging, Prev: Commands, Up: Processing
3281 4.2 Viewing the Formatted Output
3282 ================================
3284 AUCTeX allows you to start external programs for previewing the
3285 formatted output of your document.
3289 * Starting Viewers:: Starting viewers
3290 * I/O Correlation:: Forward and inverse search
3293 File: auctex.info, Node: Starting Viewers, Next: I/O Correlation, Up: Viewing
3295 4.2.1 Starting Viewers
3296 ----------------------
3298 Viewers are normally invoked by pressing `C-c C-c' once the document is
3299 formatted, which will propose the View command, or by activating the
3300 respective entry in the Command menu. Alternatively you can type `C-c
3301 C-v' which calls the function `TeX-view'.
3303 -- Command: TeX-view
3304 (`C-c C-v') Start a viewer without confirmation. The viewer is
3305 started either on a region or the master file, depending on the
3306 last command issued. This is especially useful for jumping to the
3307 location corresponding to point in the viewer when using
3308 `TeX-source-correlate-mode'.
3310 AUCTeX will try to guess which type of viewer (DVI, PostScript or
3311 PDF) has to be used and what options are to be passed over to it. This
3312 decision is based on the output files present in the working directory
3313 as well as the class and style options used in the document. For
3314 example, if there is a DVI file in your working directory, a DVI viewer
3315 will be invoked. In case of a PDF file it will be a PDF viewer. If
3316 you specified a special paper format like `a5paper' or use the
3317 `landscape' option, this will be passed to the viewer by the
3318 appropriate options. Especially some DVI viewers depend on this kind
3319 of information in order to display your document correctly. In case
3320 you are using `pstricks' or `psfrag' in your document, a DVI viewer
3321 cannot display the contents correctly and a PostScript viewer will be
3324 The association between the tests for the conditions mentioned above
3325 and the viewers is made in the variable `TeX-view-program-selection'.
3326 Therefore this variable is the starting point for customization if you
3327 want to use other viewers than the ones suggested by default.
3329 -- User Option: TeX-view-program-selection
3330 This is a list of predicates and viewers which is evaluated from
3331 front to back in order to find out which viewer to call under the
3332 given conditions. In the first element of each list item you can
3333 reference one or more predicates defined in
3334 `TeX-view-predicate-list' or `TeX-view-predicate-list-builtin'.
3335 In the second element you can reference a viewer defined in
3336 `TeX-view-program-list' or `TeX-view-program-list-builtin'. The
3337 viewer of the first item with a positively evaluated predicate is
3340 So `TeX-view-program-selection' only contains references to the
3341 actual implementations of predicates and viewer commands respectively
3342 which can be found elsewhere. AUCTeX comes with a set of preconfigured
3343 predicates and viewer commands which are stored in the variables
3344 `TeX-view-predicate-list-builtin' and `TeX-view-program-list-builtin'
3345 respectively. If you are not satisfied with those and want to
3346 overwrite one of them or add your own definitions, you can do so via
3347 the variables `TeX-view-predicate-list' and `TeX-view-program-list'.
3349 -- User Option: TeX-view-predicate-list
3350 This is a list of predicates for viewer selection and invocation.
3351 The first element of each list item is a symbol and the second
3352 element a Lisp form to be evaluated. The form should return nil
3353 if the predicate is not fulfilled.
3355 A built-in predicate from `TeX-view-predicate-list-builtin' can be
3356 overwritten by defining a new predicate with the same symbol.
3358 -- User Option: TeX-view-program-list
3359 This is a list of viewer specifications each consisting of a
3360 symbolic name and either a command line or a function to be
3361 invoked when the viewer is called. If a command line is used,
3362 parts of it can be conditionalized by prefixing them with
3363 predicates from `TeX-view-predicate-list' or
3364 `TeX-view-predicate-list-builtin'. (See the doc string for the
3365 exact format to use.) The command line can also contain
3366 placeholders as defined in `TeX-expand-list' which are expanded
3367 before the viewer is called.
3369 A built-in viewer spec from `TeX-view-program-list-builtin' can be
3370 overwritten by defining a new viewer spec with the same name.
3372 Note that the viewer selection and invocation as described above will
3373 only work if certain default settings in AUCTeX are intact. For one,
3374 the whole viewer selection machinery will only be triggered if the `%V'
3375 expander in `TeX-expand-list' is unchanged. So if you have trouble
3376 with the viewer invocation you might check if there is an older
3377 customization of the variable in place. In addition, the use of a
3378 function in `TeX-view-program-list' only works if the View command in
3379 `TeX-command-list' makes use of the hook `TeX-run-discard-or-function'.
3381 Note also that the implementation described above replaces an older
3382 one which was less flexible. This old implementation works with the
3383 variables `TeX-output-view-style' and `TeX-view-style' which are used
3384 to associate file types and style options with viewers. If desired you
3385 can reactivate it by using the placeholder `%vv' for the View command
3386 in `TeX-command-list'. Note however, that it is bound to be removed
3387 from AUCTeX once the new implementation proved to be satisfactory. For
3388 the time being, find a short description of the mentioned customization
3391 -- User Option: TeX-output-view-style
3392 List of output file extensions, style options and view options.
3393 Each item of the list consists of three elements. If the first
3394 element (a regular expression) matches the output file extension,
3395 and the second element (a regular expression) matches the name of
3396 one of the style options, any occurrence of the string `%V' in a
3397 command in `TeX-command-list' will be replaced with the third
3400 -- User Option: TeX-view-style
3401 List of style options and view options. This is the predecessor of
3402 `TeX-output-view-style' which does not provide the possibility to
3403 specify output file extensions. It is used as a fallback in case
3404 none of the alternatives specified in `TeX-output-view-style'
3405 match. In case none of the entries in `TeX-view-style' match
3406 either, no suggestion for a viewer is made.
3409 File: auctex.info, Node: I/O Correlation, Prev: Starting Viewers, Up: Viewing
3411 4.2.2 Forward and Inverse Search
3412 --------------------------------
3414 Forward and inverse search refer to the correlation between the document
3415 source in the editor and the typeset document in the viewer. Forward
3416 search allows you to jump to the place in the previewed document
3417 corresponding to a certain line in the document source and inverse
3420 AUCTeX supports three methods for forward and inverse search: source
3421 specials (only DVI output), the pdfsync LaTeX package (only PDF output)
3422 and SyncTeX (any type of output). If you want to make use of forward
3423 and inverse searching with source specials or SyncTeX, switch on
3424 `TeX-source-correlate-mode'. *Note Processor Options::, on how to do
3425 that. The use of the pdfsync package is detected automatically if
3426 document parsing is enabled.
3428 Forward search happens automatically upon calling the viewer, e.g. by
3429 typing `C-c C-v' (`TeX-view'). This will open the viewer or bring it
3430 to front and display the output page corresponding to the position of
3431 point in the source file. AUCTeX will automatically pass the necessary
3432 command line options to the viewer for this to happen.
3434 Upon opening the viewer you will be asked if you want to start a
3435 server process (Gnuserv or Emacs server) which is necessary for inverse
3436 search. This happens only if there is no server running already. You
3437 can customize the variable `TeX-source-correlate-start-server' to
3438 inhibit the question and always or never start the server respectively.
3440 -- User Option: TeX-source-correlate-start-server
3441 If `TeX-source-correlate-mode' is active and a viewer is invoked,
3442 the default behavior is to ask if a server process should be
3443 started. Set this variable to `t' if the question should be
3444 inhibited and the server should always be started. Set it to
3445 `nil' if the server should never be started. Inverse search will
3446 not be available in the latter case.
3448 Inverse search, i.e. jumping to the part of your document source in
3449 Emacs corresponding to a certain position in the viewer, is triggered
3450 from the viewer, typically by a mouse click. Refer to the documentation
3451 of your viewer to find out how it has to be configured and what you have
3452 to do exactly. In xdvi you normally have to use `C-down-mouse-1'.
3455 File: auctex.info, Node: Debugging, Next: Checking, Prev: Viewing, Up: Processing
3457 4.3 Catching the errors
3458 =======================
3460 Once you've formatted your document you may `debug' it, i.e. browse
3461 through the errors (La)TeX reported.
3463 -- Command: TeX-next-error
3464 (`C-c `') Go to the next error reported by TeX. The view will be
3465 split in two, with the cursor placed as close as possible to the
3466 error in the top view. In the bottom view, the error message will
3467 be displayed along with some explanatory text.
3469 Normally AUCTeX will only report real errors, but you may as well
3470 ask it to report `bad boxes' and warnings as well.
3472 -- Command: TeX-toggle-debug-bad-boxes
3473 (`C-c C-t C-b') Toggle whether AUCTeX should stop at bad boxes
3474 (i.e. overfull and underfull boxes) as well as normal errors.
3476 -- Command: TeX-toggle-debug-warnings
3477 (`C-c C-t C-w') Toggle whether AUCTeX should stop at warnings as
3478 well as normal errors.
3480 As default, AUCTeX will display a special help buffer containing the
3481 error reported by TeX along with the documentation. There is however
3482 an `expert' option, which allows you to display the real TeX output.
3484 -- User Option: TeX-display-help
3485 If t AUCTeX will automatically display a help text whenever an
3486 error is encountered using `TeX-next-error' (`C-c `'). If nil a
3487 terse information about the error is displayed in the echo area.
3488 If `expert' AUCTeX will display the output buffer with the raw TeX
3492 File: auctex.info, Node: Checking, Next: Control, Prev: Debugging, Up: Processing
3494 4.4 Checking for problems
3495 =========================
3497 Running TeX or LaTeX will only find regular errors in the document, not
3498 examples of bad style. Furthermore, description of the errors may
3499 often be confusing. The utility `lacheck' can be used to find style
3500 errors, such as forgetting to escape the space after an abbreviation or
3501 using `...' instead of `\ldots' and many other problems like that. You
3502 start `lacheck' with `C-c C-c Check <RET>'. The result will be a list
3503 of errors in the `*compilation*' buffer. You can go through the errors
3504 with `C-x `' (`next-error', *note Compilation: (emacs)Compilation.),
3505 which will move point to the location of the next error.
3507 Another newer program which can be used to find errors is `chktex'.
3508 It is much more configurable than `lacheck', but doesn't find all the
3509 problems `lacheck' does, at least in its default configuration. You
3510 must install the programs before using them, and for `chktex' you may
3511 also need modify `TeX-command-list' unless you use its `lacheck'
3512 compatibility wrapper. You can get `lacheck' from
3513 `<URL:ftp://ftp.ctan.org/tex-archive/support/lacheck/>' or
3514 alternatively `chktex' from
3515 `<URL:ftp://ftp.ctan.org/tex-archive/support/chktex/>'.
3518 File: auctex.info, Node: Control, Next: Cleaning, Prev: Checking, Up: Processing
3520 4.5 Controlling the output
3521 ==========================
3523 A number of commands are available for controlling the output of an
3524 application running under AUCTeX
3526 -- Command: TeX-kill-job
3527 (`C-c C-k') Kill currently running external application. This
3528 may be either of TeX, LaTeX, previewer, BibTeX, etc.
3530 -- Command: TeX-recenter-output-buffer
3531 (`C-c C-l') Recenter the output buffer so that the bottom line is
3534 -- Command: TeX-home-buffer
3535 (`C-c ^') Go to the `master' file in the document associated with
3536 the current buffer, or if already there, to the file where the
3537 current process was started.
3540 File: auctex.info, Node: Cleaning, Next: Documentation, Prev: Control, Up: Processing
3542 4.6 Cleaning intermediate and output files
3543 ==========================================
3545 -- Command: TeX-clean
3546 Remove generated intermediate files. In case a prefix argument is
3547 given, remove output files as well.
3549 Canonical access to the function is provided by the `Clean' and
3550 `Clean All' entries in `TeX-command-list', invokable with `C-c
3551 C-c' or the Command menu.
3553 The patterns governing which files to remove can be adapted
3554 separately for each AUCTeX mode by means of the variables
3555 `plain-TeX-clean-intermediate-suffixes',
3556 `plain-TeX-clean-output-suffixes',
3557 `LaTeX-clean-intermediate-suffixes', `LaTeX-clean-output-suffixes',
3558 `docTeX-clean-intermediate-suffixes',
3559 `docTeX-clean-output-suffixes',
3560 `Texinfo-clean-intermediate-suffixes',
3561 `Texinfo-clean-output-suffixes',
3562 `ConTeXt-clean-intermediate-suffixes' and
3563 `ConTeXt-clean-output-suffixes'.
3565 -- User Option: TeX-clean-confirm
3566 Control if deletion of intermediate and output files has to be
3567 confirmed before it is actually done. If non-nil, ask before
3571 File: auctex.info, Node: Documentation, Prev: Cleaning, Up: Processing
3573 4.7 Documentation about macros and packages
3574 ===========================================
3577 (`C-c ?') Get documentation about macros, packages or TeX & Co.
3578 in general. The function will prompt for the name of a command or
3579 manual, providing a list of available keywords for completion. If
3580 point is on a command or word with available documentation, this
3581 will be suggested as default.
3583 In case no documentation could be found, a prompt for querying the
3584 `texdoc' program is shown, should the latter be available.
3586 The command can be invoked by the key binding mentioned above as
3587 well as the `Find Documentation...' entry in the mode menu.
3590 File: auctex.info, Node: Customization, Next: Appendices, Prev: Processing, Up: Top
3592 5 Customization and Extension
3593 *****************************
3597 * Modes and Hooks:: Modes and Hooks
3598 * Multifile:: Multifile Documents
3599 * Parsing Files:: Automatic Parsing of TeX Files
3600 * Internationalization:: Language Support
3601 * Automatic:: Automatic Customization
3602 * Style Files:: Writing Your Own Style Support
3605 File: auctex.info, Node: Modes and Hooks, Next: Multifile, Up: Customization
3610 AUCTeX supports a wide variety of derivatives and extensions of TeX.
3611 Besides plain TeX those are LaTeX, AMS-TeX, ConTeXt, Texinfo and
3612 docTeX. For each of them there is a separate major mode in AUCTeX and
3613 each major mode runs `text-mode-hook', `TeX-mode-hook' as well as a
3614 hook special to the mode in this order. The following table provides
3615 an overview of the respective mode functions and hooks.
3617 Type Mode function Hook
3618 -------------------------------------------------------
3619 Plain TeX `plain-TeX-mode' `plain-TeX-mode-hook'
3620 LaTeX `LaTeX-mode' `LaTeX-mode-hook'
3621 AMS-TeX `ams-tex-mode' `AmS-TeX-mode-hook'
3622 ConTeXt `ConTeXt-mode' `ConTeXt-mode-hook'
3623 Texinfo `Texinfo-mode' `Texinfo-mode-hook'
3624 DocTeX `docTeX-mode' `docTeX-mode-hook'
3626 If you need to make a customization via a hook which is only relevant
3627 for one of the modes listed above, put it into the respective mode hook,
3628 if it is relevant for any AUCTeX mode, add it to `TeX-mode-hook' and if
3629 it is relevant for all text modes, append it to `text-mode-hook'.
3632 File: auctex.info, Node: Multifile, Next: Parsing Files, Prev: Modes and Hooks, Up: Customization
3634 5.2 Multifile Documents
3635 =======================
3637 You may wish to spread a document over many files (as you are likely to
3638 do if there are multiple authors, or if you have not yet discovered the
3639 power of the outline commands (*note Outline::)). This can be done by
3640 having a "master" file in which you include the various files with the
3641 TeX macro `\input' or the LaTeX macro `\include'. These files may also
3642 include other files themselves. However, to format the document you
3643 must run the commands on the top level master file.
3645 When you, for example, ask AUCTeX to run a command on the master
3646 file, it has no way of knowing the name of the master file. By default,
3647 it will assume that the current file is the master file. If you insert
3648 the following in your `.emacs' file AUCTeX will use a more advanced
3651 (setq-default TeX-master nil) ; Query for master file.
3653 If AUCTeX finds the line indicating the end of the header in a master
3654 file (`TeX-header-end'), it can figure out for itself that this is a
3655 master file. Otherwise, it will ask for the name of the master file
3656 associated with the buffer. To avoid asking you again, AUCTeX will
3657 automatically insert the name of the master file as a file variable
3658 (*note File Variables: (emacs)File Variables.). You can also insert
3659 the file variable yourself, by putting the following text at the end of
3662 %%% Local Variables:
3663 %%% TeX-master: "master"
3666 You should always set this variable to the name of the top level
3667 document. If you always use the same name for your top level
3668 documents, you can set `TeX-master' in your `.emacs' file.
3670 (setq-default TeX-master "master") ; All master files called "master".
3672 -- User Option: TeX-master
3673 The master file associated with the current buffer. If the file
3674 being edited is actually included from another file, then you can
3675 tell AUCTeX the name of the master file by setting this variable.
3676 If there are multiple levels of nesting, specify the top level
3679 If this variable is `nil', AUCTeX will query you for the name.
3681 If the variable is `t', then AUCTeX will assume the file is a
3684 If the variable is `shared', then AUCTeX will query for the name,
3685 but will not change the file.
3687 -- User Option: TeX-one-master
3688 Regular expression matching ordinary TeX files.
3690 You should set this variable to match the name of all files, for
3691 which it is a good idea to append a `TeX-master' file variable
3692 entry automatically. When AUCTeX adds the name of the master file
3693 as a file variable, it does not need to ask next time you edit the
3696 If you dislike AUCTeX automatically modifying your files, you can
3697 set this variable to `"<none>"'. By default, AUCTeX will modify
3698 any file with an extension of `.tex'.
3700 -- Command: TeX-master-file-ask
3701 (`C-c _') Query for the name of a master file and add the
3702 respective File Variables (*note File Variables: (emacs)File
3703 Variables.) to the file for setting this variable permanently.
3705 AUCTeX will not ask for a master file when it encounters existing
3706 files. This function shall give you the possibility to insert the
3709 AUCTeX keeps track of macros, environments, labels, and style files
3710 that are used in a given document. For this to work with multifile
3711 documents, AUCTeX has to have a place to put the information about the
3712 files in the document. This is done by having an `auto' subdirectory
3713 placed in the directory where your document is located. Each time you
3714 save a file, AUCTeX will write information about the file into the
3715 `auto' directory. When you load a file, AUCTeX will read the
3716 information in the `auto' directory about the file you loaded _and the
3717 master file specified by `TeX-master'_. Since the master file (perhaps
3718 indirectly) includes all other files in the document, AUCTeX will get
3719 information from all files in the document. This means that you will
3720 get from each file, for example, completion for all labels defined
3721 anywhere in the document.
3723 AUCTeX will create the `auto' directory automatically if
3724 `TeX-auto-save' is non-nil. Without it, the files in the document will
3725 not know anything about each other, except for the name of the master
3726 file. *Note Automatic Local::.
3728 -- Command: TeX-save-document
3729 (`C-c C-d') Save all buffers known to belong to the current
3732 -- User Option: TeX-save-query
3733 If non-nil, then query the user before saving each file with
3734 `TeX-save-document'.
3737 File: auctex.info, Node: Parsing Files, Next: Internationalization, Prev: Multifile, Up: Customization
3739 5.3 Automatic Parsing of TeX Files
3740 ==================================
3742 AUCTeX depends heavily on being able to extract information from the
3743 buffers by parsing them. Since parsing the buffer can be somewhat slow,
3744 the parsing is initially disabled. You are encouraged to enable them by
3745 adding the following lines to your `.emacs' file.
3747 (setq TeX-parse-self t) ; Enable parse on load.
3748 (setq TeX-auto-save t) ; Enable parse on save.
3750 The latter command will make AUCTeX store the parsed information in
3751 an `auto' subdirectory in the directory each time the TeX files are
3752 stored, *note Automatic Local::. If AUCTeX finds the pre-parsed
3753 information when loading a file, it will not need to reparse the buffer.
3754 The information in the `auto' directory is also useful for multifile
3755 documents, *note Multifile::, since it allows each file to access the
3756 parsed information from all the other files in the document. This is
3757 done by first reading the information from the master file, and then
3758 recursively the information from each file stored in the master file.
3760 The variables can also be done on a per file basis, by changing the
3761 file local variables.
3763 %%% Local Variables:
3764 %%% TeX-parse-self: t
3765 %%% TeX-auto-save: t
3768 Even when you have disabled the automatic parsing, you can force the
3769 generation of style information by pressing `C-c C-n'. This is often
3770 the best choice, as you will be able to decide when it is necessary to
3773 -- User Option: TeX-parse-self
3774 Parse file after loading it if no style hook is found for it.
3776 -- User Option: TeX-auto-save
3777 Automatically save style information when saving the buffer.
3779 -- Command: TeX-normal-mode ARG
3780 (`C-c C-n') Remove all information about this buffer, and apply the
3781 style hooks again. Save buffer first including style information.
3782 With optional argument, also reload the style hooks.
3784 When AUCTeX saves your buffer, it can optionally convert all tabs in
3785 your buffer into spaces. Tabs confuse AUCTeX's error message parsing
3786 and so should generally be avoided. However, tabs are significant in
3787 some environments, and so by default AUCTeX does not remove them. To
3788 convert tabs to spaces when saving a buffer, insert the following in
3791 (setq TeX-auto-untabify t)
3793 -- User Option: TeX-auto-untabify
3794 Automatically remove all tabs from a file before saving it.
3796 Instead of disabling the parsing entirely, you can also speed it
3797 significantly up by limiting the information it will search for (and
3798 store) when parsing the buffer. You can do this by setting the default
3799 values for the buffer local variables `TeX-auto-regexp-list' and
3800 `TeX-auto-parse-length' in your `.emacs' file.
3802 ;; Only parse LaTeX class and package information.
3803 (setq-default TeX-auto-regexp-list 'LaTeX-auto-minimal-regexp-list)
3804 ;; The class and package information is usually near the beginning.
3805 (setq-default TeX-auto-parse-length 2000)
3807 This example will speed the parsing up significantly, but AUCTeX
3808 will no longer be able to provide completion for labels, macros,
3809 environments, or bibitems specified in the document, nor will it know
3810 what files belong to the document.
3812 These variables can also be specified on a per file basis, by
3813 changing the file local variables.
3815 %%% Local Variables:
3816 %%% TeX-auto-regexp-list: TeX-auto-full-regexp-list
3817 %%% TeX-auto-parse-length: 999999
3820 -- User Option: TeX-auto-regexp-list
3821 List of regular expressions used for parsing the current file.
3823 -- User Option: TeX-auto-parse-length
3824 Maximal length of TeX file that will be parsed.
3826 The pre-specified lists of regexps are defined below. You can use
3827 these before loading AUCTeX by quoting them, as in the example above.
3829 -- Constant: TeX-auto-empty-regexp-list
3832 -- Constant: LaTeX-auto-minimal-regexp-list
3833 Only parse LaTeX class and packages.
3835 -- Constant: LaTeX-auto-label-regexp-list
3836 Only parse LaTeX labels.
3838 -- Constant: LaTeX-auto-regexp-list
3839 Parse common LaTeX commands.
3841 -- Constant: plain-TeX-auto-regexp-list
3842 Parse common plain TeX commands.
3844 -- Constant: TeX-auto-full-regexp-list
3845 Parse all TeX and LaTeX commands that AUCTeX can use.
3848 File: auctex.info, Node: Internationalization, Next: Automatic, Prev: Parsing Files, Up: Customization
3850 5.4 Language Support
3851 ====================
3853 TeX and Emacs are usable for European (Latin, Cyrillic, Greek) based
3854 languages. Some LaTeX and EmacsLisp packages are available for easy
3855 typesetting and editing documents in European languages.
3857 For CJK (Chinese, Japanese, and Korean) languages, Emacs or XEmacs
3858 with MULE (MULtilingual Enhancement to GNU Emacs) support is required.
3859 MULE is part of Emacs by default since Emacs 20. XEmacs has to be
3860 configured with the `--with-mule' option. Special versions of TeX are
3861 needed for CJK languages: CTeX and ChinaTeX for Chinese, ASCII pTeX and
3862 NTT jTeX for Japanese, HLaTeX and kTeX for Korean. The CJK-LaTeX
3863 package is required for supporting multiple CJK scripts within a single
3866 Note that Unicode is not fully supported in Emacs 21 and XEmacs 21.
3867 CJK characters are not usable. Please use the MULE-UCS EmacsLisp
3868 package or Emacs 22 (not released yet) if you need CJK.
3872 * European:: Using AUCTeX with European Languages
3873 * Japanese:: Using AUCTeX with Japanese
3876 File: auctex.info, Node: European, Next: Japanese, Up: Internationalization
3878 5.4.1 Using AUCTeX with European Languages
3879 ------------------------------------------
3881 5.4.1.1 Typing and Displaying Non-ASCII Characters
3882 ..................................................
3884 First you will need a way to write non-ASCII characters. You can either
3885 use macros, or teach TeX about the ISO character sets. I prefer the
3886 latter, it has the advantage that the usual standard emacs word
3887 movement and case change commands will work.
3889 With LaTeX2e, just add `\usepackage[latin1]{inputenc}'. Other
3890 languages than Western European ones will probably have other encoding
3893 To be able to display non-ASCII characters you will need an
3894 appropriate font and a version of GNU Emacs capable of displaying 8-bit
3895 characters (e.g. Emacs 21). The manner in which this is supported
3896 differs between Emacsen, so you need to take a look at your respective
3899 A compromise is to use an European character set when editing the
3900 file, and convert to TeX macros when reading and writing the files.
3903 Much like `iso-tex.el' but is bundled with Emacs 19.23 and later.
3906 Similar package bundled with new versions of XEmacs.
3909 a much more complete package for both Emacs and XEmacs that can
3910 also handle a lot of mathematical characters and input methods.
3912 5.4.1.2 Style Files for Different Languages
3913 ...........................................
3915 AUCTeX supports style files for several languages. Each style file may
3916 modify AUCTeX to better support the language, and will run a language
3917 specific hook that will allow you to for example change ispell
3918 dictionary, or run code to change the keyboard remapping. The
3919 following will for example choose a Danish dictionary for documents
3920 including `\usepackage[danish]{babel}'. This requires parsing to be
3921 enabled, *note Parsing Files::.
3923 (add-hook 'TeX-language-dk-hook
3924 (lambda () (ispell-change-dictionary "danish")))
3926 The following style files are recognized:
3929 Runs style hook `TeX-language-bg-hook'. Gives `"' word syntax,
3930 makes the <"> key insert a literal `"'. Typing <"> twice will
3931 insert insert `"`' or `"'' depending on context. Typing <-> twice
3932 will insert `"=', three times `--'.
3935 Runs style hook `TeX-language-cz-hook'. Pressing <"> will insert
3936 `\uv{' and `}' depending on context.
3939 Runs style hook `TeX-language-dk-hook'. Pressing <"> will insert
3940 `"`' and `"'' depending on context. Typing <-> twice will insert
3941 `"=', i.e. a hyphen string allowing hyphenation in the composing
3945 Runs style hook `TeX-language-nl-hook'.
3949 Runs style hook `TeX-language-de-hook'. Gives `"' word syntax,
3950 makes the <"> key insert a literal `"'. Pressing the key twice
3951 will give you opening or closing German quotes (`"`' or `"'').
3952 Typing <-> twice will insert `"=', three times `--'.
3956 Runs style hook `TeX-language-fr-hook'. Pressing <"> will insert
3957 `\\og' and `\\fg' depending on context. Note that the language
3958 name for customizing `TeX-quote-language-alist' is `french'.
3961 Runs style hook `TeX-language-is-hook'. Gives `"' word syntax,
3962 makes the <"> key insert a literal `"'. Typing <"> twice will
3963 insert insert `"`' or `"'' depending on context. Typing <-> twice
3964 will insert `"=', three times `--'.
3967 Runs style hook `TeX-language-it-hook'. Pressing <"> will insert
3968 `"<' and `">' depending on context.
3971 Runs style hook `TeX-language-pl-hook'. Gives `"' word syntax and
3972 makes the <"> key insert a literal `"'. Pressing <"> twice will
3973 insert `"`' or `"'' depending on context.
3976 Runs style hook `TeX-language-pl-hook'. Makes the <"> key insert
3977 a literal `"'. Pressing <"> twice will insert `,,' or `'''
3978 depending on context.
3981 Runs style hook `TeX-language-sk-hook'. Pressing <"> will insert
3982 `\uv{' and `}' depending on context.
3985 Runs style hook `TeX-language-sv-hook'. Pressing <"> will insert
3986 `'''. Typing <-> twice will insert `"=', three times `--'.
3988 Replacement of language-specific hyphen strings like `"=' with
3989 dashes does not require to type <-> three times in a row. You can put
3990 point after the hypen string anytime and trigger the replacement by
3993 In case you are not satisfied with the suggested behavior of quote
3994 and hyphen insertion you can change it by customizing the variables
3995 `TeX-quote-language-alist' and `LaTeX-babel-hyphen-language-alist'
3998 -- User Option: TeX-quote-language-alist
3999 Used for overriding the default language-specific quote insertion
4000 behavior. This is an alist where each element is a list
4001 consisting of four items. The first item is the name of the
4002 language in concern as a string. See the list of supported
4003 languages above. The second item is the opening quotation mark.
4004 The third item is the closing quotation mark. Opening and closing
4005 quotation marks can be specified directly as strings or as
4006 functions returning a string. The fourth item is a boolean
4007 controlling quote insertion. It should be non-nil if if the
4008 special quotes should only be used after inserting a literal `"'
4009 character first, i.e. on second key press.
4011 -- User Option: LaTeX-babel-hyphen-language-alist
4012 Used for overriding the behavior of hyphen insertion for specific
4013 languages. Every element in this alist is a list of three items.
4014 The first item should specify the affected language as a string.
4015 The second item denotes the hyphen string to be used as a string.
4016 The third item, a boolean, controls the behavior of hyphen
4017 insertion and should be non-nil if the special hyphen should be
4018 inserted after inserting a literal `-' character, i.e. on second
4021 The defaults of hyphen insertion are defined by the variables
4022 `LaTeX-babel-hyphen' and `LaTeX-babel-hyphen-after-hyphen' respectively.
4024 -- User Option: LaTeX-babel-hyphen
4025 String to be used when typing <->. This usually is a hyphen
4026 alternative or hyphenation aid provided by `babel' and the related
4027 language style files, like `"=', `"~' or `"-'.
4029 Set it to an empty string or nil in order to disable
4030 language-specific hyphen insertion.
4032 -- User Option: LaTeX-babel-hyphen-after-hyphen
4033 Control insertion of hyphen strings. If non-nil insert normal
4034 hyphen on first key press and swap it with the language-specific
4035 hyphen string specified in the variable `LaTeX-babel-hyphen' on
4036 second key press. If nil do it the other way round.
4039 File: auctex.info, Node: Japanese, Prev: European, Up: Internationalization
4041 5.4.2 Using AUCTeX with Japanese TeX
4042 ------------------------------------
4044 To write Japanese text with AUCTeX, you need to have versions of TeX
4045 and Emacs that support Japanese. There exist at least two variants of
4046 TeX for Japanese text (NTT jTeX and ASCII pTeX). AUCTeX can be used
4047 with MULE (MULtilingual Enhancement to GNU Emacs) supported Emacsen.
4049 To use the Japanese TeX variants, simply activate
4050 `japanese-plain-tex-mode' or `japanese-latex-mode' and everything
4051 should work. If not, send mail to Masayuki Ataka
4052 `<ataka@milk.freemail.ne.jp>', who kindly donated the code for
4053 supporting Japanese in AUCTeX. None of the primary AUCTeX maintainers
4054 understand Japanese, so they cannot help you.
4056 If you usually use AUCTeX in Japanese, setting the following
4057 variables is useful.
4059 -- User Option: TeX-default-mode
4060 Mode to enter for a new file when it cannott be determined whether
4061 the file is plain TeX or LaTeX or what.
4063 If you want to enter Japanese LaTeX mode whenever this may happen,
4064 set the variable like this:
4065 (setq TeX-default-mode 'japanese-latex-mode)
4067 -- User Option: japanese-TeX-command-default
4068 The default command for `TeX-command' in Japanese TeX mode.
4070 The default value is `"pTeX"'.
4072 -- User Option: japanese-LaTeX-command-default
4073 The default command for `TeX-command' in Japanese LaTeX mode.
4075 The default value is `"LaTeX"'.
4077 -- User Option: japanese-LaTeX-default-style
4078 The default style/class when creating a new Japanese LaTeX
4081 The default value is `"jarticle"'.
4083 See `tex-jp.el' for more information.
4086 File: auctex.info, Node: Automatic, Next: Style Files, Prev: Internationalization, Up: Customization
4088 5.5 Automatic Customization
4089 ===========================
4091 Since AUCTeX is so highly customizable, it makes sense that it is able
4092 to customize itself. The automatic customization consists of scanning
4093 TeX files and extracting symbols, environments, and things like that.
4095 The automatic customization is done on three different levels. The
4096 global level is the level shared by all users at your site, and consists
4097 of scanning the standard TeX style files, and any extra styles added
4098 locally for all users on the site. The private level deals with those
4099 style files you have written for your own use, and use in different
4100 documents. You may have a `~/lib/TeX/' directory where you store
4101 useful style files for your own use. The local level is for a specific
4102 directory, and deals with writing customization for the files for your
4103 normal TeX documents.
4105 If compared with the environment variable `TEXINPUTS', the global
4106 level corresponds to the directories built into TeX. The private level
4107 corresponds to the directories you add yourself, except for `.', which
4112 * Automatic Global:: Automatic Customization for the Site
4113 * Automatic Private:: Automatic Customization for a User
4114 * Automatic Local:: Automatic Customization for a Directory
4116 By default AUCTeX will search for customization files in all the
4117 global, private, and local style directories, but you can also set the
4118 path directly. This is useful if you for example want to add another
4119 person's style hooks to your path. Please note that all matching files
4120 found in `TeX-style-path' are loaded, and all hooks defined in the
4121 files will be executed.
4123 -- User Option: TeX-style-path
4124 List of directories to search for AUCTeX style files. Each must
4127 By default, when AUCTeX searches a directory for files, it will
4128 recursively search through subdirectories.
4130 -- User Option: TeX-file-recurse
4131 Whether to search TeX directories recursively: nil means do not
4132 recurse, a positive integer means go that far deep in the directory
4133 hierarchy, t means recurse indefinitely.
4135 By default, AUCTeX will ignore files name `.', `..', `SCCS', `RCS',
4138 -- User Option: TeX-ignore-file
4139 Regular expression matching file names to ignore.
4141 These files or directories will not be considered when searching
4142 for TeX files in a directory.
4145 File: auctex.info, Node: Automatic Global, Next: Automatic Private, Up: Automatic
4147 5.5.1 Automatic Customization for the Site
4148 ------------------------------------------
4150 Assuming that the automatic customization at the global level was done
4151 when AUCTeX was installed, your choice is now: will you use it? If you
4152 use it, you will benefit by having access to all the symbols and
4153 environments available for completion purposes. The drawback is slower
4154 load time when you edit a new file and perhaps too many confusing
4155 symbols when you try to do a completion.
4157 You can disable the automatic generated global style hooks by setting
4158 the variable `TeX-auto-global' to nil.
4160 -- User Option: TeX-macro-global
4161 Directories containing the site's TeX style files.
4163 -- User Option: TeX-style-global
4164 Directory containing hand generated TeX information. Must end
4167 These correspond to TeX macros shared by all users of a site.
4169 -- User Option: TeX-auto-global
4170 Directory containing automatically generated information.
4172 For storing automatic extracted information about the TeX macros
4173 shared by all users of a site.
4176 File: auctex.info, Node: Automatic Private, Next: Automatic Local, Prev: Automatic Global, Up: Automatic
4178 5.5.2 Automatic Customization for a User
4179 ----------------------------------------
4181 You should specify where you store your private TeX macros, so AUCTeX
4182 can extract their information. The extracted information will go to
4183 the directories listed in `TeX-auto-private'
4185 Use `M-x TeX-auto-generate <RET>' to extract the information.
4187 -- User Option: TeX-macro-private
4188 Directories where you store your personal TeX macros. The value
4189 defaults to the directories listed in the `TEXINPUTS' and
4190 `BIBINPUTS' environment variables or to the respective directories
4191 in `$TEXMFHOME' if no results can be obtained from the environment
4194 -- User Option: TeX-auto-private
4195 List of directories containing automatically generated AUCTeX style
4196 files. These correspond to the personal TeX macros.
4198 -- Command: TeX-auto-generate TEX AUTO
4199 (`M-x TeX-auto-generate <RET>') Generate style hook for TEX and
4200 store it in AUTO. If TEX is a directory, generate style hooks for
4201 all files in the directory.
4203 -- User Option: TeX-style-private
4204 List of directories containing hand generated AUCTeX style files.
4205 These correspond to the personal TeX macros.
4208 File: auctex.info, Node: Automatic Local, Prev: Automatic Private, Up: Automatic
4210 5.5.3 Automatic Customization for a Directory
4211 ---------------------------------------------
4213 AUCTeX can update the style information about a file each time you save
4214 it, and it will do this if the directory `TeX-auto-local' exist.
4215 `TeX-auto-local' is by default set to `"auto"', so simply creating an
4216 `auto' directory will enable automatic saving of style information.
4218 The advantage of doing this is that macros, labels, etc. defined in
4219 any file in a multifile document will be known in all the files in the
4220 document. The disadvantage is that saving will be slower. To disable,
4221 set `TeX-auto-local' to nil.
4223 -- User Option: TeX-style-local
4224 Directory containing hand generated TeX information. Must end
4227 These correspond to TeX macros found in the current directory.
4229 -- User Option: TeX-auto-local
4230 Directory containing automatically generated TeX information.
4231 Must end with a slash.
4233 These correspond to TeX macros found in the current directory.
4236 File: auctex.info, Node: Style Files, Prev: Automatic, Up: Customization
4238 5.6 Writing Your Own Style Support
4239 ==================================
4241 *Note Automatic::, for a discussion about automatically generated
4242 global, private, and local style files. The hand generated style files
4243 are equivalent, except that they by default are found in `style'
4244 directories instead of `auto' directories.
4248 * Simple Style:: A Simple Style File
4249 * Adding Macros:: Adding Support for Macros
4250 * Adding Environments:: Adding Support for Environments
4251 * Adding Other:: Adding Other Information
4252 * Hacking the Parser:: Automatic Extraction of New Things
4254 If you write some useful support for a public TeX style file, please
4258 File: auctex.info, Node: Simple Style, Next: Adding Macros, Up: Style Files
4260 5.6.1 A Simple Style File
4261 -------------------------
4263 Here is a simple example of a style file.
4265 ;;; book.el - Special code for book style.
4270 (LaTeX-largest-level-set "chapter")))
4272 This file specifies that the largest kind of section in a LaTeX
4273 document using the book document style is chapter. The interesting
4274 thing to notice is that the style file defines an (anonymous) function,
4275 and adds it to the list of loaded style hooks by calling
4276 `TeX-add-style-hook'.
4278 The first time the user indirectly tries to access some style
4279 specific information, such as the largest sectioning command available,
4280 the style hooks for all files directly or indirectly read by the
4281 current document is executed. The actual files will only be evaluated
4282 once, but the hooks will be called for each buffer using the style file.
4284 -- Function: TeX-add-style-hook STYLE HOOK
4285 Add HOOK to the list of functions to run when we use the TeX file
4289 File: auctex.info, Node: Adding Macros, Next: Adding Environments, Prev: Simple Style, Up: Style Files
4291 5.6.2 Adding Support for Macros
4292 -------------------------------
4294 The most common thing to define in a style hook is new symbols (TeX
4295 macros). Most likely along with a description of the arguments to the
4296 function, since the symbol itself can be defined automatically.
4298 Here are a few examples from `latex.el'.
4304 '("arabic" TeX-arg-counter)
4305 '("label" TeX-arg-define-label)
4306 '("ref" TeX-arg-label)
4307 '("newcommand" TeX-arg-define-macro [ "Number of arguments" ] t)
4308 '("newtheorem" TeX-arg-define-environment
4309 [ TeX-arg-environment "Numbered like" ]
4310 t [ TeX-arg-counter "Within counter" ]))))
4312 -- Function: TeX-add-symbols SYMBOL ...
4313 Add each SYMBOL to the list of known symbols.
4315 Each argument to `TeX-add-symbols' is a list describing one symbol.
4316 The head of the list is the name of the symbol, the remaining elements
4317 describe each argument.
4319 If there are no additional elements, the symbol will be inserted with
4320 point inside braces. Otherwise, each argument of this function should
4321 match an argument of the TeX macro. What is done depends on the
4324 If a macro is defined multiple times, AUCTeX will chose the one with
4325 the longest definition (i.e. the one with the most arguments).
4328 '("tref" 1) ; one argument
4330 '("tref" TeX-arg-label ignore) ; two arguments
4332 `ignore' is a function that does not do anything, so when you insert
4333 a `tref' you will be prompted for a label and no more.
4335 You can use the following types of specifiers for arguments:
4338 Use the string as a prompt to prompt for the argument.
4341 Insert that many braces, leave point inside the first.
4344 Insert empty braces.
4347 Insert empty braces, leave point between the braces.
4350 Call the symbol as a function. You can define your own hook, or
4351 use one of the predefined argument hooks.
4354 If the car is a string, insert it as a prompt and the next element
4355 as initial input. Otherwise, call the car of the list with the
4356 remaining elements as arguments.
4359 Optional argument. If it has more than one element, parse it as a
4360 list, otherwise parse the only element as above. Use square
4361 brackets instead of curly braces, and is not inserted on empty user
4364 A lot of argument hooks have already been defined. The first
4365 argument to all hooks is a flag indicating if it is an optional
4366 argument. It is up to the hook to determine what to do with the
4367 remaining arguments, if any. Typically the next argument is used to
4368 overwrite the default prompt.
4370 `TeX-arg-conditional'
4371 Implements if EXPR THEN ELSE. If EXPR evaluates to true, parse
4372 THEN as an argument list, else parse ELSE as an argument list.
4375 Insert its arguments into the buffer. Used for specifying extra
4379 Parse its arguments but use no braces when they are inserted.
4382 Evaluate arguments and insert the result in the buffer.
4385 Prompt for a label completing with known labels.
4388 Prompt for a TeX macro with completion.
4390 `TeX-arg-environment'
4391 Prompt for a LaTeX environment with completion.
4394 Prompt for a BibTeX citation.
4397 Prompt for a LaTeX counter.
4400 Prompt for a LaTeX savebox.
4403 Prompt for a filename in the current directory, and use it without
4406 `TeX-arg-input-file'
4407 Prompt for the name of an input file in TeX's search path, and use
4408 it without the extension. Run the style hooks for the file.
4410 `TeX-arg-define-label'
4411 Prompt for a label completing with known labels. Add label to
4412 list of defined labels.
4414 `TeX-arg-define-macro'
4415 Prompt for a TeX macro with completion. Add macro to list of
4418 `TeX-arg-define-environment'
4419 Prompt for a LaTeX environment with completion. Add environment to
4420 list of defined environments.
4422 `TeX-arg-define-cite'
4423 Prompt for a BibTeX citation.
4425 `TeX-arg-define-counter'
4426 Prompt for a LaTeX counter.
4428 `TeX-arg-define-savebox'
4429 Prompt for a LaTeX savebox.
4432 Prompt for a LaTeX side or corner position with completion.
4435 Prompt for a LaTeX side with completion.
4438 Prompt for a LaTeX side with completion.
4441 Prompt for a LaTeX pagestyle with completion.
4444 Prompt for delimiter and text.
4447 Insert a pair of numbers, use arguments for prompt. The numbers are
4448 surrounded by parentheses and separated with a comma.
4451 Insert width and height as a pair. No arguments.
4453 `TeX-arg-coordinate'
4454 Insert x and y coordinates as a pair. No arguments.
4456 If you add new hooks, you can assume that point is placed directly
4457 after the previous argument, or after the macro name if this is the
4458 first argument. Please leave point located after the argument you are
4459 inserting. If you want point to be located somewhere else after all
4460 hooks have been processed, set the value of `exit-mark'. It will point
4461 nowhere, until the argument hook sets it.
4464 File: auctex.info, Node: Adding Environments, Next: Adding Other, Prev: Adding Macros, Up: Style Files
4466 5.6.3 Adding Support for Environments
4467 -------------------------------------
4469 Adding support for environments is very much like adding support for
4470 TeX macros, except that each environment normally only takes one
4471 argument, an environment hook. The example is again a short version of
4477 (LaTeX-add-environments
4478 '("document" LaTeX-env-document)
4479 '("enumerate" LaTeX-env-item)
4480 '("itemize" LaTeX-env-item)
4481 '("list" LaTeX-env-list))))
4483 It is completely up to the environment hook to insert the
4484 environment, but the function `LaTeX-insert-environment' may be of some
4485 help. The hook will be called with the name of the environment as its
4486 first argument, and extra arguments can be provided by adding them to a
4487 list after the hook.
4489 For simple environments with arguments, for example defined with
4490 `\newenvironment', you can make AUCTeX prompt for the arguments by
4491 giving the prompt strings in the call to `LaTeX-add-environments'. The
4492 fact that an argument is optional can be indicated by wrapping the
4493 prompt string in a vector.
4495 For example, if you have defined a `loop' environment with the three
4496 arguments FROM, TO, and STEP, you can add support for them in a style
4501 \newenvironment{loop}[3]{...}{...}
4508 (LaTeX-add-environments
4509 '("loop" "From" "To" "Step"))))
4511 If an environment is defined multiple times, AUCTeX will choose the
4512 one with the longest definition. Thus, if you have an enumerate style
4513 file, and want it to replace the standard LaTeX enumerate hook above,
4514 you could define an `enumerate.el' file as follows, and place it in the
4515 appropriate style directory.
4520 (LaTeX-add-environments
4521 '("enumerate" LaTeX-env-enumerate foo))))
4523 (defun LaTeX-env-enumerate (environment &optional ignore) ...)
4525 The symbol `foo' will be passed to `LaTeX-env-enumerate' as the
4526 second argument, but since we only added it to overwrite the definition
4527 in `latex.el' it is just ignored.
4529 -- Function: LaTeX-add-environments ENV ...
4530 Add each ENV to list of loaded environments.
4532 -- Function: LaTeX-insert-environment ENV [ EXTRA ]
4533 Insert environment of type ENV, with optional argument EXTRA.
4535 Following is a list of available hooks for `LaTeX-add-environments':
4538 Insert the given environment and the first item.
4541 Insert the given figure-like environment with a caption and a
4545 Insert the given array-like environment with position and column
4549 Insert the given environment with a label.
4552 Insert the given list-like environment, a specifier for the label
4555 `LaTeX-env-minipage'
4556 Insert the given minipage-like environment with position and width
4559 `LaTeX-env-tabular*'
4560 Insert the given tabular*-like environment with width, position and
4561 column specifications.
4564 Insert the given environment with width and height specifications.
4567 Insert the given environment with a label for a bibitem.
4569 `LaTeX-env-contents'
4570 Insert the given environment with a filename as its argument.
4573 Insert the given environment with arguments. You can use this as
4574 a hook in case you want to specify multiple complex arguments just
4575 like in elements of `TeX-add-symbols'. This is most useful if the
4576 specification of arguments to be prompted for with strings and
4577 strings wrapped in a vector as described above is too limited.
4579 Here is an example from `listings.el' which calls a function with
4580 one argument in order to prompt for a key=value list to be
4581 inserted as an optional argument of the `lstlisting' environment:
4583 (LaTeX-add-environments
4584 `("lstlisting" LaTeX-env-args
4585 [TeX-arg-key-val ,LaTeX-listings-key-val-options]))
4588 File: auctex.info, Node: Adding Other, Next: Hacking the Parser, Prev: Adding Environments, Up: Style Files
4590 5.6.4 Adding Other Information
4591 ------------------------------
4593 You can also specify bibliographical databases and labels in the style
4594 file. This is probably of little use, since this information will
4595 usually be automatically generated from the TeX file anyway.
4597 -- Function: LaTeX-add-bibliographies BIBLIOGRAPHY ...
4598 Add each BIBLIOGRAPHY to list of loaded bibliographies.
4600 -- Function: LaTeX-add-labels LABEL ...
4601 Add each LABEL to the list of known labels.
4604 File: auctex.info, Node: Hacking the Parser, Prev: Adding Other, Up: Style Files
4606 5.6.5 Automatic Extraction of New Things
4607 ----------------------------------------
4609 The automatic TeX information extractor works by searching for regular
4610 expressions in the TeX files, and storing the matched information. You
4611 can add support for new constructs to the parser, something that is
4612 needed when you add new commands to define symbols.
4614 For example, in the file `macro.tex' I define the following macro.
4616 \newcommand{\newmacro}[5]{%
4617 \def#1{#3\index{#4@#5~cite{#4}}\nocite{#4}}%
4618 \def#2{#5\index{#4@#5~cite{#4}}\nocite{#4}}%
4621 AUCTeX will automatically figure out that `newmacro' is a macro that
4622 takes five arguments. However, it is not smart enough to automatically
4623 see that each time we use the macro, two new macros are defined. We
4624 can specify this information in a style hook file.
4626 ;;; macro.el --- Special code for my own macro file.
4630 (defvar TeX-newmacro-regexp
4631 '("\\\\newmacro{\\\\\\([a-zA-Z]+\\)}{\\\\\\([a-zA-Z]+\\)}"
4632 (1 2) TeX-auto-multi)
4633 "Matches \newmacro definitions.")
4635 (defvar TeX-auto-multi nil
4636 "Temporary for parsing \\newmacro definitions.")
4638 (defun TeX-macro-cleanup ()
4639 "Move symbols from `TeX-auto-multi' to `TeX-auto-symbol'."
4640 (mapcar (lambda (list)
4641 (mapcar (lambda (symbol)
4642 (setq TeX-auto-symbol
4643 (cons symbol TeX-auto-symbol)))
4647 (defun TeX-macro-prepare ()
4648 "Clear `Tex-auto-multi' before use."
4649 (setq TeX-auto-multi nil))
4651 (add-hook 'TeX-auto-prepare-hook 'TeX-macro-prepare)
4652 (add-hook 'TeX-auto-cleanup-hook 'TeX-macro-cleanup)
4657 (TeX-auto-add-regexp TeX-newmacro-regexp)
4658 (TeX-add-symbols '("newmacro"
4660 (TeX-arg-macro "Capitalized macro: \\")
4665 ;;; macro.el ends here
4667 When this file is first loaded, it adds a new entry to
4668 `TeX-newmacro-regexp', and defines a function to be called before the
4669 parsing starts, and one to be called after the parsing is done. It
4670 also declares a variable to contain the data collected during parsing.
4671 Finally, it adds a style hook which describes the `newmacro' macro, as
4672 we have seen it before.
4674 So the general strategy is: Add a new entry to `TeX-newmacro-regexp'.
4675 Declare a variable to contain intermediate data during parsing. Add
4676 hook to be called before and after parsing. In this case, the hook
4677 before parsing just initializes the variable, and the hook after parsing
4678 collects the data from the variable, and adds them to the list of
4681 -- Variable: TeX-auto-regexp-list
4682 List of regular expressions matching TeX macro definitions.
4684 The list has the following format ((REGEXP MATCH TABLE) ...), that
4685 is, each entry is a list with three elements.
4687 REGEXP. Regular expression matching the macro we want to parse.
4689 MATCH. A number or list of numbers, each representing one
4690 parenthesized subexpression matched by REGEXP.
4692 TABLE. The symbol table to store the data. This can be a
4693 function, in which case the function is called with the argument
4694 MATCH. Use `TeX-match-buffer' to get match data. If it is not a
4695 function, it is presumed to be the name of a variable containing a
4696 list of match data. The matched data (a string if MATCH is a
4697 number, a list of strings if MATCH is a list of numbers) is put in
4700 -- Variable: TeX-auto-prepare-hook nil
4701 List of functions to be called before parsing a TeX file.
4703 -- Variable: TeX-auto-cleanup-hook nil
4704 List of functions to be called after parsing a TeX file.
4707 File: auctex.info, Node: Appendices, Next: Indices, Prev: Customization, Up: Top
4709 Appendix A Copying, Changes, Development, FAQ
4710 *********************************************
4714 * Copying this Manual::
4720 File: auctex.info, Node: Copying this Manual, Next: Changes, Up: Appendices
4722 A.1 Copying this Manual
4723 =======================
4725 The copyright notice for this manual is:
4727 This manual is for AUCTeX (version 11.86 from 2010-02-21), a
4728 sophisticated TeX environment for Emacs.
4730 Copyright (C) 1992, 1993, 1994, 1995, 2001, 2002, 2004, 2005, 2006,
4731 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
4733 Permission is granted to copy, distribute and/or modify this
4734 document under the terms of the GNU Free Documentation License,
4735 Version 1.3 or any later version published by the Free Software
4736 Foundation; with no Invariant Sections, no Front-Cover Texts and
4737 no Back-Cover Texts. A copy of the license is included in the
4738 section entitled "GNU Free Documentation License."
4740 The full license text can be read here:
4744 * GNU Free Documentation License:: License for copying this manual.
4747 File: auctex.info, Node: GNU Free Documentation License, Up: Copying this Manual
4749 A.1.1 GNU Free Documentation License
4750 ------------------------------------
4752 Version 1.3, 3 November 2008
4754 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software
4755 Foundation, Inc. `http://fsf.org/'
4757 Everyone is permitted to copy and distribute verbatim copies
4758 of this license document, but changing it is not allowed.
4762 The purpose of this License is to make a manual, textbook, or other
4763 functional and useful document "free" in the sense of freedom: to
4764 assure everyone the effective freedom to copy and redistribute it,
4765 with or without modifying it, either commercially or
4766 noncommercially. Secondarily, this License preserves for the
4767 author and publisher a way to get credit for their work, while not
4768 being considered responsible for modifications made by others.
4770 This License is a kind of "copyleft", which means that derivative
4771 works of the document must themselves be free in the same sense.
4772 It complements the GNU General Public License, which is a copyleft
4773 license designed for free software.
4775 We have designed this License in order to use it for manuals for
4776 free software, because free software needs free documentation: a
4777 free program should come with manuals providing the same freedoms
4778 that the software does. But this License is not limited to
4779 software manuals; it can be used for any textual work, regardless
4780 of subject matter or whether it is published as a printed book.
4781 We recommend this License principally for works whose purpose is
4782 instruction or reference.
4784 1. APPLICABILITY AND DEFINITIONS
4786 This License applies to any manual or other work, in any medium,
4787 that contains a notice placed by the copyright holder saying it
4788 can be distributed under the terms of this License. Such a notice
4789 grants a world-wide, royalty-free license, unlimited in duration,
4790 to use that work under the conditions stated herein. The
4791 "Document", below, refers to any such manual or work. Any member
4792 of the public is a licensee, and is addressed as "you". You
4793 accept the license if you copy, modify or distribute the work in a
4794 way requiring permission under copyright law.
4796 A "Modified Version" of the Document means any work containing the
4797 Document or a portion of it, either copied verbatim, or with
4798 modifications and/or translated into another language.
4800 A "Secondary Section" is a named appendix or a front-matter section
4801 of the Document that deals exclusively with the relationship of the
4802 publishers or authors of the Document to the Document's overall
4803 subject (or to related matters) and contains nothing that could
4804 fall directly within that overall subject. (Thus, if the Document
4805 is in part a textbook of mathematics, a Secondary Section may not
4806 explain any mathematics.) The relationship could be a matter of
4807 historical connection with the subject or with related matters, or
4808 of legal, commercial, philosophical, ethical or political position
4811 The "Invariant Sections" are certain Secondary Sections whose
4812 titles are designated, as being those of Invariant Sections, in
4813 the notice that says that the Document is released under this
4814 License. If a section does not fit the above definition of
4815 Secondary then it is not allowed to be designated as Invariant.
4816 The Document may contain zero Invariant Sections. If the Document
4817 does not identify any Invariant Sections then there are none.
4819 The "Cover Texts" are certain short passages of text that are
4820 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
4821 that says that the Document is released under this License. A
4822 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
4823 be at most 25 words.
4825 A "Transparent" copy of the Document means a machine-readable copy,
4826 represented in a format whose specification is available to the
4827 general public, that is suitable for revising the document
4828 straightforwardly with generic text editors or (for images
4829 composed of pixels) generic paint programs or (for drawings) some
4830 widely available drawing editor, and that is suitable for input to
4831 text formatters or for automatic translation to a variety of
4832 formats suitable for input to text formatters. A copy made in an
4833 otherwise Transparent file format whose markup, or absence of
4834 markup, has been arranged to thwart or discourage subsequent
4835 modification by readers is not Transparent. An image format is
4836 not Transparent if used for any substantial amount of text. A
4837 copy that is not "Transparent" is called "Opaque".
4839 Examples of suitable formats for Transparent copies include plain
4840 ASCII without markup, Texinfo input format, LaTeX input format,
4841 SGML or XML using a publicly available DTD, and
4842 standard-conforming simple HTML, PostScript or PDF designed for
4843 human modification. Examples of transparent image formats include
4844 PNG, XCF and JPG. Opaque formats include proprietary formats that
4845 can be read and edited only by proprietary word processors, SGML or
4846 XML for which the DTD and/or processing tools are not generally
4847 available, and the machine-generated HTML, PostScript or PDF
4848 produced by some word processors for output purposes only.
4850 The "Title Page" means, for a printed book, the title page itself,
4851 plus such following pages as are needed to hold, legibly, the
4852 material this License requires to appear in the title page. For
4853 works in formats which do not have any title page as such, "Title
4854 Page" means the text near the most prominent appearance of the
4855 work's title, preceding the beginning of the body of the text.
4857 The "publisher" means any person or entity that distributes copies
4858 of the Document to the public.
4860 A section "Entitled XYZ" means a named subunit of the Document
4861 whose title either is precisely XYZ or contains XYZ in parentheses
4862 following text that translates XYZ in another language. (Here XYZ
4863 stands for a specific section name mentioned below, such as
4864 "Acknowledgements", "Dedications", "Endorsements", or "History".)
4865 To "Preserve the Title" of such a section when you modify the
4866 Document means that it remains a section "Entitled XYZ" according
4869 The Document may include Warranty Disclaimers next to the notice
4870 which states that this License applies to the Document. These
4871 Warranty Disclaimers are considered to be included by reference in
4872 this License, but only as regards disclaiming warranties: any other
4873 implication that these Warranty Disclaimers may have is void and
4874 has no effect on the meaning of this License.
4878 You may copy and distribute the Document in any medium, either
4879 commercially or noncommercially, provided that this License, the
4880 copyright notices, and the license notice saying this License
4881 applies to the Document are reproduced in all copies, and that you
4882 add no other conditions whatsoever to those of this License. You
4883 may not use technical measures to obstruct or control the reading
4884 or further copying of the copies you make or distribute. However,
4885 you may accept compensation in exchange for copies. If you
4886 distribute a large enough number of copies you must also follow
4887 the conditions in section 3.
4889 You may also lend copies, under the same conditions stated above,
4890 and you may publicly display copies.
4892 3. COPYING IN QUANTITY
4894 If you publish printed copies (or copies in media that commonly
4895 have printed covers) of the Document, numbering more than 100, and
4896 the Document's license notice requires Cover Texts, you must
4897 enclose the copies in covers that carry, clearly and legibly, all
4898 these Cover Texts: Front-Cover Texts on the front cover, and
4899 Back-Cover Texts on the back cover. Both covers must also clearly
4900 and legibly identify you as the publisher of these copies. The
4901 front cover must present the full title with all words of the
4902 title equally prominent and visible. You may add other material
4903 on the covers in addition. Copying with changes limited to the
4904 covers, as long as they preserve the title of the Document and
4905 satisfy these conditions, can be treated as verbatim copying in
4908 If the required texts for either cover are too voluminous to fit
4909 legibly, you should put the first ones listed (as many as fit
4910 reasonably) on the actual cover, and continue the rest onto
4913 If you publish or distribute Opaque copies of the Document
4914 numbering more than 100, you must either include a
4915 machine-readable Transparent copy along with each Opaque copy, or
4916 state in or with each Opaque copy a computer-network location from
4917 which the general network-using public has access to download
4918 using public-standard network protocols a complete Transparent
4919 copy of the Document, free of added material. If you use the
4920 latter option, you must take reasonably prudent steps, when you
4921 begin distribution of Opaque copies in quantity, to ensure that
4922 this Transparent copy will remain thus accessible at the stated
4923 location until at least one year after the last time you
4924 distribute an Opaque copy (directly or through your agents or
4925 retailers) of that edition to the public.
4927 It is requested, but not required, that you contact the authors of
4928 the Document well before redistributing any large number of
4929 copies, to give them a chance to provide you with an updated
4930 version of the Document.
4934 You may copy and distribute a Modified Version of the Document
4935 under the conditions of sections 2 and 3 above, provided that you
4936 release the Modified Version under precisely this License, with
4937 the Modified Version filling the role of the Document, thus
4938 licensing distribution and modification of the Modified Version to
4939 whoever possesses a copy of it. In addition, you must do these
4940 things in the Modified Version:
4942 A. Use in the Title Page (and on the covers, if any) a title
4943 distinct from that of the Document, and from those of
4944 previous versions (which should, if there were any, be listed
4945 in the History section of the Document). You may use the
4946 same title as a previous version if the original publisher of
4947 that version gives permission.
4949 B. List on the Title Page, as authors, one or more persons or
4950 entities responsible for authorship of the modifications in
4951 the Modified Version, together with at least five of the
4952 principal authors of the Document (all of its principal
4953 authors, if it has fewer than five), unless they release you
4954 from this requirement.
4956 C. State on the Title page the name of the publisher of the
4957 Modified Version, as the publisher.
4959 D. Preserve all the copyright notices of the Document.
4961 E. Add an appropriate copyright notice for your modifications
4962 adjacent to the other copyright notices.
4964 F. Include, immediately after the copyright notices, a license
4965 notice giving the public permission to use the Modified
4966 Version under the terms of this License, in the form shown in
4969 G. Preserve in that license notice the full lists of Invariant
4970 Sections and required Cover Texts given in the Document's
4973 H. Include an unaltered copy of this License.
4975 I. Preserve the section Entitled "History", Preserve its Title,
4976 and add to it an item stating at least the title, year, new
4977 authors, and publisher of the Modified Version as given on
4978 the Title Page. If there is no section Entitled "History" in
4979 the Document, create one stating the title, year, authors,
4980 and publisher of the Document as given on its Title Page,
4981 then add an item describing the Modified Version as stated in
4982 the previous sentence.
4984 J. Preserve the network location, if any, given in the Document
4985 for public access to a Transparent copy of the Document, and
4986 likewise the network locations given in the Document for
4987 previous versions it was based on. These may be placed in
4988 the "History" section. You may omit a network location for a
4989 work that was published at least four years before the
4990 Document itself, or if the original publisher of the version
4991 it refers to gives permission.
4993 K. For any section Entitled "Acknowledgements" or "Dedications",
4994 Preserve the Title of the section, and preserve in the
4995 section all the substance and tone of each of the contributor
4996 acknowledgements and/or dedications given therein.
4998 L. Preserve all the Invariant Sections of the Document,
4999 unaltered in their text and in their titles. Section numbers
5000 or the equivalent are not considered part of the section
5003 M. Delete any section Entitled "Endorsements". Such a section
5004 may not be included in the Modified Version.
5006 N. Do not retitle any existing section to be Entitled
5007 "Endorsements" or to conflict in title with any Invariant
5010 O. Preserve any Warranty Disclaimers.
5012 If the Modified Version includes new front-matter sections or
5013 appendices that qualify as Secondary Sections and contain no
5014 material copied from the Document, you may at your option
5015 designate some or all of these sections as invariant. To do this,
5016 add their titles to the list of Invariant Sections in the Modified
5017 Version's license notice. These titles must be distinct from any
5018 other section titles.
5020 You may add a section Entitled "Endorsements", provided it contains
5021 nothing but endorsements of your Modified Version by various
5022 parties--for example, statements of peer review or that the text
5023 has been approved by an organization as the authoritative
5024 definition of a standard.
5026 You may add a passage of up to five words as a Front-Cover Text,
5027 and a passage of up to 25 words as a Back-Cover Text, to the end
5028 of the list of Cover Texts in the Modified Version. Only one
5029 passage of Front-Cover Text and one of Back-Cover Text may be
5030 added by (or through arrangements made by) any one entity. If the
5031 Document already includes a cover text for the same cover,
5032 previously added by you or by arrangement made by the same entity
5033 you are acting on behalf of, you may not add another; but you may
5034 replace the old one, on explicit permission from the previous
5035 publisher that added the old one.
5037 The author(s) and publisher(s) of the Document do not by this
5038 License give permission to use their names for publicity for or to
5039 assert or imply endorsement of any Modified Version.
5041 5. COMBINING DOCUMENTS
5043 You may combine the Document with other documents released under
5044 this License, under the terms defined in section 4 above for
5045 modified versions, provided that you include in the combination
5046 all of the Invariant Sections of all of the original documents,
5047 unmodified, and list them all as Invariant Sections of your
5048 combined work in its license notice, and that you preserve all
5049 their Warranty Disclaimers.
5051 The combined work need only contain one copy of this License, and
5052 multiple identical Invariant Sections may be replaced with a single
5053 copy. If there are multiple Invariant Sections with the same name
5054 but different contents, make the title of each such section unique
5055 by adding at the end of it, in parentheses, the name of the
5056 original author or publisher of that section if known, or else a
5057 unique number. Make the same adjustment to the section titles in
5058 the list of Invariant Sections in the license notice of the
5061 In the combination, you must combine any sections Entitled
5062 "History" in the various original documents, forming one section
5063 Entitled "History"; likewise combine any sections Entitled
5064 "Acknowledgements", and any sections Entitled "Dedications". You
5065 must delete all sections Entitled "Endorsements."
5067 6. COLLECTIONS OF DOCUMENTS
5069 You may make a collection consisting of the Document and other
5070 documents released under this License, and replace the individual
5071 copies of this License in the various documents with a single copy
5072 that is included in the collection, provided that you follow the
5073 rules of this License for verbatim copying of each of the
5074 documents in all other respects.
5076 You may extract a single document from such a collection, and
5077 distribute it individually under this License, provided you insert
5078 a copy of this License into the extracted document, and follow
5079 this License in all other respects regarding verbatim copying of
5082 7. AGGREGATION WITH INDEPENDENT WORKS
5084 A compilation of the Document or its derivatives with other
5085 separate and independent documents or works, in or on a volume of
5086 a storage or distribution medium, is called an "aggregate" if the
5087 copyright resulting from the compilation is not used to limit the
5088 legal rights of the compilation's users beyond what the individual
5089 works permit. When the Document is included in an aggregate, this
5090 License does not apply to the other works in the aggregate which
5091 are not themselves derivative works of the Document.
5093 If the Cover Text requirement of section 3 is applicable to these
5094 copies of the Document, then if the Document is less than one half
5095 of the entire aggregate, the Document's Cover Texts may be placed
5096 on covers that bracket the Document within the aggregate, or the
5097 electronic equivalent of covers if the Document is in electronic
5098 form. Otherwise they must appear on printed covers that bracket
5099 the whole aggregate.
5103 Translation is considered a kind of modification, so you may
5104 distribute translations of the Document under the terms of section
5105 4. Replacing Invariant Sections with translations requires special
5106 permission from their copyright holders, but you may include
5107 translations of some or all Invariant Sections in addition to the
5108 original versions of these Invariant Sections. You may include a
5109 translation of this License, and all the license notices in the
5110 Document, and any Warranty Disclaimers, provided that you also
5111 include the original English version of this License and the
5112 original versions of those notices and disclaimers. In case of a
5113 disagreement between the translation and the original version of
5114 this License or a notice or disclaimer, the original version will
5117 If a section in the Document is Entitled "Acknowledgements",
5118 "Dedications", or "History", the requirement (section 4) to
5119 Preserve its Title (section 1) will typically require changing the
5124 You may not copy, modify, sublicense, or distribute the Document
5125 except as expressly provided under this License. Any attempt
5126 otherwise to copy, modify, sublicense, or distribute it is void,
5127 and will automatically terminate your rights under this License.
5129 However, if you cease all violation of this License, then your
5130 license from a particular copyright holder is reinstated (a)
5131 provisionally, unless and until the copyright holder explicitly
5132 and finally terminates your license, and (b) permanently, if the
5133 copyright holder fails to notify you of the violation by some
5134 reasonable means prior to 60 days after the cessation.
5136 Moreover, your license from a particular copyright holder is
5137 reinstated permanently if the copyright holder notifies you of the
5138 violation by some reasonable means, this is the first time you have
5139 received notice of violation of this License (for any work) from
5140 that copyright holder, and you cure the violation prior to 30 days
5141 after your receipt of the notice.
5143 Termination of your rights under this section does not terminate
5144 the licenses of parties who have received copies or rights from
5145 you under this License. If your rights have been terminated and
5146 not permanently reinstated, receipt of a copy of some or all of
5147 the same material does not give you any rights to use it.
5149 10. FUTURE REVISIONS OF THIS LICENSE
5151 The Free Software Foundation may publish new, revised versions of
5152 the GNU Free Documentation License from time to time. Such new
5153 versions will be similar in spirit to the present version, but may
5154 differ in detail to address new problems or concerns. See
5155 `http://www.gnu.org/copyleft/'.
5157 Each version of the License is given a distinguishing version
5158 number. If the Document specifies that a particular numbered
5159 version of this License "or any later version" applies to it, you
5160 have the option of following the terms and conditions either of
5161 that specified version or of any later version that has been
5162 published (not as a draft) by the Free Software Foundation. If
5163 the Document does not specify a version number of this License,
5164 you may choose any version ever published (not as a draft) by the
5165 Free Software Foundation. If the Document specifies that a proxy
5166 can decide which future versions of this License can be used, that
5167 proxy's public statement of acceptance of a version permanently
5168 authorizes you to choose that version for the Document.
5172 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
5173 World Wide Web server that publishes copyrightable works and also
5174 provides prominent facilities for anybody to edit those works. A
5175 public wiki that anybody can edit is an example of such a server.
5176 A "Massive Multiauthor Collaboration" (or "MMC") contained in the
5177 site means any set of copyrightable works thus published on the MMC
5180 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
5181 license published by Creative Commons Corporation, a not-for-profit
5182 corporation with a principal place of business in San Francisco,
5183 California, as well as future copyleft versions of that license
5184 published by that same organization.
5186 "Incorporate" means to publish or republish a Document, in whole or
5187 in part, as part of another Document.
5189 An MMC is "eligible for relicensing" if it is licensed under this
5190 License, and if all works that were first published under this
5191 License somewhere other than this MMC, and subsequently
5192 incorporated in whole or in part into the MMC, (1) had no cover
5193 texts or invariant sections, and (2) were thus incorporated prior
5194 to November 1, 2008.
5196 The operator of an MMC Site may republish an MMC contained in the
5197 site under CC-BY-SA on the same site at any time before August 1,
5198 2009, provided the MMC is eligible for relicensing.
5201 ADDENDUM: How to use this License for your documents
5202 ----------------------------------------------------
5204 To use this License in a document you have written, include a copy of
5205 the License in the document and put the following copyright and license
5206 notices just after the title page:
5208 Copyright (C) YEAR YOUR NAME.
5209 Permission is granted to copy, distribute and/or modify this document
5210 under the terms of the GNU Free Documentation License, Version 1.3
5211 or any later version published by the Free Software Foundation;
5212 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
5213 Texts. A copy of the license is included in the section entitled ``GNU
5214 Free Documentation License''.
5216 If you have Invariant Sections, Front-Cover Texts and Back-Cover
5217 Texts, replace the "with...Texts." line with this:
5219 with the Invariant Sections being LIST THEIR TITLES, with
5220 the Front-Cover Texts being LIST, and with the Back-Cover Texts
5223 If you have Invariant Sections without Cover Texts, or some other
5224 combination of the three, merge those two alternatives to suit the
5227 If your document contains nontrivial examples of program code, we
5228 recommend releasing these examples in parallel under your choice of
5229 free software license, such as the GNU General Public License, to
5230 permit their use in free software.
5233 File: auctex.info, Node: Changes, Next: Development, Prev: Copying this Manual, Up: Appendices
5235 A.2 Changes and New Features
5236 ============================
5241 * Parsing of LaTeX output was improved. It is now less likely that
5242 AUCTeX opens a non-existent file upon calling `TeX-next-error'; a
5243 problem for example encountered when using MiKTeX 2.8. In addition
5244 quoted file names as emitted by MiKTeX are now supported.
5246 * A new framework for the definition and selection of viewers was
5247 implemented. If you have customizations regarding viewers you
5248 will have to redo them in this new framework or reenable the old
5249 one. *Note Starting Viewers::, for details.
5251 * Comprehensive editing support for PSTricks was added.
5253 * Support for various LaTeX packages was added, e.g. `tabularx',
5254 `CJK', and `hyperref'.
5256 * An easy way to switch between TeX engines (PDFTeX, LuaTeX, XeTeX,
5259 * Support for SyncTeX was added. This involves the command line
5260 options for LaTeX and the viewer.
5262 * Folding can now be customized to use macro arguments as replacement
5265 * `preview.sty' now works with XeTeX.
5267 * A lot of smaller and larger bugs have been squashed.
5272 * Font locking has been improved significantly. It is now less
5273 prone to color bleeding which could lead to high resource usage.
5274 In addition it now includes information about LaTeX macro syntax
5275 and can indicate syntactically incorrect macros in LaTeX mode.
5277 * The license was updated to GPLv3.
5279 * Support for the nomencl, flashcards and comment LaTeX packages as
5280 well as the Icelandic language option of babel were added.
5282 * Support for folding of math macros was added.
5284 * Lots of minor bugs in features and documentation fixed.
5289 * There have been problems with the `-without-texmf-dir' option to
5290 `configure' when the value of `-with-kpathsea-sep' was set or
5291 determined for an installation system with a default different
5292 from that of the runtime system. `with-kpathsea-sep' has been
5293 removed; the setting is now usually determined at runtime.
5295 Due to this and other problems, preview-latex in the released
5296 XEmacs package failed under Windows or with anything except recent
5299 * AUCTeX and preview-latex have been changed in order to accommodate
5300 file names containing spaces. preview-latex now tolerates bad
5301 PostScript code polluting the stack (like some Omega fonts).
5303 * `preview.sty' had in some cases failed to emit PostScript header
5306 * Support for folding of comments was added.
5308 * The `polish' language option of the babel LaTeX package as well as
5309 the polski LaTeX package are now supported. Most notably this
5310 means that AUCTeX will help to insert quotation marks as defined
5311 by polish.sty (`"`..."'') and polski.sty (`,,...''').
5313 * The TeX tool bar is now available and enabled by default in plain
5314 TeX mode. *Note Processing Facilities::.
5316 * Bug fix in the display of math subscripts and superscripts.
5318 * Bug fix `TeX-doc' for Emacs 21.
5320 * There has been quite a number of other bug fixes to various
5321 features and documentation across the board.
5327 * The new function `TeX-doc' provides easy access to documentation
5328 about commands and packages or information related to TeX and
5329 friends in general. *Note Documentation::.
5331 * You can now get rid of generated intermediate and output files by
5332 means of the new `Clean' and `Clean All' entries in
5333 `TeX-command-list' accessible with `C-c C-c' or the Command menu.
5336 * Support for forward search with PDF files was added. That means
5337 you can jump to a place in the output file corresponding to the
5338 position in the source file. *Note Viewing::.
5340 Adding support for this feature required the default value of the
5341 variable `TeX-output-view-style' to be changed. Please make sure
5342 you either remove any customizations overriding the new default or
5343 incorporate the changes into your customizations if you want to
5346 * TeX error messages of the `-file-line-error' kind are now
5347 understood in AUCTeX and preview-latex (parsers are still
5350 * Bug fix in XyMTeX support.
5352 * The LaTeX tool bar is now enabled by default. *Note Processing
5359 * Support for the MinionPro LaTeX package was added.
5361 * Warnings and underfull/overfull boxes are now being indicated in
5362 the echo area after a LaTeX run, if the respective debugging
5363 options are activated with `TeX-toggle-debug-warnings' (`C-c C-t
5364 C-w') or `TeX-toggle-debug-bad-boxes' (`C-c C-t C-b'). In this
5365 case `TeX-next-error' will find these warnings in addition to
5368 The key binding `C-c C-w' for `TeX-toggle-debug-bad-boxes' (which
5369 was renamed from `TeX-toggle-debug-boxes') now is deprecated.
5371 * AUCTeX now can automatically insert a pair of braces after typing
5372 <_> or <^> in math constructs if the new variable
5373 `TeX-electric-sub-and-superscript' is set to a non-nil value.
5375 * Some language-specific support for French was added. There now is
5376 completion support for the commands provided by the `frenchb' (and
5377 `francais') options of the babel LaTeX package and easier input of
5378 French quotation marks (`\\og ...\\fg') which can now be inserted
5381 * Completion support for options of some LaTeX packages was added.
5383 * Already in version 11.81 the way to activate AUCTeX changed
5384 substantially. This should now be done with `(load "auctex.el" nil
5385 t t)' instead of the former `(require 'tex-site)'. Related to this
5386 change `tex-mik.el' does not load `tex-site.el' anymore. That
5387 means if you used only `(require 'tex-mik)' in order to activate
5388 AUCTeX, you have to add `(load "auctex.el" nil t t)' before the
5389 latter statement. *Note Loading the package::.
5391 * Handling of verbatim constructs was consolidated across AUCTeX.
5392 This resulted in the font-latex-specific variables
5393 `font-latex-verb-like-commands', `font-latex-verbatim-macros', and
5394 `font-latex-verbatim-environments' being removed and the more
5395 general variables `LaTeX-verbatim-macros-with-delims',
5396 `LaTeX-verbatim-macros-with-braces', and
5397 `LaTeX-verbatim-environments' being added.
5399 * The output of a BibTeX run is now checked for warnings and errors,
5400 which are reported in the echo area.
5402 * The aliases for `font-latex-title-fontify' were removed. Use
5403 `font-latex-fontify-sectioning' instead.
5405 * The problem that Japanese macros where broken across lines was
5408 * Various bug fixes.
5413 * `LaTeX-mark-section' now marks subsections of a given section as
5414 well. The former behavior is available via the prefix argument.
5416 * preview-latex which was previously available separately became a
5417 subsystem of AUCTeX. There is no documented provision for building
5418 or installing preview-latex separately. It is still possible to
5419 use and install AUCTeX without preview-latex, however.
5421 * The installation procedures have been overhauled and now also
5422 install startup files as part of the process (those had to be
5423 copied manually previously). You are advised to remove previous
5424 installations of AUCTeX and preview-latex before starting the
5425 installation procedure. A standard installation from an
5426 unmodified tarball no longer requires Makeinfo or Perl.
5428 Also note that the way AUCTeX is supposed to be activated changed.
5429 Instead of `(require 'tex-site)' you should now use `(load
5430 "auctex.el" nil t t)'. While the former method may still work,
5431 the new method has the advantage that you can deactivate a
5432 preactivated AUCTeX with the statement `(unload-feature
5433 'tex-site)' before any of its modes have been used. This may be
5434 important especially for site-wide installations.
5436 * Support for the babel LaTeX package was added.
5438 * Folding a buffer now ensures that the whole buffer is fontified
5439 before the actual folding is carried out. If this results in
5440 unbearably long execution times, you can fall back to the old
5441 behavior of relying on stealth font locking to do this job in the
5442 background by customizing the variable `TeX-fold-force-fontify'.
5444 * Folded content now reveals part of its original text in a tooltip
5445 or the echo area when hovering with the mouse pointer over it.
5447 * The language-specific insertion of quotation marks was
5448 generalized. The variables `LaTeX-german-open-quote',
5449 `LaTeX-german-close-quote', `LaTeX-german-quote-after-quote',
5450 `LaTeX-italian-open-quote', `LaTeX-italian-close-quote', and
5451 `LaTeX-italian-quote-after-quote' are now obsolete. If you are not
5452 satisfied with the default settings, you should customize
5453 `TeX-quote-language-alist' instead.
5455 * Similar to language-specific quote insertion, AUCTeX now helps you
5456 with hyphens in different languages as well. *Note European::,
5459 * Fill problems in Japanese text introduced in AUCTeX 11.55 were
5460 fixed. AUCTeX tries not to break lines between 1-byte and 2-byte
5461 chars. These features will work in Chinese text, too.
5463 * The scaling factor of the fontification of sectioning commands can
5464 now be customized using the variable
5465 `font-latex-fontify-sectioning'. This variable was previously
5466 called `font-latex-title-fontify'; In this release we provide an
5467 alias but this will disappear in one of the the next releases.
5468 The faces for the sectioning commands are now called
5469 `font-latex-sectioning-N-face' (N=0...5) instead of
5470 `font-latex-title-N-face' (N=1...4). Analogously the names of the
5471 variables holding the related keyword lists were changed from
5472 `font-latex-title-N-keywords' to
5473 `font-latex-sectioning-N-keywords'. *Note Font Locking::, for
5474 details. Make sure to adjust your customizations.
5476 * Titles in beamer slides marked by the "\frametitle" command are
5477 know displayed with the new face `font-latex-slide-title-face'.
5478 You can add macros to be highlighted with this face to
5479 `font-latex-match-slide-title-keywords'.
5481 * Of course a lot of bugs have been fixed.
5486 * A bug was fixed which lead to the insertion of trailing whitespace
5487 during filling. In particular extra spaces were added to sentence
5488 endings at the end of lines. You can make this whitespace visible
5489 by setting the variable `show-trailing-whitespace' to `t'. If you
5490 want to delete all trailing whitespace in a buffer, type `M-x
5491 delete-trailing-whitespace RET'.
5493 * A bug was fixed which lead to a `*Compile-Log*' buffer popping up
5494 when the first LaTeX file was loaded in an Emacs session.
5496 * On some systems the presence of an outdated Emacspeak package lead
5497 to the error message `File mode specification error: (error
5498 "Variable binding depth exceeds max-specpdl-size")'. Precautions
5499 were added which prevent this error from happening. But
5500 nevertheless, it is advised to upgrade or uninstall the outdated
5503 * The value of `TeX-macro-global' is not determined during
5504 configuration anymore but at load time of AUCTeX. Consequently the
5505 associated configuration option `--with-tex-input-dirs' was
5508 * Support for the LaTeX Japanese classes `jsarticle' and `jsbook'
5514 * The parser (used e.g. for `TeX-auto-generate-global') was extended
5515 to recognize keywords common in LaTeX packages and classes, like
5516 "\DeclareRobustCommand" or "\RequirePackage". Additionally a bug
5517 was fixed which led to duplicate entries in AUCTeX style files.
5519 * Folding can now be done for paragraphs and regions besides single
5520 constructs and the whole buffer. With the new `TeX-fold-dwim'
5521 command content can both be hidden and shown with a single key
5522 binding. In course of these changes new key bindings for
5523 unfolding commands where introduced. The old bindings are still
5524 present but will be phased out in future releases.
5526 * Info files of the manual now have a .info extension.
5528 * There is an experimental tool bar support now. It is not
5529 activated by default. If you want to use it, add
5530 (add-hook 'LaTeX-mode-hook 'LaTeX-install-toolbar)
5533 * The manual now contains a new chapter "Quick Start". It explains
5534 the main features and how to use them, and should be enough for a
5535 new user to start using AUCTeX.
5537 * A new section "Font Locking" was added to the manual which explains
5538 syntax highlighting in AUCTeX and its customization. Together with
5539 the sections related to folding and outlining, the section is part
5540 of the new chapter "Display".
5542 * Keywords for syntax highlighting of LaTeX constructs to be typeset
5543 in bold, italic or typewriter fonts may now be customized.
5544 Besides the built-in classes, new keyword classes may be added by
5545 customizing the variable `font-latex-user-keyword-classes'. The
5546 customization options can be found in the customization group
5547 `font-latex-keywords'.
5549 * Verbatim content is now displayed with the `fixed-pitch' face. (GNU
5552 * Syntax highlighting should not spill out of verbatim content
5553 anymore. (GNU Emacs only)
5555 * Verbatim commands like `\verb|...|' will not be broken anymore
5558 * You can customize the completion for graphic files with
5559 `LaTeX-includegraphics-read-file'.
5561 * Support for the LaTeX packages `url', `listings', `jurabib' and
5562 `csquotes' was added with regard to command completion and syntax
5565 * Performance of fontification and filling was improved.
5567 * Insertion of nodes in Texinfo mode now supports completion of
5568 existing node names.
5570 * Setting the variable `LaTeX-float' to `nil' now means that you
5571 will not be prompted for the float position of figures and tables.
5572 You can get the old behaviour of `nil' by setting the variable to
5573 `""', i.e. an empty string. See also *note Floats::.
5575 * The XEmacs-specific bug concerning `overlays-at' was fixed.
5577 * Lots of bug fixes.
5582 * The LaTeX math menu can include Unicode characters if your Emacs
5583 built supports it. See the variable `LaTeX-math-menu-unicode',
5584 *note Mathematics::.
5586 * Bug fixes for XEmacs.
5588 * Completion for graphic files in the TeX search path has been added.
5590 * `start' is used for the viewer for MiKTeX and fpTeX.
5592 * The variable `TeX-fold-preserve-comments' can now be customized to
5593 deactivate folding in comments.
5598 * Installation and menus under XEmacs work again (maybe for the first
5601 * Fontification of subscripts and superscripts is now disabled when
5602 the fontification engine is not able to support it properly.
5604 * Bug fixes in the build process.
5609 * PDFTeX and Source Special support did not work with ConTeXt, this
5610 has been fixed. Similar for Source Special support under Windows.
5612 * Omega support has been added.
5614 * Bug fixes in the build process.
5616 * `TeX-fold' now supports folding of environments in Texinfo mode.
5621 * The use of source specials when processing or viewing the document
5622 can now be controlled with the new `TeX-source-specials' minor mode
5623 which can be toggled via an entry in the Command menu or the key
5624 binding `C-c C-t C-s'. If you have customized the variable
5625 `TeX-command-list', you have to re-initialize it for this to work.
5626 This means to open a customization buffer for the variable by
5627 typing `M-x customize-variable RET TeX-command-list RET', selecting
5628 "Erase Customization" and do your customization again with the new
5631 * The content of the command menu now depends on the mode (plain TeX,
5632 LaTeX, ConTeXt etc.). Any former customization of the variable
5633 `TeX-command-list' has to be erased. Otherwise the command menu
5634 and the customization will not work correctly.
5636 * Support for hiding and auto-revealing macros, e.g. footnotes or
5637 citations, and environments in a buffer was added, *note Folding::.
5639 * You can now control if indentation is done upon typing <RET> by
5640 customizing the variable `TeX-newline-function', *note Indenting::.
5642 * Limited support for `doc.sty' and `ltxdoc.cls' (`dtx' files) was
5643 added. The new docTeX mode provides functionality for editing
5644 documentation parts. This includes formatting (indenting and
5645 filling), adding and completion of macros and environments while
5646 staying in comments as well as syntax highlighting. (Please note
5647 that the mode is not finished yet. For example syntax
5648 highlighting does not work yet in XEmacs.)
5650 * For macro completion in docTeX mode the AUCTeX style files
5651 `doc.el', `ltxdoc.el' and `ltx-base.el' were included. The latter
5652 provides general support for low-level LaTeX macros and may be
5653 used with LaTeX class and style files as well. It is currently
5654 not loaded automatically for those files.
5656 * Support for ConTeXt with a separate ConTeXt mode is now included.
5657 Macro definitions for completion are available in Dutch and
5660 * The filling and indentation code was overhauled and is now able to
5661 format commented parts of the source syntactically correct. Newly
5662 available functionality and customization options are explained in
5665 * Filling and indentation in XEmacs with preview-latex and activated
5666 previews lead to the insertion of whitespace before multi-line
5667 previews. AUCTeX now contains facilities to prevent this problem.
5669 * If `TeX-master' is set to `t', AUCTeX will now query for a master
5670 file only when a new file is opened. Existing files will be left
5671 alone. The new function `TeX-master-file-ask' (bound to `C-c _'
5672 is provided for adding the variable manually.
5674 * Sectioning commands are now shown in a larger font on display
5675 devices which support such fontification. The variable
5676 `font-latex-title-fontify' can be customized to restore the old
5677 appearance, i.e. the usage of a different color instead of a
5680 * Support for `alphanum.sty', `beamer.cls', `booktabs.sty',
5681 `captcont.sty', `emp.sty', `paralist.sty', `subfigure.sty' and
5682 `units.sty'/`nicefrac.sty' was added. Credits go to the authors
5683 mentioned in the respective AUCTeX style files.
5685 * Inserting graphics with `C-c RET \includegraphics RET' was
5686 improved. See the variable `LaTeX-includegraphics-options-alist'.
5688 * If `LaTeX-default-position' is `nil', don't prompt for position
5689 arguments in Tabular-like environments, see *note Tabular-like::.
5691 * Completion for available packages when using `C-c RET \usepackage
5692 RET' was improved on systems using the kpathsea library.
5694 * The commenting functionality was fixed. The separate functions for
5695 commenting and uncommenting were unified in one function for
5696 paragraphs and regions respectively which do both.
5698 * Syntax highlighting can be customized to fontify quotes delimited
5699 by either >>German<< or <<French>> quotation marks by changing the
5700 variable `font-latex-quotes'.
5702 * Certain TeX/LaTeX keywords for functions, references, variables
5703 and warnings will now be fontified specially. You may add your own
5704 keywords by customizing the variables
5705 `font-latex-match-function-keywords',
5706 `font-latex-match-reference-keywords',
5707 `font-latex-match-variable-keywords' and
5708 `font-latex-match-warning-keywords'.
5710 * If you include the style files `german' or `ngerman' in a document
5711 (directly or via the `babel' package), you should now customize
5712 `LaTeX-german-open-quote', `LaTeX-german-close-quote' and
5713 `LaTeX-german-quote-after-quote' instead of `TeX-open-quote',
5714 `TeX-close-quote' and `TeX-quote-after-quote' if you want to
5715 influence the type of quote insertion.
5717 * Upon viewing an output file, the right viewer and command line
5718 options for it are now determined automatically by looking at the
5719 extension of the output file and certain options used in the
5720 source file. The behavior can be adapted or extended respectively
5721 by customizing the variable `TeX-output-view-style'.
5723 * You can control whether `TeX-insert-macro' (`C-c RET') ask for all
5724 optional arguments by customizing the variable
5725 `TeX-insert-macro-default-style', *note Completion::.
5727 * `TeX-run-discard' is now able to completely detach a process that
5730 * The build process was enhanced and is now based on `autoconf'
5731 making installing AUCTeX a mostly automatic process. See *note
5732 Installation:: and *note Installation under MS Windows:: for
5738 * Many more LaTeX and LaTeX2e commands are supported. Done by
5739 Masayuki Ataka <ataka@milk.freemail.ne.jp>
5744 * Support for the KOMA-Script classes. Contributed by Mark Trettin
5745 <Mark.Trettin@gmx.de>.
5750 * Support for `prosper.sty', see `http://prosper.sourceforge.net/'.
5751 Contributed by Phillip Lord <p.lord@russet.org.uk>.
5756 * `comment-region' now inserts %% by default. Suggested by "Davide
5757 G. M. Salvetti" <salve@debian.org>.
5762 * You can now switch between using the `font-latex' (all emacsen),
5763 the `tex-font' (Emacs 21 only) or no special package for font
5764 locking. Customize `TeX-install-font-lock' for this.
5769 * Now use -t landscape by default when landscape option appears.
5770 Suggested by Erik Frisk <frisk@isy.liu.se>.
5775 * Use `tex-fptex.el' for fpTeX support. Contributed by Fabrice
5776 Popineau <Fabrice.Popineau@supelec.fr>.
5781 * New user option `LaTeX-top-caption-list' specifies environments
5782 where the caption should go at top. Contributed by
5783 ataka@milk.freemail.ne.jp (Masayuki Ataka).
5785 * Allow explicit dimensions in `graphicx.sty'. Contributed by
5786 ataka@milk.freemail.ne.jp (Masayuki Ataka).
5788 * Limited support for `verbatim.sty'. Contributed by
5789 ataka@milk.freemail.ne.jp (Masayuki Ataka).
5791 * Better support for asmmath items. Patch by
5792 ataka@milk.freemail.ne.jp (Masayuki Ataka).
5794 * More accurate error parsing. Added by David Kastrup
5795 <David.Kastrup@t-online.de>.
5805 See the file `history.texi' for older changes.
5808 File: auctex.info, Node: Development, Next: FAQ, Prev: Changes, Up: Appendices
5810 A.3 Future Development
5811 ======================
5813 The following sections describe future development of AUCTeX. Besides
5814 mid-term goals, bug reports and requests we cannot fix or honor right
5815 away are being gathered here. If you have some time for Emacs Lisp
5816 hacking, you are encouraged to try to provide a solution to one of the
5817 following problems. If you don't know Lisp, you may help us to improve
5818 the documentation. It might be a good idea to discuss proposed changes
5819 on the mailing list of AUCTeX first.
5828 File: auctex.info, Node: Mid-term Goals, Next: Wishlist, Up: Development
5830 A.3.1 Mid-term Goals
5831 --------------------
5833 * Integration of preview-latex into AUCTeX
5835 As of AUCTeX 11.81 preview-latex is a part of AUCTeX in the sense
5836 that the installation routines were merged and preview-latex is
5837 being packaged with AUCTeX.
5839 Further integration will happen at the backend. This involves
5840 folding of error parsing and task management of both packages
5841 which will ease development efforts and avoid redundant work.
5843 * More flexible option and command handling
5845 The current state of command handling with `TeX-command-list' is
5846 not very flexible because there is no distinction between
5847 executables and command line options to be passed to them.
5849 Customization of `TeX-command-list' by the user will interfere with
5852 * Error help catalogs
5854 Currently, the help for errors is more or less hardwired into
5855 `tex.el'. For supporting error help in other languages, it would
5856 be sensible to instead arrange error messages in language-specific
5857 files, make a common info file from all such catalogs in a given
5858 language and look the error texts up in an appropriate index. The
5859 user would then specify a preference list of languages, and the
5860 errors would be looked up in the catalogs in sequence until they
5863 * Combining `docTeX' with RefTeX
5865 Macro cross references should also be usable for document
5866 navigation using RefTeX.
5870 File: auctex.info, Node: Wishlist, Next: Bugs, Prev: Mid-term Goals, Up: Development
5875 * Documentation lookup for macros
5877 A parser could gather information about which macros are defined in
5878 which LaTeX packages and store the information in a hashtable which
5879 can be used in a backend for `TeX-doc' in order to open the
5880 matching documentation for a given macro. The information could
5881 also be used to insert an appropriate `\usepackage' statement if
5882 the user tries to insert a macro for which the respective package
5883 has not been requested yet.
5885 * Spell checking of macros
5887 A special ispell dictionary for macros could be nice to have.
5889 * Quick error overviews
5891 An error overview window (extract from the log file with just the
5892 error lines, clickable like a "grep" buffer) and/or fringe
5893 indicators for errors in the main text would be nice.
5897 A separate frame with a table of math character graphics to click
5898 on in order to insert the respective sequence into the buffer (cf.
5899 the "grid" of x-symbol).
5901 * Crossreferencing support
5903 It would be nice if you could index process your favorite
5904 collection of `.dtx' files (such as the LaTeX source), just call a
5905 command on arbitrary control sequence, and get either the DVI
5906 viewer opened right at the definition of that macro (using Source
5907 Specials), or the source code of the `.dtx' file.
5909 * Better plain TeX support
5911 For starters, `LaTeX-math-mode' is not very LaTeX-specific in the
5912 first place, and similar holds for indentation and formatting.
5914 * Poor man's Source Specials In particular in PDF mode (and where
5915 Source Specials cause problems), alternatives would be desirable.
5916 One could implement inverse search by something like Heiko
5917 Oberdiek's `vpe.sty', and forward search by using the `.aux' file
5918 info to correlate labels in the text (possibly in cooperation with
5919 RefTeX) with previewer pages.
5921 In AUCTeX 11.83, support for forward search with PDF files was
5922 added. Currently this only works if you use the pdfsync LaTeX
5923 package and xpdf as your PDF viewer. *Note Viewing::.
5925 * Page count when compiling should (optionally) go to modeline of the
5926 window where the compilation command was invoked, instead of the
5927 output window. Suggested by Karsten Tinnefeld
5928 <tinnefeld@irb.informatik.uni-dortmund.de>.
5930 * Command to insert a macrodefinition in the preamble, without moving
5931 point from the current location. Suggested by "Jeffrey C. Ely"
5934 * A database of all commands defined in all stylefiles. When a
5935 command or environment gets entered that is provided in one of the
5936 styles, insert the appropriate `\usepackage' in the preamble.
5938 * A way to add and overwrite math mode entries in style files, and to
5939 decide where they should be. Suggested by Remo Badii
5940 <Remo.Badii@psi.ch>.
5942 * Create template for (first) line of tabular environment.
5944 * I think prompting for the master is the intended behaviour. It
5945 corresponds to a `shared' value for TeX-master.
5947 There should probably be a `none' value which wouldn't query for
5948 the master, but instead disable all features that relies on
5951 This default value for TeX-master could then be controled with
5952 mapping based on the extension.
5954 * Multiple argument completion for `\bibliography'. In general, I
5955 ought to make `,' special for these kind of completions.
5957 * Suggest `makeindex' when appropriate.
5959 * Use index files (when available) to speed up `C-c C-m include
5962 * Option not to calculate very slow completions like for `C-c C-m
5965 * Font menu should be created from `TeX-font-list'.
5967 * Installation procedure written purely in emacs lisp.
5969 * Included PostScript files should also be counted as part of the
5972 * A nice hierarchical by-topic organization of all officially
5973 documented LaTeX macros, available from the menu bar.
5975 * `TeX-command-default' should be set from the master file, if not
5976 set locally. Suggested by Peter Whaite `<peta@cim.mcgill.ca>'.
5978 * Make AUCTeX work with `crypt++'. Suggested by Chris Moore
5979 `<Chris.Moore@src.bae.co.uk>'.
5981 * Make AUCTeX work with `longlines'. This would also apply to
5982 preview-latex, though it might make sense to unify error processing
5983 before attempting this.
5985 * The `Spell' command should apply to all files in a document. Maybe
5986 it could try to restrict to files that have been modified since
5987 last spell check? Suggested by Ravinder Bhumbla
5988 `<rbhumbla@ucsd.edu>'.
5990 * Make <.> check for abbreviations and sentences ending with capital
5993 * Use Emacs 19 minibuffer history to choose between previewers, and
5994 other stuff. Suggested by John Interrante
5995 `<interran@uluru.Stanford.EDU>'.
5999 A new command `TeX-update' (`C-c C-u') could be used to create an
6000 up-to-date dvi file by repeatedly running BibTeX, MakeIndex and
6001 (La)TeX, until an error occurs or we are done.
6003 An alternative is to have an `Update' command that ensures the
6004 `dvi' file is up to date. This could be called before printing and
6007 * Documentation of variables that can be set in a style hook.
6009 We need a list of what can safely be done in an ordinary style
6010 hook. You can not set a variable that AUCTeX depends on, unless
6011 AUCTeX knows that it has to run the style hooks first.
6013 Here is the start of such a list.
6014 `LaTeX-add-environments'
6020 `LaTeX-add-bibliographies'
6022 `LaTeX-largest-level'
6024 * Completion for counters and sboxes.
6026 * Outline should be (better) supported in TeX mode.
6028 At least, support headers, trailers, as well as TeX-outline-extra.
6030 * `TeX-header-start' and `TeX-trailer-end'.
6032 We might want these, just for fun (and outlines)
6034 * Plain TeX and LaTeX specific header and trailer expressions.
6036 We should have a way to globally specify the default value of the
6037 header and trailer regexps.
6039 * Get closer to original `TeX-mode' keybindings.
6041 A third initialization file (`tex-mode.el') containing an emulator
6042 of the standard `TeX-mode' would help convince some people to
6045 * Make `TeX-next-error' parse ahead and store the results in a list,
6046 using markers to remember buffer positions in order to be more
6047 robust with regard to line numbers and changed files. This is what
6048 `next-error' does. (Or did, until Emacs 19).
6050 * Finish the Texinfo mode. For one thing, many Texinfo mode
6051 commands do not accept braces around their arguments.
6053 * Hook up the letter environment with `bbdb.el'.
6057 File: auctex.info, Node: Bugs, Prev: Wishlist, Up: Development
6062 * The parsed files and style hooks for `example.dtx', `example.sty',
6063 `example.drv' and `example.bib' all clash. Bad.
6065 * `C-c `' should always stay in the current window, also when it
6068 * Do not overwrite emacs warnings about existing auto-save files when
6071 * Maybe the regexp for matching a TeX symbol during parsing should be
6072 `"\\\\\\([a-zA-Z]+\\|.\\)"' --
6073 `<thiemann@informatik.uni-tuebingen.de>' Peter Thiemann.
6075 * AUCTeX should not parse verbatim environments.
6077 * Make ``' check for math context in `LaTeX-math-mode'. and simply
6078 self insert if not in a math context.
6080 * Make `TeX-insert-dollar' more robust. Currently it can be fooled
6081 by `\mbox''es and escaped double dollar for example.
6083 * Correct indentation for tabular, tabbing, table, math, and array
6086 * No syntactic font locking of verbatim macros and environments.
6089 * Font locking inside of verbatim macros and environments is not
6090 inhibited. This may result in syntax highlighting of unbalanced
6091 dollar signs and the like spilling out of the verbatim content.
6094 * Folding of LaTeX constructs spanning more than one line may result
6095 in overfull lines. (XEmacs only)
6098 File: auctex.info, Node: FAQ, Prev: Development, Up: Appendices
6100 A.4 Frequently Asked Questions
6101 ==============================
6103 1. Something is not working correctly. What should I do?
6105 Well, you might have guessed it, the first place to look is in the
6106 available documentation packaged with AUCTeX. This could be the
6107 release notes (in the `RELEASE' file) or the news section of the
6108 manual in case you are experiencing problems after an upgrade, the
6109 `INSTALL' file in case you are having problems with the
6110 installation, the section about bugs in the manual in case you
6111 encountered a bug or the relevant sections in the manual for other
6114 If this did not help, you can send a bug report to the AUCTeX bug
6115 reporting list by using the command `M-x TeX-submit-bug-report
6116 RET'. But before you do this, you can try to get more information
6117 about the problem at hand which might also help you locate the
6118 cause of the error yourself.
6120 First, you can try to generate a so-called backtrace which shows
6121 functions involved in a program error. In order to do this, start
6122 Emacs with the command line `emacs --debug-init' and/or put the
6125 (setq debug-on-error t)
6127 as the first line into your init file. XEmacs users might want to
6128 add `(setq stack-trace-on-error t)' as well. After Emacs has
6129 started, you can load a file which triggers the error and a new
6130 window should pop up showing the backtrace. If you get such a
6131 backtrace, please include it in the bug report.
6133 Second, you can try to figure out if something in your personal or
6134 site configuration triggers the error by starting Emacs without
6135 such customizations. You can do this by invoking Emacs with the
6136 command line `emacs -q -no-site-file'. Once Emacs is running,
6139 (load "auctex.el" nil t t)
6141 into the `*scratch*' buffer and type `M-x eval-buffer RET'. This
6142 makes sure that AUCTeX will be used for the file types it
6143 supports. After you have done so, you can load the file
6144 triggering the error. If everything is working now, you know that
6145 you have to search either in the site configuration file or your
6146 personal init file for statements related to the problem.
6148 2. What versions of Emacs and XEmacs are supported?
6150 AUCTeX was tested with Emacs 21 and XEmacs 21.4.15. Older
6151 versions may work but are unsupported. Older versions of XEmacs
6152 might possibly made to work by updating the `xemacs-base' package
6153 through the XEmacs package system. If you are looking for a
6154 recommendation, it would appear that the smoothest working
6155 platform on all operating systems at the current point of time
6156 would be Emacs 22.1. At the time of this writing, however, it has
6157 not been released and is still under development. The quality of
6158 the development version is quite solid, so we recommend giving it
6159 a try. With a developer version, of course, you have to be
6160 prepared to update in case you managed to get your snapshot at a
6161 bad time. The second best choice would be the latest released
6162 Emacs 21.4. However, Unicode support is less good, there is no
6163 version for the popular GTK toolkit, and the native versions for
6164 Windows and MacOS don't offer toolbar and preview-latex support.
6166 Our success with XEmacs has been less than convincing. Under the
6167 Windows operating system, nominally the only option for a released,
6168 stable Emacs variant supporting toolbars and preview-latex would be
6169 XEmacs 21.4. However, code for core functionality like formatting
6170 and syntax highlighting tends to be different and often older than
6171 even Emacs 21.4, and Unicode support as delivered is problematic
6172 at best, missing on Windows. Both AUCTeX and XEmacs developers
6173 don't hear much from active users of the combination. Partly for
6174 that reason, problems tend to go unnoticed for long amounts of
6175 time and are often found, if at all, after releases. No
6176 experiences or recommendations can be given for beta or developer
6179 3. What should I do when `./configure' does not find programs like
6182 This is problem often encountered on Windows. Make sure that the
6183 `PATH' environment variable includes the directories containing the
6184 relevant programs, as described in *note Installation under MS
6185 Windows: (auctex)Installation under MS Windows.
6187 4. Why doesn't the completion, style file, or multi-file stuff work?
6189 It must be enabled first, insert this in your init file:
6191 (setq-default TeX-master nil)
6192 (setq TeX-parse-self t)
6193 (setq TeX-auto-save t)
6195 Read also the chapters about parsing and multifile documents in the
6198 5. Why doesn't `TeX-save-document' work?
6200 `TeX-check-path' has to contain "./" somewhere.
6202 6. Why is the information in `foo.tex' forgotten when I save
6205 For various reasons, AUCTeX ignores the extension when it stores
6206 information about a file, so you should use unique base names for
6207 your files. E.g. rename `foo.bib' to `foob.bib'.
6209 7. Why doesn't AUCTeX signal when processing a document is done?
6211 If the message in the minibuffer stays "Type `C-c C-l' to display
6212 results of compilation.", you probably have a misconfiguration in
6213 your init file (`.emacs', `init.el' or similar). To track this
6214 down either search in the `*Messages*' buffer for an error message
6215 or put `(setq debug-on-error t)' as the first line into your init
6216 file, restart Emacs and open a LaTeX file. Emacs will complain
6217 loudly by opening a debugging buffer as soon as an error occurs.
6218 The information in the debugging buffer can help you find the
6219 cause of the error in your init file.
6221 8. What does AUC stand for?
6223 AUCTeX came into being at Aalborg University in Denmark. Back then
6224 the Danish name of the university was Aalborg Universitetscenter;
6229 File: auctex.info, Node: Indices, Prev: Appendices, Up: Top
6242 File: auctex.info, Node: Key Index, Next: Function Index, Up: Indices