"Fossies" - the Fresh Open Source Software Archive

Member "auctex-12.3/doc/preview-latex.texi" (18 Oct 2020, 35661 Bytes) of package /linux/misc/auctex-12.3.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "preview-latex.texi": 12.2_vs_12.3.

    1 \input texinfo
    2 @comment %**start of header
    3 @setfilename preview-latex.info
    4 @include version.texi
    5 @settitle preview-latex @value{VERSION}
    6 @comment %**end of header
    7 @include macros.texi
    8 @copying
    9 This manual is for preview-latex, a @LaTeX{} preview mode for @AUCTeX{}
   10 (version @value{VERSION} from @value{UPDATED}).
   12 Copyright @copyright{} 2001, 2002, 2003,
   13 2004, 2005, 2006, 2017, 2018 Free Software Foundation, Inc.
   15 @quotation
   16 Permission is granted to copy, distribute and/or modify this document
   17 under the terms of the GNU Free Documentation License, Version 1.3 or
   18 any later version published by the Free Software Foundation; with no
   19 Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.  A
   20 copy of the license is included in the section entitled ``GNU Free
   21 Documentation License.''
   22 @end quotation
   23 @end copying
   25 @dircategory Emacs
   26 @direntry
   27 * preview-latex: (preview-latex).       Preview LaTeX fragments in Emacs
   28 @end direntry
   29 @dircategory TeX
   30 @direntry
   31 * preview-latex: (preview-latex).       Preview LaTeX fragments in Emacs
   32 @end direntry
   33 @c footnotestyle separate
   34 @c paragraphindent 2
   35 @syncodeindex vr cp
   36 @syncodeindex ky cp
   37 @syncodeindex fn cp
   39 @iftex
   40 @tolerance 10000 @emergencystretch 3em
   41 @end iftex
   43 @finalout
   44 @titlepage
   45 @title @previewlatex{}
   46 @subtitle A @LaTeX{} preview mode for @AUCTeX{} in Emacs.
   47 @subtitle Version @value{VERSION}, @value{UPDATED}
   48 @author Jan-@AA{}ke Larsson
   49 @author David Kastrup and others
   50 @page
   51 @vskip 0pt plus 1filll
   52 @insertcopying
   53 @end titlepage
   55 @c @summarycontents
   56 @contents
   58 @c Use @ifinfo _and_ @ifhtml here because Texinfo 3 cannot cope with
   59 @c @ifnottex around a top node.
   60 @ifinfo
   61 @node top, , (dir), (dir)
   62 @top @previewlatex{}
   64 This manual may be copied under the conditions spelled out in
   65 @ref{Copying this Manual}.
   67 @end ifinfo
   68 @ifhtml
   69 @node top, Copying, (dir), (dir)
   70 @top @previewlatex{}
   71 @insertcopying
   72 @end ifhtml
   74 @contents
   76 @iftex
   77 @unnumbered @previewlatex{}
   78 @end iftex
   80 @previewlatex{} is a package embedding preview fragments into Emacs
   81 source buffers under the @AUCTeX{} editing environment for @LaTeX{}.  It
   82 uses @file{preview.sty} for the extraction of certain environments (most
   83 notably displayed formulas).  Other applications of this style file are
   84 possible and exist.
   86 The name of the package is really @samp{preview-latex}, all in
   87 lowercase letters, with a hyphen.  If you typeset it, you can use a
   88 sans-serif font to visually offset it.
   90 @menu
   91 * Copying::                     Copying
   92 * Introduction::                Getting started.
   93 * Installation::                Make Install.
   94 * Keys and lisp::               Key bindings and user-level lisp functions.
   95 * Simple customization::        To make it fit in.
   96 * Known problems::              When things go wrong.
   97 * For advanced users::          Internals and more customizations.
   98 * ToDo::                        Future development.
   99 * Frequently Asked Questions::  All about @previewlatex{}
  100 * Copying this Manual::         GNU Free Documentation License
  101 * Index::                       A menu of many topics.             
  102 @end menu
  104 @node Copying, Introduction, top, top
  105 @unnumbered Copying
  106 @cindex Copying
  107 @cindex Copyright
  108 @cindex GPL
  109 @cindex General Public License
  110 @cindex License
  111 @cindex Free
  112 @cindex Free software
  113 @cindex Distribution
  114 @cindex Right
  115 @cindex Warranty
  117 For the conditions for copying parts of @previewlatex{}, see the General
  118 Public Licenses referres to in the copyright notices of the files, the
  119 General Public Licenses accompanying them and the explanatory section in
  120 @ref{Copying,,,auctex,the @AUCTeX{} manual}.
  122 This manual specifically is covered by the GNU Free Documentation
  123 License (@pxref{Copying this Manual}).
  125 @node Introduction, Installation, Copying, top
  126 @c Used as @file{README} as well: in separate file
  127 @chapter Introduction
  128 @include preview-readme.texi
  130 @node Installation, Keys and lisp, Introduction, top
  131 @chapter Installation
  132 Installation is now being covered in
  133 @ref{Installation,,,auctex,the @AUCTeX{} manual}.
  135 @node Keys and lisp, Simple customization, Installation, top
  136 @chapter Key bindings and user-level lisp functions 
  138 @cindex Menu entries
  139 @previewlatex{} adds key bindings starting with @kbd{C-c C-p} to the
  140 supported modes of @AUCTeX{} (@inforef{Key Index,,auctex}).  It will
  141 also add its own @samp{Preview} menu in the menu bar, as well as an icon
  142 in the toolbar.
  144 The following only describes the interactive use: view the documentation
  145 strings with @kbd{C-h f} if you need the Lisp information.
  147 @table @w
  148 @item @kbd{C-c C-p C-p}
  149 @itemx @code{preview-at-point}
  150 @itemx Preview/Generate previews (or toggle) at point
  151 If the cursor is positioned on or inside of a preview area, this
  152 toggles its visibility, regenerating the preview if necessary. If not,
  153 it will run the surroundings through preview. The surroundings include
  154 all areas up to the next valid preview, unless invalid previews occur
  155 before, in which case the area will include the last such preview in
  156 either direction.  And overriding any other
  157 action, if a region is active (@code{transient-mark-mode}), it is run
  158 through @code{preview-region}.
  159 @kindex @kbd{C-c C-p C-p}
  160 @findex preview-at-point
  162 @item @kbd{<mouse-2>}
  163 The middle mouse button has a similar action bound to it as
  164 @code{preview-at-point}, only that it knows which preview to apply it to
  165 according to the position of the click.  You can click either anywhere
  166 on a previewed image, or when the preview is opened and showing the
  167 source text, you can click on the icon preceding the source text.  In
  168 other areas, the usual mouse key action (typically: paste) is not
  169 affected.
  171 @item @kbd{<mouse-3>}
  172 The right mouse key pops up a context menu with several options:
  173 toggling the preview, regenerating it, removing it (leaving the
  174 unpreviewed text), copying the text inside of the preview, and copying
  175 it in a form suitable for copying as an image into a mail or news
  176 article.  This is a one-image variant of the following command:
  178 @item @kbd{C-c C-p C-w}
  179 @itemx @code{preview-copy-region-as-mml}
  180 @itemx Copy a region as MML
  181 @kindex @kbd{C-c C-p C-w}
  182 @findex preview-copy-region-as-mml
  183 This command is also available as a variant in the context menu on the
  184 right mouse button (where the region is the preview that has been
  185 clicked on).  It copies the current region into the kill buffer in a
  186 form suitable for copying as a text including images into a mail or news
  187 article using mml-mode (@pxref{Composing,,Composing,emacs-mime,Emacs
  188 MIME}).
  190 If you regenerate or otherwise kill the preview in its source buffer
  191 before the mail or news gets posted, this will fail.  Also you should
  192 generate images you want to send with @code{preview-transparent-border}
  193 @vindex preview-transparent-border
  194 set to @code{nil}, or the images will have an ugly border.
  195 @previewlatex{} detects this condition and asks whether to regenerate
  196 the region with borders switched off.  As this is an asynchronous
  197 operation running in the background, you'll need to call this command
  198 explicitly again to get the newly generated images into the kill ring.
  200 Preview your articles with @code{mml-preview} (on @kbd{C-c C-m P})
  201 @kindex @kbd{C-c C-m P}
  202 to make sure they look fine.
  204 @item @kbd{C-c C-p C-e}
  205 @itemx @code{preview-environment}
  206 @itemx Preview/Generate previews for environment
  207 Run preview on @LaTeX{} environment.  The environments in
  208 @code{preview-inner-environments} are treated as inner levels so that
  209 for instance, the @code{split} environment in
  210 @code{\begin@{equation@}\begin@{split@}@dots{}\end@{split@}\end@{equation@}}
  211 is properly displayed.  If called with a numeric argument, the
  212 corresponding number of outward nested environments is treated as inner
  213 levels.
  214 @kindex @kbd{C-c C-p C-e}
  215 @findex preview-environment
  217 @item @kbd{C-c C-p C-s}
  218 @itemx @code{preview-section} 
  219 @itemx Preview/Generate previews for section
  220 Run preview on this @LaTeX{} section.
  221 @kindex @kbd{C-c C-p C-s}
  222 @findex preview-section
  224 @item @kbd{C-c C-p C-r}
  225 @itemx @code{preview-region}
  226 @itemx Preview/Generate previews for region
  227 Run preview on current region.
  228 @kindex @kbd{C-c C-p C-r}
  229 @findex preview-region
  231 @item @kbd{C-c C-p C-b}
  232 @itemx @code{preview-buffer} 
  233 @itemx Preview/Generate previews for buffer
  234 Run preview on the current buffer.
  235 @kindex @kbd{C-c C-p C-b}
  236 @findex preview-buffer
  238 @item @kbd{C-c C-p C-d}
  239 @itemx @code{preview-document} 
  240 @itemx Preview/Generate previews for document
  241 Run preview on the current document.
  242 @kindex @kbd{C-c C-p C-d}
  243 @findex preview-document
  245 @item @kbd{C-c C-p C-c C-p}
  246 @itemx @code{preview-clearout-at-point}
  247 @itemx Preview/Remove previews at point
  248 @kindex @kbd{C-c C-p C-c C-p}
  249 @findex preview-clearout-at-point
  250 Clear out (remove) the previews that are immediately adjacent to point.
  252 @item @kbd{C-c C-p C-c C-s}
  253 @itemx @code{preview-clearout-section}
  254 @itemx Preview/Remove previews from section
  255 @kindex @kbd{C-c C-p C-c C-s}
  256 @findex preview-clearout-document
  257 Clear out all previews in current section.
  259 @item @kbd{C-c C-p C-c C-r}
  260 @itemx @code{preview-clearout}
  261 @itemx Preview/Remove previews from region
  262 @kindex @kbd{C-c C-p C-c C-r}
  263 @findex preview-clearout
  264 Clear out all previews in the current region.
  266 @item @kbd{C-c C-p C-c C-b}
  267 @itemx @code{preview-clearout-buffer}
  268 @itemx Preview/Remove previews from buffer
  269 @kindex @kbd{C-c C-p C-c C-b}
  270 @findex preview-clearout-buffer
  271 Clear out all previews in current buffer. This makes the current buffer
  272 lose all previews.
  274 @item @kbd{C-c C-p C-c C-d}
  275 @itemx @code{preview-clearout-document}
  276 @itemx Preview/Remove previews from document
  277 @kindex @kbd{C-c C-p C-c C-d}
  278 @findex preview-clearout-document
  279 Clear out all previews in current document.  The document consists of
  280 all buffers that have the same master file as the current buffer.  This
  281 makes the current document lose all previews.
  283 @item @kbd{C-c C-p C-f}
  284 @itemx @code{preview-cache-preamble}
  285 @itemx Preview/Turn preamble cache on
  286 @kindex @kbd{C-c C-p C-f}
  287 @findex preview-cache-preamble
  288 Dump a pregenerated format file.  For the rest of the session, this file
  289 is used when running on the same master file.  Use this if you know your
  290 @LaTeX{} takes a long time to start up, the speedup will be most
  291 noticeable when generating single or few previews.  If you change your
  292 preamble, do this again.  @previewlatex{} will try to detect the
  293 necessity of that automatically when editing changes to the preamble are
  294 done from within Emacs, but it will not notice if the preamble
  295 effectively changes because some included file or style file is
  296 tampered with.
  298 Note that support for preamble cache is limited for @LaTeX{} variants.
  299 c.f. @url{https://github.com/davidcarlisle/dpctex/issues/15}
  300 @itemize @bullet
  301 @item
  302 Xe@LaTeX{} cannot use preamble cache at all.  The reason is intrinsic in
  303 Xe@LaTeX{}, so @previewlatex{} can't help.
  304 @item
  305 Lua@LaTeX{} works with preamble cache only when the preamble is simple
  306 enough, i.e., when it doesn't load opentype fonts and it doesn't use lua
  307 codes in preamble.
  308 @end itemize
  310 @item @kbd{C-c C-p C-c C-f}
  311 @itemx @code{preview-cache-preamble-off}
  312 @itemx Preview/Turn preamble cache off
  313 @kindex @kbd{C-u C-c C-p C-f}
  314 @findex preview-cache-preamble-off
  315 Clear the pregenerated format file and stop using preambles for the
  316 current document. If the caching gives you problems, use this.
  318 @item @kbd{C-c C-p C-i}
  319 @itemx @code{preview-goto-info-page}
  320 @itemx Preview/Read Documentation
  321 @kindex @kbd{C-c C-p C-i}
  322 @findex preview-goto-info-page
  323 Read
  324 @ifinfo
  325 this
  326 @end ifinfo 
  327 @ifnotinfo
  328 the
  329 @end ifnotinfo
  330 info manual.
  332 @item @kbd{M-x preview-report-bug @key{RET}}
  333 @itemx @code{preview-report-bug}
  334 @itemx Preview/Report Bug
  335 @kindex @kbd{M-x preview-report-bug @key{RET}}
  336 @findex preview-report-bug
  337 @cindex Report a bug
  338 This is the preferred way of reporting bugs as it will fill in what
  339 version of @previewlatex{} you are using as well as versions of
  340 relevant other software, and also some of the more important
  341 settings. Please use this method of reporting, if at all possible and
  342 before reporting a bug, have a look at @ref{Known problems}.
  344 @item @kbd{C-c C-k}
  345 @itemx LaTeX/TeX Output/Kill Job
  346 @kindex @kbd{C-c C-k}
  347 @cindex Kill preview-generating process
  348 Kills the preview-generating process. This is really an @AUCTeX{}
  349 keybinding, but it is included here as a hint. If you are generating
  350 a preview and then make a change to the buffer, @previewlatex{} may be
  351 confused and place the previews wrong.
  352 @end table
  354 @node Simple customization, Known problems, Keys and lisp, top
  355 @chapter Simple customization
  357 Customization options can be found by typing @kbd{M-x customize-group
  358 @key{RET} preview @key{RET}}. Remember to set the option when you have
  359 changed it. The list of suggestions can be made very long (and is
  360 covered in detail in @ref{For advanced users}), but some are:
  362 @itemize @bullet
  363 @item Change the color of the preview background
  365 If you use a non-white background in Emacs, you might have color
  366 artifacts at the edges of your previews.  Playing around with the option
  367 @code{preview-transparent-color} in the @code{Preview Appearance} group
  368 might improve things.  With some settings, the cursor may cover the
  369 whole background of a preview, however.
  371 This option is specific to the display engine in use.
  373 @item Showing @code{\label}s
  374 @cindex Showing @code{\label}s
  376 When using @previewlatex{}, the @code{\label}s are hidden by the
  377 previews.  It is possible to make them visible in the output
  378 by using the @LaTeX{} package @code{showkeys} alternatively
  379 @code{showlabels}.  However, the boxes of these labels will be outside
  380 the region @previewlatex{} considers as the preview image.  To enable a
  381 similar mechanism internal to @previewlatex{}, enable the
  382 @code{showlabels} option in the variable
  383 @code{preview-default-option-list} in the @code{Preview Latex} group.
  385 It must be noted, however, that a much better idea may be to use the
  386 Ref@TeX{} package for managing references.  @xref{RefTeX in a
  387 Nutshell,,RefTeX in a Nutshell,reftex,The Ref@TeX{} Manual}.
  389 @item Open previews automatically
  391 The current default is to open previews automatically when you enter
  392 them with cursor left/right motions.  Auto-opened previews will close
  393 again once the cursor leaves them again (this is also done when doing
  394 incremental search, or query-replace operations), unless you changed
  395 anything in it.  In that case, you will have to regenerate the preview
  396 (via e.g., @kbd{C-c C-p C-p}).  Other options for
  397 @code{preview-auto-reveal} are available via @code{customize}.
  399 @item Automatically cache preambles
  401 Currently @previewlatex{} asks you whether you want to cache the
  402 document preamble (everything before @code{\begin@{document@}}) before
  403 it generates previews for a buffer the first time.  Caching the preamble
  404 will significantly speed up regeneration of previews.  The larger your
  405 preamble is, the more this will be apparent.  Once a preamble is cached,
  406 @previewlatex{} will try to keep track of when it is changed, and dump
  407 a fresh format in that case.  If you experience problems with this, or
  408 if you want it to happen without asking you the first time, you can
  409 customize the variable @code{preview-auto-cache-preamble}.
  410 @vindex preview-auto-cache-preamble
  411 @cindex Caching a preamble
  413 @item Attempt to keep counters accurate when editing
  415 @vindex preview-preserve-counters
  416 @vindex preview-required-option-list
  417 Since @previewlatex{} frequently runs only small regions through
  418 @LaTeX{}, values like equation counters are not consistent from run to
  419 run.  If this bothers you, customize the variable
  420 @code{preview-preserve-counters} to @code{t} (this is consulted by
  421 @code{preview-required-option-list}).  @LaTeX{} will then output a load
  422 of counter information during compilation, and this information will be
  423 used on subsequent updates to keep counters set to useful values.  The
  424 additional information takes additional time to analyze, but this is
  425 relevant mostly only when you are regenerating all previews at once, and
  426 maybe you will be less tempted to do so when counters appear more or
  427 less correct.
  429 @item Preview your favourite @LaTeX{} constructs
  431 If you have a certain macro or environment that you want to preview,
  432 first check if it can be chosen by cutomizing
  433 @code{preview-default-options-list} in the @code{Preview Latex} group.
  435 If it is not available there, you can add it to
  436 @code{preview-default-preamble} also in the @code{Preview Latex} group,
  437 by adding a @code{\PreviewMacro} or @code{\PreviewEnvironment} entry
  438 (@pxref{Provided commands}) @emph{after} the @code{\RequirePackage}
  439 line.  For example, if you want to preview the @code{center}
  440 environment, press the @key{Show} button and the last @key{INS} button,
  441 then add
  443 @example
  444 \PreviewEnvironment@{center@}
  445 @end example
  446 @noindent
  447 in the space that just opened.  Note that since @code{center} is a
  448 generic formatting construct of @LaTeX{}, a general configuration like
  449 that is not quite prudent.  You better to do this on a per-document
  450 base so that it is easy to disable this behavior when you find this
  451 particular entry gives you trouble.
  453 One possibility is to save such settings in the corresponding file-local
  454 variable instead of your global configuration (@pxref{File
  455 Variables,,Local Variables in Files,emacs,GNU Emacs Manual}).  A perhaps
  456 more convenient place for such options would be in a configuration file
  457 in the same directory with your project (@pxref{Package options}).
  459 The usual file for @previewlatex{} preconfiguration is
  460 @file{prauctex.cfg}.  If you also want to keep the systemwide defaults,
  461 you should add a line
  463 @example
  464 \InputIfFileExists@{preview/prauctex.cfg@}@{@}@{@}
  465 @end example
  466 @noindent
  467 to your own version of @file{prauctex.cfg} (this is assuming that
  468 global files relating to the @code{preview} package are installed in a
  469 subdirectory @file{preview}, the default behavior).
  471 @item Don't preview inline math
  472 @cindex Inline math
  474 If you have performance problems because your document is full of inline
  475 math (@code{$@dots{}$}), or if your usage of @code{$} conflicts with
  476 @previewlatex{}'s, you can turn off inline math previews. In the
  477 @code{Preview Latex} group, remove @code{textmath} from
  478 @code{preview-default-option-list} by customizing this variable.
  479 @end itemize
  481 @node Known problems, For advanced users, Simple customization, top
  482 @chapter Known problems
  483 @c also used as PROBLEMS file
  484 @include preview-problems.texi
  486 @node For advanced users, ToDo, Known problems, top
  487 @chapter For advanced users
  489 This package consists of two parts: a @LaTeX{} style that splits the
  490 output into appropriate parts with one preview object on each page, and
  491 an Emacs-lisp part integrating the thing into Emacs (aided by
  492 @AUCTeX{}).
  494 @menu
  495 * The LaTeX style file::        
  496 * The Emacs interface::         
  497 * The preview images::             
  498 * Misplaced previews::          
  499 @end menu
  501 @node The LaTeX style file, The Emacs interface, For advanced users, For advanced users
  502 @section The @LaTeX{} style file
  503 @c Autogenerated from ../preview.dtx
  504 @include preview-dtxdoc.texi
  506 @node The Emacs interface, The preview images, The LaTeX style file, For advanced users
  507 @section The Emacs interface
  509 You can use @kbd{M-x customize-group @key{RET} preview-latex @key{RET}}
  510 in order to customize these variables, or use the menus for it.  We
  511 explain the various available options together with explaining how they
  512 work together in making @previewlatex{} work as intended.
  514 @vtable @code
  515 @item preview-LaTeX-command
  516 When you generate previews on a buffer or a region, the command in
  517 @code{preview-LaTeX-command} gets run (that variable should only be
  518 changed with Customize since its structure is somewhat peculiar, though
  519 expressive).  As usual with @AUCTeX{}, you can continue working while
  520 this is going on.  It is not a good idea to change the file until after
  521 @previewlatex{} has established where to place the previews which it can
  522 only do after the @LaTeX{} run completes.  This run produces a host of
  523 pseudo-error messages that get parsed by @previewlatex{} at the end of
  524 the @LaTeX{} run and give it the necessary information about where in
  525 the source file the @LaTeX{} code for the various previews is located
  526 exactly. The parsing takes a moment and will render Emacs busy.
  528 @item preview-LaTeX-command-replacements
  529 This variable specifies transformations to be used before calling the
  530 configured command.  One possibility is to have @samp{\pdfoutput=0 }
  531 appended to every command starting with @samp{pdf}.  This particular
  532 setting is available as the shortcut
  533 @samp{preview-LaTeX-disable-pdfoutput}.  Since @previewlatex{} can work
  534 with @acronym{PDF} files by now, there is little incentive for using
  535 this option, anymore (for projects not requiring @acronym{PDF} output,
  536 the added speed of @samp{dvipng} might make this somewhat attractive).
  538 @item preview-required-option-list
  539 @code{preview-LaTeX-command} uses @code{preview-required-option-list} in
  540 order to pass options such as @option{auctex}, @option{active} and
  541 @option{dvips} to the @file{preview} package.  This means that the user
  542 need (and should) not supply these in the document itself in case he
  543 wants to be able to still compile his document without it turning into
  544 an incoherent mass of little pictures.  These options even get passed
  545 in when the user loads @file{preview} explicitly in his document.
  547 The default includes an option @code{counters} that is controlled by the
  548 boolean variable
  550 @item preview-preserve-counters
  551 This option will cause the @file{preview} package to emit information
  552 that will assist in keeping things like equation counters and section
  553 numbers reasonably correct even when you are regenerating only single
  554 previews.
  556 @item preview-default-option-list
  557 @itemx preview-default-preamble
  558 If the document does not call in the package @code{preview} itself (via
  559 @code{\usepackage}) in the preamble, the preview package is loaded using
  560 default options from @code{preview-default-option-list} and additional
  561 commands specified in @code{preview-default-preamble}.
  563 @item preview-fast-conversion
  564 This is relevant only for @acronym{DVI} mode.  It defaults to `On' and
  565 results in the whole document being processed as one large PostScript
  566 file from which the single images are extracted with the help of parsing
  567 the PostScript for use of so-called @acronym{DSC} comments.  The
  568 bounding boxes are extracted with the help of @TeX{} instead of getting
  569 them from Dvips.  If you are experiencing bounding box problems, try
  570 setting this option to `Off'.
  572 @item preview-prefer-TeX-bb
  573 If this option is `On', it tells @previewlatex{} never to try to extract
  574 bounding boxes from the bounding box comments of @acronym{EPS} files,
  575 but rather rely on the boxes it gets from @TeX{}.  If you activated
  576 @code{preview-fast-conversion}, this is done, anyhow, since there are no
  577 @acronym{EPS} files from which to read this information.  The option
  578 defaults to `Off', simply because about the only conceivable reason to
  579 switch off @code{preview-fast-conversion} would be that you have some
  580 bounding box problem and want to get Dvips' angle on that matter.
  582 @item preview-scale-function
  583 @itemx preview-reference-face
  584 @itemx preview-document-pt-list
  585 @itemx preview-default-document-pt
  586 @code{preview-scale-function} determines by what factor
  587 images should be scaled when appearing on the screen.  If you specify a
  588 numerical value here, the physical size on the screen will be that of
  589 the original paper output scaled by the specified factor, at least if
  590 Emacs' information about screen size and resolution are correct.  The
  591 default is to let @code{preview-scale-from-face} determine the scale
  592 function.  This function determines the scale factor by making the
  593 size of the default font in the document match that of the on-screen
  594 fonts.
  596 The size of the screen fonts is deduced from the font
  597 @code{preview-reference-face} (usually the default face used for
  598 display), the size of the default font for the document is determined
  599 by calling @code{preview-document-pt}.
  600 @findex preview-document-pt
  601 This function consults the members of @code{preview-document-pt-list} in
  602 turn until it gets the desired information.  The default consults first
  603 @code{preview-parsed-font-size},
  604 @vindex preview-parsed-font-size
  605 then calls @code{preview-auctex-font-size}
  606 @findex preview-auctex-font-size
  607 which asks @AUCTeX{} about any size specification like @option{12pt} to
  608 the documentclass that it might have detected when parsing the document, and
  609 finally reverts to just assuming @code{preview-default-document-pt} as
  610 the size used in the document (defaulting to 10pt).
  612 If you find that the size of previews and the other Emacs display
  613 clashes, something goes wrong.  @code{preview-parsed-font-size} is
  614 determined at @code{\begin@{document@}} time; if the default font size
  615 changes after that, it will not get reported.  If you have an outdated
  616 version of @file{preview.sty} in your path, the size might not be
  617 reported at all.  If in this case @AUCTeX{} is unable to find a size
  618 specification, and if you are using a document class with a different
  619 default value (like KomaScript), the default fallback assumption will
  620 probably be wrong and @previewlatex{} will scale up things too large.
  621 So better specify those size options even when you know that @LaTeX{}
  622 does not need them: @previewlatex{} might benefit from them.  Another
  623 possibility for error is that you have not enabled @AUCTeX{}'s document
  624 parsing options.  The fallback method of asking @AUCTeX{} about the size
  625 might be disabled in future versions of @previewlatex{} since in
  626 general it is more reliable to get this information from the @LaTeX{}
  627 run itself.
  629 @item preview-fast-dvips-command
  630 @itemx preview-dvips-command
  631 The regular command for turning a @acronym{DVI} file into a single
  632 PostScript file is @code{preview-fast-dvips-command}, while
  633 @code{preview-dvips-command} is used for cranking out a @acronym{DVI}
  634 file where every preview is in a separate @acronym{EPS} file.  Which of
  635 the two commands gets used depends on the setting of
  636 @code{preview-fast-conversion}.  The printer specified here by default
  637 is @option{-Pwww} by default, which will usually get you scalable fonts
  638 where available. If you are experiencing problems, you might want to try
  639 playing around with Dvips options (@inforef{Command-line options,,dvips}).
  641 The conversion of the previews into PostScript or @acronym{EPS} files
  642 gets started after the @LaTeX{} run completes when Emacs recognizes the
  643 first image while parsing the error messages.  When Emacs has finished
  644 parsing the error messages, it activates all detected previews.  This
  645 entails throwing away any previous previews covering the same areas, and
  646 then replacing the text in its visual appearance by a placeholder
  647 looking like a roadworks sign.
  649 @item preview-nonready-icon-specs
  650 This is the roadworks sign displayed while previews are being prepared.
  651 You may want to customize the font sizes at which @previewlatex{}
  652 switches over between different icon sizes, and the ascent ratio which
  653 determines how high above the base line the icon gets placed.
  655 @item preview-error-icon-specs
  656 @itemx preview-icon-specs
  657 Those are icons placed before the source code of an opened preview and,
  658 respectively, the image specs to be used for PostScript errors, and a
  659 normal open preview in text representation.
  661 @item preview-inner-environments
  662 This is a list of environments that are regarded as inner levels of an
  663 outer environment when doing @code{preview-environment}. One example
  664 when this is needed is in
  665 @code{\begin@{equation@}\begin@{split@}@dots{}\end@{split@}\end@{equation@}}, and
  666 accordingly @code{split} is one entry in
  667 @code{preview-inner-environments}.
  669 @end vtable
  671 @node The preview images, Misplaced previews, The Emacs interface, For advanced users
  672 @section The preview images
  674 @vtable @code
  675 @item preview-image-type
  676 @itemx preview-image-creators
  677 @itemx preview-gs-image-type-alist
  678 What happens when @LaTeX{} is finished depends on the configuration of
  679 @code{preview-image-type}.  What to do for each of the various settings
  680 is specified in the variable @code{preview-image-creators}.  The options
  681 to pass into Ghostscript and what Emacs image type to use is specified
  682 in @code{preview-gs-image-type-alist}.
  684 @code{preview-image-type} defaults to @code{png}.  For this to work,
  685 your version of Ghostscript needs to support the @option{png16m} device.
  686 If you are experiencing problems here, you might want to reconfigure
  687 @code{gs-image-type-alist} or @code{preview-image-type}.  Reconfiguring
  688 @code{preview-image-creators} is only necessary for adding additional
  689 image types.
  691 Most devices make @previewlatex{} start up a single Ghostscript process
  692 for the entire preview run (as opposed to one per image) and feed it
  693 either sections of a @acronym{PDF} file (if PDF@LaTeX{} was used), or
  694 (after running Dvips) sections of a single PostScript file or separate
  695 @acronym{EPS} files in sequence for conversion into @acronym{PNG} format
  696 which can be displayed much faster by Emacs.  Actually, not in sequence
  697 but backwards since you are most likely editing at the end of the
  698 document.  And as an added convenience, any preview that happens to be
  699 on-screen is given higher priority so that @previewlatex{} will first
  700 cater for the images that are displayed. There are various options
  701 customizable concerning aspects of that operation, see the customization
  702 group @code{Preview Gs} for this.
  704 Another noteworthy setting of @code{preview-image-type} is
  705 @samp{dvipng}: in this case, the @samp{dvipng}
  706 @pindex dvipng 
  707 program will get run on @acronym{DVI} output (see below for @acronym{PDF}).
  708 This is in general much faster than Dvips and Ghostscript.  In that
  709 case, the option
  711 @item preview-dvipng-command
  712 will get run for doing the conversion, and it is expected that
  714 @item preview-dvipng-image-type
  715 images get produced (@samp{dvipng} might be configured for other image
  716 types as well).  You will notice that @code{preview-gs-image-type-alist}
  717 contains an entry for @code{dvipng}: this actually has nothing to with
  718 @samp{dvipng} itself but specifies the image type and Ghostscript device
  719 option to use when @samp{dvipng} can't be used.  This will obviously be
  720 the case for @acronym{PDF} output by PDF@LaTeX{}, but it will also happen
  721 if the @acronym{DVI} file contains PostScript specials in which case the
  722 affected images will get run through Dvips and Ghostscript once
  723 @samp{dvipng} finishes.
  725 Note for p@LaTeX{} and up@LaTeX{} users: It is known that @code{dvipng}
  726 is not compatible with p@LaTeX{} and up@LaTeX{}.  If
  727 @code{preview-image-type} is set to @samp{dvipng} and (u)p@LaTeX{} is
  728 used, @samp{dvipng} just fails and @previewlatex{} falls back on Dvips
  729 and Ghostscript.
  731 @item preview-gs-options
  732 Most interesting to the user perhaps is the setting of this variable.
  733 It contains the default antialiasing settings @option{-dTextAlphaBits=4}
  734 and @option{-dGraphicsAlphaBits=4}.  Decreasing those values to 2 @w{or
  735 1} might increase Ghostscript's performance if you find it lacking.
  736 @end vtable
  738 Running and feeding Ghostscript from @previewlatex{} happens
  739 asynchronously again: you can resume editing while the images arrive.
  740 While those pretty pictures filling in the blanks on screen tend to
  741 make one marvel instead of work, rendering the non-displayed images
  742 afterwards will not take away your attention and will eventually
  743 guarantee that jumping around in the document will encounter only
  744 prerendered images.
  746 @node Misplaced previews,  , The preview images, For advanced users
  747 @section Misplaced previews
  749 If you are reading this section, the first thing is to check that your
  750 problem is not caused by x-symbol in connection with an installation not
  751 supporting 8-bit characters (@pxref{x-symbol interoperation}).  If not,
  752 here's the beef:
  754 As explained previously, Emacs uses pseudo-error messages generated by
  755 the @samp{preview} package in order to pinpoint the exact source
  756 location where a preview originated.  This works in running text, but
  757 fails when preview material happens to lie in macro arguments, like the
  758 contents of @code{\emph}. Those macros first read in their entire
  759 argument, munge it through, perhaps transform it somehow, process it and
  760 perhaps then typeset something. When they finally typeset something,
  761 where is the location where the stuff originated? @TeX{}, having read in
  762 the entire argument before, does not know and actually there would be no
  763 sane way of defining it.
  765 For previews contained inside such a macro argument, the default
  766 behaviour of @previewlatex{} is to use a position immediately after the
  767 closing brace of the argument. All the previews get placed there, all at
  768 a zero-width position, which means that Emacs displays it in an order
  769 that @previewlatex{} cannot influence (currently in Emacs it is even
  770 possible that the order changes between runs). And since the placement
  771 of those previews is goofed up, you will not be able to regenerate them
  772 by clicking on them. The default behaviour is thus somewhat undesirable.
  774 The solution (like with other preview problems) is to tell the @LaTeX{}
  775 @samp{preview} package how to tackle this problem (@pxref{The LaTeX
  776 style file}).  Simply, you don't need @code{\emph} do anything at all
  777 during previews! You only want the text math previewed, so the solution
  778 is to use @code{\PreviewMacro*\emph} in the preamble of your document
  779 which will make @LaTeX{} ignore @code{\emph} completely as long as it is
  780 not part of a larger preview (in which case it gets typeset as
  781 usual). Its argument thus becomes ordinary text and gets treated like
  782 ordinary text.
  784 Note that it would be a bad idea to declare
  785 @code{\PreviewMacro*[@{@{@}@}]\emph} since then both @code{\emph} as
  786 well as its argument would be ignored instead of previewed. For
  787 user-level macros, this is almost never wanted, but there may be
  788 internal macros where you might want to ignore internal arguments.
  790 The same mechanism can be used for a number of other text-formatting
  791 commands like @code{\textrm}, @code{\textit} and the like. While they
  792 all use the same internal macro @code{\text@@command}, it will not do to
  793 redefine just that, since they call it only after having read their
  794 argument in, and then it already is too late. So you need to disable
  795 every of those commands by hand in your document preamble.
  797 Actually, we wrote all of the above just to scare you.  At least all of
  798 the above mentioned macros and a few more are already catered for by a
  799 configuration file @file{prauctex.cfg} that gets loaded by default
  800 unless the @samp{preview} package gets loaded with the @option{noconfig}
  801 option.  You can make your own copy of this file in a local directory
  802 and edit it in case of need.  You can also add loading of a file of your
  803 liking to @code{preview-default-preamble},
  804 @vindex preview-default-preamble
  805 or alternatively do the
  806 manual disabling of your favorite macro in
  807 @code{preview-default-preamble},
  808 @vindex preview-default-preamble
  809 which is customizable in the Preview Latex group.
  811 @node ToDo, Frequently Asked Questions, For advanced users, top
  812 @c Also used as TODO: in separate file
  813 @appendix ToDo
  814 @include preview-todo.texi
  816 @node Frequently Asked Questions, Copying this Manual, ToDo, top
  817 @c Also used as TODO: in separate file
  818 @appendix Frequently Asked Questions
  819 @include preview-faq.texi
  821 @node Copying this Manual, Index, Frequently Asked Questions, top
  822 @c Not to be changed often, I think: in separate file.
  823 @appendix Copying this Manual
  825 @ifinfo
  826 The copyright notice for this manual is:
  828 @insertcopying
  829 @end ifinfo
  831 The full license text can be read here:
  833 @menu
  834 * GNU Free Documentation License:: License for copying this manual.
  835 @end menu
  837 @include fdl.texi
  839 @c @node Credits, Index, Internals, top
  840 @c @appendix Credits 
  842 @node Index,  , Copying this Manual, top
  843 @unnumbered Index
  845 @printindex cp
  847 @bye