\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, 2017 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{C-c C-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.

@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}.

@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