From becff06c71d277647eda4378203d03ab36e141eb Mon Sep 17 00:00:00 2001 From: mattkae Date: Tue, 17 May 2022 07:07:37 -0400 Subject: Evil mode and latex support --- elpa/auctex-13.1.3/doc/install.texi | 628 ++++++++++++++++++++++++++++++++++++ 1 file changed, 628 insertions(+) create mode 100644 elpa/auctex-13.1.3/doc/install.texi (limited to 'elpa/auctex-13.1.3/doc/install.texi') diff --git a/elpa/auctex-13.1.3/doc/install.texi b/elpa/auctex-13.1.3/doc/install.texi new file mode 100644 index 0000000..19034cb --- /dev/null +++ b/elpa/auctex-13.1.3/doc/install.texi @@ -0,0 +1,628 @@ +@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}