Source

auctex / texi / install.texi

Full commit
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
@include macros.texi
@ifset rawfile
@chapter Installing @AUCTeX{}

@end ifset
@c -----------------------
Installing @AUCTeX{} should be simple: merely @command{./configure},
@command{make}, and @code{make install}. This does not yet activate the
package, but merely makes it available. See @ref{Loading the package}
for the activation. Please read through this document fully before
installing anything.  The installation procedure has changed as
compared to earlier versions.  In particular, note that there is some
additional information for @w{MS Windows} installations in
@ifset rawfile
the file @file{INSTALL.windows}.
@end ifset
@ifclear rawfile
@xref{Installation under MS Windows}.
@end ifclear

@ifclear rawfile
@menu
* Prerequisites::
* Configure::
* Build/install::
* Loading the package::
* Advice for package providers::
* Advice for non-privileged users::
* Installation under MS Windows::
* Customizing::
@end menu
@end ifclear

@node Prerequisites, Configure,, Installation
@section Prerequisites

@itemize @bullet
@item A recent version of @w{Emacs 21}, alternatively @w{XEmacs 21}.

Support for @w{Emacs 20} has been dropped in favor of getting more
important work done.  For XEmacs, you need at least version 1.84 of the
@code{xemacs-base} package (released on 01/27/2004) or a sumo tarball
dated 02/02/2004 or newer for compiling @AUCTeX{} because of non-trivial
changes in @file{easy-mmode.el}: please use the XEmacs package system
for upgrading if necessary.  The current developers don't have the
resources for providing backward compatibility to earlier versions.

@item A working @LaTeX{} installation

This is not really needed to @emph{install} the package, but will be
required for useful operation of it. The elisp of @AUCTeX{} will probably
run without @LaTeX{}, but you will find relatively little use for it.

@item The @code{texinfo} package

This is needed for building the documentation. If you don't have this,
or you have a too old version of it (try building and you'll find out),
you may download a separate tar file with the prebuilt documentation
from Savannah and install it over the main unpacked tar archive.
@end itemize

@ignore
For some known issues with various software, see
@ifset rawfile
the @file{PROBLEMS} file.
@end ifset
@ifclear rawfile
@ref{Known problems}.
@end ifclear
@end ignore

@node Configure, Build/install, Prerequisites, Installation
@section Configure

The first step is to configure the source code, telling it where
various files will be.  To do so, run

@example
./configure @var{options}
@end example

(Note: if you have fetched @AUCTeX{} from @acronym{CVS} rather than
a regular release, you will have to first generate @command{./configure} by
running @command{autogen.sh} in the @file{auctex} directory.)

On many machines, you will not need to specify any options, but if
@command{configure} cannot determine something on its own, you'll need to
help it out with one of these options:

@table @code
@item --with-emacs[=@var{/path/to/emacs}]
If you are using a pretest which isn't in your @code{$PATH}, or
@command{configure} is not finding the right Emacs executable, you can
specify it with this option.

@item --with-xemacs[=@var{/path/to/xemacs}]
Configure for generation under XEmacs (Emacs is the default).  Again,
the name of the right XEmacs executable can be specified, complete with
path if necessary.

@item --with-lispdir=@var{/dir}
This tells where to install Emacs Lisp files.  Normally, this option is
unnecessary, but may be used if you don't like the directory that
configure is suggesting.

@item --with-packagedir=@var{/dir}
This tells where to install the XEmacs Package.  Again, this option is
normally unnecessary, but may be used if you don't like the directory
that configure is suggesting, and you know that XEmacs regards the
directory you specify as a package directory.

If you are installing @AUCTeX{} for a single user, and you have
installed no XEmacs packages as that user before, then @command{configure}
may try to install @AUCTeX{} in the systemwide package directory
(that it cannot write to), causing installation to fail.  In that case,
a good value for this option is @file{~/.xemacs/xemacs-packages}, as
XEmacs looks there for per-user packages by default.

@item --with-tex-input-dirs=@var{/dir-1/;/dir-2/;...;/dir-N/}
This option allows to specify the directories to be used for file
searches, e.g. for completion of @LaTeX{} or Bib@TeX{} style file names.
They will be used in the variable @code{TeX-macro-global}.

Normally only the subdirectories @file{tex/} and @file{bibtex/bst/}
below the used texmf trees should be relevant.  Putting the roots of
texmf trees here is possible but may slow down file searching.

The directories should be separated by semicolons and each has to end
with a directory separator, i.e. a slash or a backslash respectively.

@item --with-auto-dir=@var{/dir}
You can use this option to specify the directory containing
automatically generated information.  It is not necessary for most
@TeX{} installs, but may be used if you don't like the directory that
configure is suggesting.

@item --help
This is not an option specific to @AUCTeX{}. A number of standard
options to @command{configure} exist, and we do not have the room to
describe them here; a short description of each is available, using
@code{--help}.

@end table

@node Build/install, Loading the package, Configure, Installation
@section Build/install

@cindex Installation
@cindex Make

Once @command{configure} has been run, simply enter

@example
make
@end example
@noindent
at the prompt to byte-compile the lisp files, and build the
documentation files. To install the files into the locations chosen
earlier, type

@example
make install
@end example

@noindent
You may need special privileges to install, e.g., if you are installing
into system directories.

@node Loading the package, Advice for package providers, Build/install, Installation
@section Loading the package

@cindex @file{.emacs}

First you should make sure that @AUCTeX{} gets loaded.  You then need to
place a few lines in your personal @file{.emacs} file (or a site-wide
configuration file).

For XEmacs, if you specified a valid package directory during
installation, or none at all, then XEmacs installation should do
everything necessary in order to install @AUCTeX{} as a package
and activate it.  Restarting XEmacs should then make the package
visible, and @kbd{C-c C-c} should give you a command prompt.

If you used @code{--with-packagedir}, you have to make sure that the
directory @file{lisp/auctex} under the directory you specified is in
XEmacs' @code{load-path} variable.

For GNU Emacs, the recommended way to activate @AUCTeX{} is to add the
following line to your @file{.emacs} file:

@example
(require 'tex-site)
@end example

If you used @code{--with-lispdir}, you have to make sure that the
directory specified is in Emacs' @code{load-path} variable, so that you
would instead use, e.g.,

@example
(setq load-path (cons "~/elisp" load-path))
(require 'tex-site)
@end example

For site-wide activation in GNU Emacs, see
@ifset rawfile
below.
@end ifset
@ifclear rawfile
@xref{Advice for package providers}.
@end ifclear

That is all.  There are other ways of achieving the equivalent thing,
but we don't mention them here any more since they are not better, and
people got confused into trying everything at once.

@node Advice for package providers, Advice for non-privileged users, Loading the package, Installation
@section Providing @AUCTeX{} as a package

As a package provider, you should make sure that your users will be
served best according to their intentions, and keep in mind that a
system might be used by more than one user, with different preferences.
The use of packages should in general not impact performance negatively
if a user chooses not to employ it, but should be as convenient as
possible. The policy with regard to @AUCTeX{} has been to @emph{refrain}
from activating it automatically when it is installed as a package. This
is reasonable because

@itemize @bullet
@item Emacs comes with a simpler default @TeX{} mode with different
keybindings.  Some users might prefer that.
@item @AUCTeX{} is activated via @code{(require 'tex-site)}.  Once this
has happened, it is not possible to get back the original @TeX{} mode.
A site-wide default would for this reason be hard to override.
@end itemize

If, however, you are certain that the users all prefer @AUCTeX{}, you
may place the following line in @file{default.el}:

@example
(require 'tex-site)
@end example

XEmacs uses a package system.  The default @AUCTeX{} installation
should cater for everything necessary in that case.

@ignore
For @acronym{RPM} files we include a @file{preview-latex.spec} file in
the tarball distribution, suitable for recent RedHat systems, that
should do just that.
@end ignore

@node Advice for non-privileged users, Installation under MS Windows, Advice for package providers, Installation
@section Installation for non-privileged users

Often people without system administration privileges want to install
software for their private use.  In that case you need to specify more
options top the @command{configure} script.  For XEmacs users, this is
fairly easy, because the XEmacs package system has been designed to make
this sort of thing practical: but GNU Emacs users (and XEmacs users for
whom the package system is for some reason misbehaving) may need to do a
little more work.

GNU Emacs users can solve this problem by using the @option{--prefix}
option to the @command{configure} script, and let it point to the personal
home directory.  In that way, resulting binaries will be installed under
the @file{bin} subdirectory of your home directory, manual pages under
@file{man} and so on.  That way, it is reasonably easy to maintain a
bunch of additional packages, since the prefix argument is supported by
most @command{configure} scripts.

You'll have to add something like
@file{/home/myself/share/emacs/site-lisp} to your @code{load-path}
variable, if it isn't there already.

XEmacs users can achieve the same end by pointing @command{configure} at an
appropriate package directory (normally
@option{--with-packagedir=~/.xemacs/xemacs-packages} will serve).  This
should only need to be done once, and should be needed fairly rarely; if
you have installed any personal XEmacs packages before, @command{configure}
should detect that, and automatically install @AUCTeX{} there too;
equally, if you have installed @AUCTeX{} somewhere searched by
XEmacs, @AUCTeX{} should be automatically reinstalled over that
copy.

(@command{configure} may guess wrong if the site administrator has
installed @AUCTeX{} somewhere else: if so, just use the
@option{--with-packagedir} option to override @command{configure}'s
choice.)

But there is another problem: perhaps you want to make it easy for other
users to share parts of your personal Emacs configuration.  In general,
you can do this by writing @samp{~myself/} anywhere where you specify
paths to something installed in your personal subdirectories, not merely
@samp{~/}, since the latter, when used by other users, will point to
non-existent files.

For yourself, it will do to manipulate environment variables in your
@file{.profile} resp.@: @file{.login} files.  But if people will be
copying just Elisp files, their copies will not work.  While it would
in general be preferable if the added components where available from
a shell level, too (like when you call the standalone info reader, or
try using @file{preview.sty} for functionality besides of Emacs
previews), it will be a big help already if things work from inside
of Emacs.

Here is how to do the various parts:

@subheading Making the Elisp available

In XEmacs, you should ask the other users to add symbolic links in their
@file{~/.xemacs/xemacs-packages/lisp},
@file{~/.xemacs/xemacs-packages/info} and
@file{~/.xemacs/xemacs-packages/etc} directories. (Alas, there is
presently no easy programmatic way to do this, except to have a script
do the symlinking for them.)

In GNU Emacs, you'll want the invocation lines described
@ifset rawfile
above.
@end ifset
@ifclear rawfile
in @xref{Loading the package}.
@end ifclear
In addition, you'll want a line such as

@lisp
(add-to-list 'load-path "~myself/share/emacs/site-lisp/preview")
@end lisp

@subheading Making the Info files available

While for yourself, you'll probably want to manipulate the
@samp{INFOPATH} variable; for access inside of Elisp something like
the following might be convenient:

@lisp
(eval-after-load 'info
   '(add-to-list 'Info-directory-list "~myself/info"))
@end lisp

In XEmacs, as long as XEmacs can see the package, there should be no
need to do anything at all; the info files should be immediately
visible.  However, you might want to set @samp{INFOPATH} anyway, for the
sake of standalone readers outside of XEmacs. (The info files in XEmacs
are normally in @file{~/.xemacs/xemacs-packages/info}.)

@ifclear rawfile
@node Installation under MS Windows, Customizing, Advice for non-privileged users, Installation
@section Installation under MS Windows
@include wininstall.texi
@end ifclear

@node Customizing,  , Installation under MS Windows, Installation
@section Customizing
@cindex Site initialization
@cindex Initialization
@cindex @file{tex-site.el}
@cindex Personal customization
@cindex Site customization
@cindex Customization
@cindex Customization, personal
@cindex Customization, site
Most of the site-specific customization should already have happened
during configuration of @AUCTeX{}.  Any further customization can be
done with customization buffers directly in Emacs.  Just type @kbd{M-x
customize-group RET AUCTeX RET} to open the customization group for
@AUCTeX{} or use the menu entries provided in the mode menus.  Editing
the file @file{tex-site.el} as suggested in former versions of @AUCTeX{}
should not be done anymore because the installation routine will
overwrite those changes.

You might check some variables with a special significance.  They are
accessible directly by typing @kbd{M-x customize-variable RET <variable>
RET}.

@defopt TeX-lisp-directory
The directory where you installed the @AUCTeX{} lisp files.
@end defopt

This variable is set automatically during configuration.  If you don't
issue a @code{make install}, for example if you don't want to install
@AUCTeX{} in a different place, you will have to set this variable
manually to the location of the compiled files.  It is generally
advisable to do a full installation including @code{make install}
because program and documentation files will be copied to their proper
places.

@defopt TeX-macro-global
Directories containing the site's @TeX{} style files.
@end defopt

Normally, @AUCTeX{} will only allow you to complete macros and
environments which are built-in, specified in @AUCTeX{} style files or
defined by yourself.  If you issue the @kbd{M-x
TeX-auto-generate-global} command after loading @AUCTeX{}, you will be
able to complete on all macros available in the standard style files
used by your document.  To do this, you must set this variable to a list
of directories where the standard style files are located.  The
directories will be searched recursively, so there is no reason to list
subdirectories explicitly.  Automatic configuration will already have
set the variable for you if it could use the program @samp{kpsewhich}.
In this case you normally don't have to alter anything.

@section Contributed files

There are several files that are not part of @AUCTeX{} proper, but
included in the distribution in case they are useful.

@table @file
@item bib-cite.el
Better support for bibliographies and much more.

@item tex-jp.el
Support for Japanese.

@end table

They can be installed together with @AUCTeX{} by executing @command{make
contrib} and @command{make install-contrib}.  Read the comments in the
start of each file for more information about how to use the files, what
they do, and who wrote and maintains them.