]> code.delx.au - gnu-emacs-elpa/blobdiff - packages/auctex/doc/faq.texi
Add texi files to for auctex package.
[gnu-emacs-elpa] / packages / auctex / doc / faq.texi
diff --git a/packages/auctex/doc/faq.texi b/packages/auctex/doc/faq.texi
new file mode 100644 (file)
index 0000000..6048432
--- /dev/null
@@ -0,0 +1,148 @@
+@ifset rawfile
+@include macros.texi
+@chapheading Frequently Asked Questions about @AUCTeX{}
+@end ifset
+
+@c We should switch to sectioning commands instead of items when this
+@c list grows.  Keep in mind to formulate short questions because
+@c section headings will not be broken in contrast to items.
+@enumerate
+@item
+Something is not working correctly.  What should I do?
+
+Well, you might have guessed it, the first place to look is in the
+available documentation packaged with @AUCTeX{}.  This could be the
+release notes (in the @file{RELEASE} file) or the news section of the
+manual in case you are experiencing problems after an upgrade, the
+@file{INSTALL} file in case you are having problems with the
+installation, the section about bugs in the manual in case you
+encountered a bug or the relevant sections in the manual for other
+related problems.
+
+If this did not help, you can send a bug report to the @AUCTeX{} bug
+reporting list by using the command @kbd{M-x TeX-submit-bug-report RET}.
+But before you do this, you can try to get more information about the
+problem at hand which might also help you locate the cause of the error
+yourself.
+
+First, you can try to generate a so-called backtrace which shows
+functions involved in a program error.  In order to do this, start Emacs
+with the command line @samp{emacs --debug-init} and/or put the line
+
+@lisp
+(setq debug-on-error t)
+@end lisp
+
+as the first line into your init file.  XEmacs users might want to add
+@code{(setq stack-trace-on-error t)} as well.  After Emacs has started,
+you can load a file which triggers the error and a new window should pop
+up showing the backtrace.  If you get such a backtrace, please include
+it in the bug report.
+
+Second, you can try to figure out if something in your personal or site
+configuration triggers the error by starting Emacs without such
+customizations.  You can do this by invoking Emacs with the command line
+@samp{emacs -q -no-site-file}.  Once Emacs is running, copy the line
+
+@lisp
+(load "auctex.el" nil t t)
+@end lisp
+
+into the @samp{*scratch*} buffer and type @kbd{M-x eval-buffer RET}.
+This makes sure that @AUCTeX{} will be used for the file types it
+supports.  After you have done so, you can load the file triggering the
+error.  If everything is working now, you know that you have to search
+either in the site configuration file or your personal init file for
+statements related to the problem.
+
+@item
+What versions of Emacs and XEmacs are supported?
+
+@AUCTeX{} was tested with @w{Emacs 21} and @w{XEmacs 21.4.15}.  Older
+versions may work but are unsupported.  Older versions of XEmacs might
+possibly made to work by updating the @file{xemacs-base} package through
+the XEmacs package system.  If you are looking for a recommendation, it
+would appear that the smoothest working platform on all operating
+systems at the current point of time would be @w{Emacs 22.1}.  At the
+time of this writing, however, it has not been released and is still
+under development.  The quality of the development version is quite
+solid, so we recommend giving it a try.  With a developer version, of
+course, you have to be prepared to update in case you managed to get
+your snapshot at a bad time.  The second best choice would be the latest
+released @w{Emacs 21.4}.  However, Unicode support is less good, there
+is no version for the popular GTK toolkit, and the native versions for
+Windows and MacOS don't offer toolbar and @previewlatex{} support.
+
+Our success with XEmacs has been less than convincing.  Under the
+Windows operating system, nominally the only option for a released,
+stable Emacs variant supporting toolbars and @previewlatex{} would be
+@w{XEmacs 21.4}.  However, code for core functionality like formatting
+and syntax highlighting tends to be different and often older than even
+@w{Emacs 21.4}, and Unicode support as delivered is problematic at best,
+missing on Windows.  Both @AUCTeX{} and XEmacs developers don't hear
+much from active users of the combination.  Partly for that reason,
+problems tend to go unnoticed for long amounts of time and are often
+found, if at all, after releases.  No experiences or recommendations can
+be given for beta or developer versions of XEmacs.
+
+@item
+What should I do when @code{./configure} does not find programs like latex?
+
+This is problem often encountered on Windows.  Make sure that the
+@env{PATH} environment variable includes the directories containing the
+relevant programs, as described in
+@ifset rawfile
+the file @file{INSTALL.windows}
+@end ifset
+@ifclear rawfile
+@ref{Installation under MS Windows,,,auctex,the @AUCTeX{} manual}.
+@end ifclear
+
+@item
+Why doesn't the completion, style file, or multi-file stuff work?
+
+It must be enabled first, insert this in your init file:
+
+@lisp
+(setq-default TeX-master nil)
+(setq TeX-parse-self t)
+(setq TeX-auto-save t)
+@end lisp
+
+Read also the chapters about parsing and multifile documents in the
+manual.
+
+@item
+Why doesn't @code{TeX-save-document} work?
+
+@code{TeX-check-path} has to contain "./" somewhere.
+
+@item
+Why is the information in @file{foo.tex} forgotten when I save
+@file{foo.bib}?
+
+For various reasons, @AUCTeX{} ignores the extension when it stores
+information about a file, so you should use unique base names for your
+files.  E.g. rename @file{foo.bib} to @file{foob.bib}.
+
+@item
+Why doesn't @AUCTeX{} signal when processing a document is done?
+
+If the message in the minibuffer stays "Type `C-c C-l' to display
+results of compilation.", you probably have a misconfiguration in your
+init file (@file{.emacs}, @file{init.el} or similar).  To track this
+down either search in the @samp{*Messages*} buffer for an error message
+or put @code{(setq debug-on-error t)} as the first line into your init
+file, restart Emacs and open a @LaTeX{} file.  Emacs will complain
+loudly by opening a debugging buffer as soon as an error occurs.  The
+information in the debugging buffer can help you find the cause of the
+error in your init file.
+
+@item
+What does AUC stand for?
+
+@AUCTeX{} came into being at Aalborg University in Denmark.  Back then
+the Danish name of the university was Aalborg Universitetscenter; AUC
+for short.
+
+@end enumerate