X-Git-Url: https://code.delx.au/gnu-emacs-elpa/blobdiff_plain/17c9a37d769ade802e4adbe9f4fc3f82ea0fceea..23958974e9094261d9c72302952a5a5fb22e6072:/packages/auctex/doc/preview-latex.texi?ds=sidebyside

diff --git a/packages/auctex/doc/preview-latex.texi b/packages/auctex/doc/preview-latex.texi
new file mode 100644
index 000000000..35085be8b
--- /dev/null
+++ b/packages/auctex/doc/preview-latex.texi
@@ -0,0 +1,840 @@
+\input texinfo
+@comment %**start of header
+@setfilename preview-latex.info
+@include version.texi
+@settitle preview-latex @value{VERSION}
+@comment %**end of header
+@include macros.texi
+@copying
+This manual is for preview-latex, a @LaTeX{} preview mode for @AUCTeX{}
+(version @value{VERSION} from @value{UPDATED}).
+
+Copyright @copyright{} 2001, 2002, 2003,
+2004, 2005, 2006 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.  A
+copy of the license is included in the section entitled ``GNU Free
+Documentation License.''
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* preview-latex: (preview-latex).       Preview LaTeX fragments in Emacs
+@end direntry
+@dircategory TeX
+@direntry
+* preview-latex: (preview-latex).       Preview LaTeX fragments in Emacs
+@end direntry
+@c footnotestyle separate
+@c paragraphindent 2
+@syncodeindex vr cp
+@syncodeindex ky cp
+@syncodeindex fn cp
+
+@iftex
+@tolerance 10000 @emergencystretch 3em
+@end iftex
+
+@finalout
+@titlepage
+@title @previewlatex{}
+@subtitle A @LaTeX{} preview mode for @AUCTeX{} in Emacs.
+@subtitle Version @value{VERSION}, @value{UPDATED}
+@author Jan-@AA{}ke Larsson
+@author David Kastrup and others
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@c @summarycontents
+@contents
+
+@c Use @ifinfo _and_ @ifhtml here because Texinfo 3 cannot cope with
+@c @ifnottex around a top node.
+@ifinfo
+@node top, , (dir), (dir)
+@top @previewlatex{}
+
+This manual may be copied under the conditions spelled out in
+@ref{Copying this Manual}.
+
+@end ifinfo
+@ifhtml
+@node top, Copying, (dir), (dir)
+@top @previewlatex{}
+@insertcopying
+@end ifhtml
+
+@contents
+
+@iftex
+@unnumbered @previewlatex{}
+@end iftex
+ 
+@previewlatex{} is a package embedding preview fragments into Emacs
+source buffers under the @AUCTeX{} editing environment for @LaTeX{}.  It
+uses @file{preview.sty} for the extraction of certain environments (most
+notably displayed formulas).  Other applications of this style file are
+possible and exist.
+
+The name of the package is really @samp{preview-latex}, all in
+lowercase letters, with a hyphen.  If you typeset it, you can use a
+sans-serif font to visually offset it.
+
+@menu
+* Copying::                     Copying
+* Introduction::                Getting started.
+* Installation::                Make Install.
+* Keys and lisp::               Key bindings and user-level lisp functions.
+* Simple customization::        To make it fit in.
+* Known problems::              When things go wrong.
+* For advanced users::          Internals and more customizations.
+* ToDo::                        Future development.
+* Frequently Asked Questions::  All about @previewlatex{}
+* Copying this Manual::         GNU Free Documentation License
+* Index::                       A menu of many topics.             
+@end menu
+
+@node Copying, Introduction, top, top
+@unnumbered Copying
+@cindex Copying
+@cindex Copyright
+@cindex GPL
+@cindex General Public License
+@cindex License
+@cindex Free
+@cindex Free software
+@cindex Distribution
+@cindex Right
+@cindex Warranty
+
+For the conditions for copying parts of @previewlatex{}, see the General
+Public Licenses referres to in the copyright notices of the files, the
+General Public Licenses accompanying them and the explanatory section in
+@ref{Copying,,,auctex,the @AUCTeX{} manual}.
+
+This manual specifically is covered by the GNU Free Documentation
+License (@pxref{Copying this Manual}).
+
+@node Introduction, Installation, Copying, top
+@c Used as @file{README} as well: in separate file
+@chapter Introduction
+@include preview-readme.texi
+
+@node Installation, Keys and lisp, Introduction, top
+@chapter Installation
+Installation is now being covered in
+@ref{Installation,,,auctex,the @AUCTeX{} manual}.
+
+@node Keys and lisp, Simple customization, Installation, top
+@chapter Key bindings and user-level lisp functions 
+
+@cindex Menu entries
+@previewlatex{} adds key bindings starting with @kbd{C-c C-p} to the
+supported modes of @AUCTeX{} (@inforef{Key Index,,auctex}).  It will
+also add its own @samp{Preview} menu in the menu bar, as well as an icon
+in the toolbar.
+
+The following only describes the interactive use: view the documentation
+strings with @kbd{C-h f} if you need the Lisp information.
+
+@table @w
+@item @kbd{C-c C-p C-p}
+@itemx @code{preview-at-point}
+@itemx Preview/Generate previews (or toggle) at point
+If the cursor is positioned on or inside of a preview area, this
+toggles its visibility, regenerating the preview if necessary. If not,
+it will run the surroundings through preview. The surroundings include
+all areas up to the next valid preview, unless invalid previews occur
+before, in which case the area will include the last such preview in
+either direction.  And overriding any other
+action, if a region is active (@code{transient-mark-mode} or
+@code{zmacs-regions}), it is run through @code{preview-region}.
+@kindex @kbd{C-c C-p C-p}
+@findex preview-at-point
+
+@item @kbd{<mouse-2>}
+The middle mouse button has a similar action bound to it as
+@code{preview-at-point}, only that it knows which preview to apply it to
+according to the position of the click.  You can click either anywhere
+on a previewed image, or when the preview is opened and showing the
+source text, you can click on the icon preceding the source text.  In
+other areas, the usual mouse key action (typically: paste) is not
+affected.
+
+@item @kbd{<mouse-3>}
+The right mouse key pops up a context menu with several options:
+toggling the preview, regenerating it, removing it (leaving the
+unpreviewed text), copying the text inside of the preview, and copying
+it in a form suitable for copying as an image into a mail or news
+article.  This is a one-image variant of the following command:
+
+@item @kbd{C-c C-p C-w}
+@itemx @code{preview-copy-region-as-mml}
+@itemx Copy a region as MML
+@kindex @kbd{C-c C-p C-w}
+@findex preview-copy-region-as-mml
+This command is also available as a variant in the context menu on the
+right mouse button (where the region is the preview that has been
+clicked on).  It copies the current region into the kill buffer in a
+form suitable for copying as a text including images into a mail or news
+article using mml-mode (@pxref{Composing,,Composing,emacs-mime,Emacs
+MIME}).
+
+If you regenerate or otherwise kill the preview in its source buffer
+before the mail or news gets posted, this will fail.  Also you should
+generate images you want to send with @code{preview-transparent-border}
+@vindex preview-transparent-border
+set to @code{nil}, or the images will have an ugly border.
+@previewlatex{} detects this condition and asks whether to regenerate
+the region with borders switched off.  As this is an asynchronous
+operation running in the background, you'll need to call this command
+explicitly again to get the newly generated images into the kill ring.
+
+Preview your articles with @code{mml-preview} (on @kbd{M-m P}, or
+@kbd{C-c C-m P} in @w{Emacs 22})
+@kindex @kbd{M-m P}
+@kindex @kbd{C-c C-m P}
+to make sure they look fine.
+
+@item @kbd{C-c C-p C-e}
+@itemx @code{preview-environment}
+@itemx Preview/Generate previews for environment
+Run preview on @LaTeX{} environment.  The environments in
+@code{preview-inner-environments} are treated as inner levels so that
+for instance, the @code{split} environment in
+@code{\begin@{equation@}\begin@{split@}@dots{}\end@{split@}\end@{equation@}}
+is properly displayed.  If called with a numeric argument, the
+corresponding number of outward nested environments is treated as inner
+levels.
+@kindex @kbd{C-c C-p C-e}
+@findex preview-environment
+
+@item @kbd{C-c C-p C-s}
+@itemx @code{preview-section} 
+@itemx Preview/Generate previews for section
+Run preview on this @LaTeX{} section.
+@kindex @kbd{C-c C-p C-s}
+@findex preview-section
+
+@item @kbd{C-c C-p C-r}
+@itemx @code{preview-region}
+@itemx Preview/Generate previews for region
+Run preview on current region.
+@kindex @kbd{C-c C-p C-r}
+@findex preview-region
+
+@item @kbd{C-c C-p C-b}
+@itemx @code{preview-buffer} 
+@itemx Preview/Generate previews for buffer
+Run preview on the current buffer.
+@kindex @kbd{C-c C-p C-b}
+@findex preview-buffer
+
+@item @kbd{C-c C-p C-d}
+@itemx @code{preview-document} 
+@itemx Preview/Generate previews for document
+Run preview on the current document.
+@kindex @kbd{C-c C-p C-d}
+@findex preview-document
+
+@item @kbd{C-c C-p C-c C-p}
+@itemx @code{preview-clearout-at-point}
+@itemx Preview/Remove previews at point
+@kindex @kbd{C-c C-p C-c C-p}
+@findex preview-clearout-at-point
+Clear out (remove) the previews that are immediately adjacent to point.
+
+@item @kbd{C-c C-p C-c C-s}
+@itemx @code{preview-clearout-section}
+@itemx Preview/Remove previews from section
+@kindex @kbd{C-c C-p C-c C-s}
+@findex preview-clearout-document
+Clear out all previews in current section.
+
+@item @kbd{C-c C-p C-c C-r}
+@itemx @code{preview-clearout}
+@itemx Preview/Remove previews from region
+@kindex @kbd{C-c C-p C-c C-r}
+@findex preview-clearout
+Clear out all previews in the current region.
+
+@item @kbd{C-c C-p C-c C-b}
+@itemx @code{preview-clearout-buffer}
+@itemx Preview/Remove previews from buffer
+@kindex @kbd{C-c C-p C-c C-b}
+@findex preview-clearout-buffer
+Clear out all previews in current buffer. This makes the current buffer
+lose all previews.
+
+@item @kbd{C-c C-p C-c C-d}
+@itemx @code{preview-clearout-document}
+@itemx Preview/Remove previews from document
+@kindex @kbd{C-c C-p C-c C-d}
+@findex preview-clearout-document
+Clear out all previews in current document.  The document consists of
+all buffers that have the same master file as the current buffer.  This
+makes the current document lose all previews.
+
+@item @kbd{C-c C-p C-f}
+@itemx @code{preview-cache-preamble}
+@itemx Preview/Turn preamble cache on
+@kindex @kbd{C-c C-p C-f}
+@findex preview-cache-preamble
+Dump a pregenerated format file.  For the rest of the session, this file
+is used when running on the same master file.  Use this if you know your
+@LaTeX{} takes a long time to start up, the speedup will be most
+noticeable when generating single or few previews.  If you change your
+preamble, do this again.  @previewlatex{} will try to detect the
+necessity of that automatically when editing changes to the preamble are
+done from within Emacs, but it will not notice if the preamble
+effectively changes because some included file or style file is
+tampered with.
+
+@item @kbd{C-c C-p C-c C-f}
+@itemx @code{preview-cache-preamble-off}
+@itemx Preview/Turn preamble cache off
+@kindex @kbd{C-u C-c C-p C-f}
+@findex preview-cache-preamble-off
+Clear the pregenerated format file and stop using preambles for the
+current document. If the caching gives you problems, use this.
+
+@item @kbd{C-c C-p C-i}
+@itemx @code{preview-goto-info-page}
+@itemx Preview/Read Documentation
+@kindex @kbd{C-c C-p C-i}
+@findex preview-goto-info-page
+Read
+@ifinfo
+this
+@end ifinfo 
+@ifnotinfo
+the
+@end ifnotinfo
+info manual.
+
+@item @kbd{M-x preview-report-bug @key{RET}}
+@itemx @code{preview-report-bug}
+@itemx Preview/Report Bug
+@kindex @kbd{M-x preview-report-bug @key{RET}}
+@findex preview-report-bug
+@cindex Report a bug
+This is the preferred way of reporting bugs as it will fill in what
+version of @previewlatex{} you are using as well as versions of
+relevant other software, and also some of the more important
+settings. Please use this method of reporting, if at all possible and
+before reporting a bug, have a look at @ref{Known problems}.
+
+@item @kbd{C-c C-k}
+@itemx LaTeX/TeX Output/Kill Job
+@kindex @kbd{C-c C-k}
+@cindex Kill preview-generating process
+Kills the preview-generating process. This is really an @AUCTeX{}
+keybinding, but it is included here as a hint. If you are generating
+a preview and then make a change to the buffer, @previewlatex{} may be
+confused and place the previews wrong.
+@end table
+
+@node Simple customization, Known problems, Keys and lisp, top
+@chapter Simple customization
+
+Customization options can be found by typing @kbd{M-x customize-group
+@key{RET} preview @key{RET}}. Remember to set the option when you have
+changed it. The list of suggestions can be made very long (and is
+covered in detail in @ref{For advanced users}), but some are:
+
+@itemize @bullet
+@item Change the color of the preview background
+
+If you use a non-white background in Emacs, you might have color
+artifacts at the edges of your previews.  Playing around with the option
+@code{preview-transparent-color} in the @code{Preview Appearance} group
+might improve things.  With some settings, the cursor may cover the
+whole background of a preview, however.
+
+This option is specific to the display engine in use.  Its default is
+different in @w{Emacs 21} and @w{Emacs 22}, and it is not available in
+XEmacs.
+
+@item Showing @code{\label}s
+@cindex Showing @code{\label}s
+
+When using @previewlatex{}, the @code{\label}s are hidden by the
+previews.  It is possible to make them visible in the output
+by using the @LaTeX{} package @code{showkeys} alternatively
+@code{showlabels}.  However, the boxes of these labels will be outside
+the region @previewlatex{} considers as the preview image.  To enable a
+similar mechanism internal to @previewlatex{}, enable the
+@code{showlabels} option in the variable
+@code{preview-default-option-list} in the @code{Preview Latex} group.
+
+It must be noted, however, that a much better idea may be to use the
+Ref@TeX{} package for managing references.  @xref{RefTeX in a
+Nutshell,,RefTeX in a Nutshell,reftex,The Ref@TeX{} Manual}.
+
+@item Open previews automatically
+
+The current default is to open previews automatically when you enter
+them with cursor left/right motions.  Auto-opened previews will close
+again once the cursor leaves them again (this is also done when doing
+incremental search, or query-replace operations), unless you changed
+anything in it.  In that case, you will have to regenerate the preview
+(via e.g., @kbd{C-c C-p C-p}).  Other options for
+@code{preview-auto-reveal} are available via @code{customize}.
+
+@item Automatically cache preambles
+
+Currently @previewlatex{} asks you whether you want to cache the
+document preamble (everything before @code{\begin@{document@}}) before
+it generates previews for a buffer the first time.  Caching the preamble
+will significantly speed up regeneration of previews.  The larger your
+preamble is, the more this will be apparent.  Once a preamble is cached,
+@previewlatex{} will try to keep track of when it is changed, and dump
+a fresh format in that case.  If you experience problems with this, or
+if you want it to happen without asking you the first time, you can
+customize the variable @code{preview-auto-cache-preamble}.
+@vindex preview-auto-cache-preamble
+@cindex Caching a preamble
+
+@item Attempt to keep counters accurate when editing
+
+@vindex preview-preserve-counters
+@vindex preview-required-option-list
+Since @previewlatex{} frequently runs only small regions through
+@LaTeX{}, values like equation counters are not consistent from run to
+run.  If this bothers you, customize the variable
+@code{preview-preserve-counters} to @code{t} (this is consulted by
+@code{preview-required-option-list}).  @LaTeX{} will then output a load
+of counter information during compilation, and this information will be
+used on subsequent updates to keep counters set to useful values.  The
+additional information takes additional time to analyze, but this is
+relevant mostly only when you are regenerating all previews at once, and
+maybe you will be less tempted to do so when counters appear more or
+less correct.
+
+@item Preview your favourite @LaTeX{} constructs
+
+If you have a certain macro or environment that you want to preview,
+first check if it can be chosen by cutomizing
+@code{preview-default-options-list} in the @code{Preview Latex} group.
+
+If it is not available there, you can add it to
+@code{preview-default-preamble} also in the @code{Preview Latex} group,
+by adding a @code{\PreviewMacro} or @code{\PreviewEnvironment} entry
+(@pxref{Provided commands}) @emph{after} the @code{\RequirePackage}
+line.  For example, if you want to preview the @code{center}
+environment, press the @key{Show} button and the last @key{INS} button,
+then add
+
+@example
+\PreviewEnvironment@{center@}
+@end example
+@noindent
+in the space that just opened.  Note that since @code{center} is a
+generic formatting construct of @LaTeX{}, a general configuration like
+that is not quite prudent.  You better to do this on a per-document
+base so that it is easy to disable this behavior when you find this
+particular entry gives you trouble.
+
+One possibility is to save such settings in the corresponding file-local
+variable instead of your global configuration (@pxref{File
+Variables,,Local Variables in Files,emacs,GNU Emacs Manual}).  A perhaps
+more convenient place for such options would be in a configuration file
+in the same directory with your project (@pxref{Package options}).
+
+The usual file for @previewlatex{} preconfiguration is
+@file{prauctex.cfg}.  If you also want to keep the systemwide defaults,
+you should add a line
+
+@example
+\InputIfFileExists@{preview/prauctex.cfg@}@{@}@{@}
+@end example
+@noindent
+to your own version of @file{prauctex.cfg} (this is assuming that
+global files relating to the @code{preview} package are installed in a
+subdirectory @file{preview}, the default behavior).
+
+@item Don't preview inline math
+@cindex Inline math
+
+If you have performance problems because your document is full of inline
+math (@code{$@dots{}$}), or if your usage of @code{$} conflicts with
+@previewlatex{}'s, you can turn off inline math previews. In the
+@code{Preview Latex} group, remove @code{textmath} from
+@code{preview-default-option-list} by customizing this variable.
+@end itemize
+
+@node Known problems, For advanced users, Simple customization, top
+@chapter Known problems
+@c also used as PROBLEMS file
+@include preview-problems.texi
+
+@node For advanced users, ToDo, Known problems, top
+@chapter For advanced users
+
+This package consists of two parts: a @LaTeX{} style that splits the
+output into appropriate parts with one preview object on each page, and
+an Emacs-lisp part integrating the thing into Emacs (aided by
+@AUCTeX{}).
+
+@menu
+* The LaTeX style file::        
+* The Emacs interface::         
+* The preview images::             
+* Misplaced previews::          
+@end menu
+
+@node The LaTeX style file, The Emacs interface, For advanced users, For advanced users
+@section The @LaTeX{} style file
+@c Autogenerated from ../preview.dtx
+@include preview-dtxdoc.texi
+
+@node The Emacs interface, The preview images, The LaTeX style file, For advanced users
+@section The Emacs interface
+
+You can use @kbd{M-x customize-group @key{RET} preview-latex @key{RET}}
+in order to customize these variables, or use the menus for it.  We
+explain the various available options together with explaining how they
+work together in making @previewlatex{} work as intended.
+
+@vtable @code
+@item preview-LaTeX-command
+When you generate previews on a buffer or a region, the command in
+@code{preview-LaTeX-command} gets run (that variable should only be
+changed with Customize since its structure is somewhat peculiar, though
+expressive).  As usual with @AUCTeX{}, you can continue working while
+this is going on.  It is not a good idea to change the file until after
+@previewlatex{} has established where to place the previews which it can
+only do after the @LaTeX{} run completes.  This run produces a host of
+pseudo-error messages that get parsed by @previewlatex{} at the end of
+the @LaTeX{} run and give it the necessary information about where in
+the source file the @LaTeX{} code for the various previews is located
+exactly. The parsing takes a moment and will render Emacs busy.
+
+@item preview-LaTeX-command-replacements
+This variable specifies transformations to be used before calling the
+configured command.  One possibility is to have @samp{\pdfoutput=0 }
+appended to every command starting with @samp{pdf}.  This particular
+setting is available as the shortcut
+@samp{preview-LaTeX-disable-pdfoutput}.  Since @previewlatex{} can work
+with @acronym{PDF} files by now, there is little incentive for using
+this option, anymore (for projects not requiring @acronym{PDF} output,
+the added speed of @samp{dvipng} might make this somewhat attractive).
+
+@item preview-required-option-list
+@code{preview-LaTeX-command} uses @code{preview-required-option-list} in
+order to pass options such as @option{auctex}, @option{active} and
+@option{dvips} to the @file{preview} package.  This means that the user
+need (and should) not supply these in the document itself in case he
+wants to be able to still compile his document without it turning into
+an incoherent mass of little pictures.  These options even get passed
+in when the user loads @file{preview} explicitly in his document.
+
+The default includes an option @code{counters} that is controlled by the
+boolean variable
+
+@item preview-preserve-counters
+This option will cause the @file{preview} package to emit information
+that will assist in keeping things like equation counters and section
+numbers reasonably correct even when you are regenerating only single
+previews.
+
+@item preview-default-option-list
+@itemx preview-default-preamble
+If the document does not call in the package @code{preview} itself (via
+@code{\usepackage}) in the preamble, the preview package is loaded using
+default options from @code{preview-default-option-list} and additional
+commands specified in @code{preview-default-preamble}.
+
+@item preview-fast-conversion
+This is relevant only for @acronym{DVI} mode.  It defaults to `On' and
+results in the whole document being processed as one large PostScript
+file from which the single images are extracted with the help of parsing
+the PostScript for use of so-called @acronym{DSC} comments.  The
+bounding boxes are extracted with the help of @TeX{} instead of getting
+them from Dvips.  If you are experiencing bounding box problems, try
+setting this option to `Off'.
+
+@item preview-prefer-TeX-bb
+If this option is `On', it tells @previewlatex{} never to try to extract
+bounding boxes from the bounding box comments of @acronym{EPS} files,
+but rather rely on the boxes it gets from @TeX{}.  If you activated
+@code{preview-fast-conversion}, this is done, anyhow, since there are no
+@acronym{EPS} files from which to read this information.  The option
+defaults to `Off', simply because about the only conceivable reason to
+switch off @code{preview-fast-conversion} would be that you have some
+bounding box problem and want to get Dvips' angle on that matter.
+
+@item preview-scale-function
+@itemx preview-reference-face
+@itemx preview-document-pt-list
+@itemx preview-default-document-pt
+@code{preview-scale-function} determines by what factor
+images should be scaled when appearing on the screen.  If you specify a
+numerical value here, the physical size on the screen will be that of
+the original paper output scaled by the specified factor, at least if
+Emacs' information about screen size and resolution are correct.  The
+default is to let @code{preview-scale-from-face} determine the scale
+function.  This function determines the scale factor by making the
+size of the default font in the document match that of the on-screen
+fonts.
+
+The size of the screen fonts is deduced from the font
+@code{preview-reference-face} (usually the default face used for
+display), the size of the default font for the document is determined
+by calling @code{preview-document-pt}.
+@findex preview-document-pt
+This function consults the members of @code{preview-document-pt-list} in
+turn until it gets the desired information.  The default consults first
+@code{preview-parsed-font-size},
+@vindex preview-parsed-font-size
+then calls @code{preview-auctex-font-size}
+@findex preview-auctex-font-size
+which asks @AUCTeX{} about any size specification like @option{12pt} to
+the documentclass that it might have detected when parsing the document, and
+finally reverts to just assuming @code{preview-default-document-pt} as
+the size used in the document (defaulting to 10pt).
+
+If you find that the size of previews and the other Emacs display
+clashes, something goes wrong.  @code{preview-parsed-font-size} is
+determined at @code{\begin@{document@}} time; if the default font size
+changes after that, it will not get reported.  If you have an outdated
+version of @file{preview.sty} in your path, the size might not be
+reported at all.  If in this case @AUCTeX{} is unable to find a size
+specification, and if you are using a document class with a different
+default value (like KomaScript), the default fallback assumption will
+probably be wrong and @previewlatex{} will scale up things too large.
+So better specify those size options even when you know that @LaTeX{}
+does not need them: @previewlatex{} might benefit from them.  Another
+possibility for error is that you have not enabled @AUCTeX{}'s document
+parsing options.  The fallback method of asking @AUCTeX{} about the size
+might be disabled in future versions of @previewlatex{} since in
+general it is more reliable to get this information from the @LaTeX{}
+run itself.
+
+@item preview-fast-dvips-command
+@itemx preview-dvips-command
+The regular command for turning a @acronym{DVI} file into a single
+PostScript file is @code{preview-fast-dvips-command}, while
+@code{preview-dvips-command} is used for cranking out a @acronym{DVI}
+file where every preview is in a separate @acronym{EPS} file.  Which of
+the two commands gets used depends on the setting of
+@code{preview-fast-conversion}.  The printer specified here by default
+is @option{-Pwww} by default, which will usually get you scalable fonts
+where available. If you are experiencing problems, you might want to try
+playing around with Dvips options (@inforef{Command-line options,,dvips}).
+
+The conversion of the previews into PostScript or @acronym{EPS} files
+gets started after the @LaTeX{} run completes when Emacs recognizes the
+first image while parsing the error messages.  When Emacs has finished
+parsing the error messages, it activates all detected previews.  This
+entails throwing away any previous previews covering the same areas, and
+then replacing the text in its visual appearance by a placeholder
+looking like a roadworks sign.
+
+@item preview-nonready-icon-specs
+This is the roadworks sign displayed while previews are being prepared.
+You may want to customize the font sizes at which @previewlatex{}
+switches over between different icon sizes, and the ascent ratio which
+determines how high above the base line the icon gets placed.
+
+@item preview-error-icon-specs
+@itemx preview-icon-specs
+Those are icons placed before the source code of an opened preview and,
+respectively, the image specs to be used for PostScript errors, and a
+normal open preview in text representation.
+
+@item preview-inner-environments
+This is a list of environments that are regarded as inner levels of an
+outer environment when doing @code{preview-environment}. One example
+when this is needed is in
+@code{\begin@{equation@}\begin@{split@}@dots{}\end@{split@}\end@{equation@}}, and
+accordingly @code{split} is one entry in
+@code{preview-inner-environments}.
+
+@item preview-use-balloon-help
+If you turn this XEmacs-only option `on', then moving the mouse over
+previews and icons will show appropriate help texts.  This works by
+switching on @code{balloon-help-mode} in the buffer if it is not already
+enabled.  The default now is `off' since some users reported problems
+with their version of XEmacs.  @w{GNU Emacs} has its corresponding
+@code{tooltip-mode} enabled by default and in usable condition.
+
+@end vtable
+
+@node The preview images, Misplaced previews, The Emacs interface, For advanced users
+@section The preview images
+
+@vtable @code
+@item preview-image-type
+@itemx preview-image-creators
+@itemx preview-gs-image-type-alist
+What happens when @LaTeX{} is finished depends on the configuration of
+@code{preview-image-type}.  What to do for each of the various settings
+is specified in the variable @code{preview-image-creators}.  The options
+to pass into Ghostscript and what Emacs image type to use is specified
+in @code{preview-gs-image-type-alist}.
+
+@code{preview-image-type} defaults to @code{png}.  For this to work,
+your version of Ghostscript needs to support the @option{png16m} device.
+If you are experiencing problems here, you might want to reconfigure
+@code{gs-image-type-alist} or @code{preview-image-type}.  Reconfiguring
+@code{preview-image-creators} is only necessary for adding additional
+image types.
+
+Most devices make @previewlatex{} start up a single Ghostscript process
+for the entire preview run (as opposed to one per image) and feed it
+either sections of a @acronym{PDF} file (if PDF@LaTeX{} was used), or
+(after running Dvips) sections of a single PostScript file or separate
+@acronym{EPS} files in sequence for conversion into @acronym{PNG} format
+which can be displayed much faster by Emacs.  Actually, not in sequence
+but backwards since you are most likely editing at the end of the
+document.  And as an added convenience, any preview that happens to be
+on-screen is given higher priority so that @previewlatex{} will first
+cater for the images that are displayed. There are various options
+customizable concerning aspects of that operation, see the customization
+group @code{Preview Gs} for this.
+
+Another noteworthy setting of @code{preview-image-type} is
+@samp{dvipng}: in this case, the @samp{dvipng}@pindex{dvipng} program
+will get run on @acronym{DVI} output (see below for @acronym{PDF}).
+This is in general much faster than Dvips and Ghostscript.  In that
+case, the option
+
+@item preview-dvipng-command
+will get run for doing the conversion, and it is expected that
+
+@item preview-dvipng-image-type
+images get produced (@samp{dvipng} might be configured for other image
+types as well).  You will notice that @code{preview-gs-image-type-alist}
+contains an entry for @code{dvipng}: this actually has nothing to with
+@samp{dvipng} itself but specifies the image type and Ghostscript device
+option to use when @samp{dvipng} can't be used.  This will obviously be
+the case for @acronym{PDF} output by PDF@LaTeX{}, but it will also happen
+if the @acronym{DVI} file contains PostScript specials in which case the
+affected images will get run through Dvips and Ghostscript once
+@samp{dvipng} finishes.
+
+@item preview-gs-options
+Most interesting to the user perhaps is the setting of this variable.
+It contains the default antialiasing settings @option{-dTextAlphaBits=4}
+and @option{-dGraphicsAlphaBits=4}.  Decreasing those values to 2 @w{or
+1} might increase Ghostscript's performance if you find it lacking.
+@end vtable
+
+Running and feeding Ghostscript from @previewlatex{} happens
+asynchronously again: you can resume editing while the images arrive.
+While those pretty pictures filling in the blanks on screen tend to
+make one marvel instead of work, rendering the non-displayed images
+afterwards will not take away your attention and will eventually
+guarantee that jumping around in the document will encounter only
+prerendered images.
+
+@node Misplaced previews,  , The preview images, For advanced users
+@section Misplaced previews
+
+If you are reading this section, the first thing is to check that your
+problem is not caused by x-symbol in connection with an installation not
+supporting 8-bit characters (@pxref{x-symbol interoperation}).  If not,
+here's the beef:
+
+As explained previously, Emacs uses pseudo-error messages generated by
+the @samp{preview} package in order to pinpoint the exact source
+location where a preview originated.  This works in running text, but
+fails when preview material happens to lie in macro arguments, like the
+contents of @code{\emph}. Those macros first read in their entire
+argument, munge it through, perhaps transform it somehow, process it and
+perhaps then typeset something. When they finally typeset something,
+where is the location where the stuff originated? @TeX{}, having read in
+the entire argument before, does not know and actually there would be no
+sane way of defining it.
+
+For previews contained inside such a macro argument, the default
+behaviour of @previewlatex{} is to use a position immediately after the
+closing brace of the argument. All the previews get placed there, all at
+a zero-width position, which means that Emacs displays it in an order
+that @previewlatex{} cannot influence (currently in Emacs it is even
+possible that the order changes between runs). And since the placement
+of those previews is goofed up, you will not be able to regenerate them
+by clicking on them. The default behaviour is thus somewhat undesirable.
+
+The solution (like with other preview problems) is to tell the @LaTeX{}
+@samp{preview} package how to tackle this problem (@pxref{The LaTeX
+style file}).  Simply, you don't need @code{\emph} do anything at all
+during previews! You only want the text math previewed, so the solution
+is to use @code{\PreviewMacro*\emph} in the preamble of your document
+which will make @LaTeX{} ignore @code{\emph} completely as long as it is
+not part of a larger preview (in which case it gets typeset as
+usual). Its argument thus becomes ordinary text and gets treated like
+ordinary text.
+
+Note that it would be a bad idea to declare
+@code{\PreviewMacro*[@{@{@}@}]\emph} since then both @code{\emph} as
+well as its argument would be ignored instead of previewed. For
+user-level macros, this is almost never wanted, but there may be
+internal macros where you might want to ignore internal arguments.
+
+The same mechanism can be used for a number of other text-formatting
+commands like @code{\textrm}, @code{\textit} and the like. While they
+all use the same internal macro @code{\text@@command}, it will not do to
+redefine just that, since they call it only after having read their
+argument in, and then it already is too late. So you need to disable
+every of those commands by hand in your document preamble.
+
+Actually, we wrote all of the above just to scare you.  At least all of
+the above mentioned macros and a few more are already catered for by a
+configuration file @file{prauctex.cfg} that gets loaded by default
+unless the @samp{preview} package gets loaded with the @option{noconfig}
+option.  You can make your own copy of this file in a local directory
+and edit it in case of need.  You can also add loading of a file of your
+liking to @code{preview-default-preamble},
+@vindex preview-default-preamble
+or alternatively do the
+manual disabling of your favorite macro in
+@code{preview-default-preamble},
+@vindex preview-default-preamble
+which is customizable in the Preview Latex group.
+
+@node ToDo, Frequently Asked Questions, For advanced users, top
+@c Also used as TODO: in separate file
+@appendix ToDo
+@include preview-todo.texi
+
+@node Frequently Asked Questions, Copying this Manual, ToDo, top
+@c Also used as TODO: in separate file
+@appendix Frequently Asked Questions
+@include preview-faq.texi
+
+@node Copying this Manual, Index, Frequently Asked Questions, top
+@c Not to be changed often, I think: in separate file.
+@appendix Copying this Manual
+
+@ifinfo
+The copyright notice for this manual is:
+
+@insertcopying
+@end ifinfo
+
+The full license text can be read here:
+
+@menu
+* GNU Free Documentation License:: License for copying this manual.
+@end menu
+
+@include fdl.texi
+
+@c @node Credits, Index, Internals, top
+@c @appendix Credits 
+
+@node Index,  , Copying this Manual, top
+@unnumbered Index
+
+@printindex cp
+
+@bye