diff options
Diffstat (limited to 'elpa/auctex-13.1.3/doc/install.texi')
| -rw-r--r-- | elpa/auctex-13.1.3/doc/install.texi | 628 |
1 files changed, 0 insertions, 628 deletions
diff --git a/elpa/auctex-13.1.3/doc/install.texi b/elpa/auctex-13.1.3/doc/install.texi deleted file mode 100644 index 19034cb..0000000 --- a/elpa/auctex-13.1.3/doc/install.texi +++ /dev/null @@ -1,628 +0,0 @@ -@c This is part of the AUCTeX Manual. -@c Copyright (C) 1994, 1996, 2003-2007, 2012-2013, -@c 2015, 2017, 2018, 2020, 2021 Free Software Foundation, Inc. -@c See the file auctex.texi for copying conditions. -@ifset rawfile -@include macros.texi -@node Installation,,(dir),(dir) -@top Installing @AUCTeX{} -@end ifset - -@ifclear rawfile -@node Installation -@chapter Installing @AUCTeX{} -@end ifclear - -The modern and strongly recommended way of installing @AUCTeX{} is by -using the Emacs package manager integrated in Emacs 24 and greater -(@acronym{ELPA}). Simply do @kbd{M-x list-packages @key{RET}}, mark the -auctex package for installation with @kbd{i}, and hit @kbd{x} to execute -the installation procedure. That's all. - -@code{use-package} users can use this simple recipe in their -@code{user-init-file} which essentially does the same as the manual -installation explained above. - -@lisp -(use-package tex - :ensure auctex) -@end lisp - -Using the @acronym{ELPA} version has several advantages. Besides being -platform and @acronym{OS} independent, you will receive intermediate -bugfix releases between major @AUCTeX{} releases conveniently. For past -@acronym{ELPA} releases, see -@url{https://elpa.gnu.org/packages/auctex.html}. -@ifclear rawfile -Once the installation is completed, you can skip the rest of this -section and proceed to @ref{Quick Start}. -@end ifclear - -The remainder of this section is about installing @AUCTeX{} from a -release tarball or from a checkout of the @AUCTeX{} repository. - -Installing @AUCTeX{} should be simple: merely @command{./configure}, -@command{make}, and @code{make install} for a standard site-wide -installation (most other installations can be done by specifying a -@option{--prefix=@dots{}} option). - -On many systems, this will already activate the package, making its -modes the default instead of the built-in modes of Emacs. If this is -not the case, consult @ref{Loading the package}. Please read through -this document fully before installing anything. The installation -procedure has changed as compared to earlier versions. Users of @w{MS -Windows} are asked to consult -@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 and uninstall:: -* Loading the package:: -* Advice for package providers:: -* Advice for non-privileged users:: -* Installation under MS Windows:: -* Customizing:: -@end menu -@end ifclear - -@ifset rawfile -@menu -* Prerequisites:: -* Configure:: -* Build/install and uninstall:: -* Loading the package:: -* Advice for package providers:: -* Advice for non-privileged users:: -* Customizing:: -@end menu -@end ifset - -@ifset rawfile -@node Prerequisites -@chapter Prerequisites -@raisesections -@end ifset - -@ifclear rawfile -@node Prerequisites -@section Prerequisites -@end ifclear - -@itemize @bullet -@item GNU Emacs 25.1 or higher - -Using @previewlatex{} requires a version of Emacs compiled with image -support. - -@table @b -@item Windows -Precompiled versions are available from -@uref{https://ftp.gnu.org/gnu/emacs/windows/}. -@item macOS -For an overview of precompiled versions of Emacs for macOS see for -example @uref{https://www.emacswiki.org/emacs/EmacsForMacOS}. -@item GNU/Linux -Most GNU/Linux distributions nowadays provide a recent variant of Emacs -via their package repositories. -@item Self-compiled -Compiling Emacs yourself requires a C compiler and a number of tools and -development libraries. Details are beyond the scope of this manual. -Instructions for checking out the source code can be found at -@uref{https://savannah.gnu.org/git/?group=emacs}. -@end table - -@item A working @TeX{} installation - -Well, @AUCTeX{} would be pointless without that. Processing -documentation requires @TeX{}, @LaTeX{} and Texinfo during installation. -@previewlatex{} requires Dvips or @command{dvipng} for its operation in @acronym{DVI} mode. -The default configuration of @AUCTeX{} is tailored for @w{@TeX{} Live}-based -distributions, but can be adapted easily. - -@item A recent Ghostscript - -This is needed for operation of @previewlatex{} in both @acronym{DVI} -and @acronym{PDF} mode. Ghostscript version 7.07 or newer is required. - -@item GNU make - -Recent @AUCTeX{} uses GNU make specific capabilities in the Makefiles. -If your @acronym{OS}'s default @command{make} command is not GNU make, -you have to obtain it in order to build @AUCTeX{} by yourself. GNU make -is sometimes provided under the name @command{gmake} in your -@acronym{OS}'s binary package system. - -@item The Texinfo package - -Strictly speaking, you can get away without it if you are building -from the distribution tarball, have not modified any files and don't -need a printed version of the manual: the pregenerated info file is -included in the tarball. At least @w{version 4.0} is required. - -@end itemize - -For some known issues with various software, see -@ifset rawfile -the @file{PROBLEMS.preview} file. -@end ifset -@ifclear rawfile -@ref{Known problems,,,preview-latex,the @previewlatex{} manual}. -@end ifclear - -@node Configure -@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 Git rather than -a regular release, you will have to first follow the instructions in -@file{README.GIT}). - -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 --prefix=@var{prefix} -All automatic placements for package components will be chosen from -sensible existing hierarchies below this: directories like @file{man}, -@file{share} and @file{bin} are supposed to be directly below -@var{prefix}. - -Only if no workable placement can be found there, in some cases an -alternative search will be made in a prefix deduced from a suitable -binary. - -@file{/usr/local} is the default @var{prefix}, intended to be suitable -for a site-wide installation. If you are packaging this as an -operating system component for distribution, the setting @file{/usr} -will probably be the right choice. See @ref{Advice for package -providers} for detail. - -If you are planning to install the package as a single non-priviledged -user, you will typically set @var{prefix} to your home directory. -Consult @ref{Advice for non-privileged users} for addtional -instructions. - -@item --with-emacs=@var{/path/to/emacs} -If you are using a pretest which isn't in your @env{PATH}, or -@command{configure} is not finding the right Emacs executable, you can -specify it with this option. - -@item --with-lispdir=@var{lispdir} -This option specifies the location of the @file{site-lisp} -directory within @code{load-path} under which the files will get -installed (the bulk will get installed in a subdirectory). -@command{./configure} should figure this out by itself. - -@item --with-auctexstartfile=@file{auctex.el} -@itemx --with-previewstartfile=@file{preview-latex.el} -This is the name of the respective startup files. If @var{lispdir} -contains a subdirectory @file{site-start.d}, the start files are -placed there, and @file{site-start.el} should -load them automatically. Please be aware that you must not move the -start files after installation since other files are found -@emph{relative} to them. - -@item --with-packagelispdir=@file{auctex} -This is the directory where the bulk of the package gets located. The -startfile adds this into @code{load-path}. - -@item --with-auto-dir=@var{/dir} -You can use this option to specify the directory containing -automatically generated information by @kbd{M-x TeX-auto-generate-global @key{RET}}. 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 -@option{--help}. - -@c FIXME: It seems this no longer holds. -@c If you use @samp{--help=recursive}, then also @previewlatex{}-specific -@c options will get listed. - -@item --disable-preview -This disables configuration and installation of @previewlatex{}. This -option is not actually recommended. If your Emacs does not support -images, you should really upgrade to a newer version. Distributors -should, if possible, refrain from distributing @AUCTeX{} and -@previewlatex{} separately in order to avoid confusion and upgrade -hassles if users install partial packages on their own. - -@item --with-texmf-dir=@var{/dir} -@itemx --without-texmf-dir -@cindex preview-install-styles -This option is used for specifying a @acronym{TDS}-compliant directory -hierarchy. Using @code{--with-texmf-dir=@var{/dir}} you can specify -where the @TeX{} @acronym{TDS} directory hierarchy resides, and the -@TeX{} files will get installed in -@file{@var{/dir}/tex/latex/preview/}. - -If you use the @option{--without-texmf-dir} option, the @TeX{}-related -files will be kept in the Emacs Lisp tree, and at runtime the -@env{TEXINPUTS} environment variable will be made to point there. You -can install those files into your own @TeX{} tree at some later time -with @kbd{M-x preview-install-styles @key{RET}}. - -@item --with-tex-dir=@var{/dir} -If you want to specify an exact directory for the preview @TeX{} files, -use @code{--with-tex-dir=@var{/dir}}. In this case, the files will be -placed in @file{@var{/dir}}, and you'll also need the following option: - -@item --with-doc-dir=@var{/dir} -This option may be used to specify where the @TeX{} documentation goes. -It is to be used when you are using @code{--with-tex-dir=@var{/dir}}, -but is normally not necessary otherwise. -@end table - -@node Build/install and uninstall -@section Build/install and uninstall - -@cindex Installation -@cindex Make -@cindex Uninstallation - -Once @command{configure} has been run, simply enter - -@example -make -@end example - -@noindent -at the prompt to byte-compile the lisp files, extract the @TeX{} 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. - -Should you want to completely remove the installed package, in the same -directory you built @AUCTeX{} run - -@example -make uninstall -@end example - -@noindent -You will need administration privileges if you installed the package -into system directories. - -@node Loading the package -@section Loading the package -@cindex @file{init.el} -@cindex @file{.emacs} - -You can detect the successful activation of @AUCTeX{} and -@previewlatex{} in the menus after loading a @LaTeX{} file like -@file{circ.tex}: @AUCTeX{} then gives you a @samp{Command} menu, -and @previewlatex{} gives you a @samp{Preview} menu. - -@cindex @file{auctex.el} -@cindex @file{tex-site.el} -With Emacs (or if you explicitly disabled use of the package system), -the startup files @file{auctex.el} and @file{preview-latex.el} may -already be in a directory of the @file{site-start.d/} variety if your -Emacs installation provides it. In that case they should be -automatically loaded on startup and nothing else needs to be done. If -not, they should at least have been placed somewhere in your -@code{load-path}. You can then load them by placing the lines - -@lisp -(load "auctex.el" nil t t) -(load "preview-latex.el" nil t t) -@end lisp -@noindent -into your init file such as @file{init.el} or @file{.emacs}. - -If you explicitly used @code{--with-lispdir}, you may need to add the -specified directory into Emacs' @code{load-path} variable by adding -something like - -@lisp -(add-to-list 'load-path "~/elisp") -@end lisp -@noindent -before the above lines into your Emacs startup file. - -For site-wide activation in GNU Emacs, see -@ifset rawfile -below. -@end ifset -@ifclear rawfile -@xref{Advice for package providers}. -@end ifclear - -Once activated, the modes provided by @AUCTeX{} are used per default for -all supported file types. If you want to change the modes for which it -is operative instead of the default, use -@example -@kbd{M-x customize-option @key{RET} TeX-modes @key{RET}} -@end example - -If you want to remove a preinstalled @AUCTeX{} completely before any of -its modes have been used, -@lisp -(unload-feature 'tex-site) -@end lisp -@noindent -should accomplish that. - -@node Advice for package providers -@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. - -There are people that prefer the built-in Emacs modes for editing -@TeX{} files, in particular plain @TeX{} users. There are various -ways to tell @AUCTeX{} even after auto-activation that it should -not get used, and they are described in -@ifset rawfile -the @file{README} file. -@end ifset -@ifclear rawfile -@ref{Introduction,,Introduction to @AUCTeX{}}. -@end ifclear - -So if you have users that don't want to use the preinstalled @AUCTeX{}, -they can easily get rid of it. Activating @AUCTeX{} by default is -therefore a good choice. - -If the installation procedure did not achieve this already by placing -@file{auctex.el} and @file{preview-latex.el} into a possibly existing -@file{site-start.d} directory, you can do this by placing - -@lisp -(load "auctex.el" nil t t) -(load "preview-latex.el" nil t t) -@end lisp - -@noindent in the system-wide @file{site-start.el}. - -The @option{--without-texmf-dir} option can be convenient for systems that -are intended to support more than a single TeX distribution. Since more -often than not @TeX{} packages for operating system distributions are -either much more outdated or much less complete than separately provided -systems like @w{@TeX{} Live}, this method may be generally preferable -when providing packages. - -The following package structure would be adequate for a typical fully -supported Unix-like installation: - -@c FIXME: teTeX is much outdated now. -@table @samp -@item preview-tetex -Style files and documentation for @file{preview.sty}, placed into a -@TeX{} tree where it is accessible from the te@TeX{} executables usually -delivered with a system. If there are other commonly used @TeX{} system -packages, it might be appropriate to provide separate packages for -those. -@item auctex-emacs-tetex -This package will require the installation of @samp{preview-tetex} and -will record in @code{TeX-macro-global} where to find the @TeX{} tree. -It is also a good idea to run -@example -emacs -batch -f TeX-auto-generate-global -@end example -when either @AUCTeX{} or te@TeX{} get installed or upgraded. If your -users might want to work with a different @TeX{} distribution (nowadays -pretty common), instead consider the following: -@item auctex-emacs -This package will be compiled with @option{--without-texmf-dir} and will -consequently contain the @samp{preview} style files in its private -directory. It will probably not be possible to initialize -@code{TeX-macro-global} to a sensible value, so running -@code{TeX-auto-generate-global} does not appear useful. This package -would neither conflict with nor provide @samp{preview-tetex}. -@end table - -@node Advice for non-privileged users -@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 pass more -options to the @command{configure} script. - -The main expedient is 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. It is reasonably easy to maintain a bunch of -personal software, since the prefix argument is supported by most -@command{configure} scripts. - -You often need to specify @option{--with-lispdir} option as well. -If you haven't installed Emacs under your home directory and use Emacs -installed in system directories, the @command{configure} script might not -be able to figure out suitable place to install lisp files under your -home directory. In that case, the @command{configure} script would -silently choose, by default, the @file{site-lisp} directory within -@code{load-path} for the place, where administration privileges are -usually required to put relevant files. Thus you will have to tell -the @command{configure} script explicitly where to put those files by, -e.g., @code{--with-lispdir=@samp{/home/myself/share/emacs/site-lisp}}. - -You'll have to add something like -@samp{/home/myself/share/emacs/site-lisp} to your @code{load-path} -variable, if it isn't there already. - -In addition, you will have to tell @command{configure} script where to -install @TeX{}-related files such as @file{preview.sty} if -@previewlatex{} isn't disabled. It is enough to specify -@option{--with-texmf-dir=@file{$HOME/texmf}} for most typical cases, but -you have to create the direcotry @file{$HOME/texmf} in advance if it -doesn't exist. If this prescription doesn't work, consider using one or -more of the options @code{--with-texmf-dir=@var{/dir}}, -@code{--without-texmf-dir}, @code{--with-tex-dir=@var{/dir}} and -@code{--with-doc-dir=@var{/dir}}. See @ref{Configure} for detail of -these options. - -Now here is another thing to ponder: 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 GNU Emacs, it should be sufficient if people just do - -@lisp -(load "~myself/share/emacs/site-lisp/auctex.el" nil t t) -(load "~myself/share/emacs/site-lisp/preview-latex.el" nil t t) -@end lisp -@noindent -where the path points to your personal installation. The rest of the -package should be found relative from there without further ado. - -@subheading Making the Info files available - -For making the info files accessible from within Elisp, something like -the following might be convenient to add into your or other people's -startup files: - -@lisp -(eval-after-load 'info - '(add-to-list 'Info-directory-list "~myself/info")) -@end lisp - -@subheading Making the @LaTeX{} style available - -If you want others to be able to share your installation, you should -configure it using @option{--without-texmf-dir}, in which case things -should work as well for them as for you. - -@subsection Using @AUCTeX{} from local Git repo - -With the techniques described above, it is also possible to use @AUCTeX{} -directly from a local Git repository. Let's assume you have your Git -repositories under @samp{~/development/}. - -First, you have to fetch a copy of the @AUCTeX{} Git repository. In a -shell, change directory to @samp{~/development/} and do: -@example -git clone https://git.savannah.gnu.org/git/auctex.git -@end example - -Now change directory to @samp{~/development/auctex} and run -@samp{./autogen.sh}. Next thing is to run @command{configure} like this: -@example -./configure --without-texmf-dir --with-lispdir=. -@end example - -@noindent -When finished, simply enter -@example -make -@end example -@noindent -and you're finished. Note that the @samp{make install} step is not -necessary. - -Now you have to tell Emacs about the plan. The following variables must -be set in your init file because their normal values are only correct when -@AUCTeX{} is installed: -@lisp -(setq TeX-data-directory "~/development/auctex" - TeX-lisp-directory TeX-data-directory) -@end lisp - -@noindent -The info files will be available with this: -@lisp -(eval-after-load 'info - '(add-to-list 'Info-additional-directory-list - "~/development/auctex/doc")) -@end lisp - -@noindent -Now you're ready to load @file{auctex.el} and @file{preview-latex.el} out -of this directory: -@lisp -(load "~/development/auctex/auctex.el" nil t t) -(load "~/development/auctex/preview-latex.el" nil t t) -@end lisp - -@ifclear rawfile -@node Installation under MS Windows -@section Installation under MS Windows -@include wininstall.texi -@end ifclear - -@node Customizing -@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 @key{RET} AUCTeX @key{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 options with a special significance. They are -accessible directly by typing @kbd{M-x customize-option @key{RET} <option> -@key{RET}}. - -@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 @command{kpsewhich}. -In this case you normally don't have to alter anything. - -@c Local Variables: -@c mode: texinfo -@c TeX-master: "auctex" -@c End: |