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.

One option that you might want to switch on here is 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 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).

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