Source

auctex / doc / preview-latex.texi

Full commit
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
\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{<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{<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{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