diff options
Diffstat (limited to 'elpa/auctex-13.1.3/doc/preview-latex.texi')
| -rw-r--r-- | elpa/auctex-13.1.3/doc/preview-latex.texi | 849 |
1 files changed, 849 insertions, 0 deletions
diff --git a/elpa/auctex-13.1.3/doc/preview-latex.texi b/elpa/auctex-13.1.3/doc/preview-latex.texi new file mode 100644 index 0000000..26adb89 --- /dev/null +++ b/elpa/auctex-13.1.3/doc/preview-latex.texi @@ -0,0 +1,849 @@ +\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 |