summaryrefslogtreecommitdiffstats
path: root/doc/kdvi/index.docbook
blob: c0e3de0e6bf60ca46f591fb1e41c2d333c7cac16 (plain)
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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "&kdvi;">
  <!ENTITY package "tdegraphics">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
]>

<book lang="&language;">
  <bookinfo>
    <title>The &kdvi; Handbook</title>
    <authorgroup>
      <author>
	<firstname>Stefan</firstname>
	<surname>Kebekus</surname>
	<affiliation>
	  <address>
	   <email>kebekus@kde.org</email>
          </address>
	</affiliation>
      </author>
      <!-- TRANS:ROLES_OF_TRANSLATORS -->
    </authorgroup>
    
    <copyright>
      <year>2001-2004</year>
      <holder>Stefan Kebekus</holder>
    </copyright>
    
    <legalnotice>&FDLNotice;</legalnotice>
    
    <date>2004-02-27</date>
    <releaseinfo>1.11.00</releaseinfo>

    <abstract>
      <para>This document describes &kdvi; version 1.1</para>
    </abstract>

    <keywordset>
      <keyword>KDE</keyword>
      <keyword>linux</keyword>
      <keyword>TeX</keyword>
      <keyword>DVI</keyword>
    </keywordset>

  </bookinfo>

  <chapter id="introduction">
    <title>Introduction</title>

    <para>&kdvi; is a plugin for the &kviewshell; program which allows
    &kviewshell; to display &DVI;-files (<literal
    role="extension">.dvi</literal>) which are produced by the TeX
    typesetting system.  &kdvi; supports many extensions of the &DVI;
    standard, for instance the inclusion of &PostScript; graphics or
    hyperlinks. More details, examples and all the technical
    specifications can be found in the file
    <filename>KDVI-features.dvi</filename> (or see
    <filename>KDVI-features.tex</filename> for the TeX source of that
    file).</para>

    <para>For up-to-date information, consult <ulink
    url="http://devel-home.kde.org/~kdvi">&kdvi;'s home page</ulink>.
    </para>

    <para>TeX is a high-end typesetting system geared towards
    scientific, and in particular mathematical typesetting. More
    information about TeX and &DVI; can be found on the <ulink
    url="http://www.tug.org">homepage of the TeX user group</ulink> or
    the German <ulink url="http://www.dante.de">German DANTE
    e.V.</ulink>.
    </para>
  </chapter>


  <chapter id="starting">
    <title>Starting &kdvi;</title>
    
    <para>Most of the time, &kdvi; will be started by just clicking
    onto a <literal role="extension">.dvi</literal> file in the file
    manager. For convenience there exists a command
    <command>kdvi</command> which calls &kviewshell; with the &kdvi;
    plugin preloaded. The viewer may thus be started using the command
    <userinput><command>kdvi</command>
    <parameter>somepath/paper.dvi</parameter></userinput>. The command
    lines <userinput><command>kdvi</command>
    <parameter>somepath/paper</parameter></userinput> or
    <userinput><command>kdvi</command>
    <parameter>somepath/paper.</parameter></userinput> will also
    work. If you are connected to the internet, you can access files
    which reside on other computers by giving a &URL; as a parameter,
    like this: <userinput><command>kdvi</command>
    <parameter>http://somepath/paper.dvi</parameter></userinput>
    </para>
    
    <para>If you give a &URL; as a parameter, you can tell &kdvi; to
    jump directly to certain place of the &DVI; file.
    For example, <userinput><command>kdvi</command>
    <parameter>file:paper.dvi#43</parameter></userinput> will make
    &kdvi; to open page 43. If you have included source file
    information, a command like <userinput><command>kdvi</command>
    <parameter>file:paper.dvi#src:43paper.tex</parameter></userinput>
    will make &kdvi; search for the place in the &DVI; file which
    corresponds to line 43 in the TeX file
    <parameter>paper.tex</parameter>. You will hardly use this option
    yourself &mdash; read the section on <link
    linkend="forward-search">forward search</link> to learn how to
    set up your editor to start &kdvi; automatically.
    </para>

    <warning><para>Don't forget the <userinput>file:</userinput>
    prefix or it will give unexpected results. For example, the command
    <userinput><command>kdvi</command>
    <parameter>file:paper.dvi#43</parameter></userinput> will open
    page 43 of the file <filename>paper.dvi</filename>. The command
    <userinput><command>kdvi</command>
    <parameter>paper.dvi#43</parameter></userinput> will try to open
    the file <filename>paper.dvi#43</filename>.</para>
    </warning>

    <para>There is another option which you will most likely not need
    to specify yourself. If you type
    <userinput><command>kdvi</command> <parameter>--unique</parameter>
    <parameter>somepath/paper.dvi</parameter></userinput>, &kdvi; will
    load the file if there is no other instance running which has the
    file already loaded. If there is, this instance of &kdvi; will pop
    to the front. A command like <userinput><command>kdvi</command>
    <parameter>--unique</parameter>
    <parameter>file:paper.dvi#43</parameter></userinput> can be used
    in shell scripts to make a running instance of &kdvi; to jump to
    page 43.</para>

    <para>The usual parameters handled by &Qt; and &kde; applications
    also work: <userinput><command>kdvi</command>
    <option>-style</option> <parameter>windows</parameter>
    <option>-display</option> <parameter>:0</parameter>
    <option>-geometry</option> <parameter>400x400+0+0</parameter>
    <option>-caption</option> <parameter>&quot;DVI&quot;</parameter></userinput>
    </para>
  </chapter>
  
  
  <chapter id="print">
    <title>Printing &DVI; Files</title>
    
    <para>&kdvi; can print your &DVI; files using the standard &kde;
    printing interface. Internally, &kdvi; uses the program
    <command>dvips</command> to generate &PostScript;, which is then
    passed on to the printer. In particular, <command>dvips</command>
    must be installed if you want to print with &kdvi;. The program
    <command>dvips</command> uses its own configuration files and its
    own settings, which are fine for most purposes. However, if you
    care for optimal printing results, you should configure
    <command>dvips</command> manually and make sure to set a default
    MetaFont mode which fits your printer best &mdash; on many systems
    you'll find a <ulink url="info:/dvips">GNU-texinfo documentation
    of <command>dvips</command></ulink>, and you might also want to
    look for a file called <filename>dvips.dvi</filename> or
    similar.</para>
  </chapter>

  <chapter id="export">
    <title>Exporting the &DVI; file to other formats</title>

    <para>If you want to save your file as in &PostScript; or PDF
    format, it is not recommended that you use the printing function
    and redirect the printer output to a file. Instead, you can use
    the export functions which produce better-quality output that
    retains many of the special features of the dvi format and looks
    better in many of the viewing applications, such as Adobe's
    <application>Acrobat Reader</application>. You will find the
    export functions in the <guimenu>File</guimenu> menu.</para>

    <section id="export-ps">
      <title>Exporting to &PostScript;</title> 

      <para>As in printing, the external program
      <command>dvips</command> is used to generate the &PostScript;
      file. If the &DVI; file contains hyperlinks, these will also be
      included in the &PostScript; file. If you are an expert, and if
      you would like to generate output which is optimized for a
      specific printer, you should probably start
      <command>dvips</command> manually and choose the proper MetaFont
      mode yourself.</para>
    </section>

    <section id="export-pdf">
      <title>Exporting to <acronym>PDF</acronym></title> 

      <para>In order to produce <acronym>PDF</acronym> files of high
      quality, &kdvi; converts &DVI; to <acronym>PDF</acronym> using
      the external program <command>dvipdfm</command>. If you are
      working on a machine where an older distribution of the TeX
      typesetting system is installed, it may be that the program
      <command>dvipdfm</command> is not installed. In that case, you
      need to use the printing function to generate
      <acronym>PDF</acronym> output.</para>

      <warning>
	<itemizedlist>
	  <listitem>
	    <para>
             If you use an older TeX installation, and if are viewing
             the generated file in Adobe's <application>Acrobat
             reader</application>, you may well find that some of the
             fonts look extremely poor although a printout is fine,
             and although the document looks ok in
             <command>kghostview</command>. This is a known issue with
             the <application>Acrobat Reader</application> and bitmap
             fonts. At the time of writing, the only practicable
             workaround seems to be to avoid bitmap fonts, or to
             upgrade to a more recent TeX installation.
            </para>
	  </listitem>
	  <listitem>
	    <para>
             While <command>dvipdfm</command> produces high-quality
             <acronym>PDF</acronym> files, <command>dvipdfm</command>
             currently currently ignores the &PostScript; that is
             embedded into the &DVI; file. Embedded PostScript is
             generated e.g. by the <application>xy</application> macro
             package, or by the "Embed PostScript files" function
             &kdvi; described <link linkend="embed">below</link>.
            </para>
            <para>
             If you find that the generated <acronym>PDF</acronym>
             file misses graphical data, use the print function of
             &kdvi; instead.
            </para>
	  </listitem>
	</itemizedlist>
      </warning>
    </section>


    <section id="export-text">
      <title>Exporting to text files</title> 

      <para>&kdvi; can also save your &DVI; files in text format.</para>

      <warning>
       <para>
         The &DVI; file standard was not designed with this kind of
         functionality in mind. This function therefore only works
         well with standard ASCII characters. It will not work with
         non-European languages. Depending on the fonts used in the
         files, there may also be problems with accented characters or
         umlauts, and sometimes with ligatures.
       </para>
      </warning>
    </section>
  </chapter>
  

  <chapter id="embed">
    <title>Embedding PostScript files into the &DVI;</title>

    <para>The traditional way of using graphics with
    <application>TeX</application> does not include the graphics data
    directly in the &DVI; file. Instead, the &DVI; file contains only
    a link to a graphics file which resides on the hard disk. The
    advantage of this procedure is that the &DVI; file stays small,
    and that the graphics file can be modified indepent of the
    document's <application>TeX</application> source. The method,
    however, becomes fairly inconvenient if you intend to archive the
    &DVI; file, or if you wish to send it to someone else: rather than
    handling a single file, you have to deal with a multitude of
    files, which need to be kept in exactly the place specified in the
    &DVI; file for everything to work.</para>

    <para>For that reason, &kdvi; allows you to embed external
    &PostScript; files into your &DVI; file. To embed all &PostScript;
    files into a &DVI; file, use the menu entry <guimenu>Edit/Embed
    external PostScript files</guimenu> </para>
    
    <warning> <para>&DVI; files with embedded &PostScript; work fine
    with most other &DVI; handling software,
    e.g. <application>xdvi</application>,
    <application>dvips</application> or
    <application>dvipdf</application>. One notable exception is the
    <application>dvipdfm</application> program, which currently
    ignores the embedded &PostScript;. Since
    <application>dvipdfm</application> is used internally by the
    "Export to <acronym>PDF</acronym>" function of &kdvi;, expect
    problems when you use that function. The same issue shows with
    other software that uses embedded PostScript, e.g. the
    <application>TeX</application> <application>xy</application> macro
    package.</para> </warning>
  </chapter>
  

  <chapter id="inverse-search">
    <title>Using inverse search</title>
    <anchor id="inv-search"></anchor>

    <para>Inverse search is a very useful feature when you are writing
    a TeX document yourself. If everything is properly set up, you can
    click into &kdvi;'s window with the
    <mousebutton>middle</mousebutton> mouse button (on some systems,
    when you don't have a three-button mouse, you can simultaneously
    use the <mousebutton>left</mousebutton> and the
    <mousebutton>right</mousebutton> button). After that, your
    favorite editor will open, load the TeX source file and jump to
    the proper paragraph. To use inverse search, do the
    following:</para>


    <procedure>
      <step>
	<para>Produce a &DVI; file that contains inverse search
	information. This is explained in the section <link
	linkend="inverse-search-tex">Producing TeX files for inverse
	search</link> below. If you just want to test the inverse
	search feature, you can also use the example file
	<filename>KDVI-features.dvi</filename></para>
      </step>
      <step>
	<para>Let &kdvi; know which editor you would like to
	use. Choose an editor in the <guilabel>Preferences</guilabel>
	dialog (this dialog can be reached by choosing
	<guimenuitem>DVI Options</guimenuitem> in the
	<guimenu>Settings</guimenu> menu). The next section of this
	documentation, <link linkend="opt-rendering">Rendering
	Options</link>, explains this dialog in more detail.</para>
      </step>
      <step>
	<para>Some editors need to be started manually, or need
	additional configuration. You will find a description of all
	supported editors in the section <link
	linkend="inverse-search-editor">Setting up your
	editor for inverse search</link> below.</para>
      </step>
      <step>
	<para>Test your setup. Open your &DVI; file in &kdvi; and use
	the <mousebutton>middle</mousebutton> mouse button to click
	into &kdvi;. The editor should pop up and display the TeX
	file.</para>
      </step>
    </procedure>


    <section id="inverse-search-tex">
      <title>Producing TeX files for inverse search</title>
      <para>There are essentially two ways to produce &DVI; files
      which contain inverse search information: you can either use a
      TeX/LaTeX binary which generates and includes the necessary
      information automatically, or you can include an extra package
      which is written in TeX/LaTeX.</para>
      <itemizedlist>
	<listitem>
	  <para>A TeX binary which generates and includes the
	  necessary information automatically is certainly the
	  preferred method of including inverse search information. 
	  If you use version 2 or greater of the <ulink
	  url="http://www.tug.org/teTeX/">TeTeX TeX
	  distribution</ulink>, you can use the 'src-specials' command
	  line option of the tex or latex command, as follows.
<programlisting>
tex --src-specials myfile.tex
</programlisting>
or
<programlisting>
latex --src-specials myfile.tex
</programlisting>
	  </para>
	</listitem>
	<listitem>
	  <para>If you do not have a TeX binary which includes inverse
	  search information natively, copy the files
	  <ulink url="srcltx.sty">
	  <filename>srcltx.sty</filename> </ulink> and
	  <ulink url="srctex.sty"> <filename>srctex.sty</filename>
	  </ulink> to the folder where your TeX file resides (you
	  can do that by pressing the &Shift; key and &LMB; while the
	  mouse pointer is on a hyperlink.)  If you use LaTeX, add the
	  line
<programlisting>
\usepackage[active]{srcltx}
</programlisting>
	   to the preamble of your LaTeX file. If you use plain TeX, the line 
<programlisting>
\include{srctex}
</programlisting>
          will do the trick.</para>
	</listitem>
      </itemizedlist>

      <tip>
	<para>While inverse search is extremely useful when you are
	typing a document yourself, it might be a good idea to remove
	the inverse search information before sending the &DVI; file to
	someone else.</para>
      </tip>

    </section>

    <section id="inverse-search-editor">

    <title>Setting up your editor for inverse search</title>
    
    <para>While inverse search works generally very well with most
    editors, some of them require a bit of extra care. This section
    explains how to configure your editor.</para>

    <section id="editor-setup-emacs">
      <title><application>Emacs</application></title>

      <para><application>Emacs</application> works well with
      &kdvi;. The actual behavior of <application>Emacs</application>
      depends largely on the configuration. As usual, you can
      customize <application>Emacs</application> completely, if you
      are willing to fight your way through Lisp code.</para>

      <para>&kdvi; uses the program <command>emacsclient</command> to
      remote control <application>Emacs</application>.</para>
      <important>
	<para>The program <command>emacsclient</command> requires that
	<application>Emacs</application> is running, and that the
	program <application>Emacs Server</application> is started inside
	<application>Emacs</application>. Inverse search will not work
	optimally unless you have started both
	<application>Emacs</application> and the <application>Emacs
	Server</application>.</para>
      </important>

      <para>To start the <application>Emacs Server</application>, you can do
      one of the following:</para>
	<itemizedlist>
	<listitem>
	  <para>In <application>Emacs</application>, start the
 <application>Emacs Server</application> by typing
 <userinput><keycombo action="seq"><keycap>M</keycap><keycap>X</keycap></keycombo>
 <command>server-start</command></userinput></para>
	</listitem>
	<listitem>
	  <para>Add the line 
<programlisting>
(server-start)
</programlisting>
	   to your <filename>.emacs</filename> file. Restart
	   <application>Emacs</application></para>
	</listitem>
      </itemizedlist>

      
      <tip>
	<itemizedlist>
	  <listitem>
	      <para>Make sure that <application>Emacs</application> is
	      installed. Try to start <command>emacs</command> from
	      the command line.</para>
	  </listitem>
	<listitem>
	      <para>&kdvi; uses the command
	      <command>emacsclient</command> to remote control
	      <application>Emacs</application>. Make sure that
	      <command>emacsclient</command> is available on the
	      command line by trying the command
	      <userinput><command>emacsclient</command>
	      <parameter>Name of a text
	      file</parameter></userinput>. This should open a new
	      text in the <application>Emacs</application>
	      editor.</para>
	</listitem>
	<listitem>
	      <para>If <command>emacsclient</command> fails with an
	      error message like <computeroutput>unable to connect to
	      local</computeroutput>, make sure that
	      <application>Emacs</application> is
	      running. Furthermore, make sure that the
	      <application>Emacs Server</application> is started by typing
	      <userinput><keycombo action="seq"><keycap>M</keycap><keycap>x</keycap></keycombo>
	      <command>server-start</command></userinput>.</para>
	</listitem>
	<listitem>
	      <para>If you want the frame to be auto-raised, add the
	      <function>raise-frame</function> function to
	      <quote>server-switch-hook</quote> (do
	      <userinput><keycombo action="seq"><keycap>M</keycap><keycap>x</keycap></keycombo>
	      <command>customize-variable</command>
	      <keycap>RET</keycap>
	      <command>server-switch-hook</command></userinput> and
	      enter the function name into the text field.</para>
	</listitem>
	<listitem>
	      <para>If you have changed the buffer since your last
	      save, <application>Emacs</application> will ask you:
	      <computeroutput>Revert buffer from file ...? (yes or
	      no)</computeroutput>. You will probably always want to
	      say <emphasis>no</emphasis> here, since reverting means
	      that the file is reread from disk, <emphasis>causing all
	      your changes since the last save to be
	      lost!</emphasis></para>

	      <para><command>gnuclient</command>'s behavior
	      of silently reloading the changed buffer is probably
	      preferable &mdash; add the following lines to your
	      <filename>.emacs</filename> file to emulate
	      <command>gnuclient</command>'s behavior with
	      <command>emacsclient</command>:</para>

<programlisting>
(defadvice server-visit-files (around save-buffers last activate)
  "Try to emulate gnuclient behavior with emacsclient.
Works only for visiting one buffer at a time."
  (let* ((filen (car (car (ad-get-arg 0))))
         (buf (get-file-buffer filen))
         (this-buf-modified-p nil))
    ;;; the following is copied from server-visit-files, with
    ;;; a modification for the `verify-visited-file-modtime' test
    (if (and buf (set-buffer buf))
        (if (file-exists-p filen)
            ;;; if the file has changed on disk, reload it
            ;;; using `find-file-noselect'
            (if (not (verify-visited-file-modtime buf))
                (progn
                  (find-file-noselect filen)
                  ;;; if user answered `no', reset modtime anyway
                  ;;; so that server-visit-files doesn't realize the
                  ;;; difference:
                  (set -visited-file-modtime)))
          ;;; if file exists no longer, we let server-visit-files
          ;;; deal with that
          t)
      (set buf (find-file-noselect filen)))
    (set this-buf-modified-p (buffer-modified-p buf))
    (set-buffer buf)
    (set-buffer-modified-p nil)
    ad-do-it
    (set-buffer-modified-p this-buf-modified-p)))
</programlisting>
        </listitem>
      </itemizedlist>
      </tip>
    </section>


    <section id="editor-setup-kate">
      <title>&kate;</title> 

      <para>&kde;'s editor &kate; supports inverse search very well.
      No extra setup is required.</para> </section>


    <section id="editor-setup-kile">
      <title><application>Kile</application></title> 

      <para>The LaTeX-editor system <application>Kile</application>,
          supports KDVI very well. No extra setup is
          necessary. Further information about Kile can be found at
          <ulink url="http://kile.sourceforge.net">Kile's
          homepage</ulink>.
          </para>
    </section>


    <section id="editor-setup-nedit">
      <title><application>NEdit</application></title>

      <para><application>NEdit</application> generally works very well
      indeed. Clicking into the &DVI; file should open a new
      window. If the TeX file is already used in another window of
      <application>NEdit</application>, the newly opened window
      displays another view of the buffer. Otherwise, the TeX file is
      loaded. After opening the window,
      <application>NEdit</application> highlights the first line of
      the appropriate paragraph.</para>
      <tip>
          <para>&kdvi; uses the command <command>ncl</command> to
          remote control <application>NEdit</application>. Make sure
          that <command>ncl</command> is available on the command line
          by trying the command <userinput><command>ncl</command>
          <parameter>-noask</parameter></userinput>. This should
          open an instance of the <application>NEdit</application>
          editor. If <command>ncl</command> is not available, you
          might be using an older version of
          <application>NEdit</application>. In that case, you should
          either upgrade to a more recent version, or you have to use
          the option <guilabel>User defined editor</guilabel> from the
          <guilabel>Options</guilabel> dialog.</para>
      </tip>
    </section>

    <section id="editor-setup-xemacs">
      <title><application>XEmacs</application></title>

      <para><application>XEmacs</application> works well with
      &kdvi;. The actual behavior of
      <application>XEmacs</application> depends largely on the
      configuration. As usual, you can customize
      <application>XEmacs</application> completely, if you are willing
      to fight your way through Lisp code.</para>

      <para>&kdvi; uses the program <command>gnuclient</command> to
      remote control <application>XEmacs</application>.</para>
      <important>
        <para>The program <command>gnuclient</command> requires that
        <application>XEmacs</application> is running, and that the
        program <application>gnuserv</application> is started inside
        <application>XEmacs</application>. Inverse search will not
        work unless you have started both
        <application>XEmacs</application> and
        <application>gnuserv</application>.</para>
      </important>

      <para>To start the <application>gnuserv</application> program, you can
      do one of the following:</para>
      <itemizedlist>
        <listitem>
          <para>In <application>XEmacs</application>, start
          <application>gnuserv</application> by typing
<userinput><keycombo action="seq"><keycap>M</keycap><keycap>X</keycap></keycombo>
          <command>gnuserv-start</command></userinput></para>
        </listitem>
        <listitem>
          <para>Add the line 
<programlisting>
(gnuserv-start)
</programlisting>
           to your <filename>.xemacs</filename> file. If you use a
           more recent version of <application>XEmacs</application>,
           <filename class="directory">.xemacs</filename> will be a
           folder. In that case, you should append the line to the
           file <filename>.xemacs/init.el</filename>. Restart
           <application>XEmacs</application></para>
        </listitem>
      </itemizedlist>

      <para>If you don't want to open a new frame for each editor
      call, and want the frame to be auto-raised, set <quote>Gnuserv
      Frame</quote> to <quote>Use selected frame</quote>, and add the
      <function>raise-frame</function> function to <quote>Visit
      Hook</quote>. Do <userinput><keycombo action="seq"><keycap>M</keycap><keycap>x</keycap></keycombo>
      <command>customize-group</command> <keycap>RET</keycap>
      <command>gnuserv</command></userinput> to make these
      settings.</para>

      <tip>
        <itemizedlist>
          <listitem>
              <para>Make sure that <application>XEmacs</application>
              is installed. Try to start <command>xemacs</command>
              from the command line.</para>
          </listitem>
        <listitem>
              <para>&kdvi; uses the command <application>gnuserv</application>
              to remote control
              <application>XEmacs</application>. Make sure that
              <command>gnuclient</command> is available on the command
              line by trying the command
              <userinput><command>gnuclient</command> <parameter>Name
              of a text file</parameter></userinput>. This should open
              a new frame in the <application>XEmacs</application>
              editor.</para>
        </listitem>
        <listitem>
              <para>If <application>gnuserv</application> fails with an error
              message like <computeroutput>unable to connect to
              local</computeroutput>, make sure that
              <application>XEmacs</application> is
              running. Furthermore, make sure that
              <application>gnuserv</application> is started by typing
              <userinput><keycombo action="seq"><keycap>M</keycap><keycap>X</keycap></keycombo>
              <command>gnuserv-start</command></userinput>.</para>
        </listitem>
        <listitem>
              <para>If you don't want to open a new frame for each
              editor call, and want the frame to be auto-raised, set
              <quote>Gnuserv Frame</quote> to <quote>Use selected
              frame</quote>, and add the <quote>raise-frame</quote>
              function to <quote>Visit Hook</quote>. Do
              <userinput><keycombo action="simul"><keycap>M</keycap><keycap>X</keycap></keycombo>
              <command>customize-group</command> <keycap>RET</keycap>
              <command>gnuserv</command></userinput> to make these
              settings.</para>
        </listitem>
      </itemizedlist>
      </tip>
    </section>

    <section id="editor-setup-gvim">
      <title><application>VI iMproved</application> / &GUI;</title>

      <para>The <application>gvim</application> variant of the
      <application>vi</application> editor supports inverse search very well.
      No extra setup is required.</para>
    </section>
    </section>
  </chapter>


  <chapter id="forward-search">
    <title>Forward search</title>

    <para>The forward search functions allow you to jump from your
    editor directly into the associated position of the &DVI;
    file. Since forward search must be supported by your editor, only
    <application>Emacs</application> and
    <application>XEmacs</application> are currently supported. Other
    editors will hopefully join in soon.</para>

    <para>To use forward search, you have to do the following:</para>
    <itemizedlist>
      <listitem>
        <para>Set up your editor &mdash; this is described below.</para>
      </listitem>
      <listitem>
        <para>Add source file information to your &DVI; file, &eg; by
        using the package <command>srcltx</command>.  This has been
        described in the section <link linkend="inverse-search-tex">Producing TeX files for inverse
        search</link>.</para>
      </listitem>
      <listitem>
        <para>If you use <application>Emacs</application> and
        everything is properly set up, you just press
        <userinput><keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo> <keycombo
        action="simul">&Ctrl;<keycap>J</keycap>
        </keycombo></userinput>, and &kdvi; pops up and jumps to the
        place which corresponds to the place of the TeX file which you
        are currently editing.</para>
      </listitem>
    </itemizedlist>

    <section id="forward-search-editor">
      <title>Setting up your editor for forward search</title>
      
      <section id="forw-editor-setup-emacs">
        <title><application>Emacs</application></title>
        
        <para>In order to use forward search in
        <application>Emacs</application>, follow these steps:</para>

        <itemizedlist>
          <listitem>
                <para>Download the following
                <application>Emacs</application> script,
                <ulink url="kdvi-search.el">
                <filename>kdvi-search.el</filename> </ulink> (press
                &Shift; and &LMB; the filename to download) and store
                it in a place where <application>Emacs</application>
                can access it &mdash; we recommend a folder
                <filename class="directory">emacs-scripts</filename>.</para>
          </listitem>
          <listitem>
            <para>Add the lines 
<programlisting>
(add-to-list 'load-path (expand-file-name "~/emacs-scripts/"))
(require 'kdvi-search)
(add-hook 'LaTeX-mode-hook (lambda () (local-set-key "\C-x\C-j" 'kdvi-jump-to-line)))
(add-hook 'tex-mode-hook (lambda () (local-set-key "\C-x\C-j" 'kdvi-jump-to-line)))
</programlisting>
            to your <filename>.emacs</filename> file. Restart
            <application>Emacs</application>.</para>
          </listitem>

          <listitem>
            <para>Open <application>Emacs</application>, load a
            TeX file, produce the corresponding &DVI; file, and either
            enter the command <userinput><keycombo action="simul"><keycap>M</keycap><keycap>x</keycap>
            </keycombo><command>kdvi-jump-to-line</command></userinput>
            or press <userinput><keycombo action="seq"><keycombo
            action="simul">&Ctrl;<keycap>X</keycap></keycombo>
            <keycombo action="simul">&Ctrl;<keycap>J</keycap></keycombo>
            </keycombo></userinput>.
            It may happen that <application>Emacs</application> asks
            you for the name of a <quote>master file</quote>. This is
            useful if you use a TeX file which includes other files:
            the master file is the top-level file which includes the
            others. <application>Emacs</application> will perhaps also
            ask to save the name of the master file <quote>as a local
            variable</quote>, &ie; as a comment at the very end of the
            file. Type either <userinput>yes</userinput> or
            <userinput>no</userinput> to continue.</para> 
            </listitem>
        </itemizedlist>

        <tip>
          <itemizedlist>
            <listitem>
              <para>Make sure that <application>Emacs</application> is
              installed. Try to start <command>emacs</command> from
              the command line.</para>
            </listitem>
            <listitem>
              <para>If <application>Emacs</application> fails to start
              &kdvi;, you can find its output in the Buffer
              <guilabel>kdvi-output</guilabel>.</para>
            </listitem>
          </itemizedlist>
        </tip>
      </section>

      <section id="forw-editor-setup-kile">
        <title><application>Kile</application></title>
                <para>If you use Kile, no further setup is necessary.
                </para>
      </section>

      <section id="forw-editor-setup-xemacs">
        <title><application>XEmacs</application></title>
        
        <para>To set up <application>XEmacs</application>, follow the
        steps for <application>Emacs</application> <link
        linkend="forw-editor-setup-emacs">above</link>, but modify
        your <filename>.xemacs</filename> rather than your
        <filename>.emacs</filename> file. If you use a very recent
        version of <application>XEmacs</application>, <filename
        class="directory">.xemacs</filename> may be a folder. In
        that case, append the lines to
        <filename>.xemacs/init.el</filename>.
        </para>
      </section>

    </section>

  </chapter>

  <chapter id="preferences">
    <title>The <guilabel>Preferences</guilabel> dialog</title>
    <anchor id="opts"></anchor>

    <para>The <guilabel>Preferences</guilabel> dialog can be reached
    by choosing <guimenuitem>DVI Options</guimenuitem> in the
    <guimenu>Settings</guimenu> menu.</para>

    <para>The dialog consists of two tabs, <guilabel>Fonts</guilabel>
    and <guilabel>Rendering</guilabel>.</para>

    <sect1 id="opt-fonts">
      <title><guilabel>Fonts</guilabel> Options</title>

      <para>
       Traditionally, the TeX typsetter uses fonts that are generated
       by the <command>MetaFont</command> program. These fonts are
       stored in the PK format. While a carefully configured
       <command>MetaFont</command> system produces printouts of
       highest quality, its configuration requires serious expertise,
       <command>MetaFont</command> is not very good at producing fonts
       suitable for computer displays, and there are only few
       <command>MetaFont</command> fonts available for Asian
       languages.
      </para>
      
      <para>
       To overcome these problems, newer TeX installations therefore
       include fonts that are stored in the "PostScript Type 1"
       format, which is a widely used font format in electronic
       publishing. &kdvi; is able to use both font formats. 
      </para>

      <para>
       The following picture shows the font options dialog of &kdvi;
       that can be used to control &kdvi;'s use of the various font
       formats.
      </para>

      <screenshot>
        <screeninfo>The <guilabel>Fonts</guilabel> tab</screeninfo>
        <mediaobject>
          <imageobject>
	    <imagedata fileref="optionrequester1.png" format="PNG"></imagedata>
	  </imageobject>
          <textobject>
            <phrase>The <guilabel>Fonts</guilabel> tab</phrase>
          </textobject>
        </mediaobject>        
      </screenshot>

      <variablelist>
        <varlistentry>
          <term><guilabel>Use font hinting for Type 1 fonts, if available</guilabel> </term>
          <listitem>
	   <para>
            PostScript "Type 1" often contain "font hints",
            i.e. additional information that is supposed to
            help software produce better quality output on
            computer screens. The quality of the font hints
            varies from font to font, and you should experiment
            to see if enabling this option gives better results.
           </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>

    <sect1 id="opt-rendering">
      <title><guilabel>&DVI; specials</guilabel> Options</title>

      <para>
       &kdvi; supports a large number of extensions to the original
       &DVI; format, e.g. hyperlinks, graphic file inclusion or
       embedded source file information. These extensions are known as
       "&DVI; specials". A full account of specials supported by
       &kdvi; can be found in <ulink url="KDVI-features.dvi">this
       document</ulink>.
      </para>

      <para>
       The &DVI; specials dialog help you to configure support for
      some specials.  </para>

      <screenshot>
        <screeninfo>The <guilabel>Rendering</guilabel> tab</screeninfo>
        <mediaobject>
          <imageobject>
            <imagedata fileref="optionrequester2.png"
            format="PNG"></imagedata>
	  </imageobject>
          <textobject>
            <phrase>The <guilabel>Rendering</guilabel> tab</phrase>
          </textobject>
        </mediaobject>
      </screenshot>

      <variablelist>
        <varlistentry>
          <term><guilabel>Show PostScript specials</guilabel></term>
          <listitem>
            <para>If this option is checked, &kdvi; will display
            &PostScript; graphics which are embedded into the &DVI;
            file. You probably want to set this option.</para>

            <para>If an external &PostScript; file could not be found,
            &kdvi; will draw a red warning box in its
            place. Unfortunately, rendering &PostScript; graphics is
            very slow in the current version of &kdvi;.  We will
            improve on the speed in later versions. If this option is
            off, &kdvi; will either draw a gray box as a placeholder
            for the graphics, or it will leave the space blank.</para>

            <note>
              <para>There is no standard way to embed &PostScript;
              graphics into a &DVI; file. It may therefore happen that
              &kdvi; cannot properly display a graphic which works
              fine with other programs. Older versions of
              <command>xdvi</command> and <command>dvips</command>
              support the execution of external commands. This is a
              bad security risk and therefore deliberately not
              implemented in &kdvi;. Technical information about
              supported ways to include &PostScript; can be found in
              the document
              <filename>KDVI-features.dvi</filename>.</para>
            </note>

          </listitem>
        </varlistentry>
        
        
        <varlistentry>
          <term><guilabel>Editor for inverse search</guilabel></term>
          <listitem>
            <para>If you intend to use <link linkend="inverse-search">inverse search</link>, a
            very useful feature if you write TeX documents yourself,
            you have to specify which editor you are going to use, and
            how this editor can be started by &kdvi;. In the example
            shown, the user has opted for the
            <application>NEdit</application> editor. If you use one of
            the pre-configured editors from the
            <guilabel>Editor</guilabel> combobox, then you don't have
            to do anything else. If you whish to use a different
            editor, chose <guilabel>User-defined editor</guilabel>
            from the <guilabel>Editor</guilabel> combobox and enter
            the command line which will be used to start your
            editor. Use the placeholders <token>%f</token> and
            <token>%l</token> which will be replaced with the name of
            the TeX file, and the line of the TeX file,
            respectively.</para>

            <para>If you use an editor which is not supported, please
            send us an email at <email>kebekus@kde.org</email> and tell us
            about the command line you use and how you have configured
            your editor.</para>
          </listitem>
        </varlistentry>
      </variablelist>

    </sect1>
  </chapter>

  <chapter id="faq">
    <title>Frequently asked questions</title>

    <qandaset>
      <qandaentry>
        <question id="fontgen">
          <para>What happens when &kdvi; displays the message
          <computeroutput>KDVI is currently generating bitmap
          fonts</computeroutput>, and why does 
          the procedure take so long?</para>
        </question>
        <answer>
          <para>Many of the fonts which are typically used in a TeX
          document must be generated by the MetaFont system. Metafont
          is a language similar to TeX (included in most TeX
          distributions) which takes a description of the font
          outline, and produces a rasterized version (<literal
          role="extension">.pk</literal> file) of the font which can
          then be send to a printer or be used in a previewing program
          like &kdvi;. Metafont goes out of its way to produce the
          best possible output for your printer. For instance, it
          knows that a pixel of an inkjet printer is a roundish blot,
          and that nearby pixels tend to smear into each other. In
          contrast, a pixel on a laser printer is rectangular, but an
          isolated pixel is very often not rendered at all.</para>

          <para>Generating such highly optimized bitmap fonts is
          naturally rather time-consuming, in particular since typical
          TeX documents use a large number of different fonts. We can
          only ask for your patience. To ease the matter somewhat,
          most distributions of TeX store the <literal
          role="extension">.pk</literal> files for a limited time,
          &eg; 100 days. Therefore, if you access the same document
          more than once, the <literal role="extension">.pk</literal>
          files will be reused.</para>
        </answer>
      </qandaentry>

      <qandaentry>
        <question id="mfmodes">
          <para>What is a MetaFont Mode?</para>
        </question>
        <answer>
          <para>In order to produce bitmap fonts which are optimized
          for your printer (see the answer to the first question),
          Metafont comes with a database of printing engines &mdash; look
          for a file called <filename>modes.mf</filename>. A Metafont
          Mode is just the name of a database entry. For example, the
          name <quote>ljfour</quote> refers to the entry in the
          database that describes a &Hewlett-Packard; LaserJet 4
          printer. A MetaFont Mode is usually followed by a number,
          the resolution. The LaserJet, for instance, can print in both
          300 and 600 dots per inch. Thus, <quote>ljfour/600</quote>
          would be a full description.</para>
        </answer>
      </qandaentry>

    </qandaset>
  </chapter>


  <chapter id="credits-and-license">
    <title>Credits and Licenses</title>

    <para>&kdvi;</para>

    <para>&kdvi; is based on based on the stand-alone-program &kdvi;
    0.4.3 by Markku Hihnala. That program is in turn based on
    <application>xdvi</application> version 18f which has many
    authors.</para>

    <para>Documentation is copyright 2001-2004, Stefan Kebekus
    <email>kebekus@kde.org</email></para>

    <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
    
&underGPL;
&underFDL;

  </chapter>
    
&documentation.index;

</book>