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