/[auctex]/auctex/doc/install.texi
ViewVC logotype

Diff of /auctex/doc/install.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.30 by dak, Mon May 2 21:34:02 2005 UTC revision 1.31 by dak, Fri May 20 22:44:39 2005 UTC
# Line 10  Line 10 
10  @end ifclear  @end ifclear
11    
12  Installing @AUCTeX{} should be simple: merely @command{./configure},  Installing @AUCTeX{} should be simple: merely @command{./configure},
13  @command{make}, and @code{make install}.  On many systems, this will  @command{make}, and @code{make install} for a standard site-wide
14  already activate the package, making its modes the default instead of  installation (most other installations can be done by specifying a
15  the built-in modes of Emacs.  If this is not the case, consult  @option{--prefix=@dots{}} option).
16  @ref{Loading the package}. Please read through this document fully  
17  before installing anything.  The installation procedure has changed as  On many systems, this will already activate the package, making its
18  compared to earlier versions.  In particular, note that there is some  modes the default instead of the built-in modes of Emacs.  If this is
19  additional information for @w{MS Windows} installations in  not the case, consult @ref{Loading the package}.  Please read through
20    this document fully before installing anything.  The installation
21    procedure has changed as compared to earlier versions.  Users of @w{MS
22    Windows} are asked to consult
23  @ifset rawfile  @ifset rawfile
24  the file @file{INSTALL.windows}.  the file @file{INSTALL.windows}.
25  @end ifset  @end ifset
# Line 61  the file @file{INSTALL.windows}. Line 64  the file @file{INSTALL.windows}.
64  @end ifclear  @end ifclear
65    
66  @itemize @bullet  @itemize @bullet
67  @item A recent version of @w{Emacs 21}, alternatively @w{XEmacs 21}.  @item A recent version of Emacs, alternatively XEmacs
68    
69  Support for @w{Emacs 20} has been dropped.  For XEmacs, you need at  @w{Emacs 20} is no longer supported, and neither is XEmacs with a
70  least version 1.84 of the @code{xemacs-base} package (released on  version of @code{xemacs-base} older than 1.84 (released in sumo from
71  01/27/2004) or a sumo tarball dated 02/02/2004 or newer for compiling  02/02/2004).  Using @previewlatex{} requires a version of Emacs compiled
72  @AUCTeX{} because of non-trivial changes in @file{easy-mmode.el}:  with image support.  This means that @w{Emacs 21} will work only in the
73  please use the XEmacs package system for upgrading if necessary.  The  version for X11: for Windows and MacOSX, you need to use @w{Emacs 22}
74  current developers don't have the resources for providing backward  (which is not yet released) or a developer version.  Since the developer
75  compatibility to earlier versions.  version is quite stable by now and features four more years of
76    development and bugfixes, we recommend its use even for X11-based
77  @item A working @LaTeX{} installation  platforms.  You can get it here:
78    
79  This is not really needed to @emph{install} the package, but will be  @table @b
80  required for useful operation of it. The elisp of @AUCTeX{} will probably  @item Windows
81  run without @LaTeX{}, but you will find relatively little use for it.  Precompiled versions are available from @uref{http://www.crasseux.com}
82    and @uref{http://nqmacs.sf.net}.
83    @item MacOSX
84    A precompiled version including an installer as well as preinstalled
85    versions of @AUCTeX{} and @previewlatex{} is available from
86    @uref{http://yaced.sf.net}.  A different port (without @AUCTeX{} and
87    @previewlatex{}) is
88    @uref{http://www.apple.com/downloads/macosx/unix_open_source/carbonemacspackage.html}.
89    Some changes and patches attempt to make Emacs behave more in line with
90    MacOSX.
91    @item Debian Linux
92    @uref{http://sadleder.de/debian/}
93    @item Fedora Linux
94    @uref{http://people.redhat.com/petersen/emacs/}
95    @item Self-compiled
96    Compiling Emacs yourself requires a C compiler and a number of tools and
97    development libraries.  Details are beyond the scope of this manual.
98    Instructions for checking out the source code can be found at
99    @uref{http://savannah.gnu.org/cvs/?group=emacs}.
100    @end table
101    
102    If you really need to use @w{Emacs 21} on platforms where this implies
103    missing image support, you should disable the installation of
104    @previewlatex{} (see below).
105    
106    While XEmacs (version 21.4.15, 21.4.17 or later) is supported, doing
107    this in a satisfactory manner has proven to be difficult.  This is
108    partly due to technical shortcomings, partly because fixing problems
109    exposed by @AUCTeX{} is of minor importance to XEmacs developers.  If
110    @AUCTeX{} is your main application for XEmacs, you are likely to get
111    better results and support by switching to Emacs.  It does not appear
112    like this will change anytime soon.
113    
114    @item A working @TeX{} installation
115    
116    Well, @AUCTeX{} would be pointless without that.  Processing
117    documentation requires @TeX{}, @LaTeX{} and Texinfo during installation.
118    @previewlatex{} requires Dvips for its operation in @acronym{DVI}
119    mode.  The default configuration of @AUCTeX{} is tailored for
120    te@TeX{}-based distributions, but can be adapted easily.
121    
122    @item A recent Ghostscript
123    
124    This is needed for operation of @previewlatex{} in both @acronym{DVI}
125    and @acronym{PDF} mode.  Most versions of Ghostscript nowadays in use
126    should work fine (version 7.0 and newer).  If you encounter problems,
127    check
128    @ifset rawfile
129    the @file{PROBLEMS} file.
130    @end ifset
131    @ifclear rawfile
132    @ref{Problems with Ghostscript,,,preview-latex,the @previewlatex{} manual}.
133    @end ifclear
134    
135  @item The @code{texinfo} package  @item The @code{texinfo} package
136    
137  Strictly speaking, you can get away without it if you are building  Strictly speaking, you can get away without it if you are building
138  from the distribution tarball, have not modified any files and don't  from the distribution tarball, have not modified any files and don't
139  need a printed version of the manual: the pregenerated info file is  need a printed version of the manual: the pregenerated info file is
140  included in the tarball.  included in the tarball.  At least @w{version 4.0} is required.
141    
142  @end itemize  @end itemize
143    
 @ignore  
144  For some known issues with various software, see  For some known issues with various software, see
145  @ifset rawfile  @ifset rawfile
146  the @file{PROBLEMS} file.  the @file{PROBLEMS} file.
147  @end ifset  @end ifset
148  @ifclear rawfile  @ifclear rawfile
149  @ref{Known problems}.  @ref{Known problems,,,preview-latex,the @previewlatex{} manual}.
150  @end ifclear  @end ifclear
 @end ignore  
151    
152  @node Configure  @node Configure
153  @section Configure  @section Configure
# Line 107  various files will be.  To do so, run Line 160  various files will be.  To do so, run
160  @end example  @end example
161    
162  (Note: if you have fetched @AUCTeX{} from @acronym{CVS} rather than  (Note: if you have fetched @AUCTeX{} from @acronym{CVS} rather than
163  a regular release, you will have to first generate @command{./configure} by  a regular release, you will have to first follow the instructions in
164  running @command{./autogen.sh} in the @file{auctex} directory.)  @file{README.CVS}).
165    
166  On many machines, you will not need to specify any options, but if  On many machines, you will not need to specify any options, but if
167  @command{configure} cannot determine something on its own, you'll need to  @command{configure} cannot determine something on its own, you'll need to
# Line 152  installed (the bulk will get installed i Line 205  installed (the bulk will get installed i
205  @file{./configure} should figure this out by itself.  @file{./configure} should figure this out by itself.
206    
207  @item --with-auctex-startfile=@file{auctex.el}  @item --with-auctex-startfile=@file{auctex.el}
208  This is the name of the startup file.  If @var{lispdir} contains a  @itemx --with-preview-startfile=@file{preview-latex.el}
209  subdirectory @file{site-start.d}, @var{startfile} defaults to  This is the name of the respective startup files.  If @var{lispdir}
210  @file{site-start.d/auctex.el}, and @file{site-start.el} should  contains a subdirectory @file{site-start.d}, the start files are
211  load it automatically.  Please be aware that you must not move the  placed there, and @file{site-start.el} should
212  @var{startfile} after installation since other files are found  load them automatically.  Please be aware that you must not move the
213  @emph{relative} to it.  start files after installation since other files are found
214    @emph{relative} to them.
215    
216  @item --with-packagelispdir=@file{auctex}  @item --with-packagelispdir=@file{auctex}
217  This is the directory where the bulk of the package gets located.  The  This is the directory where the bulk of the package gets located.  The
# Line 173  configure is suggesting. Line 227  configure is suggesting.
227  This is not an option specific to @AUCTeX{}. A number of standard  This is not an option specific to @AUCTeX{}. A number of standard
228  options to @command{configure} exist, and we do not have the room to  options to @command{configure} exist, and we do not have the room to
229  describe them here; a short description of each is available, using  describe them here; a short description of each is available, using
230  @code{--help}.  @code{--help}.  If you use @samp{--help=recursive}, then also
231    @previewlatex{}-specific options will get listed.
232    
233  @item --disable-preview  @item --disable-preview
234  This disables configuration and installation of @previewlatex{}.  This  This disables configuration and installation of @previewlatex{}.  This
# Line 183  should, if possible, refrain from distri Line 238  should, if possible, refrain from distri
238  @previewlatex{} separately in order to avoid confusion and upgrade  @previewlatex{} separately in order to avoid confusion and upgrade
239  hassles if users install partial packages on their own.  hassles if users install partial packages on their own.
240    
241  @item --with-preview-startfile  @item --with-texmf-dir=@var{/dir}@*--without-texmf-dir
242  @itemx --without-texmf-dir  @cindex preview-install-styles
243  @itemx --with-texmf-dir  This option is used for specifying a @acronym{TDS}-compliant directory
244  @itemx --with-tex-dir  hierarchy.  Using @code{--with-texmf-dir=@var{/dir}} you can specify
245  @itemx --with-doc-dir  where the @TeX{} @acronym{TDS} directory hierarchy resides, and the
246    @TeX{} files will get installed in
247  Those options are explained in  @file{@var{/dir}/tex/latex/preview/}.
248  @ifset rawfile  
249  the file @file{preview/INSTALL}.  If you use the @code{--without-texmf-dir} option, the @TeX{}-related
250  @end ifset  files will be kept in the Emacs Lisp tree, and at runtime the
251  @ifclear rawfile  @env{TEXINPUTS} environment variable will be made to point there.  You
252  @ref{Installation,,,preview-latex,The @previewlatex{} Manual}.  can install those files into your own @TeX{} tree at some later time
253  @end ifclear  with @kbd{@key{M-x} preview-install-styles @key{RET}}.
254    
255  In a nutshell, if you don't want changes in your @LaTeX{} installation  @item --with-tex-dir=@var{/dir}
256  and not want to make the @LaTeX{} style files of @previewlatex{}  If you want to specify an exact directory for the preview @TeX{} files,
257  available outside of Emacs and nothing installed outside of the Emacs  use @code{--with-tex-dir=@var{/dir}}. In this case, the files will be
258  tree, then you'll specify @samp{--without-texmf-dir}.  placed in @file{@var{/dir}}, and you'll also need the following option:
259    
260    @item --with-doc-dir=@var{/dir}
261    This option may be used to specify where the @TeX{} documentation goes.
262    It is to be used when you are using @code{--with-tex-dir=@var{/dir}},
263    but is normally not necessary otherwise.
264  @end table  @end table
265    
266  @node Build/install  @node Build/install
# Line 215  Once @command{configure} has been run, s Line 275  Once @command{configure} has been run, s
275  make  make
276  @end example  @end example
277  @noindent  @noindent
278  at the prompt to byte-compile the lisp files, and build the  at the prompt to byte-compile the lisp files, extract the @TeX{} files
279  documentation files. To install the files into the locations chosen  and build the documentation files.  To install the files into the
280  earlier, type  locations chosen earlier, type
281    
282  @example  @example
283  make install  make install
284  @end example  @end example
285    
 @noindent  
286  You may need special privileges to install, e.g., if you are installing  You may need special privileges to install, e.g., if you are installing
287  into system directories.  into system directories.
288    
289  @node Loading the package  @node Loading the package
290  @section Loading the package  @section Loading the package
   
291  @cindex @file{.emacs}  @cindex @file{.emacs}
292    
293  First you should make sure that @AUCTeX{} gets loaded.  You then need to  You can detect the successful activation of @AUCTeX{} and
294  place a few lines in your personal @file{.emacs} file (or a site-wide  @previewlatex{} in the menus after loading a @LaTeX{} file like
295  configuration file).  @file{preview/circ.tex}: @AUCTeX{} then gives you a @samp{Command} menu,
296    and @previewlatex{} gives you a @samp{Preview} menu.
297  For XEmacs, if you specified a valid package directory during  
298  installation, or none at all, then XEmacs installation should do  For XEmacs, if the installation occured into a valid package directory
299  everything necessary in order to install @AUCTeX{} as a package  (which is the default), then this should work out of the box.
300  and activate it.  Restarting XEmacs should then make the package  
301  visible, and @kbd{C-c C-c} should give you a command prompt.  With Emacs (or if you explicitly disabled use of the package system),
302    the startup files @file{auctex.el} and @file{preview-latex.el} may
303  If you used @code{--with-packagedir}, you have to make sure that the  already be in a directory of the @file{site-start.d/} variety if your
304  directory @file{lisp/auctex} under the directory you specified is in  Emacs installation provides it.  In that case they should be
305  XEmacs' @code{load-path} variable.  automatically loaded on startup and nothing else needs to be done.  If
306    not, they should at least have been placed somewhere in your
307  For GNU Emacs, the recommended way to activate @AUCTeX{} is to add the  @code{load-path}.  You can then load them by placing the lines
 following line to your @file{.emacs} file:  
308    
309  @example  @example
310  (require 'tex-site)  (load "auctex.el" nil t t)
311    (load "preview-latex.el" nil t t)
312  @end example  @end example
313    
314  If you used @code{--with-lispdir}, you have to make sure that the  into your @file{~/.emacs} file.
315  directory specified is in Emacs' @code{load-path} variable, so that you  
316  would instead use, e.g.,  If you explicitly used @code{--with-lispdir}, you may need to add the
317    specified directory into Emacs' @code{load-path} variable by adding
318    something like
319    
320  @example  @example
321  (setq load-path (cons "~/elisp" load-path))  (add-to-list 'load-path "~/elisp")
 (require 'tex-site)  
322  @end example  @end example
323    
324    before the above lines into your Emacs startup file.
325    
326  For site-wide activation in GNU Emacs, see  For site-wide activation in GNU Emacs, see
327  @ifset rawfile  @ifset rawfile
328  below.  below.
# Line 293  the @file{README} file. Line 354  the @file{README} file.
354  @ref{Introduction,,Introduction to @AUCTeX{}}.  @ref{Introduction,,Introduction to @AUCTeX{}}.
355  @end ifclear  @end ifclear
356    
357  For that reason, the default installation will place the startup  So if you have users that don't want to use the preinstalled @AUCTeX{},
358  @file{auctex.el} in a possibly existing @file{site-start.d} directory,  they can easily get rid of it.  Activating @AUCTeX{} by default is
359  with the assumption that this will cause activation of the package.  therefore a good choice.
360    
361  If no such directory exists, @file{auctex.el} will be installed in a  If the installation procedure did not achieve this already by placing
362  place in the @samp{load-path}, so it should be sufficient to use the  @file{auctex.el} and @previewlatex{} into a possibly existing
363  invocation of  @file{site-start.d} directory, you can do this by placing
364    
365  @example  @example
366  (load "auctex.el" nil nil t)  (load "auctex.el" nil t t)
367    (load "preview-latex.el" nil t t)
368  @end example  @end example
369    
370  @noindent in the system-wide @file{site-start.el}.  @noindent in the system-wide @file{site-start.el}.
371    
372  @ignore  If your package is intended as an XEmacs package or to accompany a
373  For @acronym{RPM} files we include a @file{auctex.spec} file in  precompiled version of Emacs, you might not know which @TeX{} system
374  the tarball distribution, suitable for recent RedHat systems, that  will be available when @previewlatex{} gets used.  In this case you
375  should do just that.  should build using the @code{--without-texmf-dir} option described
376  @end ignore  previously.  This can also be convenient for systems that are intended
377    to support more than a single TeX distribution.  Since more often than
378    not @TeX{} packages for operating system distributions are either much
379    more outdated or much less complete than separately provided systems
380    like @w{@TeX{} live}, this method may be generally preferable when
381    providing packages.
382    
383  @node Advice for non-privileged users  @node Advice for non-privileged users
384  @section Installation for non-privileged users  @section Installation for non-privileged users
# Line 324  this sort of thing practical: but GNU Em Line 391  this sort of thing practical: but GNU Em
391  whom the package system is for some reason misbehaving) may need to do a  whom the package system is for some reason misbehaving) may need to do a
392  little more work.  little more work.
393    
394  GNU Emacs users can solve this problem by using the @option{--prefix}  The main expedient is using the @option{--prefix} option to the
395  option to the @command{configure} script, and let it point to the personal  @file{configure} script, and let it point to the personal home
396  home directory.  In that way, resulting binaries will be installed under  directory.  In that way, resulting binaries will be installed under the
397  the @file{bin} subdirectory of your home directory, manual pages under  @file{bin} subdirectory of your home directory, manual pages under
398  @file{man} and so on.  That way, it is reasonably easy to maintain a  @file{man} and so on.  It is reasonably easy to maintain a bunch of
399  bunch of additional packages, since the prefix argument is supported by  personal software, since the prefix argument is supported by most
400  most @command{configure} scripts.  @file{configure} scripts.
401    
402  You'll have to add something like  You'll have to add something like
403  @file{/home/myself/share/emacs/site-lisp} to your @code{load-path}  @file{/home/myself/share/emacs/site-lisp} to your @code{load-path}
# Line 338  variable, if it isn't there already. Line 405  variable, if it isn't there already.
405    
406  XEmacs users can achieve the same end by pointing @command{configure} at an  XEmacs users can achieve the same end by pointing @command{configure} at an
407  appropriate package directory (normally  appropriate package directory (normally
408  @option{--with-packagedir=~/.xemacs/xemacs-packages} will serve).  This  @option{--with-packagedir=~/.xemacs/xemacs-packages} will serve).  The
409  should only need to be done once, and should be needed fairly rarely; if  package directory stands a good chance at being detected automatically
410  you have installed any personal XEmacs packages before, @command{configure}  as long as it is in a subtree of the specified @var{prefix}.
411  should detect that, and automatically install @AUCTeX{} there too;  
412  equally, if you have installed @AUCTeX{} somewhere searched by  Now here is another thing to ponder: perhaps you want to make it easy
413  XEmacs, @AUCTeX{} should be automatically reinstalled over that  for other users to share parts of your personal Emacs configuration.  In
414  copy.  general, you can do this by writing @samp{~myself/} anywhere where you
415    specify paths to something installed in your personal subdirectories,
416  (@command{configure} may guess wrong if the site administrator has  not merely @samp{~/}, since the latter, when used by other users, will
417  installed @AUCTeX{} somewhere else: if so, just use the  point to non-existent files.
 @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.  
418    
419  For yourself, it will do to manipulate environment variables in your  For yourself, it will do to manipulate environment variables in your
420  @file{.profile} resp.@: @file{.login} files.  But if people will be  @file{.profile} resp.@: @file{.login} files.  But if people will be
# Line 378  In XEmacs, you should ask the other user Line 436  In XEmacs, you should ask the other user
436  presently no easy programmatic way to do this, except to have a script  presently no easy programmatic way to do this, except to have a script
437  do the symlinking for them.)  do the symlinking for them.)
438    
439  In GNU Emacs, you'll want the invocation lines described  In GNU Emacs, It should be sufficient if people just do
 @ifset rawfile  
 above.  
 @end ifset  
 @ifclear rawfile  
 in @xref{Loading the package}.  
 @end ifclear  
 In addition, you'll want a line such as  
440    
441  @lisp  @lisp
442  (add-to-list 'load-path "~myself/share/emacs/site-lisp/preview")  (load "~myself/share/emacs/site-lisp/auctex.el" nil t t)
443    (load "~myself/share/emacs/site-lisp/preview-latex.el" nil t t)
444  @end lisp  @end lisp
445    
446    where the path points to your personal installation.  The rest of the
447    package should be found relative from there without further ado.
448    
449  @subheading Making the Info files available  @subheading Making the Info files available
450    
451  While for yourself, you'll probably want to manipulate the  For making the info files accessible from within Elisp, something like
452  @samp{INFOPATH} variable; for access inside of Elisp something like  the following might be convenient to add into your or other people's
453  the following might be convenient:  startup files:
454    
455  @lisp  @lisp
456  (eval-after-load 'info  (eval-after-load 'info
# Line 404  the following might be convenient: Line 459  the following might be convenient:
459    
460  In XEmacs, as long as XEmacs can see the package, there should be no  In XEmacs, as long as XEmacs can see the package, there should be no
461  need to do anything at all; the info files should be immediately  need to do anything at all; the info files should be immediately
462  visible.  However, you might want to set @samp{INFOPATH} anyway, for the  visible.  However, you might want to set @env{INFOPATH} anyway, for the
463  sake of standalone readers outside of XEmacs. (The info files in XEmacs  sake of standalone readers outside of XEmacs. (The info files in XEmacs
464  are normally in something like @file{~/.xemacs/xemacs-packages/info}.)  are normally in @file{~/.xemacs/xemacs-packages/info}.)
465    
466    @subheading Making the @LaTeX{} style available
467    
468    If you want others to be able to share your installation, you should
469    configure it using @samp{--without-texmf-dir}, in which case things
470    should work as well for them as for you.
471    
472  @ifclear rawfile  @ifclear rawfile
473  @node Installation under MS Windows  @node Installation under MS Windows
# Line 437  You might check some variables with a sp Line 498  You might check some variables with a sp
498  accessible directly by typing @kbd{M-x customize-variable RET <variable>  accessible directly by typing @kbd{M-x customize-variable RET <variable>
499  RET}.  RET}.
500    
 @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.  
   
501  @defopt TeX-macro-global  @defopt TeX-macro-global
502  Directories containing the site's @TeX{} style files.  Directories containing the site's @TeX{} style files.
503  @end defopt  @end defopt

Legend:
Removed from v.1.30  
changed lines
  Added in v.1.31

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26