## File: preview-latex.texi

package info (click to toggle)
xemacs21-packages 2009.02.17.dfsg.2-4
 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839 \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 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.2 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 @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 @contents @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 referres 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{} (@inforef{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} or @code{zmacs-regions}), it is run through @code{preview-region}. @kindex @kbd{C-c C-p C-p} @findex preview-at-point @item @kbd{} 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{} 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{M-m P}, or @kbd{C-c C-m P} in @w{Emacs 22}) @kindex @kbd{M-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. @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 @code{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. Its default is different in @w{Emacs 21} and @w{Emacs 22}, and it is not available in XEmacs. @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 @code{Preview Latex} group. 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 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-options-list} in the @code{Preview Latex} group. If it is not available there, you can add it to @code{preview-default-preamble} also in the @code{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 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 @code{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 ../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 @samp{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 @samp{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 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 by default 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 (@inforef{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}. @item preview-use-balloon-help If you turn this XEmacs-only option on', then moving the mouse over previews and icons will show appropriate help texts. This works by switching on @code{balloon-help-mode} in the buffer if it is not already enabled. The default now is off' since some users reported problems with their version of XEmacs. @w{GNU Emacs} has its corresponding @code{tooltip-mode} enabled by default and in usable condition. @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{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 @code{Preview Gs} for this. Another noteworthy setting of @code{preview-image-type} is @samp{dvipng}: in this case, the @samp{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. @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 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