1.1 What use is it?

WYSIWYG (what you see is what you get) sometimes is considered all the rage, sometimes frowned upon. Do we really want it? Wrong question. The right question is what we want from it. Except when finetuning the layout, we don’t want to use printer fonts for on-screen text editing. The low resolution and contrast of a computer screen render all but the coarsest printer fonts (those for low-quality newsprint) unappealing, and the margins and pagination of the print are not wanted on the screen, either. On the other hand, more complex visual compositions like math formulas and tables can’t easily be taken in when seen only in the source. preview-latex strikes a balance: it only uses graphic renditions of the output for certain, configurable constructs, does this only when told, and then right in the source code. Switching back and forth between the source and preview is easy and natural and can be done for each image independently. Behind the scenes of preview-latex, a sophisticated framework of other programs like ‘dvipng’, Dvips and Ghostscript are employed together with a special LaTeX style file for extracting the material of interest in the background and providing fast interactive response.

1.2 Activating preview-latex

Successful installation automatically activates the package at Emacs startup.

If you don’t get a “Preview” menu in LaTeX mode in spite of AUCTeX showing its “Command”, your installation is broken. One possible cause are duplicate Lisp files that might be detectable with M-x list-load-path-shadows RET.

1.3 Getting started

Once activated, preview-latex and its documentation will be accessible via its menus. When you have loaded a LaTeX document (a sample document circ.tex is included in the distribution, but most documents including math and/or figures should do), you can use its menu or C-c C-p C-d (for ‘Preview/Document’). Previews will now be generated for various objects in your document. You can use the time to take a short look at the other menu entries and key bindings in the ‘Preview’ menu. You’ll see the previewed objects change into a roadworks sign when preview-latex has determined just what it is going to preview. Note that you can freely navigate the buffer while this is going on. When the process is finished you will see the objects typeset in your buffer.

It is a bad idea, however, to edit the buffer before the roadworks signs appear, since that is the moment when the correlation between the original text and the buffer locations gets established. If the buffer changes before that point of time, the previews will not be placed where they belong. If you do want to change some obvious error you just spotted, we recommend you stop the background process by pressing C-c C-k.

To see/edit the LaTeX code for a specific object, put the point (the cursor) on it and press C-c C-p C-p (for ‘Preview/at point’). It will also do to click with the middle mouse button on the preview. Now you can edit the code, and generate a new preview by again pressing C-c C-p C-p (or by clicking with the middle mouse button on the icon before the edited text).

If you are using the desktop package, previews will remain from one session to the next as long as you don’t kill your buffer.

1.4 Basic modes of operation

preview-latex has a number of methods for generating its graphics. Its default operation is equivalent to using the ‘LaTeX’ command from AUCTeX. If this happens to be a call of PDFLaTeX generating PDF output (you need at least AUCTeX 11.51 for this), then Ghostscript will be called directly on the resulting PDF file. If a DVI file gets produced, first Dvips and then Ghostscript get called by default.

The image type to be generated by Ghostscript can be configured with

M-x customize-option RET preview-image-type RET

The default is ‘png’ (the most efficient image type). A special setting is ‘dvipng’ in case you have the ‘dvipng’ program installed. In this case, ‘dvipng’ will be used for converting DVI files and Ghostscript (with a ‘PNG’ device) for converting PDF files. ‘dvipng’ is much faster than the combination of Dvips and Ghostscript. ‘dvipng’ is included in standard TeX Live distribution.

1.5 More documentation

After the installation, documentation in the form of an info manual will be available. You can access it with the standalone info reader with

info preview-latex

or by pressing C-h i d m preview-latex RET in Emacs. Once preview-latex is activated, you can instead use C-c C-p TAB (or the menu entry ‘Preview/Read documentation’).

Depending on your installation, a printable manual may also be available in the form of preview-latex.pdf.

Detailed documentation for the LaTeX style used for extracting the preview images is placed in preview.pdf in a suitable directory during installation; on typical TeX Live-based systems,

texdoc preview

will display it.

1.6 Availability

The preview-latex project is now part of AUCTeX and accessible as part of the AUCTeX project page.

Anonymous Git is available at git://git.savannah.gnu.org/auctex.git or https://git.savannah.gnu.org/git/auctex.git. You can also browse the repository via web interface.

1.7 Contacts

Bug reports should be sent by using M-x preview-report-bug RET, as this will fill in a lot of information interesting to us. If the installation fails (but this should be a rare event), report bugs to bug-auctex@gnu.org.

There is a general discussion list for AUCTeX which also covers preview-latex, look at https://lists.gnu.org/mailman/listinfo/auctex. For more information on the mailing list, send a message with just the word “help” as subject or body to auctex-request@gnu.org. For the developers, there is the auctex-devel@gnu.org list; it would probably make sense to direct feature requests and questions about internal details there. There is a low-volume read-only announcement list available to which you can subscribe by sending a mail with “subscribe” in the subject to info-auctex-request@gnu.org.

Offers to support further development will be appreciated. If you want to show your appreciation with a donation to the main developer, you can do so via PayPal to dak@gnu.org, and of course you can arrange for service contracts or for added functionality. Take a look at the ToDo list for suggestions in that area.

5.1 Font problems with Dvips

Some fonts have been reported to produce wrong characters with preview-latex. preview-latex calls Dvips by default with the option -Pwww in order to get scalable fonts for nice results. If you are using antialiasing, however, the results might be sufficiently nice with bitmapped fonts, anyway. You might try -Ppdf for another stab at scalable fonts, or other printer definitions. Use

M-x customize-option RET preview-fast-dvips-command RET

and

M-x customize-option RET preview-dvips-command RET

in order to customize this.

One particular problem is that several printer setup files (typically in a file called /usr/share/texmf/dvips/config/config.pdf if you are using the -Ppdf switch) contain the G option for ‘character shifting’. This option will result in ‘fi’ being rendered as ‘£’ (British Pounds sign) in several fonts, unless your version of Dvips has a long-standing bug in its implementation fixed (only very recent versions of Dvips have).

5.2 Too small bounding boxes

The bounding box of a preview is determined by the LaTeX package using the pure TeX bounding boxes. If there is material extending outside of the TeX box, that material will be missing from the preview image. This happens for the label-showing boxes from the showkeys package. This particular problem can be circumvented by using the showlabels option of the preview package.

In general, you should try to fix the problem in the TeX code, like avoiding drawing outside of the picture with PSTricks.

One possible remedy is to set preview-fast-conversion to ‘Off’ (see The Emacs interface). The conversion will take more time, but will then use the bounding boxes from EPS files generated by Dvips.

Dvips generally does not miss things, but it does not understand PostScript constructs like \resizebox or \rotate commands, so will generate rather wrong boxes for those. Dvips can be helped with the psfixbb package option to preview (see The LaTeX style file), which will tag the corners of the included TeX box. This will mostly be convenient for pure PostScript stuff like that created by PSTricks, which Dvips would otherwise reserve no space for.

5.3 x-symbol interoperation

Thanks to the work of Christoph Wedler, starting with version ‘4.0h/beta’ of x-symbol, the line parsing of AUCTeX and preview-latex is fully supported. Earlier versions exhibit problems. However, versions before ‘4.2.2’ will cause a drastic slowdown of preview-latex’s parsing pass, so we don’t recommend to use versions earlier than that.

If you wonder what x-symbol is, it is a package that transforms various tokens and subscripts to a more readable form while editing and offers a few input methods handy especially for dealing with math. Take a look at http://x-symbol.sourceforge.net/.

x-symbol versions up to ‘4.5.1-beta’ at least require an 8bit-clean TeX implementation (meaning that its terminal output should not use ‘^^’-started escape sequences) for cooperation with preview-latex. Later versions may get along without it, like preview-latex does now.

If you experience problems with circ.tex in connection with both x-symbol and Latin-1 characters, you may need to change your language environment or, as a last resort, customize the variable LaTeX-command-style by replacing the command latex with latex -translate-file=cp8bit.

5.4 Middle-clicks paste instead of toggling

This is probably the fault of your favorite package. isearch.el is known to be affected while searches are in progress, but the code is such a complicated mess that no patch is in sight. Better just end the search with RET before toggling and resume with C-s C-s or similar afterwards. Since previews over the current match will auto-open, anyway, this should not be much of a problem in practice.

5.5 No images are displayed with gs 9.27 and earlier

preview-latex tries to adjust the foreground and background colors of generated images to those of Emacs. Unfortunately, incompatible changes introduced in Ghostscript 9.27 breaks the traditional method partially, and preview-latex can display no images under certain circumstances.

A new method implemented alternatively works only with Ghostscript > 9.27. If you are using Ghostscript 9.27 or earlier, customize the option preview-pdf-adjust-color-method.

User Option: preview-pdf-adjust-color-method ¶

Method to adjust colors of images generated from PDF. It is not consulted when the LaTeX command produces DVI files.

When the option is t (default), preview-latex adjusts the FG and BG colors of the generated images by the new method. This method requires that Ghostscript has working DELAYBIND feature, thus is invalid with gs 9.27 (and possibly < 9.27).

When it is compatible, preview-latex uses traditional method. This option is provided for backward compatibility with older gs. See the below explanation for detail.

When nil, no adjustment is done and “black on white” image is generated regardless of Emacs color. This is provided for fallback for gs 9.27 users with customized foreground color. See the below explanation for detail.

When the LaTeX command produces PDF rather than DVI and Emacs has non-trivial foreground color, the traditional method (compatible) makes gs >= 9.27 to stop with error. Here, “non-trivial foreground color” includes customized themes.

If you use such non-trivial foreground color and the version of Ghostscript equals to 9.27, you have two options:

1. Choose the value compatible and customize preview-reference-face to have default (black) foreground color. This makes the generated image almost non-readable on dark background, so the next option would be your only choice in that case.
2. Choose the value nil, which forces plain “black on white” appearance for the generated image. You can at least read what are written in the image although they may not match with your Emacs color well.

The default value used to be compatible for short period before Ghostscript 9.50 was released but now is t.

5.6 Black texts are too hard to read on dark background

Unfortunately, foreground color adjustment discussed in the previous node doesn’t work for XeLaTeX for technical reason. The texts are always rendered as black in the preview images, so it’s almost impossible to read them on dark background. Hence XeLaTeX users who like dark background in Emacs frame should customize preview-pdf-adjust-color-method to nil.

6.1 The LaTeX style file

The main purpose of this package is the extraction of certain environments (most notably displayed formulas) from LaTeX sources as graphics. This works with DVI files postprocessed by either Dvips and Ghostscript or dvipng, but it also works when you are using PDFTeX for generating PDF files (usually also postprocessed by Ghostscript).

Current uses of the package include the preview-latex package for WYSIWYG functionality in the AUCTeX editing environment, generation of previews in LyX, as part of the operation of the pst-pdf package, the tbook XML system and some other tools.

Producing EPS files with Dvips and its derivatives using the -E option is not a good alternative: People make do by fiddling around with \thispagestyle{empty} and hoping for the best (namely, that the specified contents will indeed fit on single pages), and then trying to guess the baseline of the resulting code and stuff, but this is at best dissatisfactory. The preview package provides an easy way to ensure that exactly one page per request gets shipped, with a well-defined baseline and no page decorations. While you still can use the preview package with the ‘classic’

dvips -E -i

invocation, there are better ways available that don’t rely on Dvips not getting confused by PostScript specials.

For most applications, you’ll want to make use of the tightpage option. This will embed the page dimensions into the PostScript or PDF code, obliterating the need to use the -E -i options to Dvips. You can then produce all image files with a single run of Ghostscript from a single PDF or PostScript (as opposed to EPS) file.

Various options exist that will pass TeX dimensions and other information about the respective shipped out material (including descender size) into the log file, where external applications might make use of it.

The possibility for generating a whole set of graphics with a single run of Ghostscript (whether from LaTeX or PDFLaTeX) increases both speed and robustness of applications. It is also feasible to use dvipng on a DVI file with the options

-picky -noghostscript

to omit generating any image file that requires Ghostscript, then let a script generate all missing files using Dvips/Ghostscript. This will usually speed up the process significantly.

• Package options
• Provided commands

\usepackage[options]{preview}

6.2 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 preview-latex 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 preview-latex 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 preview-latex 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 preview-latex 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 preview-latex 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 preview-latex will scale up things too large. So better specify those size options even when you know that LaTeX does not need them: preview-latex 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 preview-latex 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 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 (dvips)Command-line options).

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 preview-latex 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-protect-point ¶

This boolean variable determines whether previews generated on top of the current point should be temporarily opened. Default value is nil.

preview-leave-open-previews-visible ¶

This boolean variable determines whether to leave preview images visible when they are opened.

There is a side effect in enabling this option. The preview image doesn’t turn into construction sign temporarily when you edit the underlying LaTeX code and regenerate the preview; it is just replaced by updated image when ready. This behavior suppresses flicker in the appearance.

6.3 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 preview-gs-image-type-alist or preview-image-type. Reconfiguring preview-image-creators is only necessary for adding additional image types.

Most devices make preview-latex 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 preview-latex 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.

Note for pLaTeX and upLaTeX users: It is known that dvipng is not compatible with pLaTeX and upLaTeX. If preview-image-type is set to ‘dvipng’ and (u)pLaTeX is used, ‘dvipng’ just fails and preview-latex falls back on Dvips and Ghostscript.

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 preview-latex 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.

6.4 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 preview-latex 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 preview-latex 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 \AtBeginDocument{\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.