diff options
Diffstat (limited to 'elpa/auctex-13.1.3/doc/wininstall.texi')
| -rw-r--r-- | elpa/auctex-13.1.3/doc/wininstall.texi | 358 |
1 files changed, 358 insertions, 0 deletions
diff --git a/elpa/auctex-13.1.3/doc/wininstall.texi b/elpa/auctex-13.1.3/doc/wininstall.texi new file mode 100644 index 0000000..230f8e2 --- /dev/null +++ b/elpa/auctex-13.1.3/doc/wininstall.texi @@ -0,0 +1,358 @@ +@c This is part of the AUCTeX Manual. +@c Copyright (C) 2003-2007, 2009, 2018, 2021 +@c Free Software Foundation, Inc. +@c See the file auctex.texi for copying conditions. +@ifset rawfile +@include macros.texi +@end ifset + +@subheading In a Nutshell + +The following are brief installation instructions for the impatient. In +case you don't understand some of this, run into trouble of some sort, +or need more elaborate information, refer to the detailed instructions +further below. + +@enumerate +@item +Install the prerequisites, i.e.@: GNU Emacs, MSYS or Cygwin, a @TeX{} +system, and Ghostscript. + +@item +Open the MSYS shell or a Cygwin shell and change to the directory +containing the unzipped file contents. + +@item +Configure @AUCTeX{}: + +For Emacs: Many people like to install @AUCTeX{} into the pseudo file +system hierarchy set up by the Emacs installation. Assuming Emacs is +installed in @file{C:/Program Files/Emacs} and the directory for local +additions of your @TeX{} system, e.g.@: MiK@TeX{}, is +@file{C:/localtexmf}, you can do this by typing the following statement +at the shell prompt: + +@example +./configure --prefix='C:/Program Files/Emacs' \ + --infodir='C:/Program Files/Emacs/info' \ + --with-texmf-dir='C:/localtexmf' +@end example + +The commands above is example for common usage. More on configuration +options can be found in the detailed installation instructions below. + +If the configuration script failed to find all required programs, make +sure that these programs are in your system path and add directories +containing the programs to the @env{PATH} environment variable if +necessary. Here is how to do that in W2000/XP: + +@enumerate +@cindex Adding to @env{PATH} in Windows +@cindex @env{PATH} in Windows +@item +On the desktop, right click ``My Computer'' and select properties. +@item +Click on ``Advanced'' in the ``System Properties'' window. +@item +Select ``Environment Variables''. +@item +Select ``path'' in ``System Variables'' and click ``edit''. Move to the +front in the line (this might require scrolling) and add the missing +path including drive letter, ended with a semicolon. +@end enumerate + +@item +If there were no further error messages, type + +@example +make +@end example + +In case there were, please refer to the detailed description below. + +@item +Finish the installation by typing + +@example +make install +@end example +@end enumerate + +@subheading Detailed Installation Instructions + +Installation of @AUCTeX{} under Windows is in itself not more +complicated than on other platforms. However, meeting the prerequisites +might require more work than on some other platforms, and feel less +natural. + +If you are experiencing any problems, even if you think they are of your +own making, be sure to report them to @email{auctex-devel@@gnu.org} so +that we can explain things better in future. + +Windows is a problematic platform for installation scripts. The main +problem is that the installation procedure requires consistent file +names in order to find its way in the directory hierarchy, and Windows +path names are a mess. + +The installation procedure tries finding stuff in system search paths +and in Emacs paths. For that to succeed, you have to use the same +syntax and spelling and case of paths everywhere: in your system search +paths, in Emacs' @code{load-path} variable, as argument to the scripts. +If your path names contain spaces or other `shell-unfriendly' +characters, most notably backslashes for directory separators, place the +whole path in @samp{"double quote marks"} whenever you specify it on a +command line. + +Avoid `helpful' magic file names like @samp{/cygdrive/c} and +@samp{C:\PROGRA~1\} like the plague. It is quite unlikely that the +scripts will be able to identify the actual file names involved. Use +the full paths, making use of normal Windows drive letters like +@samp{ 'C:/Program Files/Emacs' } where required, and using the same +combination of upper- and lowercase letters as in the actual files. +File names containing shell-special characters like spaces or +backslashes (if you prefer that syntax) need to get properly quoted to +the shell: the above example used single quotes for that. + +Ok, now here are the steps to perform: + +@enumerate +@item +You need to unpack the @AUCTeX{} distribution (which you seemingly have +done since you are reading this). It must be unpacked in a separate +installation directory outside of your Emacs file hierarchy: the +installation will later copy all necessary files to their final +destination, and you can ultimately remove the directory where you +unpacked the files. + +Line endings are a problem under Windows. The distribution contains +only text files, and theoretically most of the involved tools should get +along with that. However, the files are processed by various utilities, +and it is conceivable that not all of them will use the same line ending +conventions. If you encounter problems, it might help if you try +unpacking (or checking out) the files in binary mode, if your tools +allow that. + +If you don't have a suitable unpacking tool, skip to the next step: this +should provide you with a working @samp{unzip} command. + +@item +The installation of @AUCTeX{} will require the MSYS tool set from +@uref{http://www.mingw.org/} or the Cygwin tool set from +@uref{https://cygwin.com/}. The latter is slower and larger (the download +size of the base system is about 15 MB) but comes with a package manager +that allows for updating the tool set and installing additional packages +like, for example, the spell checker @w{aspell}. + +If Cygwin specific paths like @samp{/cygdrive/c} crop up in the course +of the installation, using a non-Cygwin Emacs could conceivably cause +trouble. Using Cygwin either for everything or nothing might save +headaches, @emph{if} things don't work out. + +@item +Install a current version of @w{Emacs} from +@uref{https://ftp.gnu.org/gnu/emacs/windows/}. + +@item +You need a working @TeX{} installation. One popular installation under +Windows is @uref{https://miktex.org/,MiK@TeX{}}. Another much more +extensive system is @uref{https://www.tug.org/texlive/,@w{@TeX{} Live}} +which is rather close to its Unix cousins. + +@item +A working copy of @uref{https://www.ghostscript.com/,Ghostscript} is +required for @previewlatex{} operation. Examining the output from +@example +gswin32c -h +@end example +on a Windows command line should tell you whether your Ghostscript +supports the @code{png16m} device needed for @acronym{PNG} support. +MiK@TeX{} apparently comes with its own Ghostscript called @file{mgs.exe}. + +@item +@uref{https://www.perl.org/,Perl} is needed for rebuilding the +documentation if you are working with a copy from Git or have +touched documentation source files in the @previewlatex{} part. If the +line endings of the file @file{preview/latex/preview.dtx} don't +correspond with what Perl calls @code{\n} when reading text files, +you'll run into trouble. + +@item +Now the fun stuff starts. If you have not yet done so, unpack the +@AUCTeX{} distribution into a separate directory after rereading the +instructions for unpacking above. + +@item +Ready for takeoff. Start some shell (typically @command{bash}) capable of +running @command{configure}, change into the installation directory and +call @command{./configure} with appropriate options. + +Typical options you'll want to specify will be +@table @code +@item --prefix=@var{drive:/path/to/emacs-hierarchy} +which tells @command{configure} where to perform the installation. It may +also make @command{configure} find Emacs automatically; if this doesn't +happen, try @option{--with-emacs} as described below. All automatic +detection of files and directories restricts itself to directories below +the @var{prefix} or in the same hierarchy as the program accessing the +files. Usually, directories like @file{man}, @file{share} and +@file{bin} will be situated right under @var{prefix}. + +This option also affects the defaults for placing the Texinfo +documentation files (see also @option{--infodir} below) and automatically +generated style hooks. + +If you have a central directory hierarchy (not untypical with Cygwin) +for such stuff, you might want to specify its root here. You stand a +good chance that this will be the only option you need to supply, as +long as your @TeX{}-related executables are in your system path, which +they better be for @AUCTeX{}'s operation, anyway. + +@item --with-emacs +if you are installing for a version of Emacs. You can use +@samp{--with-emacs=@var{drive:/path/to/emacs}} to specify the name of the +installed Emacs executable, complete with its path if necessary (if +Emacs is not within a directory specified in your @env{PATH} environment +setting). + +@item --with-lispdir=@var{drive:/path/to/site-lisp} +This option tells a place in @code{load-path} below which the +files are situated. The startup files @file{auctex.el} and +@file{preview-latex.el} will get installed here unless a subdirectory +@file{site-start.d} exists which will then be used instead. The other +files from @AUCTeX{} will be installed in a subdirectory called +@file{auctex}. + +If you think that you need a different setup, please refer to the full +installation instructions in +@ifset rawfile +the @file{INSTALL} file. +@end ifset +@ifclear rawfile +@ref{Configure}. +@end ifclear + +@item --infodir=@var{drive:/path/to/info/directory} +If you are installing into an Emacs directory, info files have to be put +into the @file{info} folder below that directory. The configuration +script will usually try to install into the folder @file{share/info}, so +you have to override this by specifying something like +@samp{--infodir='C:/Program Files/info'} for the configure call. + +@item --with-auto-dir=@var{drive:/dir} +Directory containing automatically generated information. You should +not normally need to set this, as @samp{--prefix} should take care of +this. + +@item --disable-preview +Use this option if your Emacs version is unable to support image +display. + +@item --with-texmf-dir=@var{drive:/dir} +This will specify the directory where your @TeX{} installation sits. If +your @TeX{} installation does not conform to the @acronym{TDS} (@TeX{} directory +standard), you may need to specify more options to get everything in +place. +@end table + +For more information about any of the above and additional options, see +@ifset rawfile +the `Configure' section in the @file{INSTALL} file. +@end ifset +@ifclear rawfile +@ref{Configure}. +@end ifclear + +@c FIXME: It seems this no longer holds. +@c Calling +@c @file{./configure --help=recursive} +@c will tell about other options, but those are almost never required. + +Some executables might not be found in your path. That is not a good +idea, but you can get around by specifying environment variables to +@command{configure}: +@example +GS="@var{drive:/path/to/gswin32c.exe}" ./configure @dots{} +@end example +should work for this purpose. @file{gswin32c.exe} is the usual name for +the required @emph{command line} executable under Windows; in contrast, +@file{gswin32.exe} is likely to fail. + +As an alternative to specifying variables for the @command{configure} call +you can add directories containing the required executables to the +@env{PATH} variable of your Windows system. This is especially a good +idea if Emacs has trouble finding the respective programs later during +normal operation. + +@item +Run @command{make} in the installation directory. + +@item +Run @code{make install} in the installation directory. + +@item +With Emacs, activation of @AUCTeX{} and @previewlatex{} depends on a +working @file{site-start.d} directory or similar setup, since then the +startup files @file{auctex.el} and @file{preview-latex.el} will have +been placed there. If this has not been done, you should be able to +load the startup files manually with +@lisp +(load "auctex.el" nil t t) +(load "preview-latex.el" nil t t) +@end lisp +in either a site-wide @file{site-start.el} or your personal startup file +(usually accessible as @file{~/.emacs} or @file{~/.emacs.d/init.el} from +within Emacs). + +@cindex @file{tex-mik.el} +The default configuration of @AUCTeX{} is probably not the best fit for +Windows systems with MiK@TeX{}. You might want to add +@lisp +(require 'tex-mik) +@end lisp +after loading @file{auctex.el} and @file{preview-latex.el} in order to +get more appropriate values for some customization options. + +You can always use + +@example +@kbd{M-x customize-group @key{RET} AUCTeX @key{RET}} +@end example + +in order to customize more stuff, or use the @samp{Customize} menu. + +@item +Load @file{circ.tex} into Emacs and see if you get the @samp{Command} +menu. Try using it to @LaTeX{} the file. + +@item +Check whether the @samp{Preview} menu is available in this file. Use it +to generate previews for the document. + +If this barfs and tells you that image type @samp{png} is not supported, +you can either add @acronym{PNG} support to your Emacs installation or +choose another image format to be used by @previewlatex{}. + +Adding support for an image format usually involves the installation of +a library, e.g.@: from @uref{http://gnuwin32.sf.net/}. If you got your +Emacs from @uref{https://www.gnu.org/} you might want to check its +@uref{https://ftp.gnu.org/gnu/emacs/windows/README,README file} for +details. + +A different image format can be chosen by setting the variable +@code{preview-image-type}. While it is recommended to keep the +@samp{dvipng} or @samp{png} setting, you can temporarily select a +different format like @samp{pnm} to check if the lack of @acronym{PNG} +support is the only problem with your Emacs installation. + +Try adding the line + +@lisp +(setq preview-image-type 'pnm) +@end lisp + +to your init file for a quick test. You should remove the line after +the test again, because @acronym{PNM} files take away @strong{vast} +amounts of disk space, and thus also of load/save time. +@end enumerate + +Well, that about is all. Have fun! |