850 lines
35 KiB
Plaintext
850 lines
35 KiB
Plaintext
|
\input texinfo
|
||
|
|
@comment %**start of header
|
||
|
|
@setfilename preview-latex.info
|
||
|
|
@include version.texi
|
||
|
|
@settitle preview-latex @value{VERSION}
|
||
|
|
@comment %**end of header
|
||
|
|
@include macros.texi
|
||
|
|
@copying
|
||
|
|
This manual is for preview-latex, a @LaTeX{} preview mode for @AUCTeX{}
|
||
|
|
(version @value{VERSION} from @value{UPDATED}).
|
||
|
|
|
||
|
|
Copyright @copyright{} 2001, 2002, 2003,
|
||
|
|
2004, 2005, 2006, 2017-2019, 2021 Free Software Foundation, Inc.
|
||
|
|
|
||
|
|
@quotation
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3 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.''
|
||
|
|
@end quotation
|
||
|
|
@end copying
|
||
|
|
|
||
|
|
@dircategory Emacs
|
||
|
|
@direntry
|
||
|
|
* preview-latex: (preview-latex). Preview LaTeX fragments in Emacs
|
||
|
|
@end direntry
|
||
|
|
@dircategory TeX
|
||
|
|
@direntry
|
||
|
|
* preview-latex: (preview-latex). Preview LaTeX fragments in Emacs
|
||
|
|
@end direntry
|
||
|
|
@c footnotestyle separate
|
||
|
|
@c paragraphindent 2
|
||
|
|
@syncodeindex vr cp
|
||
|
|
@syncodeindex ky cp
|
||
|
|
@syncodeindex fn cp
|
||
|
|
|
||
|
|
@iftex
|
||
|
|
@tolerance 10000 @emergencystretch 3em
|
||
|
|
@end iftex
|
||
|
|
|
||
|
|
@finalout
|
||
|
|
@titlepage
|
||
|
|
@title @previewlatex{}
|
||
|
|
@subtitle A @LaTeX{} preview mode for @AUCTeX{} in Emacs.
|
||
|
|
@subtitle Version @value{VERSION}, @value{UPDATED}
|
||
|
|
@author Jan-@AA{}ke Larsson
|
||
|
|
@author David Kastrup and others
|
||
|
|
@page
|
||
|
|
@vskip 0pt plus 1filll
|
||
|
|
@insertcopying
|
||
|
|
@end titlepage
|
||
|
|
|
||
|
|
@c @summarycontents
|
||
|
|
@contents
|
||
|
|
|
||
|
|
@c Use @ifinfo _and_ @ifhtml here because Texinfo 3 cannot cope with
|
||
|
|
@c @ifnottex around a top node.
|
||
|
|
@ifinfo
|
||
|
|
@node top, , (dir), (dir)
|
||
|
|
@top @previewlatex{}
|
||
|
|
|
||
|
|
This manual may be copied under the conditions spelled out in
|
||
|
|
@ref{Copying this Manual}.
|
||
|
|
|
||
|
|
@end ifinfo
|
||
|
|
@ifhtml
|
||
|
|
@node top, Copying, (dir), (dir)
|
||
|
|
@top @previewlatex{}
|
||
|
|
@insertcopying
|
||
|
|
@end ifhtml
|
||
|
|
|
||
|
|
@iftex
|
||
|
|
@unnumbered @previewlatex{}
|
||
|
|
@end iftex
|
||
|
|
|
||
|
|
@previewlatex{} is a package embedding preview fragments into Emacs
|
||
|
|
source buffers under the @AUCTeX{} editing environment for @LaTeX{}. It
|
||
|
|
uses @file{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 @samp{preview-latex}, all in
|
||
|
|
lowercase letters, with a hyphen. If you typeset it, you can use a
|
||
|
|
sans-serif font to visually offset it.
|
||
|
|
|
||
|
|
@menu
|
||
|
|
* Copying:: Copying
|
||
|
|
* Introduction:: Getting started.
|
||
|
|
* Installation:: Make Install.
|
||
|
|
* Keys and lisp:: Key bindings and user-level lisp functions.
|
||
|
|
* Simple customization:: To make it fit in.
|
||
|
|
* Known problems:: When things go wrong.
|
||
|
|
* For advanced users:: Internals and more customizations.
|
||
|
|
* ToDo:: Future development.
|
||
|
|
* Frequently Asked Questions:: All about @previewlatex{}
|
||
|
|
* Copying this Manual:: GNU Free Documentation License
|
||
|
|
* Index:: A menu of many topics.
|
||
|
|
@end menu
|
||
|
|
|
||
|
|
@node Copying, Introduction, top, top
|
||
|
|
@unnumbered Copying
|
||
|
|
@cindex Copying
|
||
|
|
@cindex Copyright
|
||
|
|
@cindex GPL
|
||
|
|
@cindex General Public License
|
||
|
|
@cindex License
|
||
|
|
@cindex Free
|
||
|
|
@cindex Free software
|
||
|
|
@cindex Distribution
|
||
|
|
@cindex Right
|
||
|
|
@cindex Warranty
|
||
|
|
|
||
|
|
For the conditions for copying parts of @previewlatex{}, see the General
|
||
|
|
Public Licenses referred to in the copyright notices of the files, the
|
||
|
|
General Public Licenses accompanying them and the explanatory section in
|
||
|
|
@ref{Copying,,,auctex,the @AUCTeX{} manual}.
|
||
|
|
|
||
|
|
This manual specifically is covered by the GNU Free Documentation
|
||
|
|
License (@pxref{Copying this Manual}).
|
||
|
|
|
||
|
|
@node Introduction, Installation, Copying, top
|
||
|
|
@c Used as @file{README} as well: in separate file
|
||
|
|
@chapter Introduction
|
||
|
|
@include preview-readme.texi
|
||
|
|
|
||
|
|
@node Installation, Keys and lisp, Introduction, top
|
||
|
|
@chapter Installation
|
||
|
|
Installation is now being covered in
|
||
|
|
@ref{Installation,,,auctex,the @AUCTeX{} manual}.
|
||
|
|
|
||
|
|
@node Keys and lisp, Simple customization, Installation, top
|
||
|
|
@chapter Key bindings and user-level lisp functions
|
||
|
|
|
||
|
|
@cindex Menu entries
|
||
|
|
@previewlatex{} adds key bindings starting with @kbd{C-c C-p} to the
|
||
|
|
supported modes of @AUCTeX{} (@xref{Key Index,,,auctex}). It will
|
||
|
|
also add its own @samp{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 @kbd{C-h f} if you need the Lisp information.
|
||
|
|
|
||
|
|
@table @w
|
||
|
|
@item @kbd{C-c C-p C-p}
|
||
|
|
@itemx @code{preview-at-point}
|
||
|
|
@itemx 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 (@code{transient-mark-mode}), it is run
|
||
|
|
through @code{preview-region}.
|
||
|
|
@kindex @kbd{C-c C-p C-p}
|
||
|
|
@findex preview-at-point
|
||
|
|
|
||
|
|
@item @kbd{@key{mouse-2}}
|
||
|
|
The middle mouse button has a similar action bound to it as
|
||
|
|
@code{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.
|
||
|
|
|
||
|
|
@item @kbd{@key{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:
|
||
|
|
|
||
|
|
@item @kbd{C-c C-p C-w}
|
||
|
|
@itemx @code{preview-copy-region-as-mml}
|
||
|
|
@itemx Copy a region as MML
|
||
|
|
@kindex @kbd{C-c C-p C-w}
|
||
|
|
@findex preview-copy-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 (@pxref{Composing,,Composing,emacs-mime,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 @code{preview-transparent-border}
|
||
|
|
@vindex preview-transparent-border
|
||
|
|
set to @code{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 @code{mml-preview} (on @kbd{C-c C-m P})
|
||
|
|
@kindex @kbd{C-c C-m P}
|
||
|
|
to make sure they look fine.
|
||
|
|
|
||
|
|
@item @kbd{C-c C-p C-e}
|
||
|
|
@itemx @code{preview-environment}
|
||
|
|
@itemx Preview/Generate previews for environment
|
||
|
|
Run preview on @LaTeX{} environment. The environments in
|
||
|
|
@code{preview-inner-environments} are treated as inner levels so that
|
||
|
|
for instance, the @code{split} environment in
|
||
|
|
@code{\begin@{equation@}\begin@{split@}@dots{}\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.
|
||
|
|
@kindex @kbd{C-c C-p C-e}
|
||
|
|
@findex preview-environment
|
||
|
|
|
||
|
|
@item @kbd{C-c C-p C-s}
|
||
|
|
@itemx @code{preview-section}
|
||
|
|
@itemx Preview/Generate previews for section
|
||
|
|
Run preview on this @LaTeX{} section.
|
||
|
|
@kindex @kbd{C-c C-p C-s}
|
||
|
|
@findex preview-section
|
||
|
|
|
||
|
|
@item @kbd{C-c C-p C-r}
|
||
|
|
@itemx @code{preview-region}
|
||
|
|
@itemx Preview/Generate previews for region
|
||
|
|
Run preview on current region.
|
||
|
|
@kindex @kbd{C-c C-p C-r}
|
||
|
|
@findex preview-region
|
||
|
|
|
||
|
|
@item @kbd{C-c C-p C-b}
|
||
|
|
@itemx @code{preview-buffer}
|
||
|
|
@itemx Preview/Generate previews for buffer
|
||
|
|
Run preview on the current buffer.
|
||
|
|
@kindex @kbd{C-c C-p C-b}
|
||
|
|
@findex preview-buffer
|
||
|
|
|
||
|
|
@item @kbd{C-c C-p C-d}
|
||
|
|
@itemx @code{preview-document}
|
||
|
|
@itemx Preview/Generate previews for document
|
||
|
|
Run preview on the current document.
|
||
|
|
@kindex @kbd{C-c C-p C-d}
|
||
|
|
@findex preview-document
|
||
|
|
|
||
|
|
@item @kbd{C-c C-p C-c C-p}
|
||
|
|
@itemx @code{preview-clearout-at-point}
|
||
|
|
@itemx Preview/Remove previews at point
|
||
|
|
@kindex @kbd{C-c C-p C-c C-p}
|
||
|
|
@findex preview-clearout-at-point
|
||
|
|
Clear out (remove) the previews that are immediately adjacent to point.
|
||
|
|
|
||
|
|
@item @kbd{C-c C-p C-c C-s}
|
||
|
|
@itemx @code{preview-clearout-section}
|
||
|
|
@itemx Preview/Remove previews from section
|
||
|
|
@kindex @kbd{C-c C-p C-c C-s}
|
||
|
|
@findex preview-clearout-document
|
||
|
|
Clear out all previews in current section.
|
||
|
|
|
||
|
|
@item @kbd{C-c C-p C-c C-r}
|
||
|
|
@itemx @code{preview-clearout}
|
||
|
|
@itemx Preview/Remove previews from region
|
||
|
|
@kindex @kbd{C-c C-p C-c C-r}
|
||
|
|
@findex preview-clearout
|
||
|
|
Clear out all previews in the current region.
|
||
|
|
|
||
|
|
@item @kbd{C-c C-p C-c C-b}
|
||
|
|
@itemx @code{preview-clearout-buffer}
|
||
|
|
@itemx Preview/Remove previews from buffer
|
||
|
|
@kindex @kbd{C-c C-p C-c C-b}
|
||
|
|
@findex preview-clearout-buffer
|
||
|
|
Clear out all previews in current buffer. This makes the current buffer
|
||
|
|
lose all previews.
|
||
|
|
|
||
|
|
@item @kbd{C-c C-p C-c C-d}
|
||
|
|
@itemx @code{preview-clearout-document}
|
||
|
|
@itemx Preview/Remove previews from document
|
||
|
|
@kindex @kbd{C-c C-p C-c C-d}
|
||
|
|
@findex preview-clearout-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.
|
||
|
|
|
||
|
|
@item @kbd{C-c C-p C-f}
|
||
|
|
@itemx @code{preview-cache-preamble}
|
||
|
|
@itemx Preview/Turn preamble cache on
|
||
|
|
@kindex @kbd{C-c C-p C-f}
|
||
|
|
@findex preview-cache-preamble
|
||
|
|
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.
|
||
|
|
|
||
|
|
Note that support for preamble cache is limited for @LaTeX{} variants.
|
||
|
|
c.f.@: @url{https://github.com/davidcarlisle/dpctex/issues/15}
|
||
|
|
@itemize @bullet
|
||
|
|
@item
|
||
|
|
Xe@LaTeX{} cannot use preamble cache at all. The reason is intrinsic in
|
||
|
|
Xe@LaTeX{}, so @previewlatex{} can't help.
|
||
|
|
@item
|
||
|
|
Lua@LaTeX{} works with preamble cache only when the preamble is simple
|
||
|
|
enough, i.e., when it doesn't load opentype fonts and it doesn't use lua
|
||
|
|
codes in preamble.
|
||
|
|
@end itemize
|
||
|
|
|
||
|
|
@item @kbd{C-c C-p C-c C-f}
|
||
|
|
@itemx @code{preview-cache-preamble-off}
|
||
|
|
@itemx Preview/Turn preamble cache off
|
||
|
|
@kindex @kbd{C-u C-c C-p C-f}
|
||
|
|
@findex preview-cache-preamble-off
|
||
|
|
Clear the pregenerated format file and stop using preambles for the
|
||
|
|
current document. If the caching gives you problems, use this.
|
||
|
|
|
||
|
|
@item @kbd{C-c C-p C-i}
|
||
|
|
@itemx @code{preview-goto-info-page}
|
||
|
|
@itemx Preview/Read Documentation
|
||
|
|
@kindex @kbd{C-c C-p C-i}
|
||
|
|
@findex preview-goto-info-page
|
||
|
|
Read
|
||
|
|
@ifinfo
|
||
|
|
this
|
||
|
|
@end ifinfo
|
||
|
|
@ifnotinfo
|
||
|
|
the
|
||
|
|
@end ifnotinfo
|
||
|
|
info manual.
|
||
|
|
|
||
|
|
@item @kbd{M-x preview-report-bug @key{RET}}
|
||
|
|
@itemx @code{preview-report-bug}
|
||
|
|
@itemx Preview/Report Bug
|
||
|
|
@kindex @kbd{M-x preview-report-bug @key{RET}}
|
||
|
|
@findex preview-report-bug
|
||
|
|
@cindex Report a 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 @ref{Known problems}.
|
||
|
|
|
||
|
|
@item @kbd{C-c C-k}
|
||
|
|
@itemx LaTeX/TeX Output/Kill Job
|
||
|
|
@kindex @kbd{C-c C-k}
|
||
|
|
@cindex Kill preview-generating process
|
||
|
|
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.
|
||
|
|
@end table
|
||
|
|
|
||
|
|
@node Simple customization, Known problems, Keys and lisp, top
|
||
|
|
@chapter Simple customization
|
||
|
|
|
||
|
|
Customization options can be found by typing @kbd{M-x customize-group
|
||
|
|
@key{RET} preview @key{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 @ref{For advanced users}), but some are:
|
||
|
|
|
||
|
|
@itemize @bullet
|
||
|
|
@item 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
|
||
|
|
@code{preview-transparent-color} in the @samp{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.
|
||
|
|
|
||
|
|
@item Showing @code{\label}s
|
||
|
|
@cindex Showing @code{\label}s
|
||
|
|
|
||
|
|
When using @previewlatex{}, the @code{\label}s are hidden by the
|
||
|
|
previews. It is possible to make them visible in the output
|
||
|
|
by using the @LaTeX{} package @code{showkeys} alternatively
|
||
|
|
@code{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
|
||
|
|
@code{showlabels} option in the variable
|
||
|
|
@code{preview-default-option-list} in the @samp{Preview Latex} group.
|
||
|
|
@vindex preview-default-option-list
|
||
|
|
|
||
|
|
It must be noted, however, that a much better idea may be to use the
|
||
|
|
Ref@TeX{} package for managing references. @xref{RefTeX in a
|
||
|
|
Nutshell,,RefTeX in a Nutshell,reftex,The Ref@TeX{} Manual}.
|
||
|
|
|
||
|
|
@item 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., @kbd{C-c C-p C-p}). Other options for
|
||
|
|
@code{preview-auto-reveal} are available via @code{customize}.
|
||
|
|
|
||
|
|
@item Automatically cache preambles
|
||
|
|
|
||
|
|
Currently @previewlatex{} asks you whether you want to cache the
|
||
|
|
document preamble (everything before @code{\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 @code{preview-auto-cache-preamble}.
|
||
|
|
@vindex preview-auto-cache-preamble
|
||
|
|
@cindex Caching a preamble
|
||
|
|
|
||
|
|
@item Attempt to keep counters accurate when editing
|
||
|
|
|
||
|
|
@vindex preview-preserve-counters
|
||
|
|
@vindex preview-required-option-list
|
||
|
|
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
|
||
|
|
@code{preview-preserve-counters} to @code{t} (this is consulted by
|
||
|
|
@code{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.
|
||
|
|
|
||
|
|
@item Preview your favourite @LaTeX{} constructs
|
||
|
|
|
||
|
|
@vindex preview-default-option-list
|
||
|
|
@vindex preview-default-preamble
|
||
|
|
If you have a certain macro or environment that you want to preview,
|
||
|
|
first check if it can be chosen by cutomizing
|
||
|
|
@code{preview-default-option-list} in the @samp{Preview Latex} group.
|
||
|
|
|
||
|
|
If it is not available there, you can add it to
|
||
|
|
@code{preview-default-preamble} also in the @samp{Preview Latex} group,
|
||
|
|
by adding a @code{\PreviewMacro} or @code{\PreviewEnvironment} entry
|
||
|
|
(@pxref{Provided commands}) @emph{after} the @code{\RequirePackage}
|
||
|
|
line. For example, if you want to preview the @code{center}
|
||
|
|
environment, press the @key{Show} button and the last @key{INS} button,
|
||
|
|
then add
|
||
|
|
|
||
|
|
@example
|
||
|
|
\PreviewEnvironment@{center@}
|
||
|
|
@end example
|
||
|
|
@noindent
|
||
|
|
in the space that just opened. Note that since @code{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 (@pxref{File
|
||
|
|
Variables,,Local Variables in Files,emacs,GNU Emacs Manual}). A perhaps
|
||
|
|
more convenient place for such options would be in a configuration file
|
||
|
|
in the same directory with your project (@pxref{Package options}).
|
||
|
|
|
||
|
|
The usual file for @previewlatex{} preconfiguration is
|
||
|
|
@file{prauctex.cfg}. If you also want to keep the systemwide defaults,
|
||
|
|
you should add a line
|
||
|
|
|
||
|
|
@example
|
||
|
|
\InputIfFileExists@{preview/prauctex.cfg@}@{@}@{@}
|
||
|
|
@end example
|
||
|
|
@noindent
|
||
|
|
to your own version of @file{prauctex.cfg} (this is assuming that
|
||
|
|
global files relating to the @code{preview} package are installed in a
|
||
|
|
subdirectory @file{preview}, the default behavior).
|
||
|
|
|
||
|
|
@item Don't preview inline math
|
||
|
|
@cindex Inline math
|
||
|
|
@vindex preview-default-option-list
|
||
|
|
|
||
|
|
If you have performance problems because your document is full of inline
|
||
|
|
math (@code{$@dots{}$}), or if your usage of @code{$} conflicts with
|
||
|
|
@previewlatex{}'s, you can turn off inline math previews. In the
|
||
|
|
@samp{Preview Latex} group, remove @code{textmath} from
|
||
|
|
@code{preview-default-option-list} by customizing this variable.
|
||
|
|
@end itemize
|
||
|
|
|
||
|
|
@node Known problems, For advanced users, Simple customization, top
|
||
|
|
@chapter Known problems
|
||
|
|
@c also used as PROBLEMS file
|
||
|
|
@include preview-problems.texi
|
||
|
|
|
||
|
|
@node For advanced users, ToDo, Known problems, top
|
||
|
|
@chapter 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{}).
|
||
|
|
|
||
|
|
@menu
|
||
|
|
* The LaTeX style file::
|
||
|
|
* The Emacs interface::
|
||
|
|
* The preview images::
|
||
|
|
* Misplaced previews::
|
||
|
|
@end menu
|
||
|
|
|
||
|
|
@node The LaTeX style file, The Emacs interface, For advanced users, For advanced users
|
||
|
|
@section The @LaTeX{} style file
|
||
|
|
@c Autogenerated from ../latex/preview.dtx
|
||
|
|
@include preview-dtxdoc.texi
|
||
|
|
|
||
|
|
@node The Emacs interface, The preview images, The LaTeX style file, For advanced users
|
||
|
|
@section The Emacs interface
|
||
|
|
|
||
|
|
You can use @kbd{M-x customize-group @key{RET} preview-latex @key{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.
|
||
|
|
|
||
|
|
@vtable @code
|
||
|
|
@item preview-LaTeX-command
|
||
|
|
When you generate previews on a buffer or a region, the command in
|
||
|
|
@code{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.
|
||
|
|
|
||
|
|
@item preview-LaTeX-command-replacements
|
||
|
|
This variable specifies transformations to be used before calling the
|
||
|
|
configured command. One possibility is to have @samp{\pdfoutput=0 }
|
||
|
|
appended to every command starting with @samp{pdf}. This particular
|
||
|
|
setting is available as the shortcut
|
||
|
|
@code{preview-LaTeX-disable-pdfoutput}. Since @previewlatex{} can work
|
||
|
|
with @acronym{PDF} files by now, there is little incentive for using
|
||
|
|
this option, anymore (for projects not requiring @acronym{PDF} output,
|
||
|
|
the added speed of @command{dvipng} might make this somewhat attractive).
|
||
|
|
|
||
|
|
@item preview-required-option-list
|
||
|
|
@code{preview-LaTeX-command} uses @code{preview-required-option-list} in
|
||
|
|
order to pass options such as @option{auctex}, @option{active} and
|
||
|
|
@option{dvips} to the @file{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 @file{preview} explicitly in his document.
|
||
|
|
|
||
|
|
The default includes an option @code{counters} that is controlled by the
|
||
|
|
boolean variable
|
||
|
|
|
||
|
|
@item preview-preserve-counters
|
||
|
|
This option will cause the @file{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.
|
||
|
|
|
||
|
|
@item preview-default-option-list
|
||
|
|
@itemx preview-default-preamble
|
||
|
|
If the document does not call in the package @code{preview} itself (via
|
||
|
|
@code{\usepackage}) in the preamble, the preview package is loaded using
|
||
|
|
default options from @code{preview-default-option-list} and additional
|
||
|
|
commands specified in @code{preview-default-preamble}.
|
||
|
|
|
||
|
|
@item preview-fast-conversion
|
||
|
|
This is relevant only for @acronym{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 @acronym{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'.
|
||
|
|
|
||
|
|
@item 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 @acronym{EPS} files,
|
||
|
|
but rather rely on the boxes it gets from @TeX{}. If you activated
|
||
|
|
@code{preview-fast-conversion}, this is done, anyhow, since there are no
|
||
|
|
@acronym{EPS} files from which to read this information. The option
|
||
|
|
defaults to `Off', simply because about the only conceivable reason to
|
||
|
|
switch off @code{preview-fast-conversion} would be that you have some
|
||
|
|
bounding box problem and want to get Dvips' angle on that matter.
|
||
|
|
|
||
|
|
@item preview-scale-function
|
||
|
|
@itemx preview-reference-face
|
||
|
|
@itemx preview-document-pt-list
|
||
|
|
@itemx preview-default-document-pt
|
||
|
|
@code{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 @code{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
|
||
|
|
@code{preview-reference-face} (usually the default face used for
|
||
|
|
display), the size of the default font for the document is determined
|
||
|
|
by calling @code{preview-document-pt}.
|
||
|
|
@findex preview-document-pt
|
||
|
|
This function consults the members of @code{preview-document-pt-list} in
|
||
|
|
turn until it gets the desired information. The default consults first
|
||
|
|
@code{preview-parsed-font-size},
|
||
|
|
@vindex preview-parsed-font-size
|
||
|
|
then calls @code{preview-auctex-font-size}
|
||
|
|
@findex preview-auctex-font-size
|
||
|
|
which asks @AUCTeX{} about any size specification like @option{12pt} to
|
||
|
|
the documentclass that it might have detected when parsing the document, and
|
||
|
|
finally reverts to just assuming @code{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. @code{preview-parsed-font-size} is
|
||
|
|
determined at @code{\begin@{document@}} time; if the default font size
|
||
|
|
changes after that, it will not get reported. If you have an outdated
|
||
|
|
version of @file{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 @samp{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.
|
||
|
|
|
||
|
|
@item preview-fast-dvips-command
|
||
|
|
@itemx preview-dvips-command
|
||
|
|
The regular command for turning a @acronym{DVI} file into a single
|
||
|
|
PostScript file is @code{preview-fast-dvips-command}, while
|
||
|
|
@code{preview-dvips-command} is used for cranking out a @acronym{DVI}
|
||
|
|
file where every preview is in a separate @acronym{EPS} file. Which of
|
||
|
|
the two commands gets used depends on the setting of
|
||
|
|
@code{preview-fast-conversion}. The printer specified here
|
||
|
|
is @option{-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 (@xref{Command-line options,,,dvips}).
|
||
|
|
|
||
|
|
The conversion of the previews into PostScript or @acronym{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.
|
||
|
|
|
||
|
|
@item 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.
|
||
|
|
|
||
|
|
@item preview-error-icon-specs
|
||
|
|
@itemx 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.
|
||
|
|
|
||
|
|
@item preview-inner-environments
|
||
|
|
This is a list of environments that are regarded as inner levels of an
|
||
|
|
outer environment when doing @code{preview-environment}. One example
|
||
|
|
when this is needed is in
|
||
|
|
@code{\begin@{equation@}\begin@{split@}@dots{}\end@{split@}\end@{equation@}}, and
|
||
|
|
accordingly @code{split} is one entry in
|
||
|
|
@code{preview-inner-environments}.
|
||
|
|
|
||
|
|
@end vtable
|
||
|
|
|
||
|
|
@node The preview images, Misplaced previews, The Emacs interface, For advanced users
|
||
|
|
@section The preview images
|
||
|
|
|
||
|
|
@vtable @code
|
||
|
|
@item preview-image-type
|
||
|
|
@itemx preview-image-creators
|
||
|
|
@itemx preview-gs-image-type-alist
|
||
|
|
What happens when @LaTeX{} is finished depends on the configuration of
|
||
|
|
@code{preview-image-type}. What to do for each of the various settings
|
||
|
|
is specified in the variable @code{preview-image-creators}. The options
|
||
|
|
to pass into Ghostscript and what Emacs image type to use is specified
|
||
|
|
in @code{preview-gs-image-type-alist}.
|
||
|
|
|
||
|
|
@code{preview-image-type} defaults to @code{png}. For this to work,
|
||
|
|
your version of Ghostscript needs to support the @option{png16m} device.
|
||
|
|
If you are experiencing problems here, you might want to reconfigure
|
||
|
|
@code{preview-gs-image-type-alist} or @code{preview-image-type}. Reconfiguring
|
||
|
|
@code{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 @acronym{PDF} file (if PDF@LaTeX{} was used), or
|
||
|
|
(after running Dvips) sections of a single PostScript file or separate
|
||
|
|
@acronym{EPS} files in sequence for conversion into @acronym{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 @samp{Preview Gs} for this.
|
||
|
|
|
||
|
|
Another noteworthy setting of @code{preview-image-type} is
|
||
|
|
@samp{dvipng}: in this case, the @command{dvipng}
|
||
|
|
@pindex dvipng
|
||
|
|
program will get run on @acronym{DVI} output (see below for @acronym{PDF}).
|
||
|
|
This is in general much faster than Dvips and Ghostscript. In that
|
||
|
|
case, the option
|
||
|
|
|
||
|
|
@item preview-dvipng-command
|
||
|
|
will get run for doing the conversion, and it is expected that
|
||
|
|
|
||
|
|
@item preview-dvipng-image-type
|
||
|
|
images get produced (@samp{dvipng} might be configured for other image
|
||
|
|
types as well). You will notice that @code{preview-gs-image-type-alist}
|
||
|
|
contains an entry for @code{dvipng}: this actually has nothing to with
|
||
|
|
@samp{dvipng} itself but specifies the image type and Ghostscript device
|
||
|
|
option to use when @samp{dvipng} can't be used. This will obviously be
|
||
|
|
the case for @acronym{PDF} output by PDF@LaTeX{}, but it will also happen
|
||
|
|
if the @acronym{DVI} file contains PostScript specials in which case the
|
||
|
|
affected images will get run through Dvips and Ghostscript once
|
||
|
|
@samp{dvipng} finishes.
|
||
|
|
|
||
|
|
Note for p@LaTeX{} and up@LaTeX{} users: It is known that @command{dvipng}
|
||
|
|
is not compatible with p@LaTeX{} and up@LaTeX{}. If
|
||
|
|
@code{preview-image-type} is set to @samp{dvipng} and (u)p@LaTeX{} is
|
||
|
|
used, @samp{dvipng} just fails and @previewlatex{} falls back on Dvips
|
||
|
|
and Ghostscript.
|
||
|
|
|
||
|
|
@item preview-gs-options
|
||
|
|
Most interesting to the user perhaps is the setting of this variable.
|
||
|
|
It contains the default antialiasing settings @option{-dTextAlphaBits=4}
|
||
|
|
and @option{-dGraphicsAlphaBits=4}. Decreasing those values to 2 @w{or
|
||
|
|
1} might increase Ghostscript's performance if you find it lacking.
|
||
|
|
@end vtable
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
@node Misplaced previews, , The preview images, For advanced users
|
||
|
|
@section 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 (@pxref{x-symbol interoperation}). If not,
|
||
|
|
here's the beef:
|
||
|
|
|
||
|
|
As explained previously, Emacs uses pseudo-error messages generated by
|
||
|
|
the @samp{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 @code{\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{}
|
||
|
|
@samp{preview} package how to tackle this problem (@pxref{The LaTeX
|
||
|
|
style file}). Simply, you don't need @code{\emph} do anything at all
|
||
|
|
during previews! You only want the text math previewed, so the solution
|
||
|
|
is to use @code{\PreviewMacro*\emph} in the preamble of your document
|
||
|
|
which will make @LaTeX{} ignore @code{\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
|
||
|
|
@code{\PreviewMacro*[@{@{@}@}]\emph} since then both @code{\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 @code{\textrm}, @code{\textit} and the like. While they
|
||
|
|
all use the same internal macro @code{\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 @file{prauctex.cfg} that gets loaded by default
|
||
|
|
unless the @samp{preview} package gets loaded with the @option{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 @code{preview-default-preamble},
|
||
|
|
@vindex preview-default-preamble
|
||
|
|
or alternatively do the
|
||
|
|
manual disabling of your favorite macro in
|
||
|
|
@code{preview-default-preamble},
|
||
|
|
@vindex preview-default-preamble
|
||
|
|
which is customizable in the @samp{Preview Latex} group.
|
||
|
|
|
||
|
|
@node ToDo, Frequently Asked Questions, For advanced users, top
|
||
|
|
@c Also used as TODO: in separate file
|
||
|
|
@appendix ToDo
|
||
|
|
@include preview-todo.texi
|
||
|
|
|
||
|
|
@node Frequently Asked Questions, Copying this Manual, ToDo, top
|
||
|
|
@c Also used as TODO: in separate file
|
||
|
|
@appendix Frequently Asked Questions
|
||
|
|
@include preview-faq.texi
|
||
|
|
|
||
|
|
@node Copying this Manual, Index, Frequently Asked Questions, top
|
||
|
|
@c Not to be changed often, I think: in separate file.
|
||
|
|
@appendix Copying this Manual
|
||
|
|
|
||
|
|
@ifinfo
|
||
|
|
The copyright notice for this manual is:
|
||
|
|
|
||
|
|
@insertcopying
|
||
|
|
@end ifinfo
|
||
|
|
|
||
|
|
The full license text can be read here:
|
||
|
|
|
||
|
|
@menu
|
||
|
|
* GNU Free Documentation License:: License for copying this manual.
|
||
|
|
@end menu
|
||
|
|
|
||
|
|
@include fdl.texi
|
||
|
|
|
||
|
|
@c @node Credits, Index, Internals, top
|
||
|
|
@c @appendix Credits
|
||
|
|
|
||
|
|
@node Index, , Copying this Manual, top
|
||
|
|
@unnumbered Index
|
||
|
|
|
||
|
|
@printindex cp
|
||
|
|
|
||
|
|
@bye
|