     [file version.texi not included]
     [file macros.texi not included]

previewlatex
************

This manual may be copied under the conditions spelled out in Copying this Manual.

previewlatex is a package embedding preview fragments into Emacs source buffers under the AUCTeX editing environment for LaTeX.  It uses 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 preview-latex, all in lowercase letters, with a hyphen.  If you typeset it, you can use a sans-serif font to visually offset it.

Copying
*******

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 Copying (the AUCTeX manual).

This manual specifically is covered by the GNU Free Documentation License (see Copying this Manual).

Introduction
************

     [file preview-readme.texi not included]

Installation
************

Installation is now being covered in Installation (the AUCTeX manual).

Key bindings and user-level lisp functions
******************************************

previewlatex adds key bindings starting with C-c C-p to the supported modes of AUCTeX (see Key Index (auctex)).  It will also add its own 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 C-h f if you need the Lisp information.

C-c C-p C-p
preview-at-point
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 (transient-mark-mode or zmacs-regions), it is run through preview-region.

<mouse-2>
     The middle mouse button has a similar action bound to it as 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.

<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:

C-c C-p C-w
preview-copy-region-as-mml
Copy a 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 (see Composing (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 preview-transparent-border set to 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 mml-preview (on M-m P, or C-c C-m P in Emacs 22) to make sure they look fine.

C-c C-p C-e
preview-environment
Preview/Generate previews for environment
     Run preview on LaTeX environment.  The environments in preview-inner-environments are treated as inner levels so that for instance, the split environment in \begin{equation}\begin{split}...\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.

C-c C-p C-s
preview-section
Preview/Generate previews for section
     Run preview on this LaTeX section.

C-c C-p C-r
preview-region
Preview/Generate previews for region
     Run preview on current region.

C-c C-p C-b
preview-buffer
Preview/Generate previews for buffer
     Run preview on the current buffer.

C-c C-p C-d
preview-document
Preview/Generate previews for document
     Run preview on the current document.

C-c C-p C-c C-p
preview-clearout-at-point
Preview/Remove previews at point
     Clear out (remove) the previews that are immediately adjacent to point.

C-c C-p C-c C-s
preview-clearout-section
Preview/Remove previews from section
     Clear out all previews in current section.

C-c C-p C-c C-r
preview-clearout
Preview/Remove previews from region
     Clear out all previews in the current region.

C-c C-p C-c C-b
preview-clearout-buffer
Preview/Remove previews from buffer
     Clear out all previews in current buffer. This makes the current buffer lose all previews.

C-c C-p C-c C-d
preview-clearout-document
Preview/Remove previews from 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.

C-c C-p C-f
preview-cache-preamble
Preview/Turn preamble cache on
     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.

C-c C-p C-c C-f
preview-cache-preamble-off
Preview/Turn preamble cache off
     Clear the pregenerated format file and stop using preambles for the current document. If the caching gives you problems, use this.

C-c C-p C-i
preview-goto-info-page
Preview/Read Documentation
     Read this info manual.

M-x preview-report-bug RET
preview-report-bug
Preview/Report 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 Known problems.

C-c C-k
LaTeX/TeX Output/Kill Job
     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.

Simple customization
********************

Customization options can be found by typing M-x customize-group RET preview 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 For advanced users), but some are:

  * 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 preview-transparent-color in the 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 Emacs 21 and Emacs 22, and it is not available in XEmacs.

  * Showing \labels

     When using previewlatex, the \labels are hidden by the previews.  It is possible to make them visible in the output by using the LaTeX package showkeys alternatively 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 showlabels option in the variable preview-default-option-list in the Preview Latex group.

     It must be noted, however, that a much better idea may be to use the RefTeX package for managing references.  See RefTeX in a Nutshell (The RefTeX Manual).

  * 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., C-c C-p C-p).  Other options for preview-auto-reveal are available via customize.

  * Automatically cache preambles

     Currently previewlatex asks you whether you want to cache the document preamble (everything before \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 preview-auto-cache-preamble.

  * Attempt to keep counters accurate when editing

     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 preview-preserve-counters to t (this is consulted by 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.

  * 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 preview-default-options-list in the Preview Latex group.

     If it is not available there, you can add it to preview-default-preamble also in the Preview Latex group, by adding a \PreviewMacro or \PreviewEnvironment entry (see Provided commands) after the \RequirePackage line.  For example, if you want to preview the center environment, press the Show button and the last INS button, then add

          \PreviewEnvironment{center}

     in the space that just opened.  Note that since 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 (see Local Variables in Files (GNU Emacs Manual)).  A perhaps more convenient place for such options would be in a configuration file in the same directory with your project (see Package options).

     The usual file for previewlatex preconfiguration is prauctex.cfg.  If you also want to keep the systemwide defaults, you should add a line

          \InputIfFileExists{preview/prauctex.cfg}{}{}

     to your own version of prauctex.cfg (this is assuming that global files relating to the preview package are installed in a subdirectory preview, the default behavior).

  * Don't preview inline math

     If you have performance problems because your document is full of inline math ($...$), or if your usage of $ conflicts with previewlatex's, you can turn off inline math previews. In the Preview Latex group, remove textmath from preview-default-option-list by customizing this variable.

Known problems
**************

     [file preview-problems.texi not included]

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).

The LaTeX style file
====================

     [file preview-dtxdoc.texi not included]

The Emacs interface
===================

You can use M-x customize-group RET preview-latex 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.

preview-LaTeX-command
     When you generate previews on a buffer or a region, the command in 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.

preview-LaTeX-command-replacements
     This variable specifies transformations to be used before calling the configured command.  One possibility is to have \pdfoutput=0 appended to every command starting with pdf.  This particular setting is available as the shortcut preview-LaTeX-disable-pdfoutput.  Since previewlatex can work with PDF files by now, there is little incentive for using this option, anymore (for projects not requiring PDF output, the added speed of dvipng might make this somewhat attractive).

preview-required-option-list
     preview-LaTeX-command uses preview-required-option-list in order to pass options such as auctex, active and dvips to the 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 preview explicitly in his document.

     The default includes an option counters that is controlled by the boolean variable

preview-preserve-counters
     This option will cause the 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.

preview-default-option-list
preview-default-preamble
     If the document does not call in the package preview itself (via \usepackage) in the preamble, the preview package is loaded using default options from preview-default-option-list and additional commands specified in preview-default-preamble.

preview-fast-conversion
     This is relevant only for 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 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'.

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 EPS files, but rather rely on the boxes it gets from TeX.  If you activated preview-fast-conversion, this is done, anyhow, since there are no EPS files from which to read this information.  The option defaults to `Off', simply because about the only conceivable reason to switch off preview-fast-conversion would be that you have some bounding box problem and want to get Dvips' angle on that matter.

preview-scale-function
preview-reference-face
preview-document-pt-list
preview-default-document-pt
     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 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 preview-reference-face (usually the default face used for display), the size of the default font for the document is determined by calling preview-document-pt. This function consults the members of preview-document-pt-list in turn until it gets the desired information.  The default consults first preview-parsed-font-size, then calls preview-auctex-font-size which asks AUCTeX about any size specification like 12pt to the documentclass that it might have detected when parsing the document, and finally reverts to just assuming 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.  preview-parsed-font-size is determined at \begin{document} time; if the default font size changes after that, it will not get reported.  If you have an outdated version of 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.

preview-fast-dvips-command
preview-dvips-command
     The regular command for turning a DVI file into a single PostScript file is preview-fast-dvips-command, while preview-dvips-command is used for cranking out a DVI file where every preview is in a separate EPS file.  Which of the two commands gets used depends on the setting of preview-fast-conversion.  The printer specified here by default is -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 (see Command-line options (dvips)).

     The conversion of the previews into PostScript or 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.

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.

preview-error-icon-specs
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.

preview-inner-environments
     This is a list of environments that are regarded as inner levels of an outer environment when doing preview-environment. One example when this is needed is in \begin{equation}\begin{split}...\end{split}\end{equation}, and accordingly split is one entry in preview-inner-environments.

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 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.  GNU Emacs has its corresponding tooltip-mode enabled by default and in usable condition.

The preview images
==================

preview-image-type
preview-image-creators
preview-gs-image-type-alist
     What happens when LaTeX is finished depends on the configuration of preview-image-type.  What to do for each of the various settings is specified in the variable preview-image-creators.  The options to pass into Ghostscript and what Emacs image type to use is specified in preview-gs-image-type-alist.

     preview-image-type defaults to png.  For this to work, your version of Ghostscript needs to support the png16m device. If you are experiencing problems here, you might want to reconfigure gs-image-type-alist or preview-image-type.  Reconfiguring 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 PDF file (if PDFLaTeX was used), or (after running Dvips) sections of a single PostScript file or separate EPS files in sequence for conversion into 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 Preview Gs for this.

     Another noteworthy setting of preview-image-type is dvipng: in this case, the dvipng program will get run on DVI output (see below for PDF). This is in general much faster than Dvips and Ghostscript.  In that case, the option

preview-dvipng-command
     will get run for doing the conversion, and it is expected that

preview-dvipng-image-type
     images get produced (dvipng might be configured for other image types as well).  You will notice that preview-gs-image-type-alist contains an entry for dvipng: this actually has nothing to with dvipng itself but specifies the image type and Ghostscript device option to use when dvipng can't be used.  This will obviously be the case for PDF output by PDFLaTeX, but it will also happen if the DVI file contains PostScript specials in which case the affected images will get run through Dvips and Ghostscript once dvipng finishes.

preview-gs-options
     Most interesting to the user perhaps is the setting of this variable. It contains the default antialiasing settings -dTextAlphaBits=4 and -dGraphicsAlphaBits=4.  Decreasing those values to 2 or 1 might increase Ghostscript's performance if you find it lacking.

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.

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 (see x-symbol interoperation).  If not, here's the beef:

As explained previously, Emacs uses pseudo-error messages generated by the 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 \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 preview package how to tackle this problem (see The LaTeX style file).  Simply, you don't need \emph do anything at all during previews! You only want the text math previewed, so the solution is to use \PreviewMacro*\emph in the preamble of your document which will make LaTeX ignore \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 \PreviewMacro*[{{}}]\emph since then both \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 \textrm, \textit and the like. While they all use the same internal macro \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 prauctex.cfg that gets loaded by default unless the preview package gets loaded with the 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 preview-default-preamble, or alternatively do the manual disabling of your favorite macro in preview-default-preamble, which is customizable in the Preview Latex group.

ToDo
****

     [file preview-todo.texi not included]

Frequently Asked Questions
**************************

     [file preview-faq.texi not included]

Copying this Manual
*******************

The copyright notice for this manual is:

This manual is for preview-latex, a LaTeX preview mode for AUCTeX (version VERSION from UPDATED).

Copyright © 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 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.''

The full license text can be read here:

     [file fdl.texi not included]