-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathpreview-latex.info
2629 lines (2162 loc) · 121 KB
/
preview-latex.info
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
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
This is docUfyEMz.info, produced by makeinfo version 6.8 from
preview-latex.texi.
This manual is for preview-latex, a LaTeX preview mode for AUCTeX
(version 14.0.9.2025-03-11_18:24:01 from 2025-03-11_18:24:01).
Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2017-2019, 2021
Free Software Foundation, Inc.
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."
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* preview-latex: (preview-latex). Preview LaTeX fragments in Emacs
END-INFO-DIR-ENTRY
INFO-DIR-SECTION TeX
START-INFO-DIR-ENTRY
* preview-latex: (preview-latex). Preview LaTeX fragments in Emacs
END-INFO-DIR-ENTRY
File: docUfyEMz.info, Node: Top, Prev: (dir), Up: (dir)
preview-latex
*************
This manual may be copied under the conditions spelled out in *note
Copying this Manual::.
preview-latex is a package embedding preview fragments into Emacs
source buffers under the AUCTeX editing environment for LaTeX. It uses
'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 '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 preview-latex
* Copying this Manual:: GNU Free Documentation License
* Index:: A menu of many topics.
File: docUfyEMz.info, Node: Copying, Next: Introduction, Prev: Top, Up: Top
Copying
*******
For the conditions for copying parts of preview-latex, 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
*note (auctex)Copying::.
This manual specifically is covered by the GNU Free Documentation
License (*note Copying this Manual::).
File: docUfyEMz.info, Node: Introduction, Next: Installation, Prev: Copying, Up: Top
1 Introduction
**************
Does your neck hurt from turning between previewer windows and the
source too often? This AUCTeX component will render your displayed
LaTeX equations right into the editing window where they belong.
The purpose of preview-latex is to embed LaTeX environments such as
display math or figures into the source buffers and switch conveniently
between source and image representation.
* Menu:
* What use is it?::
* Activating preview-latex::
* Getting started::
* Basic modes of operation::
* More documentation::
* Availability::
* Contacts::
File: docUfyEMz.info, Node: What use is it?, Next: Activating preview-latex, Prev: Introduction, Up: Introduction
1.1 What use is it?
===================
WYSIWYG (what you see is what you get) sometimes is considered all the
rage, sometimes frowned upon. Do we really want it? Wrong question.
The right question is _what_ we want from it. Except when finetuning
the layout, we don't want to use printer fonts for on-screen text
editing. The low resolution and contrast of a computer screen render
all but the coarsest printer fonts (those for low-quality newsprint)
unappealing, and the margins and pagination of the print are not wanted
on the screen, either. On the other hand, more complex visual
compositions like math formulas and tables can't easily be taken in when
seen only in the source. preview-latex strikes a balance: it only uses
graphic renditions of the output for certain, configurable constructs,
does this only when told, and then right in the source code. Switching
back and forth between the source and preview is easy and natural and
can be done for each image independently. Behind the scenes of
preview-latex, a sophisticated framework of other programs like
'dvipng', Dvips and Ghostscript are employed together with a special
LaTeX style file for extracting the material of interest in the
background and providing fast interactive response.
File: docUfyEMz.info, Node: Activating preview-latex, Next: Getting started, Prev: What use is it?, Up: Introduction
1.2 Activating preview-latex
============================
Successful installation automatically activates the package at Emacs
startup.
If you don't get a "Preview" menu in LaTeX mode in spite of AUCTeX
showing its "Command", your installation is broken. One possible cause
are duplicate Lisp files that might be detectable with 'M-x
list-load-path-shadows <RET>'.
File: docUfyEMz.info, Node: Getting started, Next: Basic modes of operation, Prev: Activating preview-latex, Up: Introduction
1.3 Getting started
===================
Once activated, preview-latex and its documentation will be accessible
via its menus. When you have loaded a LaTeX document (a sample document
'circ.tex' is included in the distribution, but most documents including
math and/or figures should do), you can use its menu or 'C-c C-p C-d'
(for 'Preview/Document'). Previews will now be generated for various
objects in your document. You can use the time to take a short look at
the other menu entries and key bindings in the 'Preview' menu. You'll
see the previewed objects change into a roadworks sign when
preview-latex has determined just what it is going to preview. Note
that you can freely navigate the buffer while this is going on. When
the process is finished you will see the objects typeset in your buffer.
It is a bad idea, however, to edit the buffer before the roadworks
signs appear, since that is the moment when the correlation between the
original text and the buffer locations gets established. If the buffer
changes before that point of time, the previews will not be placed where
they belong. If you do want to change some obvious error you just
spotted, we recommend you stop the background process by pressing 'C-c
C-k'.
To see/edit the LaTeX code for a specific object, put the point (the
cursor) on it and press 'C-c C-p C-p' (for 'Preview/at point'). It will
also do to click with the middle mouse button on the preview. Now you
can edit the code, and generate a new preview by again pressing 'C-c C-p
C-p' (or by clicking with the middle mouse button on the icon before the
edited text).
If you are using the 'desktop' package, previews will remain from one
session to the next as long as you don't kill your buffer.
File: docUfyEMz.info, Node: Basic modes of operation, Next: More documentation, Prev: Getting started, Up: Introduction
1.4 Basic modes of operation
============================
preview-latex has a number of methods for generating its graphics. Its
default operation is equivalent to using the 'LaTeX' command from
AUCTeX. If this happens to be a call of PDFLaTeX generating PDF output
(you need at least AUCTeX 11.51 for this), then Ghostscript will be
called directly on the resulting PDF file. If a DVI file gets produced,
first Dvips and then Ghostscript get called by default.
The image type to be generated by Ghostscript can be configured with
M-x customize-option <RET> preview-image-type <RET>
The default is 'png' (the most efficient image type). A special setting
is 'dvipng' in case you have the 'dvipng' program installed. In this
case, 'dvipng' will be used for converting DVI files and Ghostscript
(with a 'PNG' device) for converting PDF files. 'dvipng' is much faster
than the combination of Dvips and Ghostscript. 'dvipng' is included in
standard TeX Live distribution.
File: docUfyEMz.info, Node: More documentation, Next: Availability, Prev: Basic modes of operation, Up: Introduction
1.5 More documentation
======================
After the installation, documentation in the form of this info manual
will be available. You can access it with the standalone info reader
with
info preview-latex
or by pressing 'C-h i d m preview-latex <RET>' in Emacs. Once
preview-latex is activated, you can instead use 'C-c C-p <TAB>' (or the
menu entry 'Preview/Read documentation').
Depending on your installation, a printable manual may also be
available in the form of 'preview-latex.pdf'.
Detailed documentation for the LaTeX style used for extracting the
preview images is placed in 'preview.pdf' in a suitable directory during
installation; on typical TeX Live-based systems,
texdoc preview
will display it.
File: docUfyEMz.info, Node: Availability, Next: Contacts, Prev: More documentation, Up: Introduction
1.6 Availability
================
The preview-latex project is now part of AUCTeX and accessible as part
of the AUCTeX project page (https://savannah.gnu.org/projects/auctex).
Anonymous Git is available at <git://git.savannah.gnu.org/auctex.git>
or <https://git.savannah.gnu.org/git/auctex.git>. You can also browse
the repository (https://git.savannah.gnu.org/cgit/auctex.git) via web
interface.
File: docUfyEMz.info, Node: Contacts, Prev: Availability, Up: Introduction
1.7 Contacts
============
Bug reports should be sent by using 'M-x preview-report-bug <RET>', as
this will fill in a lot of information interesting to us. If the
installation fails (but this should be a rare event), report bugs to
<bug-auctex@gnu.org>.
There is a general discussion list for AUCTeX which also covers
preview-latex, look at <https://lists.gnu.org/mailman/listinfo/auctex>.
For more information on the mailing list, send a message with just the
word "help" as subject or body to <auctex-request@gnu.org>. For the
developers, there is the <auctex-devel@gnu.org> list; it would probably
make sense to direct feature requests and questions about internal
details there. There is a low-volume read-only announcement list
available to which you can subscribe by sending a mail with "subscribe"
in the subject to <info-auctex-request@gnu.org>.
Offers to support further development will be appreciated. If you
want to show your appreciation with a donation to the main developer,
you can do so via PayPal to <dak@gnu.org>, and of course you can arrange
for service contracts or for added functionality. Take a look at the
*note ToDo:: list for suggestions in that area.
File: docUfyEMz.info, Node: Installation, Next: Keys and lisp, Prev: Introduction, Up: Top
2 Installation
**************
Installation is now being covered in *note (auctex)Installation::.
File: docUfyEMz.info, Node: Keys and lisp, Next: Simple customization, Prev: Installation, Up: Top
3 Key bindings and user-level lisp functions
********************************************
preview-latex adds key bindings starting with 'C-c C-p' to the supported
modes of AUCTeX (*Note (auctex)Key Index::). It will also add its own
'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 'C-h f' if you need the Lisp information.
'C-c C-p C-p'
'preview-at-point'
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 ('transient-mark-mode'), it is
run through 'preview-region'.
'<mouse-2>'
The middle mouse button has a similar action bound to it as
'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.
'<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:
'C-c C-p C-w'
'preview-copy-region-as-mml'
Copy a 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 (*note Composing:
(emacs-mime)Composing.).
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
'preview-transparent-border' set to 'nil', or the images will have
an ugly border. preview-latex 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 'mml-preview' (on 'C-c C-m P') to make
sure they look fine.
'C-c C-p C-e'
'preview-environment'
Preview/Generate previews for environment
Run preview on LaTeX environment. The environments in
'preview-inner-environments' are treated as inner levels so that
for instance, the 'split' environment in
'\begin{equation}\begin{split}...\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.
'C-c C-p C-s'
'preview-section'
Preview/Generate previews for section
Run preview on this LaTeX section.
'C-c C-p C-r'
'preview-region'
Preview/Generate previews for region
Run preview on current region.
'C-c C-p C-b'
'preview-buffer'
Preview/Generate previews for buffer
Run preview on the current buffer.
'C-c C-p C-d'
'preview-document'
Preview/Generate previews for document
Run preview on the current document.
'C-c C-p C-c C-p'
'preview-clearout-at-point'
Preview/Remove previews at point
Clear out (remove) the previews that are immediately adjacent to
point.
'C-c C-p C-c C-s'
'preview-clearout-section'
Preview/Remove previews from section
Clear out all previews in current section.
'C-c C-p C-c C-r'
'preview-clearout'
Preview/Remove previews from region
Clear out all previews in the current region.
'C-c C-p C-c C-b'
'preview-clearout-buffer'
Preview/Remove previews from buffer
Clear out all previews in current buffer. This makes the current
buffer lose all previews.
'C-c C-p C-c C-d'
'preview-clearout-document'
Preview/Remove previews from 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.
'C-c C-p C-f'
'preview-cache-preamble'
Preview/Turn preamble cache on
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. preview-latex 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. <https://github.com/davidcarlisle/dpctex/issues/15>
* XeLaTeX cannot use preamble cache at all. The reason is
intrinsic in XeLaTeX, so preview-latex can't help.
* LuaLaTeX 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.
'C-c C-p C-c C-f'
'preview-cache-preamble-off'
Preview/Turn preamble cache off
Clear the pregenerated format file and stop using preambles for the
current document. If the caching gives you problems, use this.
'C-c C-p C-i'
'preview-goto-info-page'
Preview/Read Documentation
Read this info manual.
'M-x preview-report-bug <RET>'
'preview-report-bug'
Preview/Report Bug
This is the preferred way of reporting bugs as it will fill in what
version of preview-latex 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 *note Known problems::.
'C-c C-k'
LaTeX/TeX Output/Kill Job
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,
preview-latex may be confused and place the previews wrong.
File: docUfyEMz.info, Node: Simple customization, Next: Known problems, Prev: Keys and lisp, Up: Top
4 Simple customization
**********************
Customization options can be found by typing 'M-x customize-group <RET>
preview <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 *note For advanced users::), but some are:
* 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 'preview-transparent-color' in the '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.
* Showing '\label's
When using preview-latex, the '\label's are hidden by the previews.
It is possible to make them visible in the output by using the
LaTeX package 'showkeys' alternatively 'showlabels'. However, the
boxes of these labels will be outside the region preview-latex
considers as the preview image. To enable a similar mechanism
internal to preview-latex, enable the 'showlabels' option in the
variable 'preview-default-option-list' in the 'Preview Latex'
group.
It must be noted, however, that a much better idea may be to use
the RefTeX package for managing references. *Note RefTeX in a
Nutshell: (reftex)RefTeX in a Nutshell.
* 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., 'C-c C-p C-p'). Other options
for 'preview-auto-reveal' are available via 'customize'. Note that
the default behavior of 'preview-auto-reveal' derives from the list
'preview-auto-reveal-commands' which can be customized as well.
* Automatically cache preambles
Currently preview-latex asks you whether you want to cache the
document preamble (everything before '\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, preview-latex 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
'preview-auto-cache-preamble'.
* Attempt to keep counters accurate when editing
Since preview-latex 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
'preview-preserve-counters' to 't' (this is consulted by
'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.
* 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
'preview-default-option-list' in the 'Preview Latex' group.
If it is not available there, you can add it to
'preview-default-preamble' also in the 'Preview Latex' group, by
adding a '\PreviewMacro' or '\PreviewEnvironment' entry (*note
Provided commands::) _after_ the '\RequirePackage' line. For
example, if you want to preview the 'center' environment, press the
<Show> button and the last <INS> button, then add
\PreviewEnvironment{center}
in the space that just opened. Note that since '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 (*note
Local Variables in Files: (emacs)File Variables.). A perhaps more
convenient place for such options would be in a configuration file
in the same directory with your project (*note Package options::).
The usual file for preview-latex preconfiguration is
'prauctex.cfg'. If you also want to keep the systemwide defaults,
you should add a line
\InputIfFileExists{preview/prauctex.cfg}{}{}
to your own version of 'prauctex.cfg' (this is assuming that global
files relating to the 'preview' package are installed in a
subdirectory 'preview', the default behavior).
* Don't preview inline math
If you have performance problems because your document is full of
inline math ('$...$'), or if your usage of '$' conflicts with
preview-latex's, you can turn off inline math previews. In the
'Preview Latex' group, remove 'textmath' from
'preview-default-option-list' by customizing this variable.
File: docUfyEMz.info, Node: Known problems, Next: For advanced users, Prev: Simple customization, Up: Top
5 Known problems
****************
A number of issues are known concerning the interoperation with various
other software. Some of the known problems can be solved by moving to
newer versions of the problematic software or by simple patches.
* Menu:
* Font problems with Dvips::
* Too small bounding boxes::
* x-symbol interoperation::
* Middle-clicks paste instead of toggling::
* No images are displayed with gs 9.27 and earlier::
* Black texts are too hard to read on dark background::
If you find something not mentioned here, please send a bug report
using 'M-x preview-report-bug <RET>', which will fill in a lot of
information interesting to us and send it to the <bug-auctex@gnu.org>
list. Please use the bug reporting commands if at all possible.
File: docUfyEMz.info, Node: Font problems with Dvips, Next: Too small bounding boxes, Up: Known problems
5.1 Font problems with Dvips
============================
Some fonts have been reported to produce wrong characters with
preview-latex. preview-latex calls Dvips by default with the option
'-Pwww' in order to get scalable fonts for nice results. If you are
using antialiasing, however, the results might be sufficiently nice with
bitmapped fonts, anyway. You might try '-Ppdf' for another stab at
scalable fonts, or other printer definitions. Use
'M-x customize-option <RET> preview-fast-dvips-command <RET>'
and
'M-x customize-option <RET> preview-dvips-command <RET>'
in order to customize this.
One particular problem is that several printer setup files (typically
in a file called '/usr/share/texmf/dvips/config/config.pdf' if you are
using the '-Ppdf' switch) contain the 'G' option for 'character
shifting'. This option will result in 'fi' being rendered as '£'
(British Pounds sign) in several fonts, unless your version of Dvips has
a long-standing bug in its implementation fixed (only very recent
versions of Dvips have).
File: docUfyEMz.info, Node: Too small bounding boxes, Next: x-symbol interoperation, Prev: Font problems with Dvips, Up: Known problems
5.2 Too small bounding boxes
============================
The bounding box of a preview is determined by the LaTeX package using
the pure TeX bounding boxes. If there is material extending outside of
the TeX box, that material will be missing from the preview image. This
happens for the label-showing boxes from the 'showkeys' package. This
particular problem can be circumvented by using the 'showlabels' option
of the preview package.
In general, you should try to fix the problem in the TeX code, like
avoiding drawing outside of the picture with PSTricks.
One possible remedy is to set 'preview-fast-conversion' to 'Off'
(*note The Emacs interface::). The conversion will take more time, but
will then use the bounding boxes from EPS files generated by Dvips.
Dvips generally does not miss things, but it does not understand
PostScript constructs like '\resizebox' or '\rotate' commands, so will
generate rather wrong boxes for those. Dvips can be helped with the
'psfixbb' package option to preview (*note The LaTeX style file::),
which will tag the corners of the included TeX box. This will mostly be
convenient for _pure_ PostScript stuff like that created by PSTricks,
which Dvips would otherwise reserve no space for.
File: docUfyEMz.info, Node: x-symbol interoperation, Next: Middle-clicks paste instead of toggling, Prev: Too small bounding boxes, Up: Known problems
5.3 x-symbol interoperation
===========================
Thanks to the work of Christoph Wedler, starting with version
'4.0h/beta' of x-symbol, the line parsing of AUCTeX and preview-latex is
fully supported. Earlier versions exhibit problems. However, versions
before '4.2.2' will cause a drastic slowdown of preview-latex's parsing
pass, so we don't recommend to use versions earlier than that.
If you wonder what x-symbol is, it is a package that transforms
various tokens and subscripts to a more readable form while editing and
offers a few input methods handy especially for dealing with math. Take
a look at <http://x-symbol.sourceforge.net/>.
x-symbol versions up to '4.5.1-beta' at least require an 8bit-clean
TeX implementation (meaning that its terminal output should not use
'^^'-started escape sequences) for cooperation with preview-latex.
Later versions may get along without it, like preview-latex does now.
If you experience problems with 'circ.tex' in connection with both
x-symbol and Latin-1 characters, you may need to change your language
environment or, as a last resort, customize the variable
'LaTeX-command-style' by replacing the command 'latex' with 'latex
-translate-file=cp8bit'.
File: docUfyEMz.info, Node: Middle-clicks paste instead of toggling, Next: No images are displayed with gs 9.27 and earlier, Prev: x-symbol interoperation, Up: Known problems
5.4 Middle-clicks paste instead of toggling
===========================================
This is probably the fault of your favorite package. 'isearch.el' is
known to be affected while searches are in progress, but the code is
such a complicated mess that no patch is in sight. Better just end the
search with '<RET>' before toggling and resume with 'C-s C-s' or similar
afterwards. Since previews over the current match will auto-open,
anyway, this should not be much of a problem in practice.
File: docUfyEMz.info, Node: No images are displayed with gs 9.27 and earlier, Next: Black texts are too hard to read on dark background, Prev: Middle-clicks paste instead of toggling, Up: Known problems
5.5 No images are displayed with gs 9.27 and earlier
====================================================
preview-latex tries to adjust the foreground and background colors of
generated images to those of Emacs. Unfortunately, incompatible changes
introduced in Ghostscript 9.27 breaks the traditional method partially,
and preview-latex can display no images under certain circumstances.
A new method implemented alternatively works only with Ghostscript >
9.27. If you are using Ghostscript 9.27 or earlier, customize the
option 'preview-pdf-adjust-color-method'.
-- User Option: preview-pdf-adjust-color-method
Method to adjust colors of images generated from PDF. It is not
consulted when the LaTeX command produces DVI files.
When the option is 't' (default), preview-latex adjusts the FG and
BG colors of the generated images by the new method. This method
requires that Ghostscript has working 'DELAYBIND' feature, thus is
invalid with gs 9.27 (and possibly < 9.27).
When it is 'compatible', preview-latex uses traditional method.
This option is provided for backward compatibility with older gs.
See the below explanation for detail.
When 'nil', no adjustment is done and "black on white" image is
generated regardless of Emacs color. This is provided for fallback
for gs 9.27 users with customized foreground color. See the below
explanation for detail.
When the LaTeX command produces PDF rather than DVI and Emacs has
non-trivial foreground color, the traditional method ('compatible')
makes gs >= 9.27 to stop with error. Here, "non-trivial foreground
color" includes customized themes.
If you use such non-trivial foreground color and the version of
Ghostscript equals to 9.27, you have two options:
1. Choose the value 'compatible' and customize
'preview-reference-face' to have default (black) foreground
color. This makes the generated image almost non-readable on
dark background, so the next option would be your only choice
in that case.
2. Choose the value 'nil', which forces plain "black on white"
appearance for the generated image. You can at least read
what are written in the image although they may not match with
your Emacs color well.
The default value used to be 'compatible' for short period before
Ghostscript 9.50 was released but now is 't'.
File: docUfyEMz.info, Node: Black texts are too hard to read on dark background, Prev: No images are displayed with gs 9.27 and earlier, Up: Known problems
5.6 Black texts are too hard to read on dark background
=======================================================
Unfortunately, foreground color adjustment discussed in the previous
node doesn't work for XeLaTeX for technical reason. The texts are
always rendered as black in the preview images, so it's almost
impossible to read them on dark background. Hence XeLaTeX users who
like dark background in Emacs frame should customize
'preview-pdf-adjust-color-method' to 'nil'.
File: docUfyEMz.info, Node: For advanced users, Next: ToDo, Prev: Known problems, Up: Top
6 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::
File: docUfyEMz.info, Node: The LaTeX style file, Next: The Emacs interface, Prev: For advanced users, Up: For advanced users
6.1 The LaTeX style file
========================
The main purpose of this package is the extraction of certain
environments (most notably displayed formulas) from LaTeX sources as
graphics. This works with DVI files postprocessed by either Dvips and
Ghostscript or dvipng, but it also works when you are using PDFTeX for
generating PDF files (usually also postprocessed by Ghostscript).
Current uses of the package include the preview-latex package for
WYSIWYG functionality in the AUCTeX editing environment, generation of
previews in LyX, as part of the operation of the pst-pdf package, the
tbook XML system and some other tools.
Producing EPS files with Dvips and its derivatives using the '-E'
option is not a good alternative: People make do by fiddling around with
'\thispagestyle{empty}' and hoping for the best (namely, that the
specified contents will indeed fit on single pages), and then trying to
guess the baseline of the resulting code and stuff, but this is at best
dissatisfactory. The preview package provides an easy way to ensure
that exactly one page per request gets shipped, with a well-defined
baseline and no page decorations. While you still can use the preview
package with the 'classic'
dvips -E -i
invocation, there are better ways available that don't rely on Dvips not
getting confused by PostScript specials.
For most applications, you'll want to make use of the 'tightpage'
option. This will embed the page dimensions into the PostScript or PDF
code, obliterating the need to use the '-E -i' options to Dvips. You
can then produce all image files with a single run of Ghostscript from a
single PDF or PostScript (as opposed to EPS) file.
Various options exist that will pass TeX dimensions and other
information about the respective shipped out material (including
descender size) into the log file, where external applications might
make use of it.
The possibility for generating a whole set of graphics with a single
run of Ghostscript (whether from LaTeX or PDFLaTeX) increases both speed
and robustness of applications. It is also feasible to use dvipng on a
DVI file with the options
-picky -noghostscript
to omit generating any image file that requires Ghostscript, then let a
script generate all missing files using Dvips/Ghostscript. This will
usually speed up the process significantly.
* Menu:
* Package options::
* Provided commands::
File: docUfyEMz.info, Node: Package options, Next: Provided commands, Prev: The LaTeX style file, Up: The LaTeX style file
6.1.1 Package options
---------------------
The package is included with the customary
\usepackage[OPTIONS]{preview}
You should usually load this package as the last one, since it redefines
several things that other packages may also provide.
The following options are available:
'active'
is the most essential option. If this option is not specified, the
'preview' package will be inactive and the document will be typeset
as if the 'preview' package were not loaded, except that all
declarations and environments defined by the package are still
legal but have no effect. This allows defining previewing
characteristics in your document, and only activating them by
calling LaTeX as
latex '\PassOptionsToPackage{active}{preview} \input{FILENAME}'
'noconfig'
Usually the file 'prdefault.cfg' gets loaded whenever the 'preview'
package gets activated. 'prdefault.cfg' is supposed to contain
definitions that can cater for otherwise bad results, for example,
if a certain document class would otherwise lead to trouble. It
also can be used to override any settings made in this package,
since it is loaded at the very end of it. In addition, there may
be configuration files specific for certain 'preview' options like
'auctex' which have more immediate needs. The 'noconfig' option
suppresses loading of those option files, too.
'psfixbb'
Dvips determines the bounding boxes from the material in the DVI
file it understands. Lots of PostScript specials are not part of
that. Since the TeX boxes do not make it into the DVI file, but
merely characters, rules and specials do, Dvips might include far
too small areas. The option 'psfixbb' will include '/dev/null' as
a graphic file in the ultimate upper left and lower right corner of
the previewed box. This will make Dvips generate an appropriate
bounding box.
'dvips'
If this option is specified as a class option or to other packages,
several packages pass things like page size information to Dvips,
or cause crop marks or draft messages written on pages. This
seriously hampers the usability of previews. If this option is
specified, the changes will be undone if possible.
'pdftex'
If this option is set, PDFTeX is assumed as the output driver.
This mainly affects the 'tightpage' option.
'xetex'
If this option is set, XeTeX is assumed as the output driver. This
mainly affects the 'tightpage' option.
'displaymath'
will make all displayed math environments subject to preview
processing. This will typically be the most desired option.
'floats'
will make all float objects subject to preview processing. If you
want to be more selective about what floats to pass through to a
preview, you should instead use the '\PreviewSnarfEnvironment'
command on the floats you want to have previewed.
'textmath'
will make all text math subject to previews. Since math mode is
used throughly inside of LaTeX even for other purposes, this works
by redefining '\(', '\)' and '$' and the 'math' environment
(apparently some people use that). Only occurences of these text
math delimiters in later loaded packages and in the main document
will thus be affected.
'graphics'
will subject all '\includegraphics' commands to a preview.
'sections'
will subject all section headers to a preview.
'delayed'
will delay all activations and redefinitions the 'preview' package
makes until '\''begin{document}'. The purpose of this is to cater
for documents which should be subjected to the 'preview' package
without having been prepared for it. You can process such
documents with
latex '\RequirePackage[active,delayed,OPTIONS]{preview}
\input{FILENAME}'
This relaxes the requirement to be loading the 'preview' package as
last package.
DRIVER
loads a special driver file 'prDRIVER.def'. The remaining options
are implemented through the use of driver files.
'auctex'
This driver will produce fake error messages at the start and end
of every preview environment that enable the Emacs package
preview-latex in connection with AUCTeX to pinpoint the exact
source location where the previews have originated. Unfortunately,
there is no other reliable means of passing the current TeX input
position _in_ a line to external programs. In order to make the
parsing more robust, this option also switches off quite a few
diagnostics that could be misinterpreted.
You should not specify this option manually, since it will only be
needed by automated runs that want to parse the pseudo error
messages. Those runs will then use '\PassOptionsToPackage' in
order to effect the desired behaviour. In addition, 'prauctex.cfg'
will get loaded unless inhibited by the 'noconfig' option. This
caters for the most frequently encountered problematic commands.
'showlabels'
During the editing process, some people like to see the label names
in their equations, figures and the like. Now if you are using
Emacs for editing, and in particular preview-latex, I'd strongly
recommend that you check out the RefTeX package which pretty much
obliterates the need for this kind of functionality. If you still
want it, standard LaTeX provides it with the 'showkeys' package,
and there is also the less encompassing 'showlabels' package.
Unfortunately, since those go to some pain not to change the page
layout and spacing, they also don't change 'preview''s idea of the
TeX dimensions of the involved boxes. So if you are using
'preview' for determing bounding boxes, those packages are mostly
useless. The option 'showlabels' offers a substitute for them.
'tightpage'
It is not uncommon to want to use the results of 'preview' as
graphic images for some other application. One possibility is to
generate a flurry of EPS files with
dvips -E -i -Pwww -o OUTPUTFILE.000 INPUTFILE
However, in case those are to be processed further into graphic
image files by Ghostscript, this process is inefficient since all
of those files need to be processed one by one. In addition, it is
necessary to extract the bounding box comments from the EPS files
and convert them into page dimension parameters for Ghostscript in
order to avoid full-page graphics. This is not even possible if
you wanted to use Ghostscript in a _single_ run for generating the
files from a single PostScript file, since Dvips will in that case
leave no bounding box information anywhere.
The solution is to use the 'tightpage' option. That way a single
command line like
gs -sDEVICE=png16m -dTextAlphaBits=4 -r300
-dGraphicsAlphaBits=4 -dSAFER -q -dNOPAUSE
-sOutputFile=OUTPUTFILE%d.png INPUTFILE.ps
will be able to produce tight graphics from a single PostScript
file generated with Dvips _without_ use of the options '-E -i', in
a single run.
The 'tightpage' option actually also works when using the 'pdftex'
option and generating PDF files with PDFTeX. The resulting PDF
file has separate page dimensions for every page and can directly
be converted with one run of Ghostscript into image files.
If neither 'dvips' or 'pdftex' have been specified, the
corresponding option will get autodetected and invoked.
If you need this in a batch environment where you don't want to use
'preview''s automatic extraction facilities, no problem: just don't
use any of the extraction options, and wrap everything to be
previewed into 'preview' environments. This is how LyX does its
math previews.
If the pages under the 'tightpage' option are just too tight, you
can adjust by setting the length '\PreviewBorder' to a different
value by using '\setlength'. The default value is '0.50001bp',
which is half of a usual PostScript point, rounded up. If you go
below this value, the resulting page size may drop below '1bp', and
Ghostscript does not seem to like that. If you need finer control,
you can adjust the bounding box dimensions individually by changing
the macro '\PreviewBbAdjust' with the help of '\renewcommand'. Its
default value is
\newcommand \PreviewBbAdjust
{-\PreviewBorder -\PreviewBorder
\PreviewBorder \PreviewBorder}
This adjusts the left, lower, right and upper borders by the given