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.

• Showing \labels

  When using preview-latex, 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 preview-latex considers as the preview image. To enable a similar mechanism internal to preview-latex, 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 in 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. Note that the default behavior of preview-auto-reveal derives from the list preview-auto-reveal-commands which can be customized as well.

• Automatically cache preambles

  Currently preview-latex 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, preview-latex 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 preview-latex 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-option-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 in 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 preview-latex 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 preview-latex’s, you can turn off inline math previews. In the ‘Preview Latex’ group, remove textmath from preview-default-option-list by customizing this variable.

• Customize where previews are shown

  Set preview-visibility-style to control when previews appear:

  off-point

  Previews replace the source when point is elsewhere. When a preview is opened to show the source, the preview is replaced by an icon. This is the default value.

  at-point

  Previews never obscure the source. In this mode, preview visibility is inverted: previews are hidden when they would normally be closed and made visible when they would normally be opened. The value of preview-auto-reveal controls when a preview is considered opened (e.g., set to t to open a preview whenever the cursor enters the preview’s source).

  always

  Previews are always visible when available. Away from point they replace the source; when opened they remain displayed alongside the source.

  The placement of previews when shown with their source is controlled with preview-at-point-placement, which can take these values:

  before-string

  Show the preview before the source (default).

  after-string

  Show the preview after the source.

  buframe

  Show the preview in a side frame adjacent to point. Requires the buframe package (available on ELPA). Only one frame is used, showing the preview whose source is at point. If preview-visibility-style is set to off-point or always, a preview opened away from point is shown only when point is on its source.