preview-latex: The Emacs interface
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 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 (
(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'.
Info Catalog
preview-latex: The LaTeX style file
preview-latex: For advanced users
preview-latex: The preview images