1 This is the README file for the AUCTeX distribution.
3 Copyright (C) 2008 Free Software Foundation, Inc.
5 Copying and distribution of this file, with or without
6 modification, are permitted in any medium without royalty provided
7 the copyright notice and this notice are preserved.
10 **********************
12 This file gives a brief overview of what AUCTeX is. It is *not* an
13 attempt to document AUCTeX. Real documentation for AUCTeX is available
14 in the manual, which should be available as an info file after
17 AUCTeX is a comprehensive customizable integrated environment for
18 writing input files for TeX, LaTeX, ConTeXt, Texinfo, and docTeX using
21 It supports you in the insertion of macros, environments, and sectioning
22 commands by providing completion alternatives and prompting for
23 parameters. It automatically indents your text as you type it and lets
24 you format a whole file at once. The outlining and folding facilities
25 provide you with a focused and clean view of your text.
27 AUCTeX lets you process your source files by running TeX and related
28 tools (such as output filters, post processors for generating indices
29 and bibliographies, and viewers) from inside Emacs. AUCTeX lets you
30 browse through the errors TeX reported, while it moves the cursor
31 directly to the reported error, and displays some documentation for
32 that particular error. This will even work when the document is spread
35 One component of AUCTeX that LaTeX users will find attractive is
36 preview-latex, a combination of folding and in-source previewing that
37 provides true "What You See Is What You Get" experience in your
38 sourcebuffer, while letting you retain full control. For more
39 information, see further below.
41 More detailed information about the features and usage of AUCTeX can be
42 found in the AUCTeX manual. You can access it from within Emacs by
43 typing `C-h i d m auctex <RET>'. If you prefer the standalone info
44 reader, issue the command `info auctex' in a terminal.
46 AUCTeX is written entirely in Emacs Lisp, and hence you can easily add
47 new features for your own needs. It is a GNU project and distributed
48 under the `GNU General Public License Version 3'.
50 The most recent version is always available at
51 `http://ftp.gnu.org/pub/gnu/auctex/'.
53 WWW users may want to check out the AUCTeX page at
54 `http://www.gnu.org/software/auctex/'.
56 For comprehensive information about how to install AUCTeX read the file
57 `INSTALL' or `INSTALL.windows', respectively.
59 If you are considering upgrading AUCTeX, the recent changes are
60 described in the `CHANGES' file.
62 If you want to discuss AUCTeX with other users or its developers, there
63 are several mailing lists you can use.
65 Send a mail with the subject "subscribe" to <auctex-request@gnu.org> in
66 order to join the general discussion list for AUCTeX. Articles should
67 be sent to <auctex@gnu.org>. In a similar way, you can subscribe to
68 the <info-auctex@gnu.org> list for just getting important announcements
69 about AUCTeX. The list <bug-auctex@gnu.org> is for bug reports which
70 you should usually file with the `M-x TeX-submit-bug-report <RET>'
71 command. If you want to address the developers of AUCTeX themselves
72 with technical issues, they can be found on the discussion list
73 <auctex-devel@gnu.org>.
75 preview-latex in a nutshell
76 ***************************
78 Does your neck hurt from turning between previewer windows and the
79 source too often? This AUCTeX component will render your displayed
80 LaTeX equations right into the editing window where they belong.
82 The purpose of preview-latex is to embed LaTeX environments such as
83 display math or figures into the source buffers and switch conveniently
84 between source and image representation.
89 WYSIWYG (what you see is what you get) sometimes is considered all the
90 rage, sometimes frowned upon. Do we really want it? Wrong question.
91 The right question is _what_ we want from it. Except when finetuning
92 the layout, we don't want to use printer fonts for on-screen text
93 editing. The low resolution and contrast of a computer screen render
94 all but the coarsest printer fonts (those for low-quality newsprint)
95 unappealing, and the margins and pagination of the print are not wanted
96 on the screen, either. On the other hand, more complex visual
97 compositions like math formulas and tables can't easily be taken in
98 when seen only in the source. preview-latex strikes a balance: it only
99 uses graphic renditions of the output for certain, configurable
100 constructs, does this only when told, and then right in the source code.
101 Switching back and forth between the source and preview is easy and
102 natural and can be done for each image independently. Behind the scenes
103 of preview-latex, a sophisticated framework of other programs like
104 `dvipng', Dvips and Ghostscript are employed together with a special
105 LaTeX style file for extracting the material of interest in the
106 background and providing fast interactive response.
108 2 Activating preview-latex
109 **************************
111 After installation, the package may need to be activated (and remember
112 to activate AUCTeX too). In XEmacs, and in any prepackaged versions
113 worth their salt, activation should be automatic upon installation. If
114 this seems not the case, complain to your installation provider.
116 The usual activation (if it is not done automatically) would be
118 (load "preview-latex.el" nil t t)
120 If you still don't get a "Preview" menu in LaTeX mode in spite of
121 AUCTeX showing its "Command", your installation is broken. One
122 possible cause are duplicate Lisp files that might be detectable with
123 `<M-x> list-load-path-shadows <RET>'.
128 Once activated, preview-latex and its documentation will be accessible
129 via its menus (note that preview-latex requires AUCTeX to be loaded).
130 When you have loaded a LaTeX document (a sample document `circ.tex' is
131 included in the distribution, but most documents including math and/or
132 figures should do), you can use its menu or `C-c C-p C-d' (for
133 `Preview/Document'). Previews will now be generated for various
134 objects in your document. You can use the time to take a short look at
135 the other menu entries and key bindings in the `Preview' menu. You'll
136 see the previewed objects change into a roadworks sign when
137 preview-latex has determined just what it is going to preview. Note
138 that you can freely navigate the buffer while this is going on. When
139 the process is finished you will see the objects typeset in your buffer.
141 It is a bad idea, however, to edit the buffer before the roadworks signs
142 appear, since that is the moment when the correlation between the
143 original text and the buffer locations gets established. If the buffer
144 changes before that point of time, the previews will not be placed where
145 they belong. If you do want to change some obvious error you just
146 spotted, we recommend you stop the background process by pressing `C-c
149 To see/edit the LaTeX code for a specific object, put the point (the
150 cursor) on it and press `C-c C-p C-p' (for `Preview/at point'). It
151 will also do to click with the middle mouse button on the preview. Now
152 you can edit the code, and generate a new preview by again pressing
153 `C-c C-p C-p' (or by clicking with the middle mouse button on the icon
154 before the edited text).
156 If you are using the `desktop' package, previews will remain from one
157 session to the next as long as you don't kill your buffer. If you are
158 using XEmacs, you will probably need to upgrade the package to the
159 newest one; things are being fixed just as I am writing this.
161 4 Basic modes of operation
162 **************************
164 preview-latex has a number of methods for generating its graphics. Its
165 default operation is equivalent to using the `LaTeX' command from
166 AUCTeX. If this happens to be a call of PDFLaTeX generating PDF output
167 (you need at least AUCTeX 11.51 for this), then Ghostscript will be
168 called directly on the resulting PDF file. If a DVI file gets
169 produced, first Dvips and then Ghostscript get called by default.
171 The image type to be generated by Ghostscript can be configured with
173 M-x customize-variable RET preview-image-type RET
175 The default is `png' (the most efficient image type). A special
176 setting is `dvipng' in case you have the `dvipng' program installed.
177 In this case, `dvipng' will be used for converting DVI files and
178 Ghostscript (with a `PNG' device) for converting PDF files. `dvipng'
179 is much faster than the combination of Dvips and Ghostscript. You can
180 get downloads, access to its CVS archive and further information from
181 its project site (http://savannah.nongnu.org/projects/dvipng).
186 After the installation, documentation in the form of an info manual
187 will be available. You can access it with the standalone info reader
192 or by pressing `C-h i d m preview-latex <RET>' in Emacs. Once
193 preview-latex is activated, you can instead use `C-c C-p <TAB>' (or the
194 menu entry `Preview/Read documentation').
196 Depending on your installation, a printable manual may also be
197 available in the form of `preview-latex.dvi' or `preview-latex.ps'.
199 Detailed documentation for the LaTeX style used for extracting the
200 preview images is placed in `preview.dvi' in a suitable directory
201 during installation; on typical teTeX-based systems,
210 The preview-latex project is now part of AUCTeX and accessible as part
211 of the AUCTeX project page (http://savannah.gnu.org/projects/auctex).
212 You can get its files from the AUCTeX download area
213 (ftp://ftp.gnu.org/pub/gnu/auctex). As of AUCTeX 11.81, preview-latex
214 should already be integrated into AUCTeX, so no separate download will
217 You will also find `.rpm' files there for Fedora and possibly SuSE.
218 Anonymous CVS is available as well.
223 Bug reports should be sent by using `M-x preview-report-bug <RET>', as
224 this will fill in a lot of information interesting to us. If the
225 installation fails (but this should be a rare event), report bugs to
226 <bug-auctex@gnu.org>.
228 There is a general discussion list for AUCTeX which also covers
229 preview-latex, look at `http://lists.gnu.org/mailman/listinfo/auctex'.
230 For more information on the mailing list, send a message with just the
231 word "help" as subject or body to <auctex-request@gnu.org>. For the
232 developers, there is the <auctex-devel@gnu.org> list; it would probably
233 make sense to direct feature requests and questions about internal
234 details there. There is a low-volume read-only announcement list
235 available to which you can subscribe by sending a mail with "subscribe"
236 in the subject to <info-auctex-request@gnu.org>.
238 Offers to support further development will be appreciated. If you want
239 to show your appreciation with a donation to the main developer, you can
240 do so via PayPal to <dak@gnu.org>, and of course you can arrange for
241 service contracts or for added functionality. Take a look at the
242 `TODO' list for suggestions in that area.