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