1
Installation of AUCTeX is a bit more complicated, but we are working to
2
resolve the issues involved. Please report success/failure to us at
3
`auc-tex@sunsite.dk'. Here are the steps to perform:
5
1. The installation of AUCTeX will require the MSYS tool set from
6
`http://www.mingw.org'. If you have the Cygwin tool set from
7
`http://cygwin.com' installed, that should do just fine as well,
8
but it is quite larger and slower.
10
If you are installing AUCTeX with one of those sets for an Emacs
11
compiled in a different one, you should try to avoid tool-specific
12
path names like `/cygwin/c'. Instead, use the `c:' syntax. It
13
might also help to use forward slashes instead of the backward
14
slashes more typical for MS Windows: while backward slashes are
15
supposed to work if properly escaped in the shell, this is one
16
area easily overlooked by the developers. The same holds for file
17
or directory names with spaces in them. Of course, we want to
18
hear about any problems in that area.
20
Compiling Emacs is outside of the scope of this manual. AUCTeX
21
itself does not require a C compiler for installation.
23
2. Install GNU Emacs from `http://ftp.gnu.org/pub/gnu/windows/emacs/'
24
or XEmacs from `http://www.xemacs.org'.
26
3. You need a working TeX installation. One popular installation
4
The following are brief installation instructions for the impatient. In
5
case you don't understand some of this, run into trouble of some sort,
6
or need more elaborate information, refer to the detailed instructions
9
1. Install the prerequisites, i.e. GNU Emacs or XEmacs, MSYS or
10
Cygwin, a TeX system, and Ghostscript.
12
2. Open the MSYS shell or a Cygwin shell and change to the directory
13
containing the unzipped file contents.
17
For GNU Emacs: Many people like to install AUCTeX into the pseudo
18
file system hierarchy set up by the Emacs installation. Assuming
19
Emacs is installed in `C:/Program Files/Emacs' and the directory
20
for local additions of your TeX system, e.g. MikTeX, is
21
`C:/localtexmf', you can do this by typing the following statement
24
./configure --prefix='C:/Program Files/Emacs' \
25
--with-texmf-dir='C:/localtexmf'
27
For XEmacs: You can install AUCTeX as an XEmacs package. Assuming
28
XEmacs is installed in `C:/Program Files/XEmacs' and the directory
29
for local additions of your TeX system, e.g. MikTeX, is
30
`C:/localtexmf', you can do this by typing the following command at
33
./configure --with-xemacs='C:/Program Files/XEmacs/bin/xemacs' \
34
--with-texmf-dir='C:/localtexmf'
36
The commands above are examples for common usage. More on
37
configuration options can be found in the detailed installation
40
If the configuration script failed to find all required programs,
41
make sure that these programs are in your system path and add
42
directories containing the programs to the `PATH' environment
43
variable if necessary.
45
4. If there were no further error messages, type
49
In case there were, please refer to the detailed description below.
51
5. Finish the installation by typing
55
Detailed Installation Instructions
56
----------------------------------
58
Installation of AUCTeX under Windows is in itself not more complicated
59
than on other platforms. However, meeting the prerequisites might
60
require more work than on some other platforms, and feel less natural.
62
If you are experiencing any problems, even if you think they are of
63
your own making, be sure to report them to <auctex-devel@gnu.org> so
64
that we can explain things better in future.
66
Windows is a problematic platform for installation scripts. The main
67
problem is that the installation procedure requires consistent file
68
names in order to find its way in the directory hierarchy, and Windows
69
path names are a mess.
71
The installation procedure tries finding stuff in system search paths
72
and in Emacs paths. For that to succeed, you have to use the same
73
syntax and spelling and case of paths everywhere: in your system search
74
paths, in Emacs' `load-path' variable, as argument to the scripts. If
75
your path names contain spaces or other `shell-unfriendly' characters,
76
most notably backslashes for directory separators, place the whole path
77
in `"double quote marks"' whenever you specify it on a command line.
79
Avoid `helpful' magic file names like `/cygdrive/c' and
80
`C:\PROGRA~1\' like the plague. It is quite unlikely that the scripts
81
will be able to identify the actual file names involved. Use the full
82
paths, making use of normal Windows drive letters like ` 'C:/Program
83
Files/Emacs' ' where required, and using the same combination of upper-
84
and lowercase letters as in the actual files. File names containing
85
shell-special characters like spaces or backslashes (if you prefer that
86
syntax) need to get properly quoted to the shell: the above example
87
used single quotes for that.
89
Ok, now here are the steps to perform:
91
1. You need to unpack the AUCTeX distribution (which you seemingly
92
have done since you are reading this). It must be unpacked in a
93
separate installation directory outside of your Emacs file
94
hierarchy: the installation will later copy all necessary files to
95
their final destination, and you can ultimately remove the
96
directory where you unpacked the files.
98
Line endings are a problem under Windows. The distribution
99
contains only text files, and theoretically most of the involved
100
tools should get along with that. However, the files are
101
processed by various utilities, and it is conceivable that not all
102
of them will use the same line ending conventions. If you
103
encounter problems, it might help if you try unpacking (or
104
checking out) the files in binary mode, if your tools allow that.
106
If you don't have a suitable unpacking tool, skip to the next
107
step: this should provide you with a working `unzip' command.
109
2. The installation of AUCTeX will require the MSYS tool set from
110
`http://www.mingw.org' or the Cygwin tool set from
111
`http://cygwin.com'. The latter is slower and larger (the download
112
size of the base system is about 15 MB) but comes with a package
113
manager that allows for updating the tool set and installing
114
additional packages like, for example, the spell checker aspell.
116
If Cygwin specific paths like `/cygdrive/c' crop up in the course
117
of the installation, using a non-Cygwin Emacs could conceivably
118
cause trouble. Using Cygwin either for everything or nothing
119
might save headaches, _if_ things don't work out.
121
3. Install a current version of XEmacs from `http://www.xemacs.org'
122
or try getting and compiling a developer version of Emacs 22 from
123
Savannah (http://savannah.gnu.org/cvs/?group=emacs). Compiling
124
Emacs is outside of the scope of this manual. Precompiled versions
125
currently happen to be available at
126
`http://www.crasseux.com/emacs/' and `http://nqmacs.sf.net/'.
128
If you don't want to use a developer version and Emacs 22 has not
129
yet been released, it is also possible to use an Emacs 21 binary
130
from `http://ftp.gnu.org/pub/gnu/windows/emacs/', but then you
131
should disable the installation of preview-latex (it will not
132
work). Since the developer version has seen quite a few
133
improvements relevant also for other features of AUCTeX, we really
134
recommend you give it a try.
136
4. You need a working TeX installation. One popular installation
27
137
under Windows is MikTeX (http://www.miktex.org). Another much more
28
extensive system is TeX live (http://www.tug.org/texlive) which is
138
extensive system is TeX Live (http://www.tug.org/texlive) which is
29
139
rather close to its Unix cousins.
31
4. Now the fun stuff starts. Unpack the AUCTeX distribution into some
32
installation directory. *Do not* unpack it right into your Emacs'
33
own directories: the installation will copy the material that
34
needs to be placed there. Keep the installation directory
35
separate: you can remove its contents after installation
36
completes. Since you are reading this, you probably have already
37
unpacked AUCTeX, but it should still be easy to move it elsewhere
40
5. Ready for takeoff. Start some shell (typically `bash') capable of
141
5. A working copy of Ghostscript (http://www.cs.wisc.edu/~ghost) is
142
required for preview-latex operation. Examining the output from
144
on a Windows command line should tell you whether your Ghostscript
145
supports the `png16m' device needed for PNG support. MikTeX
146
apparently comes with its own Ghostscript called `mgs.exe'.
148
6. Perl (http://www.perl.org) is needed for rebuilding the
149
documentation if you are working with a copy from CVS or have
150
touched documentation source files in the preview-latex part. If
151
the line endings of the file `preview/latex/preview.dtx' don't
152
correspond with what Perl calls `\n' when reading text files,
153
you'll run into trouble.
155
7. Now the fun stuff starts. If you have not yet done so, unpack the
156
AUCTeX distribution into a separate directory after rereading the
157
instructions for unpacking above.
159
8. Ready for takeoff. Start some shell (typically `bash') capable of
41
160
running `configure', change into the installation directory and
42
161
call `./configure' with appropriate options.
44
163
Typical options you'll want to specify will be
45
`--prefix=DRIVE:/PATH/TO/EMACS-DIRECTORY'
46
which makes sure that (1) the AUCTeX manual will be installed
47
in the `info/' directory of your Emacs installation and (2)
48
the automatically generated global style hooks will be
49
installed in the `var/' directory of your Emacs installation.
50
If you are collecting stuff like that in a central directory
51
hierarchy (not untypical with Cygwin), you might want to
52
specify that here instead. You stand a good chance that this
53
will be the only option you need to supply, as long as your
54
TeX-related executables are in your system path, which they
55
better be for AUCTeX's operation, anyway.
164
`--prefix=DRIVE:/PATH/TO/EMACS-HIERARCHY'
165
which tells `configure' where to perform the installation. It
166
may also make `configure' find Emacs or XEmacs automatically;
167
if this doesn't happen, try one of `--with-emacs' or
168
`--with-xemacs' as described below. All automatic detection
169
of files and directories restricts itself to directories
170
below the PREFIX or in the same hierarchy as the program
171
accessing the files. Usually, directories like `man',
172
`share' and `bin' will be situated right under PREFIX.
174
This option also affects the defaults for placing the Texinfo
175
documentation files and automatically generated style hooks.
177
If you have a central directory hierarchy (not untypical with
178
Cygwin) for such stuff, you might want to specify its root
179
here. You stand a good chance that this will be the only
180
option you need to supply, as long as your TeX-related
181
executables are in your system path, which they better be for
182
AUCTeX's operation, anyway.
58
185
if you are installing for a version of Emacs. You can use
59
`--with-emacs=/PATH/TO/EMACS' to specify the name of the
186
`--with-emacs=DRIVE:/PATH/TO/EMACS' to specify the name of the
60
187
installed Emacs executable, complete with its path if
61
188
necessary (if Emacs is not within a directory specified in
62
your PATH environment setting).
189
your `PATH' environment setting).
65
192
if you are installing for a version of XEmacs. Again, you
66
can use `--with-xemacs=/PATH/TO/XEMACS' to specify the name
67
of the installed XEmacs executable complete with its path if
68
necessary. It may also be necessary to specify this option
69
if a copy of Emacs is found in your PATH environment setting,
70
but you still would like to install a copy of AUCTeX for
74
This may be needed for GNU Emacs installation, but hopefully
75
`configure' should figure this out by itself. Don't use this
76
for XEmacs, rather use
78
`--with-packagedir=/DIR'
79
which gives the location of the package directory for XEmacs
80
where stuff should be installed. Again, hopefully this is not
83
`--with-auto-dir=/DIR'
193
can use `--with-xemacs=DRIVE:/PATH/TO/XEMACS' to specify the
194
name of the installed XEmacs executable complete with its
195
path if necessary. It may also be necessary to specify this
196
option if a copy of Emacs is found in your `PATH' environment
197
setting, but you still would like to install a copy of AUCTeX
200
`--with-packagedir=DRIVE:/DIR'
201
is an XEmacs-only option giving the location of the package
202
directory. This will install and activate the package.
203
Emacs uses a different installation scheme:
205
`--with-lispdir=DRIVE:/PATH/TO/SITE-LISP'
206
This Emacs-only option tells a place in `load-path' below
207
which the files are situated. The startup files `auctex.el'
208
and `preview-latex.el' will get installed here unless a
209
subdirectory `site-start.d' exists which will then be used
210
instead. The other files from AUCTeX will be installed in a
211
subdirectory called `auctex'.
213
If you think that you need a different setup, please refer to
214
the full installation instructions in the `INSTALL' file.
216
`--with-auto-dir=DRIVE:/DIR'
84
217
Directory containing automatically generated information.
85
218
You should not normally need to set this, as `--prefix'
86
219
should take care of this.
88
Some additional information about the above options may be found in
89
the `Configure' section in the `INSTALL' file.
91
6. If you need to use the prebuilt documentation (see above), now is
92
the time to unpack it over the rest of the installation directory.
94
7. Run `make' in the installation directory (we have had one report
95
that Emacs did not manage to byte compile the Elisp files, and
96
that had to be done by hand. No idea about what might have gone
99
8. Run `make install' in the installation directory.
101
9. For GNU Emacs, the recommended way to activate AUCTeX is to add the
102
following line to your `.emacs' file:
106
The configuration for Windows systems is probably not quite
107
fitting. Instead of loading `tex-site.el' in that manner, you
108
might want to load `tex-mik.el' (for MikTeX) or `tex-fptex' (for
109
fpTeX) instead. Those will lead to somewhat more appropriate
110
values for your system. You can always use
112
M-x customize-group <RET> AUCTeX <RET>
222
Use this option if your Emacs version is unable to support
223
image display. This will be the case if you are using a
224
native variant of Emacs 21.
226
`--with-texmf-dir=DRIVE:/DIR'
227
This will specify the directory where your TeX installation
228
sits. If your TeX installation does not conform to the TDS
229
(TeX directory standard), you may need to specify more
230
options to get everything in place:
232
For more information about any of the above and additional
233
options, see the `Configure' section in the `INSTALL' file.
235
Calling `./configure --help=recursive' will tell about other
236
options, but those are almost never required.
238
Some executables might not be found in your path. That is not a
239
good idea, but you can get around by specifying environment
240
variables to `configure':
241
GS="DRIVE:/PATH/TO/GSWIN32C.EXE" ./configure ...
242
should work for this purpose. `gswin32c.exe' is the usual name for
243
the required _command line_ executable under Windows; in contrast,
244
`gswin32.exe' is likely to fail.
246
As an alternative to specifying variables for the `configure' call
247
you can add directories containing the required executables to the
248
`PATH' variable of your Windows system. This is especially a good
249
idea if Emacs has trouble finding the respective programs later
250
during normal operation.
252
9. Run `make' in the installation directory.
254
10. Run `make install' in the installation directory.
256
11. With XEmacs, AUCTeX and preview-latex should now be active by
257
default. With Emacs, activation depends on a working
258
`site-start.d' directory or similar setup, since then the startup
259
files `auctex.el' and `preview-latex.el' will have been placed
260
there. If this has not been done, you should be able to load the
261
startup files manually with
262
(load "auctex.el" nil t t)
263
(load "preview-latex.el" nil t t)
264
in either a site-wide `site-start.el' or your personal startup file
265
(usually accessible as `~/.emacs' from within Emacs and
266
`~/.xemacs/init.el' from within XEmacs).
268
The default configuration of AUCTeX is probably not the best fit
269
for Windows systems. You might want to additionally use
273
in order to get more appropriate values for MikTeX and fpTeX,
278
M-x customize-group RET AUCTeX RET
114
280
in order to customize more stuff, or use the `Customize' menu.
116
10. Load a `.tex' file Emacs or XEmacs and see if you get the
117
`Command' menu. Try using that to LaTeX the file.
282
12. Load `preview/circ.tex' into Emacs or XEmacs and see if you get the
283
`Command' menu. Try using it to LaTeX the file.
285
13. Check whether the `Preview' menu is available in this file. Use it
286
to generate previews for the document.
288
If this barfs and tells you that image type `png' is not
289
supported, try adding the line
291
(setq preview-image-type 'pnm)
293
at the end of your installed version of `preview-latex.el'. If
294
this helps, complain to wherever you got your Emacs from: all
295
current Emacs/XEmacs versions capable of running preview-latex by
296
now can be compiled to support PNG images. Which is important,
297
because PNM files take away *vast* amounts of disk space, and thus
298
also of load/save time.
119
300
Well, that about is all. Have fun!
added
removed
INSTALL.windows
