[gnu-emacs-elpa] / packages / auctex / doc / preview-latex.texi

\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