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