Debian Codegraph @

texmf-dist/doc/man/man1/xdvi.1

raw
1 .\" Copyright 1990-2022 Paul Vojta and others
2 .\"
3 .\" This is Paul's license, included here only for reference, it does not apply
4 .\" to all parts of the k version.
5 .\" ----
6 .\" Permission is hereby granted, free of charge, to any person obtaining a copy
7 .\" of this software and associated documentation files (the "Software"), to
8 .\" deal in the Software without restriction, including without limitation the
9 .\" rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 .\" sell copies of the Software, and to permit persons to whom the Software is
11 .\" furnished to do so, subject to the following conditions:
12 .\"
13 .\" The above copyright notice and this permission notice shall be included in
14 .\" all copies or substantial portions of the Software.
15 .\"
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19 .\" PAUL VOJTA OR ANY OTHER AUTHOR OF THIS SOFTWARE BE LIABLE FOR ANY CLAIM,
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22 .\" DEALINGS IN THE SOFTWARE.
23 .\" ----
24 .\" This is the xdvik license:
25 .\" Redistribution and use in source and binary forms, with or without
26 .\" modification, are permitted provided that the following conditions
27 .\" are met:
28 .\" 1. Redistributions of source code must retain the above copyright
29 .\" notice, this list of conditions and the following disclaimer.
30 .\" 2. Redistributions in binary form must reproduce the above copyright
31 .\" notice, this list of conditions and the following disclaimer in the
32 .\" documentation and/or other materials provided with the distribution.
33 .\"
34 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
35 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
36 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
37 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
38 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
39 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
40 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
41 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
42 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
43 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
44 .\" SUCH DAMAGE.
45 .\"
46 .\" following is UGLY ... use La\*(Te\& instead:
47 .\" .if t .ds La L\\h'-0.1667m'\\v'-0.20v'A\\v'0.20v'\\h'-0.1667m'T\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X
48 .\" .if n .ds La LaTeX
49 .if t .ds Te T\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X
50 .if n .ds Te TeX
51 .\" # small and boldface (not all -man's provide it)
52 .de SB
53 \&\fB\s-1\&\\$1 \\$2\s0\fR
54 ..
55 .TH XDVI 1 "2022-02-17" "Xdvik 22.87.06"
56 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
57 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
58 .SH NAME
59 xdvi \- DVI Previewer for the X Window System
60 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
61 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
62 .SH SYNOPSIS
63 .B xdvi
64 .nh
65 [\fB+\fP[\fIpage\fP]]
66 [\fB\--help\fP]
67 [\fB\-allowshell\fP]
68 [\fB\-altfont\fP \fIfont\fP]
69 [\fB\-anchorposition\fP \fIanchor\fP]
70 [\fB\-bg\fP \fIcolor\fP]
71 [\fB\-browser\fP \fIWWWbrowser\fP]
72 [\fB\-copy\fP]
73 [\fB\-cr\fP \fIcolor\fP]
74 [\fB\-debug\fP \fIbitmask\fP|\fIstring[,string ...]\fP]
75 [\fB\-display\fP \fIhost:display\fP]
76 [\fB\-dvipspath\fP \fIpath\fP]
77 [\fB\-editor\fP \fIcommand\fP]
78 [\fB\-expert\fP]
79 [\fB\-expertmode\fP \fIflag\fP]
80 [\fB\-fg\fP \fIcolor\fP]
81 [\fB\-findstring\fP \fIstring\fP]
82 [\fB\-font\fP \fIfont\fP]
83 [\fB\-fullscreen \fP]
84 [\fB\-gamma\fP \fIg\fP]
85 [\fB\-geometry\fP \fIgeometry\fP]
86 [\fB\-gsalpha\fP]
87 [\fB\-gspalette\fP \fIpalette\fP]
88 [\fB\-h\fP]
89 [\fB\-help\fP]
90 [\fB\-hl\fP \fIcolor\fP]
91 [\fB\-hush\fP]
92 [\fB\-hushbell\fP]
93 [\fB\-hushchars\fP]
94 [\fB\-hushchecksums\fP]
95 [\fB\-hushstdout\fP]
96 [\fB\-icongeometry\fP \fIgeometry\fP]
97 [\fB\-iconic\fP]
98 [\fB\-install\fP]
99 [\fB\-interpreter\fP \fIpath\fP]
100 [\fB\-keep\fP]
101 [\fB\-l\fP]
102 [\fB\-license\fP]
103 [\fB\-linkcolor\fP \fIcolor\fP]
104 [\fB\-linkstyle\fP \fI0|1|2|3\fP]
105 [\fB\-margins\fP \fIdimen\fP]
106 [\fB\-mfmode\fP \fImode-def\fP[\fB:\fP\fIdpi\fP]]
107 [\fB\-mgs\fP[\fIn\fP] \fIsize\fP]
108 [\fB\-mousemode\fP \fI0|1|2\fP]
109 [\fB\-nocolor\fP]
110 [\fB\-nofork\fP]
111 [\fB\-noghostscript\fP]
112 [\fB\-nogrey\fP]
113 [\fB\-nogssafer\fP]
114 [\fB\-noinstall\fP]
115 [\fB\-nomakepk\fP]
116 [\fB\-nomatchinverted\fP]
117 [\fB\-noomega\fP]
118 [\fB\-noscan\fP]
119 [\fB\-notempfile\fP]
120 [\fB\-notype1fonts\fP]
121 [\fB\-offsets\fP \fIdimen\fP]
122 [\fB\-p\fP \fIpixels\fP]
123 [\fB\-paper\fP \fIpapertype\fP]
124 [\fB\-pause\fP]
125 [\fB\-pausespecial\fP \fIspecial-string\fP]
126 [\fB\-postscript\fP \fIflag\fP]
127 [\fB\-rulecolor\fP \fIcolor\fP]
128 [\fB\-rv\fP]
129 [\fB\-S\fP \fIdensity\fP]
130 [\fB\-s\fP \fIshrink\fP]
131 [\fB\-safer\fP]
132 [\fB\-sidemargin\fP \fIdimen\fP]
133 [\fB\-sourceposition\fP \fIline\fP[\fB:\fP\fIcol\fP][\ ]\fIfilename\fP]
134 [\fB\-statusline\fP]
135 [\fB\-text-encoding\fP \fIencoding\fP]
136 [\fB\-thorough\fP]
137 [\fB\-topmargin\fP \fIdimen\fP]
138 [\fB\-unique\fP]
139 [\fB\-version\fP]
140 [\fB\-visitedlinkcolor\fP \fIcolor\fP]
141 [\fB\-warnspecials\fP]
142 [\fB\-watchfile\fP \fIsecs\fP]
143 [\fB\-wheelunit\fP \fIpixels\fP]
144 [\fB\-xoffset\fP \fIdimen\fP]
145 [\fB\-yoffset\fP \fIdimen\fP]
146 [\fIdvi_file\fP]
147 .hy
148 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
149 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
150 .SH DESCRIPTION
151 .B Xdvi
152 is a program for previewing
153 .I dvi
154 files, as produced e.g. by the
155 .BR tex (1)
156 program, under the X window system.
157 .PP
158 .B Xdvi
159 can show the file shrunken by various
160 integer factors, and it has a ``magnifying glass'' for viewing
161 parts of the page enlarged (see the section MAGNIFIER below). This version
162 of
163 .B xdvi
164 is also referred to as
165 .B xdvik
166 since it uses the kpathsea library to locate and generate font files.
167 In addition to that, it supports the following features:
168 .RS 2
169 .TP 2
170 -
171 hyperlinks in DVI files (section HYPERLINKS),
172 .TP
173 -
174 direct rendering of PostScript<tm> Type 1 fonts (section TYPE 1 FONTS),
175 .TP
176 -
177 source specials in the DVI file (section SOURCE SPECIALS),
178 .TP
179 -
180 string search in DVI files (section STRING SEARCH),
181 .TP
182 -
183 saving or printing (parts of) the DVI file (sections PRINT DIALOG and SAVE DIALOG).
184 .RE
185 .PP
186 .B Xdvi
187 can be compiled with the Motif toolkit or the Xaw (Athena) toolkit
188 (and variants of it), and the Motif version has a slightly different GUI;
189 these differences are noted below.
190 .PP
191 Before displaying a page of a DVI file,
192 .B xdvi
193 will check to see if the file has changed since the last time it was
194 displayed. If this is the case, it will reload the file. This
195 feature allows you to preview many versions of the same file while
196 running
197 .B xdvi
198 only once. Since it cannot read partial DVI files,
199 .B xdvik
200 versions starting from 22.74.3 will create a temporary copy of the
201 DVI file being viewed, to ensure that the file can be viewed without
202 interruptions. (The
203 .B \-notempfile
204 can be used to turn off this feature).
205 .PP
206 .B Xdvi
207 can show PostScript<tm> specials by any of three methods.
208 It will try first to use Display PostScript<tm>, then NeWS, then it
209 will try to use Ghostscript to render the images. All of these options
210 depend on additional software to work properly; moreover, some of them
211 may not be compiled into this copy of
212 .BR xdvi .
213 .PP
214 For performance reasons,
215 .B xdvi
216 does not render PostScript specials in the magnifying glass.
217 .PP
218 If no file name has been specified on the command line,
219 xdvi will try to open the most recently opened file; if the file
220 history (accessible via the
221 .B File > Open Recent
222 menu) is empty, or if none of the files in the history are valid DVI files,
223 it will pop up a file selector for choosing a file name.
224 (In previous versions, which didn't have a file history, the file selector
225 was always used; you can set the X resource
226 .B noFileArgUseHistory
227 to
228 .I false
229 to get back the old behaviour.)
230 .PP
231 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
232 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
233 .SH OPTIONS
234 In addition to specifying the
235 .I dvi
236 file (with or without the
237 .B .dvi
238 extension),
239 .B xdvi
240 supports the following command line options. If the option begins with a
241 .RB ` + '
242 instead of a
243 .RB ` \- ',
244 the option is restored to its default value. By default, these options can
245 be set via the resource names given in parentheses in the description of
246 each option.
247 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
248 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
249 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
250 .TP
251 .BI + page
252 Specifies the first page to show. If
253 .B +
254 is given without a number, the last page is assumed; the first page is
255 the default.
256 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
257 .TP
258 .B \-allowshell
259 .RB ( .allowShell )
260 This option enables the shell escape in PostScript specials.
261 (For security reasons, shell escapes are disabled by default.)
262 This option should be rarely used; in particular it should not be used just
263 to uncompress files: that function is done automatically if the file name
264 ends in
265 .BR .Z ,
266 .BR .gz ,
267 or
268 .BR .bz2 .
269 Shell escapes are always turned off if the
270 .B \-safer
271 option is used.
272 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
273 .TP
274 .BI \-altfont " font"
275 .RB ( .altFont )
276 Declares a default font to use when the font in the
277 .I dvi
278 file cannot be found. This is useful, for example, with PostScript <tm> fonts.
279 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
280 .TP
281 .BI \-anchorposition " anchor"
282 Jump to
283 .I anchor
284 after opening the DVI file. This is only useful when invoking
285 .B xdvi
286 from other applications.
287 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
288 .TP
289 .BI \-background " color"
290 .RB ( .background )
291 Determines the color of the background. Same as
292 .BR -bg .
293 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
294 .TP
295 .BI \-bg " color"
296 .RB ( .background )
297 Determines the color of the background.
298 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
299 .TP
300 .BI \-browser " browser"
301 .RB ( .wwwBrowser )
302 Defines the web browser used for handling external URLs. The value of this
303 option or resource has the same syntax as the
304 .B BROWSER
305 environment variable; see the explanation of that variable in the
306 section `ENVIRONMENT' below for a detailed description.
307 If neither the option nor the X resource
308 .I wwwBrowser
309 is specified, the environment variables
310 .B BROWSER
311 and
312 .B WWWBROWSER
313 (in that order) are used to determine the browser command. If these are
314 not set either, the following default value is used:
315 \fBxdg-open %s:htmlview %s:firefox -remote -remote "openURL(%s,new-window)":mozilla -remote "openURL(%s,new-window)":netscape -raise -remote "openURL(%s,new-window)":xterm -e w3m %s:xterm -e lynx %s:xterm -e wget %s\fP
316 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
317 .TP
318 .B \-copy
319 .RB ( .copy )
320 Always use the
321 .I copy
322 operation when writing characters to the display.
323 This option may be necessary for correct operation on a color display, but
324 overstrike characters will be incorrect.
325 If greyscale anti-aliasing is in use, the
326 .B \-copy
327 operation will disable the use of colorplanes and make overstrikes come
328 out incorrectly.
329 See also
330 .BR \-thorough .
331 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
332 .TP
333 .BI \-cr " color"
334 .RB ( .cursorColor )
335 Determines the color of the mouse cursor. The default is the same as
336 the foreground color.
337 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
338 .TP
339 .BI \-debug " bitmask|string[,string ...]"
340 .RB ( .debugLevel )
341 If nonzero, prints additional information on standard output. The
342 argument can be either a bitmask specified as a decimal number, or
343 comma-separated list of strings.
344 .br
345 For the bitmask representation, multiple values can
346 be specified by adding the numbers that represent the individual bits;
347 e.g. to debug all file searching and opening commands, use 4032
348 (= 2048 + 1024 + 512 + 256 + 128 + 64). Use -1 to turn on debugging
349 of everything (this will produce huge output).
350 .br
351 For the string representation, use the strings listed in the following
352 table, with a comma to separate the values; e.g. to debug
353 all file searching and opening commands, use
354 .BR search,expand,paths,hash,stat,open .
355 (The option `kpathsea' is provided as a shorthand for these.)
356 Note that such a list may need to be quoted to prevent the shell
357 from interpreting commas or spaces in the list.
358 .br
359 The individual numbers and strings have the following meanings:
360 .nf
361 .sp 1n
362 .ta 1L +8L +12L
363 1 bitmap Bitmap creation
364 2 dvi DVI translation
365 4 pk PK fonts
366 8 batch Batch mode: Exit after
367 reading the DVI file
368 16 event Event handling
369 32 ps PostScript interpreter calls
370 64 stat Kpathsea stat(2) calls
371 128 hash Kpathsea hash table lookups
372 256 open Kpathsea file opening
373 512 paths Kpathsea path definitions
374 1024 expand Kpathsea path expansion
375 2048 search Kpathsea searching
376 4032 kpathsea All Kpathsea options
377 4096 htex Hypertex specials
378 8192 src Source specials
379 16384 client Client/server mode (see -unique
380 and -sourceposition options)
381 32768 ft FreeType library messages (Type 1 fonts)
382 65536 ft_verbose Verbose FreeType library messages (currently unused)
383 131072 gui GUI elements
384 262144 find Searching for strings in the DVI file
385 524288 files File history and opening DVI files
386 .sp 1n
387 .fi
388 Some of the Kpathsea debugging options are actually provided by Kpathsea;
389 see the Debugging section in the Kpathsea manual for more information on
390 these.
391 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
392 .TP
393 .BI \-density " density"
394 .RB ( .densityPercent )
395 Determines the density used when shrinking bitmaps for fonts.
396 A higher value produces a lighter font. The default value is 40.
397 If greyscaling is in use, this argument does not apply; use
398 .B \-gamma
399 instead.
400 See also the
401 .RB ` S '
402 keystroke.
403 Same as
404 .BR \-S .
405 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
406 .TP
407 .BI \-display " host" : display
408 Specifies the host and screen to be used for displaying the
409 .I dvi
410 file. By default this is obtained from the environment variable
411 .SB DISPLAY.
412 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
413 .TP
414 .BI \-dvipspath " path"
415 .RB ( .dvipsPath )
416 Use
417 .I path
418 as the
419 .B dvips
420 program to use when printing. The default for this is
421 .BR dvips .
422 The program or script should read the DVI file from standard input,
423 and write the PostScript file to standard output.
424 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
425 .TP
426 .BI \-editor " editor"
427 .RB ( .editor )
428 Specifies the editor that will be invoked when the
429 .I source-special()
430 action is triggered to start a reverse search (by default via Ctrl-Mouse 1).
431 The argument to this option is a format string in which occurrences of
432 .RB `` %f ''
433 are replaced by the file name, occurrences of
434 .RB `` %l ''
435 are replaced by the line number within the file, and optional
436 occurrences of
437 .RB `` %c ''
438 are replaced by the column number within the line.
439 .sp
440 If neither the option nor the X resource
441 .I .editor
442 is specified, the following environment variables are checked
443 to determine the editor command:
444 .BR XEDITOR ,
445 .BR VISUAL ,
446 and
447 .B EDITOR
448 (in this sequence). If the string is found as the value
449 of the
450 .SB VISUAL
451 or
452 .SB EDITOR
453 environment variables, then
454 .RI `` "xterm -e "''
455 is prepended to the string; if the editor is specified by other means, then
456 it must be in the form of a shell command to pop up an X window with an
457 editor in it. If none of these variables is set, a warning message is displayed
458 and the command
459 .RI `` "xterm -e vi +%l %f"''
460 is used.
461 .sp
462 If no
463 .RB `` %f ''
464 or
465 .RB `` %l ''
466 occurs in the string, the missing format strings are appended automatically.
467 (This is for compatibility with other programs when using one of the environment
468 variables).
469 .sp
470 A new instance of the editor is started each time this command is used;
471 therefore it is preferable to use an editor that can be invoked in
472 `client' mode to load new files into the same instance. Example
473 settings are:
474 .RS 7
475 .TP 7
476 .SB emacsclient --no-wait
477 (older Emacsen)
478 .TP
479 .SB gnuclient -q
480 (XEmacs and newer Emacsen)
481 .TP
482 .SB gvim --servername xdvi --remote
483 (VIM v6.0+; the `--servername xdvi' option will cause gvim to run a
484 dedicated instance for the files opened by xdvi.)
485 .TP
486 .SB nc
487 (nedit)
488 .PP
489 .sp
490 Note that those strings need to be enclosed
491 into quotes when using them on the command-line
492 to protect them from the shell; when using them
493 as argument for the
494 .I .editor
495 resource in an X resource file, no quotes should be used.
496 .sp
497 .B NOTE ON SECURITY:
498 The argument of this option isn't executed as a shell command,
499 but via
500 .I exec()
501 to prevent evil tricks with the contents of source specials.
502 .RE
503 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
504 .TP
505 .B \-expert
506 This option is only supported for backwards compatibility;
507 it is equivalent to
508 .BR "\-expertmode 0" ,
509 which should be preferred.
510 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
511 .TP
512 .BI \-expertmode " flag"
513 .RB ( .expertMode )
514 With an argument of
515 .IR 0 ,
516 this option switches off the display of the buttons, scrollbars,
517 the toolbar (Motif only),
518 the statusline and the page list. These GUI elements
519 can also be (de)activated separately, by combining the
520 appropriate values in the
521 .I flag
522 argument. This acts similar to the
523 .B \-debug
524 option: The integer
525 .I flag
526 is treated as a bitmap where each bit represents one
527 element. If the bit has the value
528 .IR 1 ,
529 the element is switched on, if it has the value
530 .IR 0 ,
531 the element is switched off. The meaning of the bits
532 is as follows:
533 .nf
534 .sp 1n
535 .ta 1L +8L +12L
536 1 statusline
537 2 scrollbars
538 4 Motif: pagelist, Xaw: buttons and pagelist
539 8 toolbar (Motif only)
540 16 menubar (Motif only)
541 .sp 1n
542 .fi
543 For example, to turn on only the statusline and the scrollbars,
544 use 3 (= 1 + 2).
545 See also the
546 .RB ` x '
547 keystroke, where the bits are addressed by their positions, from 1 to
548 3 (Xaw) or 5 (Motif), respectively.
549 .PP
550 If the statusline is not active, all messages
551 that would normally be printed to the statusline will be printed to
552 .IR stdout ,
553 unless the
554 .B \-hushstdout
555 option is used.
556 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
557 .TP
558 .BI \-fg " color"
559 .RB ( .foreground )
560 Determines the color of the text (foreground).
561 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
562 .TP
563 .B \-findstring\fP \fIstring\fP
564 This option triggers a search for
565 .I string
566 in the DVI file mentioned on the command-line, similar to forward search
567 (see the description of the
568 .B sourceposition
569 option):
570 If there is already another
571 instance of
572 .B xdvi
573 running on the displaying that DVI file, it will cause that instance
574 to perform the search instead. The search starts at the top of the current
575 page of the DVI file.
576 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
577 .TP
578 .BI \-font " font"
579 .RB ( *font )
580 Sets the font used in menus, buttons etc., as described in the
581 .I X(7x)
582 man page. The font for child windows can be set separately,
583 e.g.:
584 .RS 7
585 .nf
586 .ft 3
587 .sp 1n
588 xdvi*statusline*font: \e
589 -*-helvetica-medium-r-*-*-12-*-*-*-*-*-*-*
590 .sp 1n
591 .ft
592 .fi
593 .RE
594 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
595 .TP
596 .BI \-foreground " color"
597 Same as
598 .BR -fg .
599 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
600 .TP
601 .B \-fullscreen
602 When this option is used, xdvi will (try to) run in fullscreen mode, with
603 no window decorations.
604 This option is not guaranteed to work with all windowmanagers/desktops;
605 if you're experiencing problems with it, please use the
606 .B \-geometry
607 option instead, and a suitable window manager setting to remove
608 the window decorations.
609 When using this option for presentations, you might want
610 to get rid of all the control widgets as well, using the
611 .B -expertmode
612 option. This option can also be toggled at runtime using the
613 .B fullscreen
614 action (by default bound to Ctrl-l).
615 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
616 .TP
617 .BI \-gamma " gamma"
618 .RB ( .gamma )
619 Controls the interpolation of colors in the greyscale anti-aliasing color
620 palette. Default value is 1.0. For 0 <
621 .I gamma
622 < 1, the fonts will be lighter (more like the background), and for
623 .I gamma
624 > 1, the fonts will be darker (more like the foreground). Negative
625 values behave the same way, but use a slightly different algorithm.
626 For color and grayscale displays; for monochrome, see
627 .BR \-density .
628 See also the
629 .RB ` S '
630 keystroke.
631 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
632 .TP
633 .BI \-geometry " geometry"
634 .RB ( .geometry )
635 Specifies the initial geometry of the main window,
636 as described in the
637 .I X(7x)
638 man page. The geometry of child windows can be set
639 separately, e.g.:
640 .br
641 .I xdvi*helpwindow.geometry: 600x800
642 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
643 .TP
644 .B \-gsalpha
645 .RB ( .gsAlpha )
646 Causes
647 .B Ghostscript
648 to be called with the
649 .B x11alpha
650 driver instead of the
651 .B x11
652 driver. The
653 .B x11alpha
654 driver enables anti-aliasing in PostScript specials, for a nicer appearance.
655 It is available on newer versions of
656 .BR Ghostscript .
657 This option can also be toggled with the
658 .RB ` V '
659 keystroke.
660 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
661 .TP
662 .BI \-gspalette " palette"
663 .RB ( .palette )
664 Specifies the palette to be used when using Ghostscript for rendering
665 PostScript specials. Possible values are
666 .BR Color ,
667 .BR Greyscale ,
668 and
669 .BR Monochrome .
670 The default is
671 .BR Color .
672 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
673 .TP
674 .BR \-h , " \-help" , " \--help"
675 Prints a short help text with an overview of the command-line options
676 to standard output.
677 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
678 .TP
679 .BI \-hl " color"
680 .RB ( .highlight )
681 Determines the color of the page border, of the ruler in `ruler mode',
682 and of the highlighting markers in forward search and string search.
683 The default is the foreground color.
684 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
685 .TP
686 .B \-hush
687 .RB ( .Hush )
688 Causes
689 .B xdvi
690 to suppress all suppressible warnings.
691 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
692 .TP
693 .B \-hushbell
694 .RB ( .hushBell )
695 Don't sound the X bell when an error occurs.
696 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
697 .TP
698 .B \-hushchars
699 .RB ( .hushLostChars )
700 Causes
701 .B xdvi
702 to suppress warnings about references to characters which are not defined
703 in the font.
704 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
705 .TP
706 .B \-hushchecksums
707 .RB ( .hushChecksums )
708 Causes
709 .B xdvi
710 to suppress warnings about checksum mismatches between the
711 .I dvi
712 file and the font file.
713 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
714 .TP
715 .B \-hushstdout
716 .RB ( .hushStdout )
717 Suppresses printing of status messages to
718 .IR stdout .
719 Note that errors or warnings will still be printed to
720 .I stderr
721 even if this option is used.
722 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
723 .TP
724 .BI \-icongeometry " geometry"
725 .RB ( .iconGeometry )
726 Specifies the initial position for the icon.
727 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
728 .TP
729 .B \-iconic
730 .RB ( .iconic )
731 Causes the
732 .B xdvi
733 window to start in the iconic state. The default is to start with the
734 window open.
735 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
736 .TP
737 .B \-install
738 .RB ( .install )
739 If
740 .B xdvi
741 is running under a
742 .B PseudoColor
743 visual, then (by default) it will check for
744 .B TrueColor
745 visuals with more bits per pixel, and switch to such a visual if one exists.
746 If no such visual exists, it will use the current visual and colormap. If
747 .B \-install
748 is selected, however, it will still use a
749 .B TrueColor
750 visual with a greater depth, if one is available; otherwise, it will
751 install its own colormap on the current visual. If the current visual is not
752 .BR PseudoColor ,
753 then
754 .B xdvi
755 will not switch the visual or colormap, regardless of its options.
756 The default value of the
757 .B install
758 resource is the special value,
759 .BR maybe .
760 There is no
761 .B +install
762 option. See also
763 .BR \-noinstall ,
764 and the GREYSCALING AND COLORMAPS section.
765 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
766 .TP
767 .BI \-interpreter " filename"
768 .RB ( .interpreter )
769 Use
770 .I filename
771 as the Ghostscript interpreter. By default it uses
772 .BR gs .
773 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
774 .TP
775 .B \-keep
776 .RB ( .keepPosition )
777 Sets a flag to indicate that
778 .B xdvi
779 should not move to the home position when moving to a new page. See also the
780 .RB ` k '
781 keystroke. This flag is honored by all page switching actions and by
782 .B up-or-previous() /
783 .BR down-or-next() ,
784 although the latter only honor the horizontal position, not the vertical one.
785 This allows for a "continuous" scrolling back an forth through a document with
786 a display window narrower than a page width.
787 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
788 .TP
789 .B \-l
790 .RB ( .listFonts )
791 List the names of all fonts used.
792 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
793 .TP
794 .B \-license
795 Prints licensing information.
796 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
797 .TP
798 .B \-linkcolor
799 .RB ( .linkColor )
800 Color used for unvisited hyperlinks (`Blue2' by default). Hyperlinks
801 are unvisited before you click on them, or after the DVI file has been reloaded.
802 The value should be either a valid X color name (such as
803 .IR DarkGoldenrod4 )
804 or a hexadecimal color string (such as
805 .IR #8b6508 ).
806 See also
807 .B \-visitedlinkcolor
808 and
809 .BR \-linkstyle .
810 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
811 .TP
812 .B \-linkstyle
813 .RB ( .LinkStyle )
814 Determines the style in which hyperlinks are displayed. Possible
815 values and their meanings are:
816 .nf
817 .sp 1n
818 .ta 1L +8L
819 0 No highlighting of links
820 1 Underline links with \fIlink color\fR
821 2 No underlining, color text with \fIlink color\fR
822 3 Underline and display text colored with
823 \fIlink color\fR
824 .sp 1n
825 .fi
826 The values for \fIlink color\fR are specified by the options/resources
827 .B \-linkcolor
828 and
829 .B \-visitedlinkcolor
830 (which see).
831 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
832 .TP
833 .BI \-margins " dimen"
834 .RB ( .Margin )
835 Specifies the size of both the top margin and side margin.
836 This determines the ``home'' position of the page within the window as
837 follows. If the entire page fits in the window, then the margin settings
838 are ignored. If, even after removing the margins from the left, right,
839 top, and bottom, the page still cannot fit in the window, then the page
840 is put in the window such that the top and left margins are hidden, and
841 presumably the upper left-hand corner of the text on the page will be
842 in the upper left-hand corner of the window.
843 Otherwise, the text is centered in the window.
844 The dimension should be a decimal number optionally followed by
845 any of the two-letter abbreviations for units accepted by \*(Te\&
846 .RB ( pt ,
847 .BR pc ,
848 .BR in ,
849 .BR bp ,
850 .BR cm ,
851 .BR mm ,
852 .BR dd ,
853 .BR cc ,
854 or
855 .BR sp ).
856 By default, the unit will be
857 .BR cm " (centimeters)".
858 See also
859 .BR \-sidemargin ", " \-topmargin ,
860 and the keystroke
861 .RB ` M .'
862 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
863 .TP
864 .BI \-mfmode " mode-def"
865 .RB ( .mfMode )
866 Specifies a
867 .I mode-def
868 string, which can be used in searching for fonts (see ENVIRONMENT, below).
869 Generally, when changing the
870 .IR mode-def ,
871 it is also necessary to change the font size to the appropriate value
872 for that mode. This is done by adding a colon and the value in dots per inch;
873 for example,
874 .BR "\-mfmode ljfour:600" .
875 This method overrides any value given by the
876 .B pixelsPerInch
877 resource or the
878 .B \-p
879 command-line argument.
880 The metafont mode is also passed to
881 .B metafont
882 during automatic creation of fonts.
883 By default, it is
884 .BR "unspecified" .
885 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
886 .TP
887 .BI \-mgs " size"
888 Same as
889 .BR \-mgs1 .
890 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
891 .TP
892 .BI \-mgs[ n ] " size"
893 .RB ( .magnifierSize\fR[\fIn\fR] )
894 Specifies the size of the window to be used for the ``magnifying glass''
895 for Button
896 .IR n .
897 The size may be given as an integer (indicating that the magnifying glass
898 is to be square), or it may be given in the form
899 .IR width x height .
900 See the MOUSE ACTIONS section. Defaults are 200x150, 400x250, 700x500,
901 1000x800, and 1200x1200.
902 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
903 .TP
904 .BI \-mousemode " " [ 0 | 1 | 2 ]
905 .RB ( .mouseMode )
906 Specifies the default mode of xdvi at startup: Magnifier (0), Text Selection Mode (1)
907 or Ruler Mode (2). See the section
908 .BR MODES ,
909 below, for more information.
910 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
911 .TP
912 .B \-nocolor
913 .RB ( .color )
914 Turns off the use of color specials. This option can be toggled with the
915 .RB ` C '
916 keystroke.
917 (Note:
918 .B \-nocolor
919 corresponds to
920 .BR color:off ;
921 .B +nocolor
922 to
923 .BR color:on .)
924 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
925 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
926 .TP
927 .B \-nofork
928 .RB ( .fork )
929 With the
930 .B \-sourceposition
931 and
932 .B \-unique
933 options, the default behavior is for
934 .B xdvi
935 to put itself into the background (like a daemon) if there
936 is no appropriate instance of
937 .B xdvi
938 already running.
939 This argument makes it run in the foreground instead. This is useful
940 for debugging, or if your client application cannot deal well with
941 a program self-backgrounding itself in this way -- e.g. the IPC functions
942 in
943 .B emacs
944 are known to have problems with this.
945 If no
946 .B \-sourceposition
947 or
948 .B \-unique
949 argument is given, then this option has no effect.
950 (Note:
951 .B \-nofork
952 corresponds to
953 .BR fork:off ;
954 .B +nofork
955 to
956 .BR fork:on .)
957 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
958 .TP
959 .B \-noghostscript
960 .RB ( .ghostscript )
961 Inhibits the use of Ghostscript for displaying PostScript<tm> specials.
962 (Note:
963 .B \-noghostscript
964 corresponds to
965 .BR ghostscript:off ;
966 .B +noghostscript
967 to
968 .BR ghostscript:on .)
969 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
970 .TP
971 .B \-nogrey
972 .RB ( .grey )
973 Turns off the use of greyscale anti-aliasing when printing shrunken bitmaps.
974 (Note:
975 .B \-nogrey
976 corresponds to
977 .BR grey:off ;
978 .B +nogrey
979 to
980 .BR grey:on .)
981 See also the
982 .RB ` G '
983 keystroke.
984 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
985 .TP
986 .B \-nogssafer
987 .RB ( .gsSafer )
988 Normally, if Ghostscript is used to render PostScript specials, the Ghostscript
989 interpreter is run with the option
990 .BR \-dSAFER .
991 The
992 .B \-nogssafer
993 option runs Ghostscript without
994 .BR \-dSAFER .
995 The
996 .B \-dSAFER
997 option in Ghostscript disables PostScript operators such as
998 .BR deletefile ,
999 to prevent possibly malicious PostScript programs from having any effect.
1000 If the
1001 .B \-safer
1002 option is specified, then this option has no effect; in that case Ghostscript
1003 is always run with
1004 .BR \-dSAFER .
1005 (Note:
1006 .B \-nogssafer
1007 corresponds to
1008 .BR gsSafer:off ;
1009 .B +nogssafer
1010 to
1011 .BR gsSafer:on .)
1012 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1013 .TP
1014 .B \-noinstall
1015 .RB ( .install )
1016 Inhibit the default behavior of switching to a
1017 .B TrueColor
1018 visual if one is available with more bits per pixel than the current visual.
1019 (Note:
1020 \-noinstall
1021 corresponds
1022 .BR install:off ;
1023 there is no
1024 .B +noinstall
1025 option.)
1026 See also
1027 .BR \-install ,
1028 and the GREYSCALING AND COLORMAPS section.
1029 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1030 .TP
1031 .B \-nomakepk
1032 .RB ( .makePk )
1033 Turns off automatic generation of font files that cannot be found by other
1034 means.
1035 (Note:
1036 .B \-nomakepk
1037 corresponds to
1038 .BR makePk:off ;
1039 .B +nomakepk
1040 to
1041 .BR makePK:on .)
1042 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1043 .TP
1044 .B \-nomatchinverted
1045 .RB ( .matchInverted )
1046 Don't highlight string search matches in inverted color; instead, draw a rectangle in
1047 .I highlight
1048 color (see the
1049 .B \-hl
1050 option) around the match. This option is activated automatically if
1051 the display isn't running in TrueColor.
1052 (Note:
1053 .B \-nomatchinverted
1054 corresponds to
1055 .BR matchInverted:off ;
1056 .B +nomatchinverted
1057 to
1058 .BR matchInverted:on .)
1059 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1060 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1061 .TP
1062 .B \-noomega
1063 .RB ( .omega )
1064 This will disable the use of Omega extensions when interpreting DVI files.
1065 By default, the additional opcodes
1066 .I 129
1067 and
1068 .I 134
1069 are recognized by xdvi as Omega extensions and interpreted as requests
1070 to set 2-byte characters. The only drawback is that the virtual font
1071 array will require 65536 positions instead of the default 256 positions,
1072 i.e. the memory requirements of xdvi will be slightly larger. If you find
1073 this unacceptable or encounter another problem with the Omega extensions,
1074 you can switch this extension off by using
1075 .B \-noomega
1076 (but please do send a bug report if you find such problems - see the bug
1077 address in the
1078 .B AUTHORS
1079 section below).
1080 .br
1081 (Note:
1082 .B \-noomega
1083 corresponds to
1084 .BR "omega: off" ;
1085 .B +noomega
1086 to
1087 .BR "omega: on" .)
1088 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1089 .TP
1090 .B \-noscan
1091 .RB ( .prescan )
1092 By default,
1093 .B xdvi
1094 does a preliminary scan of the
1095 .I dvi
1096 file to process any
1097 .B papersize
1098 specials; this is especially important at startup since the paper size may be
1099 needed to determine the window size.
1100 If PostScript<tm> is in use, then prescanning is also necessary in order to
1101 properly process header files.
1102 In addition, prescanning is needed to correctly determine the background color
1103 of a page.
1104 This option turns off such prescanning.
1105 (Prescanning will be automatically be turned back on if
1106 .B xdvi
1107 detects any of the specials mentioned above.)
1108 (Note:
1109 .B \-noscan
1110 corresponds to
1111 .BR prescan:off ;
1112 .B +noscan
1113 to
1114 .BR prescan:on .)
1115 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1116 .TP
1117 .B \-notempfile
1118 .RB ( .tempFile )
1119 As mentioned in the section
1120 .B DESCRIPTION
1121 above, xdvi will create a temporary copy of the DVI file so that it
1122 can be accessed without interruptions even while the file is being
1123 rewritten by
1124 .BR TeX .
1125 Since this introduces the overhead of copying the file every time
1126 it has changed, the
1127 .B \-notempfile
1128 allows you to turn off this behaviour. In this case, exposing parts of the
1129 window while the DVI file is being written by \*(Te\& will erase the current
1130 window contents until the DVI file can be completely reread.
1131 .br
1132 (Note:
1133 .B \-notempfile
1134 corresponds to
1135 .BR tempFile:off ;
1136 .B +notempfile
1137 to
1138 .BR tempFile:on .)
1139 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1140 .TP
1141 .B \-notype1fonts
1142 .RB ( .type1 )
1143 This will disable the use of the FreeType library to display PostScript<tm>
1144 Type 1 fonts.
1145 Use this option as a workaround when you encounter problems with the
1146 display of Type 1 fonts (but please don't forget to send a bug report in
1147 this case, to the URL mentioned in the section AUTHORS below).
1148 .br
1149 (Note:
1150 .B \-notype1fonts
1151 corresponds to
1152 .BR type1:off ;
1153 .B +notype1fonts
1154 to
1155 .BR type1:on .)
1156 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1157 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1158 .TP
1159 .BI \-offsets " dimen"
1160 .RB ( .Offset )
1161 Specifies the size of both the horizontal and vertical offsets of the
1162 output on the page. By decree of the Stanford \*(Te\& Project,
1163 the default \*(Te\& page origin is always 1 inch over and down from
1164 the top-left page corner, even when non-American paper sizes are used.
1165 Therefore, the default offsets are 1.0 inch.
1166 The argument
1167 .I dimen
1168 should be a decimal number optionally followed by any of the two-letter
1169 abbreviations for units accepted by \*(Te\&
1170 .RB ( pt ,
1171 .BR pc ,
1172 .BR in ,
1173 .BR bp ,
1174 .BR cm ,
1175 .BR mm ,
1176 .BR dd ,
1177 .BR cc ,
1178 or
1179 .BR sp ).
1180 By default, the unit will be
1181 .BR cm " (centimeters)".
1182 See also
1183 .B \-xoffset
1184 and
1185 .BR \-yoffset .
1186 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1187 .TP
1188 .BI \-p " pixels"
1189 .RB ( .pixelsPerInch )
1190 Defines the size of the fonts to use, in pixels per inch. The
1191 default value is 600. This option is provided only for backwards
1192 compatibility; the preferred way is to set both the resolution
1193 and the Metafont mode via the
1194 .B \-mfmode
1195 option (which see).
1196 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1197 .TP
1198 .BI \-paper " papertype"
1199 .RB ( .paper )
1200 Specifies the size of the printed page. Note that in most cases it's
1201 best to specify the paper size in the TeX input file via the line
1202 .sp
1203 .B \eusepackage[dvips]{geometry}
1204 .sp
1205 which will be recognized by both dvips and xdvi; in that case the
1206 use of a `-paper' option should be unnecessary.
1207 .br
1208 The paper size may be specified in the form
1209 \fIwidth\fBx\fIheight\fR optionally followed by a unit, where
1210 .I width
1211 and
1212 .I height
1213 are decimal numbers giving the width and height of the paper, respectively,
1214 and the unit is any of the two-letter abbreviations for units accepted
1215 by \*(Te\&
1216 .RB ( pt ,
1217 .BR pc ,
1218 .BR in ,
1219 .BR bp ,
1220 .BR cm ,
1221 .BR mm ,
1222 .BR dd ,
1223 .BR cc ,
1224 or
1225 .BR sp ).
1226 By default, the unit is
1227 .BR cm " (centimeters)"\fR.
1228 .br
1229 There are also synonyms which may be used:
1230 .B us
1231 (8.5x11in),
1232 .B legal
1233 (8.5x14in),
1234 .B foolscap
1235 (13.5x17in),
1236 as well as the ISO sizes
1237 .BR a1 - a7 ,
1238 .BR b1 - b7 ,
1239 .BR c1 - c7 .
1240 Each of these also has a landscape or `rotated' variant:
1241 .B usr
1242 (11x8.5in),
1243 .BR a1r - a7r ,
1244 etc. For compatibility with
1245 .BR dvips ,
1246 the formats
1247 .B letter
1248 (8.5x11in),
1249 .B ledger
1250 (17x11in)
1251 and
1252 .B tabloid
1253 (11x17in)
1254 are also supported (these don't have rotated variants).
1255 .br
1256 Any of the above sizes may be preceded by a plus sign
1257 .RB (` + ');
1258 this causes the paper size given here to override any paper size given in the
1259 .I dvi
1260 file. The default paper size is 21 x 29.7 cm (A4 size).
1261 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1262 .TP
1263 .B \-pause
1264 .RB ( .pause )
1265 This option provides a simple implementation of incremental
1266 (stepwise) display, which can be used for presentations.
1267 When this option is used,
1268 .B xdvi
1269 will pause the display of the current page whenever it encounters a
1270 special
1271 .I special-string
1272 .RI ( xdvi:pause
1273 by default; the string can be customized via
1274 .IR \-pausespecial ,
1275 see below), and the cursor will change its shape. The action
1276 .B unpause-or-next()
1277 (by default bound to the
1278 .B Space
1279 key) will display the next portion of the page up to the following
1280 .IR special-string ,
1281 or until the end of the page is reached.
1282 When the option is not used, specials containing
1283 .I special-string
1284 will be ignored.
1285 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1286 .TP
1287 .BI \-pausespecial " special-string"
1288 .RB ( .pauseSpecial )
1289 Sets the special string that causes xdvi to pause when the
1290 .I -pause
1291 option is active. The default value of
1292 .I special-string
1293 is
1294 .IR xdvi:pause .
1295 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1296 .TP
1297 .BI \-postscript " flag"
1298 .RB ( .postscript )
1299 If
1300 .I flag = 0,
1301 rendering of PostScript<tm> specials is disabled; instead, bounding
1302 boxes will be displayed (if available). A value of
1303 .I 1
1304 (the default) switches PostScript<tm> specials on. With a value of
1305 .IR 2 ,
1306 the PostScript<tm> specials are displayed along with their
1307 bounding boxes; this allows you to visually check the correctness
1308 of the bounding boxes. The values can also be toggled at runtime
1309 with the
1310 .RB ` v '
1311 keystroke and the corresponding numerical prefix arguments 0, 1 and 2.
1312 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1313 .TP
1314 .BI \-ps2pdfpath " path"
1315 .RB ( .ps2pdfPath )
1316 Use
1317 .I path
1318 as a conversion program from PostScript to PDF. The program or script
1319 should accept two command-line arguments: The PostScript file as first
1320 argument, and the PDF output file as second argument.
1321 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1322 .TP
1323 .BI \-rulecolor " color"
1324 .RB ( .ruleColor )
1325 Determines the color of the rules used for the magnifier
1326 (default: foreground color).
1327 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1328 .TP
1329 .B \-q
1330 .RB ( .noInitFile )
1331 Ignore the
1332 .I $HOME/.xdvirc
1333 startup file (i.e. don't read it at startup, and don't write it
1334 at exit). This forces the defaults defined in
1335 .I $HOME/.Xdefaults
1336 to be used. See
1337 .B FILES
1338 for more information on
1339 .IR $HOME/.xdvirc .
1340 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1341 .TP
1342 .B \-rv
1343 .RB ( .reverseVideo )
1344 Causes the page to be displayed with white characters on a black background,
1345 instead of vice versa.
1346 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1347 .TP
1348 .BI \-S " density"
1349 .RB ( .densityPercent )
1350 Same as
1351 .B \-density
1352 (which see).
1353 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1354 .TP
1355 .BI \-s " shrink"
1356 .RB ( .shrinkFactor )
1357 Defines the initial shrink factor. The default value is 8. If
1358 .I shrink
1359 is given as 0, then the initial shrink factor is computed so that the
1360 page fits within the window (as if the `s' keystroke were given without
1361 a number).
1362 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1363 .TP
1364 .B \-safer
1365 .RB ( .safer )
1366 This option turns on all available security options; it is designed for use when
1367 .B xdvi
1368 is called by a browser that obtains a
1369 .I dvi
1370 or \*(Te\& file from another site.
1371 This option selects
1372 .B +nogssafer
1373 and
1374 .BR +allowshell .
1375 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1376 .TP
1377 .BI \-sidemargin " dimen"
1378 .RB ( .sideMargin )
1379 Specifies the side margin (see
1380 .BR \-margins ).
1381 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1382 .TP
1383 .BI \-sourceposition " line" [: col "][ ]" filename
1384 This option makes
1385 .B xdvi
1386 search in the
1387 .I dvi
1388 file for the place corresponding to the indicated line (and, optionally,
1389 column) in the .tex source file, and highlight the place found by drawing a
1390 rectangle in the
1391 .I highlight
1392 color (see the
1393 .B \-hl
1394 option) around the corresponding text. In addition, when run with this
1395 argument (and the
1396 .B \-nofork
1397 option is not given, which see),
1398 .B xdvi
1399 will always return immediately: if it finds another instance of
1400 .B xdvi
1401 already showing
1402 .I dvi_file,
1403 then it will cause that instance to raise its window and move to the given
1404 place in the
1405 .I dvi
1406 file; otherwise it will start up its own instance in the background.
1407 If several instances of xdvi are displaying the respective
1408 .I dvi
1409 file, the instance which was last raised to the foreground will be used.
1410 .sp
1411 The space before
1412 .I filename
1413 is only needed if the filename starts
1414 with a digit. When the space is used, the argument
1415 needs to be enclosed in quotes to prevent the shell from
1416 misinterpreting the space as argument separator.
1417 .sp
1418 This option requires that
1419 .I dvi_file
1420 be prepared with source special information. See the section on SOURCE SPECIALS
1421 for details on how to do this.
1422 .sp
1423 Here is a more detailed description of how the filename in the
1424 .I \-sourceposition
1425 argument is matched with the filename in the source specials:
1426 .RS 7
1427 .TP 3
1428 1.
1429 If neither of the filenames contains a path name component, the filenames
1430 are compared ignoring the
1431 .RI ` .tex '
1432 extensions in both filenames.
1433 .TP
1434 2.
1435 Otherwise, if one of the filenames does contain a path component (e.g.:
1436 .IR ./test.tex ,
1437 .IR ../test.tex ,
1438 .I /my/homedir/tex/test.tex
1439 or any combination of these), both filenames are expanded to a full path,
1440 with any occurrences of
1441 .I ../
1442 and
1443 .I ./
1444 expanded, and multiple slashes removed.
1445 .br
1446 The pathname in the
1447 .I \-sourceposition
1448 is expanded relative to the current working directory of the
1449 .I xdvi \-sourceposition
1450 invocation, and the pathnames in the source specials are expanded
1451 relative to the path of the current DVI file being viewed.
1452 .br
1453 The path names are then compared ignoring the
1454 .RI ` .tex '
1455 extensions in both path names.
1456 .RE
1457 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1458 .TP
1459 .B \-statusline\fP
1460 .RB ( .statusline )
1461 This option is obsolete; use
1462 \fB\-expertmode \fP \fIflag\fP
1463 instead (which see).
1464 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1465 .TP
1466 .BI \-text-encoding " encoding"
1467 .RB ( .textEncoding )
1468 Use
1469 .I encoding
1470 as the text encoding of the string in the "Find" window. Usually, this
1471 should not be needed since the encoding is determined from the locale settings.
1472 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1473 .TP
1474 .B \-thorough
1475 .RB ( .thorough )
1476 .B Xdvi
1477 will usually try to ensure that overstrike characters (e.g.\&
1478 .BR \enotin )
1479 are printed correctly. On monochrome displays, this is always possible
1480 with one logical operation, either
1481 .I and
1482 or
1483 .IR or .
1484 On color displays, however, this may take two operations, one to set the
1485 appropriate bits and one to clear other bits. If this is the case, then
1486 by default
1487 .B xdvi
1488 will instead use the
1489 .I copy
1490 operation, which does not handle overstriking correctly. The
1491 .B \-thorough
1492 option chooses the slower but more correct choice. See also
1493 .BR \-copy .
1494 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1495 .TP
1496 .BI \-topmargin " dimen"
1497 .RB ( .topMargin )
1498 Specifies the top and bottom margins (see
1499 .BR \-margins ).
1500 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1501 .TP
1502 .B \-unique
1503 .RB ( .unique )
1504 This option will make another instance of xdvi running on the same display
1505 act as a `server'. For example, the invocation
1506 .sp
1507 .B xdvi -unique +5 file.dvi
1508 .sp
1509 will cause this other instance to load
1510 .I file.dvi
1511 on page 5 in place of the file that it is currently displaying. If there is
1512 already another instance of xdvi already displaying the file
1513 .IR file.dvi ,
1514 then it will just jump to page 5.
1515 If the other instance of xdvi is displaying a different file, it will load
1516 .I file.dvi
1517 instead. Otherwise, if no other instance of
1518 xdvi is currently running on the display, this option instead
1519 starts a new instance of xdvi in the background (unless the
1520 .I \-nofork
1521 option is specified, which see) displaying page 5 of
1522 .IR file.dvi .
1523 .br
1524 The filename and the
1525 .B +n
1526 option for the page number are the only options available for
1527 controlling a remote instance of xdvi like this; all other options are
1528 currently ignored.
1529 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1530 .TP
1531 .B \-useTeXpages
1532 Use logical \*(Te\& pages (the values of the
1533 .I \ecount0
1534 register) instead of physical pages for the pagelist labels and
1535 when jumping to a page in a document with the `g' keystroke (or the
1536 .B goto-page()
1537 action).
1538 This option can be toggled via the
1539 .RB ` T '
1540 keystroke.
1541 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1542 .TP
1543 .B \-version
1544 Print information on the version of
1545 .BR xdvi .
1546 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1547 .TP
1548 .B \-visitedlinkcolor
1549 .RB ( .visitedLinkColor )
1550 Color used for visited hyperlinks (`Purple4' by default). Hyperlinks become
1551 visited once you click on them. As for
1552 .BR linkColor ,
1553 the value should be either a valid X color name or a hexadecimal color string.
1554 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1555 .TP
1556 .B \-warnspecials
1557 .RB ( .warnSpecials )
1558 Causes
1559 .B xdvi
1560 to print warnings about
1561 .B \especial
1562 strings that it cannot process to stderr. These warnings are suppressed by default.
1563 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1564 .TP
1565 .BI \-watchfile " n"
1566 .RB ( .watchFile )
1567 If this option is set to a value larger than 0, xdvi will check
1568 the DVI file for changes every
1569 .I n
1570 seconds. If the DVI file has been completely written by TeX, it will
1571 be reloaded automatically. Fractional values (e.g. `2.5') are
1572 possible. The default for this option is 0, i.e. no watching.
1573 .br
1574 Since xdvi cannot handle partial DVI files, it tries not to reload
1575 the file while it is being rewritten. However, use of the magnifier
1576 or switching of pages requires reading (a part of) the DVI file, and
1577 if the
1578 .B tempfile
1579 option is switched off, this will erase the current contents of the window
1580 until the DVI file can be read entirely.
1581 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1582 .TP
1583 .BI \-wheelunit " pixels"
1584 .RB ( .wheelUnit )
1585 Sets the number of pixels that a motion of a wheel mouse will move the
1586 image up, down, left, or right. (See the
1587 .B wheel
1588 and
1589 .B hwheel
1590 actions, below, for more information on this.)
1591 If set to zero, the wheel mouse functionality is (essentially) disabled.
1592 The default value is 80.
1593 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1594 .TP
1595 .BI \-xoffset " dimen"
1596 .RB ( .xOffset )
1597 Specifies the size of the horizontal offset of the output on the page. See
1598 .BR \-offsets .
1599 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1600 .TP
1601 .BI \-yoffset " dimen"
1602 .RB ( .yOffset )
1603 Specifies the size of the vertical offset of the output on the page. See
1604 .BR -offsets .
1605 .PP
1606
1607
1608
1609 .SH KEYSTROKES
1610 .B Xdvi
1611 recognizes the following keystrokes when typed in its window.
1612 Each may optionally be preceded by a (positive or negative) number, a
1613 `prefix argument', whose interpretation will depend on the particular keystroke.
1614 This prefix argument can be discarded by pressing the ``Escape'' key.
1615 If present, the ``Help'', ``Prior'' and ``Next'' keys are synonyms for
1616 .RB ` ? ',
1617 .RB ` b ',
1618 and
1619 .RB ` f '
1620 keys, respectively.
1621 .PP
1622 The key bindings listed here are those that
1623 .B xdvi
1624 assigns by default. The names appearing in brackets at the beginning
1625 of the descriptions are the names of the actions associated with the
1626 keys; these can be used to customize the key bindings, as explained in
1627 more detail in the section
1628 .B CUSTOMIZATION
1629 below. If only a lowercase binding is listed, both upper- and lowercase
1630 keys will work for that binding.
1631 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1632 .\"
1633 .\" SPECIAL KEYS
1634 .\"
1635 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1636 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1637 .TP
1638 .BR ESC " key"
1639 .RB [ discard-number() ]
1640 The escape key discards the numerical prefix for all actions
1641 (useful when you mistyped a number).
1642 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1643 .TP
1644 .BR Return " key"
1645 .RB [ forward-page() ]
1646 Moves to the next page (or to the
1647 .IR n th
1648 next page if a number is given). Synonyms are
1649 .RB ` n ',
1650 .RB ` f '
1651 and Line Feed.
1652 .TP
1653 .BR Backspace " key"
1654 .RB [ back-page() ]
1655 Moves to the previous page (or back
1656 .I n
1657 pages). Synonyms are
1658 .RB ` p ',
1659 .RB ` b '
1660 and
1661 .BR Ctrl-h .
1662 .TP
1663 .BR Delete " key"
1664 .RB [ up-or-previous() ]
1665 Moves up two-thirds of a window-full, or to the top of the previous page
1666 if already at the top of the page. With a float argument, moves up the
1667 corresponding fraction of a window-full.
1668 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1669 .TP
1670 .BR Space " key"
1671 .RB [ unpause-or-next() ]
1672 Moves down two-thirds of a window-full, or to the next page if already at
1673 the bottom of the page.
1674 .br
1675 When the option
1676 .BI \-pause " special-string"
1677 is used and the display is currently paused, this key will instead
1678 display the next portion of the page until the next
1679 .I special-string
1680 or the end of the page is encountered. See the description of the
1681 .B \-pause
1682 option for details. The action
1683 .RB [ down-or-next() ]
1684 does a similar thing, but without pausing; it is not bound to a key
1685 by default.
1686 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1687 .TP
1688 .BR Ctrl-Home " (Xaw), " Ctrl-osfBeginLine " (Motif)"
1689 .RB [ goto-page(1) ]
1690 Moves to the first page of the document.
1691 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1692 .TP
1693 .BR Ctrl-End " (Xaw), " Ctrl-osfEndLine " (Motif)"
1694 .RB [ goto-page() ]
1695 Moves to the last page of the document.
1696 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1697 .TP
1698 .BR Home " (Xaw), " osfBeginLine " (Motif)"
1699 .RB [ home-or-top() ]
1700 Move to the ``home'' position of the page, or to the top of the page if
1701 the
1702 .I keep
1703 flag is set (in this case, the page doesn't scroll horizontally).
1704 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1705 .TP
1706 .BR End " (Xaw), " osfEndLine " (Motif)"
1707 .RB [ end-or-bottom() ]
1708 Move to the ``end'' position of the page (the lower right-hand corner),
1709 or to the bottom of the page if the
1710 .I keep
1711 flag is set (in this case, the page doesn't scroll horizontally).
1712 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1713 .\"
1714 .\" ARROW KEYS
1715 .\"
1716 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1717 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1718 .TP
1719 .B Down arrow
1720 .RB [ down(0.015) ]
1721 Scrolls page down.
1722 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1723 .TP
1724 .B Up arrow
1725 .RB [ up(0.015) ]
1726 Scrolls page up.
1727 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1728 .TP
1729 .B Right arrow
1730 .RB [ right(0.015) ]
1731 Scrolls page right.
1732 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1733 .TP
1734 .B Left arrow
1735 .RB [ left(0.015) ]
1736 Scrolls page left.
1737 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1738 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1739 .\"
1740 .\" ORDINARY KEYS. Note that the special symbols ([ ] + - etc.) are not in
1741 .\" strict ASCII order (found that more intuitive). Sequence for each letter
1742 .\" is: Alt-Ctrl, Ctrl, uppercase, lowercase.
1743 .\"
1744 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1745 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1746 .TP
1747 .B Alt-Ctrl-+
1748 .RB [ change-density(25) ]
1749 Increase the darkness of the fonts in the DVI window by adding to the gamma value
1750 (see also the
1751 .RB ` S '
1752 keystroke).
1753 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1754 .TP
1755 .B Alt-Ctrl--
1756 .RB [ change-density(-25) ]
1757 Decrease the darkness of the fonts in the DVI window by subtracting from the gamma value
1758 (see also the
1759 .RB ` S '
1760 keystroke).
1761 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1762 .TP
1763 .B Ctrl-+
1764 .RB [ set-shrink-factor(+) ]
1765 Increase the shrink factor (see also the
1766 .RB ` s '
1767 keystroke).
1768 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1769 .TP
1770 .B Ctrl--
1771 .RB [ set-shrink-factor(-) ]
1772 Decrease the shrink factor (see also the
1773 .RB ` s '
1774 keystroke).
1775 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1776 .TP
1777 .B Ctr-[
1778 .RB [ pagehistory-delete-backward() ]
1779 Delete the current item in the page history and move to the history
1780 item before the deleted one. With a prefix argument
1781 .BR n ,
1782 delete
1783 .B n
1784 previous history items. See
1785 .B PAGE HISTORY
1786 for details.
1787 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1788 .TP
1789 .B [
1790 .RB [ pagehistory-back() ]
1791 Move back in the page history (see
1792 .B PAGE HISTORY
1793 for details). With a prefix argument
1794 .BR n ,
1795 move back
1796 .B n
1797 history items.
1798 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1799 .TP
1800 .B Ctr-]
1801 .RB [ pagehistory-delete-forward() ]
1802 Delete the current item in the page history and move to the history
1803 item after the deleted one. With a prefix argument
1804 .BR n ,
1805 delete
1806 .B n
1807 next history items. See
1808 .B PAGE HISTORY
1809 for details.
1810 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1811 .TP
1812 .B ]
1813 .RB [ pagehistory-forward() ]
1814 Move forward in the page history (see
1815 .B PAGE HISTORY
1816 for details). With a prefix argument
1817 .BR n ,
1818 move forward
1819 .B n
1820 history items.
1821 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1822 .TP
1823 .B ^
1824 .RB [ home() ]
1825 Move to the ``home'' position of the page. This is normally the upper
1826 left-hand corner of the page, depending on the margins as described in the
1827 .B \-margins
1828 option, above.
1829 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1830 .TP
1831 .B ?
1832 .RB [ help() ]
1833 Same as the
1834 .B h
1835 key (which see).
1836 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1837 .TP
1838 .B B
1839 .RB [ htex-back() ]
1840 This key jumps back to the previous hyperlink anchor. See the
1841 section
1842 .B HYPERLINKS
1843 for more information on navigating the links.
1844 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1845 .TP
1846 .B b
1847 .RB [ back-page() ]
1848 Moves to the previous page (or back
1849 .I n
1850 pages). Synonyms are
1851 .RB ` p ',
1852 .B Ctrl-h
1853 and
1854 .BR Backspace .
1855 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1856 .TP
1857 .B C
1858 .RB [ set-color() ]
1859 This key toggles the use of color specials. The key sequences
1860 .RB ` 0C '
1861 and
1862 .RB ` 1C '
1863 turn interpretation of color specials off and on, respectively.
1864 See also the
1865 .B \-nocolor
1866 option.
1867 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1868 .TP
1869 .B c
1870 .RB [ center() ]
1871 Moves the page so that the point currently beneath the mouse cursor is moved to
1872 the middle of the window, and warps the mouse cursor to the same place.
1873 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1874 .TP
1875 .B D
1876 .RB [ toggle-grid-mode() ]
1877 This key toggles the use of a grid on the displayed page.
1878 If no number is given, the grid mode is switched on or off.
1879 By prepending a number from 1 to 3, 3 different grid levels can be set.
1880 The units of the grid are inches or centimeters, depending
1881 on whether the paper format is letter (in) or a4 (cm).
1882 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1883 .TP
1884 .B d
1885 .RB [ down() ]
1886 Moves page down two thirds of a window-full. With a float argument to ``down'',
1887 moves down the corresponding fraction of a window-full.
1888 .\" Therefore, a more
1889 .\" ``smooth'' scrolling using the ``Up'' and ``Down'' keys can be
1890 .\" achieved by the following setting:
1891 .\" .sp
1892 .\" xdvi.mainTranslations: #override\e
1893 .\" .br
1894 .\" <Key>Up:up(0.01)\en\e
1895 .\" .br
1896 .\" <Key>Down:down(0.01)\en
1897 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1898 .TP
1899 .B Ctrl-f
1900 .RB [ find() ]
1901 Pop up a window to search for a string in the DVI file. See the section
1902 .BR "STRING SEARCH" ,
1903 below, for more details.
1904 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1905 .TP
1906 .B f
1907 .RB [ forward-page() ]
1908 Moves to the next page (or to the
1909 .IR n th
1910 next page if a number is given). Synonyms are
1911 .RB ` n ',
1912 Return, and Line Feed.
1913 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1914 .TP
1915 .B G
1916 .RB [ set-greyscaling() ]
1917 This key toggles the use of greyscale anti-aliasing for displaying shrunken
1918 bitmaps. In addition, the key sequences
1919 .RB ` 0G '
1920 and
1921 .RB ` 1G '
1922 clear and set this flag, respectively. See also the
1923 .B \-nogrey
1924 option.
1925 .sp
1926 If given a numeric argument that is not 0 or 1, greyscale anti-aliasing is
1927 turned on, and the gamma resource is set to the value divided by
1928 100. E.g.\&
1929 .RB ` 150G '
1930 turns on greyscale and sets gamma to 1.5.
1931 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1932 .TP
1933 .B Ctrl-g
1934 .RB [ find-next() ]
1935 Find the next match string in the DVI file; this can be used instead
1936 of pressing the `Find' button in the search window.
1937 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1938 .TP
1939 .B g
1940 .RB [ goto-page() ]
1941 Moves to the page with the given number. If no page number is given, xdvi jumps to the last page.
1942 .br
1943 If the option/resource
1944 .B useTeXpages
1945 is active, the numbers correspond to the actual page numbers in the TeX file;
1946 otherwise, absolute page numbers (starting from 1) are used. In the latter case,
1947 the page numbers can be changed with the
1948 .RB ` P '
1949 keystroke, below.
1950 Note that with the
1951 .B useTeXpages
1952 option it is possible that the same page number occurs multiple
1953 times; in such a case, xdvi will use the first page number that matches.
1954 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1955 .TP
1956 .B h
1957 Pops up a help window with a short explanation of the most important key
1958 bindings and concepts.
1959 .\"
1960 .\" Ummh, surely nobody will use the following ...
1961 .\"
1962 .\" For I18n purposes, the help texts and menu entries are configurable
1963 .\" via the following X resources:
1964 .\" .BR helpGeneral ,
1965 .\" #ifhyper
1966 .\" .BR helpHypertex ,
1967 .\" #endif
1968 .\" .BR helpOthercommands ,
1969 .\" .BR helpMarking ,
1970 .\" .BR helpPagemotion ,
1971 .\" .BR helpMousebuttons ,
1972 .\" .BR helpRulermode ,
1973 .\" .BR helpSearch and
1974 .\" .BR helpSourcespecials .
1975 .\" The values of this resource should be a text string, the first line of
1976 .\" which should contain two fields separated by `\en'. The first field is
1977 .\" used as list entry for the list of help topics on the left of the help
1978 .\" window, and the second field is used as the heading on the right-hand side.
1979 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1980 .TP
1981 .B k
1982 .RB [ set-keep-flag() ]
1983 Normally when
1984 .B xdvi
1985 switches pages, it moves to the home position as well. The
1986 .RB ` k '
1987 keystroke toggles a `keep-position' flag which, when set, will keep
1988 the same position when moving between pages. Also
1989 .RB ` 0k '
1990 and
1991 .RB ` 1k '
1992 clear and set this flag, respectively. See also the
1993 .B \-keep
1994 option.
1995 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1996 .TP
1997 .B Ctrl-l
1998 .RB [ fullscreen(toggle) ]
1999 Toggles fullscreen mode (see the description of the
2000 .B \-fullscreen
2001 option for more information on this). This is even more flaky than
2002 using the command-line option: There is no universal standard
2003 how a window could change its own geometry or window decorations at
2004 run-time, so this will not work with most window managers or
2005 desktops. Generally, it's better to use the window manager controls to
2006 change the size or decorations of the xdvi window.
2007 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2008 .TP
2009 .B l
2010 .RB [ left() ]
2011 Moves page left two thirds of a window-full.
2012 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2013 .TP
2014 .B M
2015 .RB [ set-margins() ]
2016 Sets the margins so that the point currently under the mouse cursor defines
2017 the upper left-hand corner of the text in the page. Note that the command
2018 does
2019 .I not
2020 move the image, but only determines the margins
2021 for the page switching commands. For details on how the margins
2022 are used, see the
2023 .B \-margins
2024 option.
2025 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2026 .TP
2027 .B m
2028 .RB [ toggle-mark() ]
2029 Toggles the mark for the current page in the page list. When a page
2030 is marked, it is displayed with a small star `*' next to the page number.
2031 The marked pages can then be printed or saved to a file.
2032 A page or several pages can also be marked by clicking or dragging
2033 .B Mouse-2
2034 in the page list.
2035 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2036 .TP
2037 .B Ctrl-n
2038 .RB [ toggle-mark()forward-page() ]
2039 Toggles the mark for the current page in the page list, and moves to
2040 the next page. This lets you quickly mark a series of subsequent pages.
2041 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2042 .TP
2043 .B n
2044 .RB [ forward-page() ]
2045 Moves to the next page (or to the
2046 .IR n th
2047 next page if a number is given). Synonyms are
2048 .RB ` f ',
2049 Return, and Line Feed.
2050 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2051 .TP
2052 .B Ctrl-o
2053 .RB [ select-dvi-file() ]
2054 Read a new
2055 .I dvi
2056 file. A file-selection widget is popped up for you to choose the DVI
2057 file from. If a prefix argument
2058 .I n
2059 is given, the
2060 .I n th
2061 file from the file history is opened instead.
2062 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2063 .TP
2064 .B P
2065 .RB [ declare-page-number() ]
2066 ``This is page number
2067 .IR n .''
2068 This can be used to make the
2069 .RB ` g '
2070 keystroke refer to a different page number than the physical page.
2071 (If you want to use `logical' or \*(Te\& page numbers instead of physical pages,
2072 consider using the option
2073 .B \-useTeXpages
2074 instead.)
2075 The argument
2076 .I n
2077 should be given as prefix to this key.
2078 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2079 .TP
2080 .B Ctrl-p
2081 .RB [ print() ]
2082 Opens a popup window for printing the DVI file, or parts of it.
2083 See the section
2084 .B PRINT DIALOG
2085 for an explanation of the options available, and the resources to customize
2086 the default behaviour.
2087 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2088 .TP
2089 .B p
2090 .RB [ back-page() ]
2091 Moves to the previous page (or back
2092 .I n
2093 pages). Synonyms are
2094 .RB ` b ',
2095 .B Ctrl-h
2096 and
2097 .BR Backspace .
2098 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2099 .TP
2100 .B q
2101 .RB [ quit() ]
2102 Quits the program.
2103 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2104 .TP
2105 .B Ctrl-r
2106 .RB [ forward-page(0) ]
2107 Redisplays the current page.
2108 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2109 .TP
2110 .B R
2111 .RB [ reread-dvi-file() ]
2112 Forces the
2113 .I dvi
2114 file to be reread. This allows you to preview many versions of the same
2115 file while running
2116 .B xdvi
2117 only once.
2118 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2119 .TP
2120 .B r
2121 .RB [ right() ]
2122 Moves page right two thirds of a window-full.
2123 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2124 .TP
2125 .B Ctrl-s
2126 .RB [ save() ]
2127 Opens a popup window for saving the DVI file, or parts of it. See the section
2128 SAVE DIALOG below for more information on this.
2129 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2130 .TP
2131 .B S
2132 .RB [ set-density() ]
2133 Sets the density factor to be used when shrinking bitmaps. This should
2134 be a number between 0 and 100; higher numbers produce lighter characters.
2135 If greyscaling mode is in effect, this changes the value of gamma instead.
2136 The new value of gamma is the given number divided by 100; negative values
2137 are allowed.
2138 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2139 .TP
2140 .B s
2141 .RB [ set-shrink-factor() ]
2142 Changes the shrink factor to the given number. If no number is given, the
2143 smallest factor that makes the entire page fit in the window will be used.
2144 (Margins are ignored in this computation.)
2145 .\" NOTE: following only works in action string, not interactively!!!
2146 .\" Two special values are
2147 .\" .B +
2148 .\" and
2149 .\" .B -
2150 .\" which zoom in and out respectively, by decrementing/incrementing the
2151 .\" shrinkfactor by one step.
2152 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2153 .TP
2154 .B T
2155 .RB [ use-tex-pages() ]
2156 Use logical \*(Te\& pages (the values of the
2157 .I \ecount0
2158 register) instead of physical pages for the pagelist labels and
2159 when jumping to a page in a document via
2160 .BR goto-page() .
2161 See also the
2162 .B \-useTeXpages
2163 option.
2164 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2165 .TP
2166 .B t
2167 .RB [ switch-magnifier-units() ]
2168 Switches the units used for the magnifier tick marks, and for reporting
2169 the distance between the mouse pointer and the ruler centre in
2170 ruler mode (see the section
2171 .BR MODES ).
2172 The default value is specified by the X resource
2173 .B tickUnits
2174 (`mm' by default). The units toggle through the following
2175 values; except for `px', they all correspond to \*(Te\&'s units:
2176 .I mm
2177 (millimeters)
2178 .I pt
2179 (\*(Te\& points),
2180 .I in
2181 (inches),
2182 .I sp
2183 (scaled points, the unit used internally by \*(Te\&)
2184 .I bp
2185 (big points or `PostScript points'),
2186 .I cc
2187 (cicero points),
2188 .I dd
2189 (didot points),
2190 .I pc
2191 (pica), and
2192 .I px
2193 (screen pixels).
2194 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2195 .TP
2196 .B Ctrl-u
2197 .RB [ back-page()toggle-mark() ]
2198 Moves to the previous page, and toggles the mark for that page. This
2199 is the dual action to
2200 .BR Ctrl-n .
2201 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2202 .TP
2203 .B u
2204 .RB [ up() ]
2205 Moves page up two thirds of a window-full. With a float argument to ``up'',
2206 moves up the corresponding fraction of a window-full.
2207 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2208 .TP
2209 .B Ctrl-v
2210 .RB [ show-source-specials() ]
2211 Show bounding boxes for every source special on the current page, and print
2212 the strings contained in these specials to stderr. With prefix 1,
2213 show every bounding box on the page. This is for debugging purposes mainly.
2214 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2215 .TP
2216 .B V
2217 .RB [ set-gs-alpha() ]
2218 This key toggles the anti-aliasing of PostScript<tm> specials when
2219 .B Ghostscript
2220 is used as renderer. In addition the key sequences
2221 .RB ` 0V '
2222 and
2223 .RB ` 1V '
2224 clear and set this flag, respectively. See also the
2225 .B \-gsalpha
2226 option.
2227 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2228 .TP
2229 .B v
2230 .RB [ set-ps() ]
2231 This key toggles the rendering of PostScript<tm> specials between 3 states:
2232 .RS 7
2233 .TP 0
2234 .SB - specials (like EPS graphics) are displayed;
2235 .TP
2236 .SB - specials are displayed along with their bounding box (if available);
2237 .TP
2238 .SB - only the bounding box is displayed.
2239 .PP
2240 .sp
2241 The states can also be selected directly by using
2242 .RB ` 1v ',
2243 .RB ` 2v '
2244 and
2245 .RB ` 0v '
2246 respectively.
2247 See also the
2248 .B \-postscript
2249 option.
2250 .RE
2251 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2252 .TP
2253 .B Ctrl-x
2254 .RB [ source-what-special() ]
2255 Display information about the source special next to the mouse cursor in the
2256 statusline. This is the same special that would be found by
2257 .IR source-special() ,
2258 but without invoking the editor. For debugging purposes.
2259 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2260 .TP
2261 .B x
2262 .RB [ set-expert-mode() ]
2263 Toggles expert mode, in which
2264 the statusline, the scrollbars, the menu buttons, the toolbar (Motif only)
2265 and the page list are not shown.
2266 Typing
2267 .RB ` 1x '
2268 toggles the display of the statusline at the bottom of
2269 the window. Typing
2270 .RB ` 2x '
2271 toggles the scrollbars (if available). For Xaw,
2272 .RB ` 3x '
2273 toggles the menu buttons and the page list, for Motif,
2274 it toggles the page list. In Motif, the additional bindings
2275 .RB ` 4x '
2276 toggle the toolbar, and
2277 .RB ` 5x '
2278 the menu bar.
2279 .br
2280 Without a prefix argument, all of the mentioned GUI elements are either
2281 switched on (if they had been invisible before) or off.
2282 .br
2283 Toggling the scrollbars may behave erratically with the
2284 Xaw widgets; e.g. the scrollbars may reappear after
2285 resizing the window, and at certain window sizes one of the
2286 scrollbars may fail to disappear.
2287 .br
2288 See also the option
2289 .B \-expertmode
2290 (the numbers above correspond to the bits in the argument to
2291 .BR \-expertmode ).
2292 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2293 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2294 .SH MOUSE ACTIONS IN THE MAIN WINDOW
2295 The mouse actions can be customized by setting the X resource
2296 .BR mouseTranslations .
2297 Since there are three different mouse modes (see the section
2298 .B MODES
2299 below), there is a special action
2300 .B mouse-modes
2301 which lists the actions for each of the three modes:
2302 \fBmouse-modes("ACTIONS-FOR-MODE1", "ACTIONS-FOR-MODE2", "ACTIONS-FOR-MODE3")\fR.
2303 If only one argument is specified, this action is used for all modes.
2304 The default bindings are as follows:
2305 .RS 5
2306 .nf
2307 .ft 3
2308 .sp 1n
2309 xdvi.mouseTranslations: \e
2310 Shift<Btn1Down>:mouse-modes("drag(+)")\en\e
2311 Shift<Btn2Down>:mouse-modes("drag(|)")\en\e
2312 Shift<Btn3Down>:mouse-modes("drag(-)")\en\e
2313 Ctrl<Btn1Down>:mouse-modes("source-special()")\en\e
2314 <Btn1Down>: mouse-modes("do-href()magnifier(*2)", "text-selection()", "ruler()")\en\e
2315 <Btn2Down>: mouse-modes("do-href-newwindow()magnifier(*2)", "text-selection()", "ruler()")\en\e
2316 <Btn3Down>: mouse-modes("magnifier(*3)")\en\e
2317 <Btn4Down>: mouse-modes("wheel(-0.2)")\en\e
2318 <Btn5Down>: mouse-modes("wheel(0.2)")\en\e
2319 <Btn6Down>: mouse-modes("hwheel(-0.2)")\en\e
2320 <Btn7Down>: mouse-modes("hwheel(0.2)")\en\e
2321 .sp 1n
2322 .ft
2323 .fi
2324 .RE
2325 All of these actions are described in more detail below.
2326 Note the use of quote symbols around the action strings, which are necessary
2327 to group them into one argument.
2328 Buttons 4, 5, 6, and 7 refer to wheel movements (wheel up/down/left/right)
2329 on wheel mice. Not all mice support horizontal scrolling.
2330 .PP
2331 The X Toolkit routines that implement translations do not support event
2332 types of
2333 .B Btn6Down
2334 or
2335 .BR Btn7Down .
2336 Because of this,
2337 .B xdvi
2338 implements its own parser for translations given in
2339 .BR mouseTranslations .
2340 This parser is more limited than the parser built in to the X Toolkit.
2341 The string given in
2342 .B mouseTranslations
2343 should not begin with
2344 .RB `` #replace '',
2345 .RB `` #augment '',
2346 or
2347 .RB `` #override ''.
2348 Modifiers of the form
2349 .BI @ keysym
2350 are not supported, and the event type must be of the form
2351 .B BtnDown
2352 or
2353 .BI Btn n Down\fR,\fP
2354 where
2355 .I n
2356 is a positive integer without leading zeroes. Also, some limitations apply
2357 to the action field.
2358 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2359 .TP
2360 .B do-href()
2361 .TP
2362 .B do-href-newwindow()
2363 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2364 Usually, if a binding specifies more then one action, all actions
2365 are executed in a sequence. The hyperlink bindings
2366 .B do-href()
2367 and
2368 .B do-href-newwindow()
2369 are special in that they are used as an
2370 .I alternative
2371 to other actions that might follow them
2372 .I if
2373 the mouse is currently located on a hyperlink.
2374 In this case, none of the other actions will be executed;
2375 otherwise, only the other actions are executed.
2376 .br
2377 The action
2378 .B do-href()
2379 jumps to the link target in the current xdvi
2380 window (eventually switching to another page), and
2381 .B do-href-newwindow()
2382 opens a new instance of xdvi for the link target.
2383 In both cases, the location of the target is
2384 indicated by a small arrow drawn in the same color
2385 as a visited link
2386 in the left corner of the window.
2387 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2388 .TP
2389 .B magnifier(n x m)
2390 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2391 .TP
2392 .B magnifier(*n)
2393 This action will pop up a ``magnifying glass'' which shows the unshrunk
2394 image of the region around the mouse pointer. The magnifier disappears when
2395 the mouse button is released. Moving the mouse cursor while holding the button down will move the
2396 magnifier.
2397 .br
2398 Different mouse buttons produce different sized
2399 windows, as indicated by
2400 the argument of the
2401 .I magnifier()
2402 action. Its argument is either a string of the form
2403 .IR width x height ,
2404 as in the
2405 .BI \-mgs n
2406 command-line option, or one of the strings
2407 .B *1
2408 through
2409 .BR *5 ,
2410 referring to the value specified by the corresponding
2411 .BI \-mgs n
2412 option.
2413 .\" Note that in order to assign magnifier actions to
2414 .\" the buttons 4 or 5, you need to use the resource
2415 .\" .B wheelTranslations
2416 .\" (more about this resource below), e.g.:
2417 .\" .sp
2418 .\" xdvi.wheelTranslations: <Btn4Down>: magnifier(*4)\en\e
2419 .\" <Btn5Down>: magnifier(*5)\en
2420 .\" .sp
2421 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2422 .TP
2423 .B drag(+)
2424 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2425 .TP
2426 .B drag(|)
2427 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2428 .TP
2429 .B drag(-)
2430 Drags the page with the mouse. This action should have one parameter, the character
2431 .RB `` | '',
2432 .RB `` - '',
2433 or
2434 .RB `` + '',
2435 indicating vertical dragging only, horizontal dragging only, or dragging in all
2436 directions.
2437 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2438 .TP
2439 .B source-special()
2440 This action starts a ``reverse search'',
2441 opening the editor at the location in the \*(Te\& file corresponding
2442 to the pointer location in the DVI file.
2443 See the section on SOURCE SPECIALS, below, for more information on this.
2444 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2445 .TP
2446 .B wheel()
2447 This action can be used to scroll the image with a wheel mouse, where it
2448 is usually bound to mouse button 4 (wheel up) or 5 (wheel down).
2449 The action takes one parameter, giving the distance to scroll the
2450 image. If the parameter contains a decimal point, the distance is
2451 given in wheel units; otherwise, pixels. A negative value scrolls up,
2452 a positive value scrolls down.
2453 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2454 .TP
2455 .B hwheel()
2456 This action can be used to scroll the image horizontally with a wheel mouse,
2457 where it is usually bound to mouse button 6 (wheel left) or 7 (wheel right).
2458 The action takes one parameter, giving the distance to scroll the
2459 image. If the parameter contains a decimal point, the distance is
2460 given in wheel units; otherwise, pixels. A negative value scrolls left,
2461 a positive value scrolls right. Not all mice support horizontal scrolling;
2462 this is mostly for touchpads, trackpads, etc.
2463 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2464 .TP
2465 .B text-selection()
2466 This action allows you to mark a rectangular region of text in the DVI file.
2467 The text is put into the X selection buffer and can be pasted into other
2468 applications (e.g. text editors). This works similar to the Plain text option
2469 in the
2470 .B Save
2471 dialog; see the discussion there for more information on encoding issues.
2472 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2473 .TP
2474 .B ruler()
2475 This action creates a cross-shaped ruler. Moving the mouse and holding
2476 the button down drags the ruler and lets you measure distances on the page.
2477 See the section
2478 .B Ruler Mode
2479 for more information on this.
2480 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2481 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2482 .SH UNBOUND ACTIONS
2483 The following actions are not bound to a key by default, but are available
2484 for customization.
2485 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2486 .TP
2487 .B quit-confirm()
2488 Pops up a confirmation window to quit xdvi. To bind it to the
2489 .RB ` q '
2490 key instead of the default `quit()' action, put the following into your
2491 .I ~/.Xdefaults
2492 file:
2493 .sp
2494 xdvi.mainTranslations: #override\e
2495 .br
2496 <Key>q: quit-confirm()\en
2497 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2498 .TP
2499 .B down-or-next()
2500 Similar to
2501 .IR unpause-or-next() :
2502 Moves down two-thirds of a window-full, or to the next page if already
2503 at the bottom of the page.
2504 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2505 .TP
2506 .B shrink-to-dpi()
2507 This action takes one (required) argument. It sets the shrink factor to
2508 an integer so as to approximate the use of fonts with the corresponding
2509 number of dots per inch. If
2510 .B xdvi
2511 is using fonts scaled for
2512 .I p
2513 dots per inch, and the argument to
2514 .B shrink-to-dpi
2515 is
2516 .IR n ,
2517 then the corresponding shrink factor is the ratio
2518 .IR p / n ,
2519 rounded to the nearest integer.
2520 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2521 .TP
2522 .B user-exec()
2523 This action takes one (required) argument. Runs an external program
2524 specified by the argument, which is tokenized on whitespace. The
2525 .B XDVI_FILE
2526 environment variable is set to the absolute pathname of the DVI file,
2527 so that the program can find the DVI. As an example, to establish the
2528 key
2529 .RB ` m '
2530 as a keybinding that regenerates the DVI file with `make', put the
2531 following into your
2532 .I ~/.Xdefaults
2533 file:
2534 .sp
2535 xdvi.mainTranslations: #override\e
2536 .br
2537 <Key>m: user-exec(xdvi-remake)\en
2538
2539 where `xdvi-remake' names a program in your
2540 .B PATH
2541 analogous to `cd $(dirname $XDVI_FILE) && make $(basename $XDVI_FILE)'.
2542 (See also the section
2543 .B SIGNALS
2544 for a way to get
2545 .B xdvi
2546 to reload the DVI file once it has been regenerated.)
2547 .PP
2548 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2549 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2550 .SH CUSTOMIZATION
2551 Key and mouse button assignments can be changed by setting the
2552 .B mainTranslations
2553 resource to a string of translations as defined in the documentation for the
2554 X toolkit. The actions should take the form of action names listed in the
2555 KEYSTROKES and MOUSE ACTIONS sections.
2556 .PP
2557 An exception to this are the Motif keys
2558 .IR osfPageUp " (" PgUp ),
2559 .IR osfPageDown " (" PgDown ),
2560 .IR osfBeginLine " (" Home )
2561 and
2562 .IR osfEndLine " (" End )
2563 which are currently not customizable in the Motif version.
2564 .PP
2565 Key actions will usually be without arguments; if they are passed an argument,
2566 it represents the optional number or `prefix argument' typed prior to the action.
2567 .PP
2568 Some key actions may take special arguments, as follows: The argument of
2569 .B goto-page
2570 may be the letter
2571 .RB ` e ',
2572 indicating the action of going to the end of the document.
2573 The argument of
2574 .B set-shrink-factor
2575 may be the letter
2576 .RB ` a ',
2577 indicating that the shrink factor should be set to the smallest value such that
2578 the page will fit in the window, or one of the signs
2579 .RB ` + '
2580 or
2581 .RB ` - ',
2582 indicating that the shrink factor should be increased or decreased, respectively.
2583 Finally, actions that would perform a toggle, such as
2584 .BR set-keep-flag ,
2585 may receive an argument
2586 .RB ` t ',
2587 indicating that the action should toggle regardless of the current prefix argument.
2588 .PP
2589 Mouse actions should refer only to
2590 .B ButtonPress
2591 events (e.g.\&
2592 .BR "<Btn1Down>:magnifier(*1)" ).
2593 The corresponding motion and release events will be handled internally.
2594 A key action may be bound to a mouse event, but not vice versa.
2595 .PP
2596 Usually the string of translations should begin with
2597 .RB `` #override '',
2598 indicating that the default key and mouse button assignments should not
2599 be discarded.
2600 .PP
2601 When keys or mouse buttons involving modifiers (such as Ctrl or Shift)
2602 are customized together with their non-modified equivalents, the modified
2603 keys should come first, for example:
2604 .RS 5
2605 .nf
2606 .ft 3
2607 .sp 1n
2608 xdvi.mainTranslations: #override \e
2609 Shift<Key>s: select-dvi-file()\en\e
2610 Ctrl<Key>s: save()\en\e
2611 <Key>s: find()\en
2612 .sp 1n
2613 .ft
2614 .fi
2615 .RE
2616 .PP
2617 Because
2618 .B xdvi
2619 needs to capture pointer motion events, and because the X Toolkit
2620 translations mechanism cannot accommodate both motion events and double-click
2621 events at the same time, it is not possible to specify double-click
2622 actions in
2623 .B xdvi
2624 customizations. For information on this and other aspects of translations,
2625 see the X Toolkit Intrinsics documentation.
2626 .PP
2627 There is no command-line option to set the
2628 .B mainTranslations
2629 resource, since changing this resource on the command line would be cumbersome.
2630 To set the resource for testing purposes, use the
2631 .B -xrm
2632 command-line option provided by the X toolkit. For example,
2633 \fBxdvi \-xrm 'XDvi.mainTranslations: #override "z":quit()' ...\fR
2634 or
2635 .B "xdvi \-xrm 'XDvi.mainTranslations: #override <Key>z:quit()' ..."
2636 will cause the key
2637 .RB ` z '
2638 to quit
2639 .BR xdvi .
2640 .PP
2641 Some resources are provided to allow customization of the geometry of
2642 the Xaw command buttons. Again, they are not changeable via command-line
2643 options, other than via the
2644 .B \-xrm
2645 option. All of these resources take integer values.
2646 .TP
2647 .B buttonSideSpacing
2648 The number of pixels to be placed on either side of the buttons.
2649 The default value is 6.
2650 .TP
2651 .B buttonTopSpacing
2652 The number of pixels between the top button and the top of the window.
2653 The default value is 50.
2654 .TP
2655 .B buttonBetweenSpacing
2656 The number of pixels between the buttons.
2657 The default value is 20.
2658 .TP
2659 .B buttonBetweenExtra
2660 The number of pixels of additional space to be inserted if the
2661 .B buttonTranslations
2662 resource string contains an extra newline character.
2663 The default value is 50.
2664 .TP
2665 .B buttonBorderWidth
2666 The border width of the button windows. The default value is 1.
2667 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2668 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2669 .SH PAGE LIST
2670 The scrollable page list on the right of the main window allows you to
2671 jump directly to a page in the DVI file.
2672 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2673 .TP
2674 .B Mouse-1
2675 Jumps to the page the mouse is located on.
2676 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2677 .TP
2678 .B Mouse-2
2679 .RB [ toggle-mark() ]
2680 Toggle the mark of the current page. The marks are used by the `Print'
2681 and `Save to file' dialogs to select only marked pages from the DVI file.
2682 .PP
2683 When the mouse pointer is inside the page list, the mouse wheel switches
2684 to the next or previous page.
2685 .PP
2686 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2687 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2688 .SH SCROLLBARS
2689 The scrollbars (if present) behave in the standard way: pushing Button 2
2690 in a scrollbar moves the top or left edge of the scrollbar to that point
2691 and optionally drags it;
2692 pushing Button 1 moves the image up or right by an amount equal to the distance
2693 from the button press to the upper left-hand corner of the window; pushing
2694 Button 3 moves the image down or left by the same amount.
2695 .PP
2696 The scrollbars can be removed via the
2697 .I -expertmode
2698 flag/keystroke (which see).
2699 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2700 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2701 .SH MAGNIFIER
2702 By default, the mouse buttons 1 to 5 will pop up a ``magnifying glass''
2703 that shows an unshrunken image of the page (i.e. an image at the resolution
2704 determined by the option/X resource
2705 .B pixels
2706 or
2707 .BR mfmode )
2708 at varying sizes. When the magnifier is moved, small ruler-like
2709 tick marks are displayed at the edges of the magnifier (unless
2710 the X resource
2711 .B delayRulers
2712 is set to false, in which case the tick marks will always be displayed).
2713 The unit of the marks is determined by the X resource
2714 .B tickUnits
2715 (mm by default). This unit can be changed at runtime via the action
2716 .BR switch-magnifier-units() ,
2717 by default bound to the keystroke
2718 .RB ` t '
2719 (see the description of that key, and of switch-magnifier-units() for
2720 more details on the units available).
2721 .br
2722 The length of the tick marks can be changed via the X resource
2723 .B tickLength
2724 (4 by default). A zero or negative value suppresses the tick marks.
2725 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2726 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2727 .SH PAGE HISTORY
2728 .B Xdvi
2729 keeps a history of viewed pages, and you can move through the history
2730 and delete items using the keys
2731 .B [
2732 .RI ( pagehistory-back() ),
2733 .B ]
2734 .RI ( pagehistory-forward() ),
2735 .B Ctr-[
2736 .RI ( pagehistory-delete-backward() )
2737 and
2738 .B Ctr-]
2739 .RI ( pagehistory-delete-forward() ).
2740 .PP
2741 When one of the history commands is used, the page history is displayed
2742 in the status line at the bottom of the window, with the current list
2743 item marked by square brackets `[', `]' and a left and right context of
2744 at most 10 items. File boundaries are marked by `#'.
2745 .PP
2746 The size of the history can be customized with the X resource
2747 .B pageHistorySize
2748 (the default size is 1000 items). If the size is set to 0, the
2749 history commands are disabled.
2750 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2751 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2752 .SH HYPERLINKS
2753 The actions
2754 .B do-href()
2755 and
2756 .B do-href-newwindow()
2757 (by default bound to Mouse-1 and Mouse-2 if the pointer is currently located
2758 on a hyperlink) can be used to open the link target in the same window
2759 .RB ( do-href() )
2760 or in a new window
2761 .RB ( do-href-newwindow() ).
2762 .PP
2763 If the link target is not a file on the local disk,
2764 xdvi tries to launch a web browser (as specified by the
2765 .B -browser
2766 command line option, the
2767 .B BROWSER
2768 environment variable or the
2769 .B wwwBrowser
2770 X resource, in this order) to retrieve the document. See the description
2771 of the
2772 .B BROWSER
2773 environment variable, below, for an example setting.
2774 .PP
2775 If the file is a local file, xdvi tries to determine if it is a DVI
2776 file. If it is, xdvi will try to display the file; otherwise it will
2777 try to determine the MIME type of the file, and from that an
2778 application suitable for opening the file.
2779 This is done by parsing the files specified by the environment variable
2780 .B EXTENSIONMAPS
2781 for a mapping of filename extensions to MIME types,
2782 and the files determined by the environment variable
2783 .B MAILCAPS
2784 for a mapping of MIME types to application programs.
2785 See the descriptions of these variables in the section
2786 .BR ENVIRONMENT ,
2787 below, for a more detailed description and the default values of these
2788 variables. If no suitable files are found, a set of built-in default
2789 MIME types and applications is used.
2790 .PP
2791 .B Xdvi
2792 currently uses no heuristics apart from the filename suffix
2793 to determine the mime type of a file. If a filename has no suffix,
2794 the value of the resource
2795 .B noMimeSuffix
2796 is used (by default
2797 .IR application/x-unknown ).
2798 If the suffix doesn't match any of the suffixes in
2799 .BR mime.types ,
2800 the value of the resource
2801 .B unknownMimeSuffix
2802 is used (by default
2803 .IR application/x-unknown ).
2804 If the
2805 .B mailcap
2806 entries do not list a viewer for a given mime type, xdvi will show
2807 a warning popup. If you want to avoid this warning, and for example
2808 want to always use the netscape browser for unknown MIME types,
2809 you could add the following line to your ~/.mailcap file:
2810 .RS 4
2811 .nf
2812 .ft 3
2813 .sp 1n
2814 application/xdvi-unknown; \e
2815 netscape -raise -remote 'openURL(%s,new-window)'
2816 .sp 1n
2817 .ft
2818 .fi
2819 .RE
2820 .\" As an example, consider the following settings, which are the default
2821 .\" settings for buttons 1 and 2:
2822 .\" .RS 5
2823 .\" .nf
2824 .\" .ft 3
2825 .\" .sp 1n
2826 .\" xdvi.mainTranslations: #override \e
2827 .\" <Btn1Down>: do-href()magnifier(*1)\en\e
2828 .\" <Btn2Down>: do-href-newwindow()magnifier(*2)\en\e
2829 .\" <Btn3Down>: magnifier(*3)\en
2830 .\" .sp 1n
2831 .\" .ft
2832 .\" .fi
2833 .\" .RE
2834 .\" .PP
2835 .\" If a link points to a file which is not a DVI file (e.g. HTML, or
2836 .\" PostScript), the files
2837 .\" .B mime.types
2838 .\" and
2839 .\" .B mailcap
2840 .\" are parsed to determine a suitable viewer; if no suitable
2841 .\" .B mailcap
2842 .\" entry was found, if the
2843 .\" .SB WWWBROWSER
2844 .\" environment variable is set, or
2845 .\" .B \-browser
2846 .\" was specified on the command line, the browser is launched to load the file.
2847 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2848 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2849 .SH STRING SEARCH
2850 The keystroke
2851 .I Ctrl-f
2852 or the menu entry
2853 .I File > Find ...
2854 (or the `Binoculars' symbol in the toolbar, for Motif)
2855 opens a dialog window to search for a text string or
2856 a regular expression in the DVI file.
2857 The keystroke
2858 .I Ctrl-g
2859 jumps to the next match (like pressing the `Find' button in the search window).
2860 .PP
2861 By default, the matches are highlighted in inverted color.
2862 If the display isn't running in TrueColor, or if the X resource
2863 .B matchHighlightInverted
2864 is set to false or the command-line option
2865 .B \-nomatchinverted
2866 is used, xdvi will instead draw a rectangle in
2867 .I highlight
2868 color (see the
2869 .B \-hl
2870 option) around the match.
2871 .PP
2872 If a match crosses a page boundary, only the part on the
2873 first page is highlighted.
2874 .B Xdvi
2875 will scan up to 2 adjacent pages to match strings crossing page
2876 boundaries; but note that header or footer
2877 lines, or intervening float pages will be treated as parts of the
2878 scanned text. Such text will usually cause multi-page matching to fail.
2879 .PP
2880 This emphasizes the fact that searching in the
2881 formatted text (the DVI output) works differently from
2882 searching in the source text: Searching in the DVI file makes it easier to
2883 skip formatting instructions, and makes it possible to search for e.g.\&
2884 hyphenation and equation numbers; but sometimes the
2885 formatting results can also get in the way, e.g. in the case of
2886 footnotes. In these cases it's better to search in the \*(Te\& source
2887 instead. The use of
2888 .I source specials
2889 will make switching between the
2890 xdvi display and the editor with the \*(Te\& source easier; see the
2891 section
2892 .B SOURCE SPECIALS
2893 below for more information on this.
2894 .PP
2895 The text extracted from the DVI file is in encoded in UTF-8
2896 (you can view that text by saving the file in UTF-8 format via the
2897 .I File > Save as ...
2898 menu item).
2899 If xdvi has been compiled with locale,
2900 .I nl_langinfo()
2901 and
2902 .I iconv
2903 support, the search term is converted from the character set
2904 specified by the current locale into UTF-8. (See the output of
2905 .B locale -a
2906 for a list of locale settings available on your system).
2907 If
2908 .I nl_langinfo()
2909 is not available, but
2910 .I iconv
2911 is, you can specify the input encoding for
2912 .I iconv
2913 via the X resource
2914 .I textEncoding
2915 (see the output of
2916 .B iconv -l
2917 for a list of valid encodings). If
2918 .I iconv
2919 support is not available, only the encodings
2920 .I ISO-8859-1
2921 and
2922 .I UTF-8
2923 are supported (these names are case-insensitive).
2924 .PP
2925 Ideographic characters from CJKV fonts are treated specially: All white space
2926 (spaces and newlines) before and after such characters is ignored in
2927 the search string and in the DVI file.
2928 .PP
2929 To match a newline character, use \fI\en\fR in the search string;
2930 to match the string \fI\en\fR, use \fI\e\en\fR.
2931 .PP
2932 If the checkbox
2933 .I Regular Expression
2934 is activated, the string is treated as a regular expression in
2935 extended POSIX syntax, with the following properties:
2936 .RS 2
2937 .TP 2
2938 -
2939 \fIa?\fR matches \fIa\fR zero or one times.
2940 .TP
2941 -
2942 \fIa*\fR matches \fIa\fR zero or more times.
2943 .TP
2944 -
2945 \fIa+\fR matches \fIa\fR one or more times.
2946 Note that \fI*\fR and \fI+\fR are greedy, i.e. they match the longest possible substring.
2947 .TP
2948 -
2949 The pattern \fI.\fR matches any character except for newline. To also match a newline, use `\fI(.|\en)\fR'.
2950 .TP
2951 -
2952 \fIa{n}\fR matches \fIa\fR exactly n times.
2953 .TP
2954 -
2955 \fIa{n,m}\fR matches \fIa\fR at least n and no more than m times.
2956 .TP
2957 -
2958 \fIa|b\fR matches \fIa\fR or \fIb\fR. Brackets can be used
2959 for grouping, e.g.: \fI(a|b)|c\fR.
2960 .TP
2961 -
2962 The string matched by the nth group can be referenced by \fI\en\fR, e.g. \fI\e1\fR refers to the
2963 first match.
2964 .TP
2965 -
2966 The characters \fI^\fR and \fI$\fR match the beginning and the end of a line, respectively.
2967 .TP
2968 -
2969 \fI[abc]\fR matches any of the letters a, b, c, and \fI[a-z]\fR matches all characters from a to z.
2970 .TP
2971 -
2972 Each item in a regular expression can also be one of the following POSIX
2973 character classes:
2974 .br
2975 .nf
2976 .I [[:alnum:]] [[:alpha:]] [[:blank:]] [[:cntrl:]] [[:digit:]]
2977 .I [[:graph:]] [[:lower:]] [[:print:]] [[:space:]] [[:upper:]]
2978 .fi
2979
2980
2981 These can be negated by inserting a \fI^\fR symbol after the first bracket:
2982 .I [^[:alpha:]]
2983
2984 For more details on POSIX regular expressions, see e.g. the
2985 .B IEEE Std 1003.1
2986 standard definition available online from:
2987
2988 .nf
2989 http://www.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap09.html
2990 .fi
2991 .TP
2992 -
2993 As a non-standard extension, the following Perl-like abbreviations
2994 can be used instead of the POSIX classes:
2995 .nf
2996 .sp 1n
2997 .ta 1L +8L +30L
2998 Symbol Meaning POSIX Class
2999
3000 \fI\ew\fR an alphanumeric character \fI[[:alnum:]]\fR
3001 \fI\eW\fR a non-alphanumeric character \fI[^[:alnum:]]\fR
3002 \fI\ed\fR a digit character \fI[[:digit:]]\fR
3003 \fI\eD\fR a non-digit character \fI[^[:digit:]]\fR
3004 \fI\es\fR a whitespace character \fI[[:space:]]\fR
3005 \fI\eS\fR a non-whitespace character \fI[^[:space:]]\fR
3006 .sp 1n
3007 .fi
3008 .TP
3009 -
3010 The following characters are special symbols; they need to be escaped
3011 with \fI\e\fR in order to match them literally: \fI ( ) [ ] . * ? + ^ $ \e\fR.
3012 .TP
3013 -
3014 Matches of length zero are silently skipped.
3015 .RE
3016 .PP
3017 The dialog also provides checkboxes to:
3018 .RS 2
3019 .TP 2
3020 -
3021 search backwards;
3022 .TP
3023 -
3024 match in a case-sensitive manner (the default is to ignore case, i.e. a search
3025 string
3026 .I Test
3027 will match both the strings
3028 .I test
3029 and
3030 .I TEST
3031 in the DVI file);
3032 .TP
3033 -
3034 ignore line breaks and hyphens: This removes all hyphens at the ends
3035 of lines and the following newline characters, and replaces all
3036 remaining newline characters by white spaces. So hyphenated words will
3037 appear as one word to the search, and a search for two words with a space
3038 in between will also match the words if they are separated by a linebreak.
3039 .br
3040 Note that the hyphen removal may cause unwanted side effects for compound words
3041 containing hyphens that are wrapped after the hyphen, and that replacing the
3042 newlines affects the interpretation of regular expressions as follows:
3043 The \fI.\fR pattern will also match newlines, and \fI^\fR and \fI$\fR won't match
3044 begin and end of lines any more. (Since currently there is no option for turning
3045 off the greediness of \fI*\fR and \fI+\fR, turning on this option will usually
3046 result in matches that are longer than desired.)
3047 .RE
3048 .PP
3049 The current checkbox settings are saved in the
3050 .I ~/.xdvirc
3051 file.
3052 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3053 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3054 .SH PRINT DIALOG
3055 The print dialog window allows you to print all pages, marked pages
3056 (click or drag Mouse-2 in the page list to mark them), or a range
3057 of pages. Note that the page numbers always refer to physical pages,
3058 so if you're using the option `use TeX pages', you may want to disable
3059 it to make it easier to determine the correct page numbers (or avoid this
3060 problem altogether by marking the pages to be printed).
3061 .PP
3062 The value of the
3063 .B Printer
3064 text filed is passed to
3065 .B dvips
3066 via the
3067 .B -o!
3068 mechanism, as a single argument after the `!'. Any arguments
3069 listed in the
3070 .B Dvips options
3071 field are segmented at whitespace and passed as separate arguments to dvips.
3072 If you e.g. want to print the file 2-up, you should enter
3073 the following string into the
3074 .B Printer
3075 field:
3076 .RS 5
3077 .nf
3078 .sp 1n
3079 \fIpsnup -2 -q | lpr -Plp\fP
3080 .sp 1n
3081 .fi
3082 .RE
3083 .PP
3084 There are several resources for customizing the behaviour and the default entries
3085 of the print dialog:
3086 .TP
3087 .B dvipsPrinterString
3088 .TP
3089 .B dvipsOptionsString
3090 These can be used to provide default entries for the
3091 .B Printer
3092 and the
3093 .B Dvips options
3094 text fields, respectively. If no paper size is specified in the DVI file
3095 (via e.g. \eusepackage[dvips]{geometry} - this is the preferred method),
3096 the input field is initialized with the current value of the
3097 command line option/X resource
3098 .BR paper .
3099 E.g. the option
3100 .I -paper a4r
3101 is translated into the dvips options
3102 .IR "-t a4 -t landscape" .
3103 Note that no check is performed whether dvips actually understands these
3104 options (it will ignore them if it can't); currently not all options
3105 used by xdvi are also covered by dvips.
3106 .TP
3107 .B dvipsHangTime
3108 .TP
3109 .B dvipsFailHangTime
3110 These specify the time (in milliseconds) that the printing progress window will
3111 stay open after the
3112 .B dvips
3113 process has terminated. The value of
3114 .B dvipsHangTime
3115 is used if the process terminates successfully;
3116 .B dvipsFailHangTime
3117 is used if it terminates with an error. The default values are 1.5 and 5 seconds, respectively.
3118 If both values are negative, the window will stay open until it is closed by the user.
3119 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3120 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3121 .SH SAVE DIALOG
3122 This dialog allows you to save all or selected/marked pages in the current
3123 DVI file. You can save in one of the following formats:
3124 .RS 2
3125 .TP 2
3126 -
3127 PostScript (uses
3128 .B dvips
3129 to convert the DVI file to a PostScript file, just like when printing
3130 to a PostScript file).
3131 .TP
3132 -
3133 PDF (first uses
3134 .B dvips
3135 to convert the DVI file to a PostScript file, then uses
3136 .B ps2pdf
3137 to convert the PostScript file to PDF).
3138 .TP
3139 -
3140 Plain text in ISO-8859-1 or UTF-8 encoding. The latter will preserve more
3141 of the special LaTeX characters e.g. from mathematical mode. Note however
3142 that e.g. only few of LaTeX's mathematical symbols can be rendered correctly
3143 as text; so this functionality works best for plain text documents.
3144 If a character cannot be displayed in the selected
3145 charset, it is replaced by `\e' followed by the hexadecimal character code.
3146 If a character is not recognized at all, it is replaced by `?'.
3147 .RE
3148 .PP
3149 The programs for PostScript and PDF conversion can be customized via
3150 the command line options or X resources
3151 .BR -dvipspath / .dvipsPath
3152 and
3153 .BR -ps2pdfpath / .ps2pdfPath ,
3154 respectively; see the explanation of these options above for more details.
3155 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3156 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3157 .SH MODES
3158 The keystroke
3159 .B Ctrl-m
3160 [\fBswitch-mode()\fR]
3161 switches between three different mouse bindings,
3162 which can also be activated via the
3163 .B Modes
3164 menu (in Motif, this is a submenu of the
3165 .B Options
3166 menu called
3167 .BR "Mouse Mode" ).
3168 The default mode at startup can be customized via the X resource
3169 .B mouseMode
3170 or the command-line option
3171 .BR \-mousemode .
3172 The default startup mode is Magnifier Mode.
3173 .PP
3174 .B Note:
3175 The modes are implemented by changing the
3176 .I magnifier()
3177 action. Switching the mode will not work if
3178 .B Mouse-1
3179 has been customized to an action sequence that does
3180 not contain the magnifier() action.
3181 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3182 .TP
3183 .B "Magnifier Mode"
3184 In this mode, the mouse buttons 1 to 5 pop up a ``magnifying glass''
3185 that shows an unshrunken image of the page (i.e. an image at the resolution
3186 determined by the option/X resource
3187 .B pixels
3188 or
3189 .BR mfmode )
3190 at varying sizes. When the magnifier is moved, small ruler-like
3191 tick marks are displayed at the edges of the magnifier (unless
3192 the X resource
3193 .B delayRulers
3194 is set to false, in which case the tick marks are always displayed).
3195 The unit of the marks is determined by the X resource
3196 .B tickUnits
3197 (mm by default). This unit can be changed at runtime via the action
3198 .BR switch-magnifier-units() ,
3199 by default bound to the keystroke
3200 .RB ` t '
3201 (see the description of that key, and of switch-magnifier-units() for
3202 more details on the units available).
3203 .br
3204 The length of the tick marks can be changed via the X resource
3205 .B tickLength
3206 (4 by default). A zero or negative value suppresses the tick marks.
3207 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3208 .TP
3209 .B "Text Selection Mode"
3210 This mode allows you to select a rectangular region of text in the DVI
3211 file by holding down
3212 .B Mouse-1
3213 and moving the mouse. The text is put into
3214 the X primary selection so that it can be pasted into other X applications
3215 with
3216 .B Mouse-2
3217 as usual.
3218 .br
3219 If xdvi has been compiled with locale,
3220 .I nl_langinfo()
3221 and
3222 .I iconv
3223 support, the selected text is converted into the character set of the
3224 current locale (see the output of
3225 .B locale -a
3226 for a list of locale settings available on your system).
3227 If
3228 .I nl_langinfo()
3229 is not available, but
3230 .I iconv
3231 is, you can specify the input encoding for
3232 .I iconv
3233 via the X resource
3234 .I textEncoding
3235 (see the output of
3236 .B iconv -l
3237 for a list of valid encodings). If
3238 .I iconv
3239 support is not available, only the encodings
3240 .I ISO-8859-1
3241 and
3242 .I UTF-8
3243 are supported (these names are case-insensitive).
3244 .br
3245 Note that UTF-8 is
3246 the only encoding that can render all characters (e.g. mathematical
3247 symbols) of a DVI file. If ISO-8859-1 is active, characters that cannot be displayed
3248 are replaced by `\e' followed by the hexadecimal character code.
3249 For other encodings, such characters may trigger iconv error messages.
3250 If a character is not recognized at all, it is replaced by `?'.
3251 .br
3252 To extract larger portions of text, you can alternatively
3253 save selected pages or the entire file in text format via the
3254 .B File > Save as ...
3255 menu.
3256 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3257 .TP
3258 .B "Ruler Mode"
3259 This mode provides a simple way of measuring distances on the page.
3260 .br
3261 When this mode is activated, the mouse cursor changes into a
3262 thin cross, and a larger, cross-shaped ruler is drawn in the
3263 highlight color at the mouse location. The ruler doesn't have
3264 units attached to it; instead, the current distance between the
3265 ruler and the mouse cursor is continuously printed to the
3266 statusline.
3267 .br
3268 When activating Ruler Mode, the ruler is at first attached to
3269 the mouse and can be moved around. It can then be positioned at
3270 a fixed place by clicking
3271 .BR Mouse-1 .
3272 After that, the mouse cursor
3273 can be moved to measure the horizontal
3274 .RI ( dx ),
3275 vertical
3276 .RI ( dy )
3277 and direct (shortest)
3278 .RI ( dr )
3279 distance between the ruler center point and the mouse.
3280 .br
3281 Clicking
3282 .B Mouse-1
3283 again will move the ruler to the current mouse
3284 position, and holding down
3285 .B Mouse-1
3286 will drag the ruler around.
3287 .br
3288 In Ruler Mode, the following special keybindings extend or
3289 replace the default bindings:
3290 .RS 7
3291 .TP 7
3292 .B o
3293 .RB [ ruler-snap-origin() ]
3294 Snap the ruler back to the origin coordinate (0,0).
3295 .TP
3296 .B t
3297 \fR[overrides \fBswitch-magnifier-units()\fP]
3298 Toggle between various ruler units, which can be specified by the X
3299 resource
3300 .B tickUnits
3301 (`mm' by default).
3302 .TP
3303 .B P
3304 \fR[overrides \fBdeclare-page-number()\fP]
3305 Print the distances shown in the statusline to standard output.
3306 .RE
3307 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3308 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3309 .SH TOOLBAR (Motif only)
3310 The Motif toolbar can also be customized. The XPM file used for the
3311 toolbar icons can be specified via the resource
3312 .BR toolbarPixmapFile ,
3313 which should contain a filename that can be found in one of
3314 .B XFILESEARCHPATH
3315 or
3316 .B XDVIINPUTS
3317 (see the section
3318 .B FILE SEARCHING
3319 below for more information on these variables).
3320 .B Xdvi
3321 will try to split this pixmap horizontally into
3322 .I n
3323 pieces, where each piece is as wide as the pixmap is high
3324 and is treated as an image for toolbar button
3325 .IR n .
3326 This means that each icon should be a square, and that the entire
3327 pixmap should have width
3328 \fIn\fR x \fIh\fR if \fIh\fR is the height of the pixmap.
3329 .PP
3330 The resource
3331 .B toolbarTranslations
3332 can be used to map icons/buttons to specific actions.
3333 The resource should contain a string separated by newline characters,
3334 similar to the resources
3335 .B mainTranslations
3336 and
3337 .BR menuTranslations .
3338 Every line must contain either a spacer definition, or an icon definition:
3339 .PP
3340 A spacer definition is a string \fBSPACER(\fIn\fB)\fR,
3341 where
3342 .I n
3343 is the number of pixels inserted as separator to the following button.
3344 .PP
3345 An icon definition is a colon-separated list containing the following elements:
3346 .RS 2
3347 .TP 2
3348 .SB - the index of an icon in the pixmap file (starting from zero);
3349 .TP
3350 .SB - a long tooltip string, displayed in the status area;
3351 .TP
3352 .SB - a short tooltip string, displayed as popup;
3353 .TP
3354 .SB - a sequence of actions to be performed when the corresponding toolbar button is pushed.
3355 .RE
3356 .PP
3357 To illustrate this, the default value of
3358 .B toolbarTranslations
3359 looks as follows:
3360 .RS 5
3361 .nf
3362 .ft 3
3363 .sp 1n
3364 xdvi.toolbarTranslations: \e
3365 SPACER(5)\en\e
3366 0:Open a new document (Key\e\e: Ctrl-f):\e
3367 Open file:select-dvi-file()\en\e
3368 SPACER(10)\en\e
3369 1:Reread this document (Key\e\e: R):\e
3370 Reread file:reread-dvi-file()\en\e
3371 SPACER(10)\en\e
3372 2:Go to the first page of this document (Key\e\e: 1g):\e
3373 Go to first page:goto-page(1)\en\e
3374 3:Go to the previous page of this document (Key\e\e: p):\e
3375 Go to previous page:back-page(1)\en\e
3376 4:Go to the next page of this document (Key\e\e: n):\e
3377 Go to next page:forward-page(1)\en\e
3378 5:Go to the last page of this document (Key\e\e: g):\e
3379 Go to last page:goto-page()\en\e
3380 SPACER(10)\en\e
3381 6:Enlarge the display (Key\e\e: Ctrl-+):Zoom in:\e
3382 set-shrink-factor(+)\en\e
3383 7:Shrink the display (Key\e\e: Ctrl--):Zoom out:\e
3384 set-shrink-factor(-)\en\e
3385 SPACER(10)\en\e
3386 8:Jump back to the previous hyperlink (Key\e\e: B):\e
3387 Back hyperlink:htex-back()\en\e
3388 SPACER(10)\en\e
3389 10:Print this document:Print:print()\en\e
3390 SPACER(10)\en\e
3391 11:Toggle marks for odd pages (Key\e\e: 1m):\e
3392 Toggle odd:toggle-mark(1)\en\e
3393 12:Toggle marks for even pages (Key\e\e: 2m):\e
3394 Toggle even:toggle-mark(2)\en\e
3395 13:Toggle mark for current page (Key\e\e: 2m):\e
3396 Toggle current:toggle-mark()\en\e
3397 14:Unmark all pages (Key\e\e: 0m):\e
3398 Unmark all:toggle-mark(0)\en\e
3399 SPACER(10)\en\e
3400 18:Display fonts darker (Key\e\e: Alt-Ctrl-+):\e
3401 Fonts darker:change-density(5)\en\e
3402 19:Display fonts lighter (Key\e\e: Alt-Ctrl--):\e
3403 Fonts lighter:change-density(-5)\en
3404 .sp 1n
3405 .ft
3406 .fi
3407 .RE
3408 .PP
3409 When the mouse remains over a toolbar button for a certain period, a `tooltip'
3410 window is shown, describing what the button does using the
3411 .I short tooltip string
3412 from the above resource. At the same time, the
3413 .I long tooltip string
3414 is displayed in the statusline.
3415 The appearance and behaviour of these tooltips can be customized via
3416 the following resources:
3417 .TP
3418 .B tipShell.background
3419 Background color of the tooltip window.
3420 .TP
3421 .B tipShell.fontSet
3422 Font used for the tooltip.
3423 .TP
3424 .B tipShell.waitPeriod
3425 The time (in milliseconds) the mouse pointer needs to be over
3426 the button before the tooltip is shown. Set it to a negative value
3427 to suppress the tooltips altogether.
3428
3429 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3430 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3431 .SH GREYSCALING AND COLORMAPS
3432 The greyscale anti-aliasing feature in
3433 .B xdvi
3434 will not work at its best if the display does not have enough colors available.
3435 This can happen if other applications are using most of the colormap
3436 (even if they are iconified). If this occurs, then
3437 .B xdvi
3438 will print an error message and turn on the
3439 .B -copy
3440 option. This will result in overstrike characters appearing wrong;
3441 it may also result in poor display quality if the number of available
3442 colors is very small.
3443 .PP
3444 Typically this problem occurs on displays that allocate eight bits
3445 of video memory per pixel. To see how many bits per pixel your display
3446 uses, type
3447 .B xwininfo
3448 in an
3449 .B xterm
3450 window, and then click the mouse on the root window when asked. The
3451 ``Depth:'' entry will tell you how many bits are allocated per pixel.
3452 .PP
3453 Displays using at least 15 bits per pixel are typically
3454 .B TrueColor
3455 visuals, which do not have this problem, since their colormap is
3456 permanently allocated and available to all applications. (The visual
3457 class is also displayed by
3458 .BR xwininfo .)
3459 For more information on visual classes see the documentation for the
3460 X Window System.
3461 .PP
3462 To alleviate this problem, therefore, one may (a) run with more bits
3463 per pixel (this may require adding more video memory or replacing the video
3464 card), (b) shut down other applications that may be using much of the colormap
3465 and then restart
3466 .BR xdvi ,
3467 or (c) run
3468 .B xdvi
3469 with the
3470 .B \-install
3471 option.
3472 .PP
3473 One application which is often the cause of this problem is
3474 .BR Netscape .
3475 In this case there are two more alternatives to remedying the situation.
3476 One can run
3477 .RB `` "netscape -install" ''
3478 to cause
3479 .B Netscape
3480 to install a private colormap. This can cause colors to change in
3481 bizarre ways when the mouse is moved to a different window.
3482 Or, one can run
3483 .RB `` "netscape -ncols 220" ''
3484 to limit
3485 .B Netscape
3486 to a smaller number of colors. A smaller number will ensure that
3487 other applications have more colors available, but will degrade the
3488 color quality in the
3489 .B Netscape
3490 window.
3491
3492 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3493 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3494 .SH HANDLING OF POSTSCRIPT FIGURES
3495 .B Xdvi
3496 can display Encapsulated PostScript (EPS) files included in the
3497 .I dvi
3498 file. Such files are first searched for in the directory where the
3499 .I dvi
3500 file is, and then using normal
3501 .B Kpathsea
3502 rules. There is an exception to this, however: if the file name begins
3503 with a backtick
3504 .RB ( ` ),
3505 then the remaining characters in the file name give a shell command (often
3506 .BR zcat )
3507 which is executed; its standard output is then sent to be interpreted as
3508 PostScript.
3509 Since the execution of arbitrary shell commands with the user's
3510 permissions is a huge security risk, evaluation of these backtick
3511 commands is disabled by default. It needs to be activated via the
3512 .B \-allowshell
3513 command-line option.
3514 .B NOTE:
3515 You should never use this option when viewing documents that you
3516 didn't compile yourself. The backtick specials are not needed for
3517 uncompressing gzipped PostScript files, since
3518 .B xdvi
3519 can do that on the fly if the filename ends with
3520 .I .eps.gz
3521 or
3522 .I .eps.Z
3523 (and if the first bytes of the file indicate that the file is indeed
3524 compressed). This is both safer and more flexible than the backtick
3525 approach, since the default file searching rules will apply to such
3526 filenames too.
3527 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3528 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3529 .SH TYPE 1 FONTS
3530 Using FreeType (version 2),
3531 .B xdvi
3532 can render PostScript<tm> Type 1 fonts directly, without the
3533 route via \*(Te\& pixel (pk)
3534 fonts. The advantage of this is that only one size of each font needs
3535 to be stored on disk.
3536 Unless the
3537 .B -notype1fonts
3538 option is used,
3539 .B xdvi
3540 will try to render every font using FreeType. Only as a fallback will it
3541 invoke an external program (like
3542 .BR mktexpk ,
3543 which in turn may invoke utilities like
3544 .B ps2pk
3545 or
3546 .BR gsftopk )
3547 to generate a pixel font from the Type 1 source. The direct rendering
3548 of the
3549 .B Computer Modern
3550 fonts should work out-of-the box, whereas other Type 1 fonts such as
3551 the 35 `standard' PostScript<tm> fonts resident in printers may need
3552 to be made accessible for use with
3553 .BR xdvi ,
3554 unless your system
3555 administrator or TeX distribution has already done so (which is the case
3556 e.g. for current TeX Live systems). For the 35 PostScript<tm> resident
3557 fonts,
3558 .B xdvik
3559 will search using the
3560 .B Fontmap
3561 provided with
3562 .BR Ghostscript ,
3563 if necessary. Also, the
3564 .B xdvik
3565 distribution comes with a utility called
3566 .B t1mapper
3567 to make these fonts available for xdvi;
3568 see the manual page for t1mapper(1) for usage details. This program is
3569 likely to be dropped in the future, however, since it is probably not
3570 needed anymore.
3571 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3572 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3573 .SH SPECIALS (GENERALLY)
3574 Any of the specials used by
3575 .B xdvi
3576 may be preceded by the characters
3577 .RB `` xdvi: ''.
3578 Doing so does not change the behavior of the special under
3579 .BR xdvi ,
3580 but it tells other dvi drivers (such as e.g. dvips) to ignore the special.
3581 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3582 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3583 .SH SOURCE SPECIALS
3584 Some \*(Te\& implementations or macro packages provide the facility to
3585 automatically include so-called `source specials' into a DVI file.
3586 These contain the line number, eventually a column number, and the
3587 filename of the .tex source. This makes it possible to jump from a .dvi
3588 file to the corresponding place in the .tex source and vice versa (also
3589 called `inverse search' - jumping from the DVI file to the TeX file is
3590 also known as `reverse search', and jumping from the TeX file to the
3591 DVI file as `forward search').
3592 .P
3593 To be usable with
3594 .BR xdvi ,
3595 source specials in the
3596 .I dvi
3597 file must have one of the following formats:
3598 .RS 5
3599 .nf
3600 .sp 1n
3601 \fBsrc:\fP\fIline\fP[ ]\fIfilename\fP
3602 \fBsrc:\fP\fIline\fP\fB:\fP\fIcol\fP[ ]\fIfilename\fP
3603 \fBsrc:\fP\fIline\fP
3604 \fBsrc:\fP\fIline\fP\fB:\fP\fIcol\fP
3605 \fBsrc::\fP\fIcol\fP
3606 .sp 1n
3607 .fi
3608 .RE
3609 If
3610 .I filename
3611 or
3612 .I line
3613 are omitted, the most recent values are used. The first source special on
3614 each page must be in one of the first two forms, since defaults are not
3615 inherited across pages.
3616 .sp
3617 You will need a \*(Te\& implementation that provides an appropriate
3618 switch (e.g.\&
3619 .IR -src )
3620 or a macro package
3621 (such as
3622 .I srcltx.sty
3623 or
3624 .IR srctex.sty ,
3625 available from CTAN:macros/latex/contrib/supported/srcltx/)
3626 to insert such source specials into the DVI file.
3627 .sp
3628 For reverse search, the combination
3629 .I Ctrl-Mouse 1
3630 will make xdvi open an editor (the value of the
3631 .I \-editor
3632 command line option) with the file and the line number of the .tex
3633 source. See the description of the
3634 .I \-editor
3635 option for more information
3636 and example settings.
3637 .P
3638 For forward search,
3639 .B xdvi
3640 has a
3641 .I \-sourceposition
3642 option that makes
3643 .B xdvi
3644 jump to the page in
3645 the DVI file corresponding to the given line (or the closest
3646 line having a source special) of the specified file and highlight
3647 the found region. See the description of the
3648 .I \-sourceposition
3649 option for more details.
3650 .PP
3651 More information on setting up various editors for use with source
3652 specials can be found at:
3653 .RS 5
3654 .nf
3655 .sp 1n
3656 http://xdvi.sourceforge.net/inverse-search.html
3657 .sp 1n
3658 .fi
3659 .RE
3660 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3661 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3662 .SH PAPERSIZE SPECIALS
3663 .B xdvi
3664 accepts specials to set the paper size for the document. These specials
3665 should be of the form
3666 .RS 5
3667 .nf
3668 .sp 1n
3669 \fBpapersize=\fP[\fB*\fP]\fIwidth\fP,\fIheight\fP
3670 .sp 1n
3671 .fi
3672 .RE
3673 .PP
3674 where
3675 .I width
3676 and
3677 .I height
3678 give the width and height of the paper, respectively. Each of these should
3679 appear in the form of a decimal number followed by any of the two-letter
3680 abbreviations for units accepted by \*(Te\&
3681 .RB ( pt ,
3682 .BR pc ,
3683 .BR in ,
3684 .BR bp ,
3685 .BR cm ,
3686 .BR mm ,
3687 .BR dd ,
3688 .BR cc ,
3689 or
3690 .BR sp ).
3691 If an asterisk
3692 .RB ( * )
3693 appears just before the width, then the measurements refer to the document
3694 dimensions (e.g.\&
3695 .B pt
3696 as opposed to
3697 .BR truept ).
3698 This allows a macro package to vary the page size according to elements
3699 of the document; e.g.\&
3700 .RS 5
3701 .ft 3
3702 .nf
3703 .sp 1n
3704 \especial{xdvi: papersize=*\enumber\ewd\emybox sp,
3705 \enumber\eht\emybox sp}
3706 .sp 1n
3707 .ft
3708 .fi
3709 .RE
3710 .PP
3711 Except for the asterisk, this format is compatible with
3712 .BR dvips .
3713 .P
3714 The last
3715 .B papersize
3716 special on a page determines the size of that page. If there is no such
3717 special on a given page, the most recent
3718 .B papersize
3719 is used, or, if there are no
3720 .B papersize
3721 specials on any preceding page, then the value of the
3722 .B paper
3723 resource (or
3724 .B \-paper
3725 option on the command line) is used. Thus the paper size may vary for
3726 different pages of the
3727 .I dvi
3728 file.
3729 .P
3730 If the
3731 .B paper
3732 resource (or
3733 .B \-paper
3734 command-line option) begins with a plus sign
3735 .RB (` + '),
3736 then all
3737 .B papersize
3738 specials in the
3739 .I dvi
3740 file are ignored.
3741 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3742 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3743 .SH COLOR SPECIALS
3744 The color specials supported by
3745 .B xdvi
3746 are the same as those supported by
3747 .BR dvips ,
3748 except that the literal PostScript color specification (as in the
3749 .B AggiePattern
3750 example in the
3751 .B dvips
3752 documentation) is not supported.
3753 There are also some restrictions due to the way xdvi's drawing routines
3754 are implemented; e.g. the
3755 .B \ecolorbox
3756 and
3757 .B \efcolorbox
3758 macros don't work with
3759 .BR xdvi .
3760 See the section LIMITATIONS below for more information on these restrictions.
3761 .B Xdvi
3762 supports the same list of named colors as
3763 .B dvips
3764 does, namely:
3765 .P
3766 .BR Apricot ,
3767 .BR Aquamarine ,
3768 .BR Bittersweet ,
3769 .BR Black ,
3770 .BR Blue ,
3771 .BR BlueGreen ,
3772 .BR BlueViolet ,
3773 .BR BrickRed ,
3774 .BR Brown ,
3775 .BR BurntOrange ,
3776 .BR CadetBlue ,
3777 .BR CarnationPink ,
3778 .BR Cerulean ,
3779 .BR CornflowerBlue ,
3780 .BR Cyan ,
3781 .BR Dandelion ,
3782 .BR DarkOrchid ,
3783 .BR Emerald ,
3784 .BR ForestGreen ,
3785 .BR Fuchsia ,
3786 .BR Goldenrod ,
3787 .BR Gray ,
3788 .BR Green ,
3789 .BR GreenYellow ,
3790 .BR JungleGreen ,
3791 .BR Lavender ,
3792 .BR LimeGreen ,
3793 .BR Magenta ,
3794 .BR Mahogany ,
3795 .BR Maroon ,
3796 .BR Melon ,
3797 .BR MidnightBlue ,
3798 .BR Mulberry ,
3799 .BR NavyBlue ,
3800 .BR OliveGreen ,
3801 .BR Orange ,
3802 .BR OrangeRed ,
3803 .BR Orchid ,
3804 .BR Peach ,
3805 .BR Periwinkle ,
3806 .BR PineGreen ,
3807 .BR Plum ,
3808 .BR ProcessBlue ,
3809 .BR Purple ,
3810 .BR RawSienna ,
3811 .BR Red ,
3812 .BR RedOrange ,
3813 .BR RedViolet ,
3814 .BR Rhodamine ,
3815 .BR RoyalBlue ,
3816 .BR RoyalPurple ,
3817 .BR RubineRed ,
3818 .BR Salmon ,
3819 .BR SeaGreen ,
3820 .BR Sepia ,
3821 .BR SkyBlue ,
3822 .BR SpringGreen ,
3823 .BR Tan ,
3824 .BR TealBlue ,
3825 .BR Thistle ,
3826 .BR Turquoise ,
3827 .BR Violet ,
3828 .BR VioletRed ,
3829 .BR White ,
3830 .BR WildStrawberry ,
3831 .BR Yellow ,
3832 .BR YellowGreen ,
3833 .BR YellowOrange .
3834 .P
3835 Note that these names are case sensitive.
3836 .P
3837 The documentation of the La\*(Te\&
3838 .B color
3839 package provides more details on how to use such specials with
3840 La\*(Te\&; see the
3841 .B dvips
3842 documentation for a detailed description of the
3843 syntax and semantics of the color specials.
3844 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3845 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3846 .SH SIGNALS
3847 When
3848 .B xdvi
3849 receives a
3850 .SB SIGUSR1
3851 signal, it rereads the
3852 .I dvi
3853 file.
3854 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3855 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3856 .SH ENVIRONMENT
3857 .B Xdvik
3858 uses the same environment variables and algorithms for searching for
3859 font files as \*(Te\& and friends. See the documentation for the
3860 .B Kpathsea
3861 library,
3862 .BR kpathsea.dvi ,
3863 for a detailed description of these.
3864 .PP
3865 In addition,
3866 .B xdvik
3867 accepts the following variables:
3868 .TP
3869 .SB DISPLAY
3870 Specifies which graphics display terminal to use.
3871 .TP
3872 .SB KPATHSEA_DEBUG
3873 Trace
3874 .B Kpathsea
3875 lookups; set it to
3876 .B -1
3877 (= all bits on) for complete tracing.
3878 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3879 .TP
3880 .SB EXTENSIONMAPS
3881 A list of files to be searched for mime types entries (as for Acrobat Reader).
3882 Earlier entries in one of these files override later ones.
3883 If this variable is not set, the following default path is used:
3884 .RS 7
3885 .nf
3886 .ft 3
3887 .sp 1n
3888 $HOME/.mime.types:/etc/mime.types:\e
3889 /usr/etc/mime.types:/usr/local/etc/mime.types
3890 .sp 1n
3891 .ft
3892 .fi
3893 .RE
3894
3895 .TP
3896 .SB MAILCAPS
3897 A list of files to be searched for mailcap entries, as defined by RFC
3898 1343. See this RFC or the
3899 .BR mailcap (4)
3900 manual page for a detailed description of the mailcap file format.
3901 Currently, only the following mailcap features are supported:
3902 .RS 7
3903 .TP 7
3904 .BI test= command
3905 The entry is only used if
3906 .I command
3907 can be executed via the
3908 .B system()
3909 call and if the system() call returns with value 0 (success).
3910 The
3911 .I command
3912 string may contain the format string
3913 .IR %s ,
3914 which will be replaced by the file name.
3915 .TP
3916 .B needsterminal
3917 If this flag is used, the command will be executed in a new xterm
3918 window by prepending
3919 .RI `` "xterm -e "''
3920 to the command string.
3921 .RE
3922 .PP
3923 .RS 7
3924 All other fields in the mailcap entry are ignored by xdvi.
3925 Earlier entries in one of these files override later ones.
3926 If the variable is not defined, the following default path is used:
3927 .RS 4
3928 .nf
3929 .ft 3
3930 .sp 1n
3931 $HOME/.mailcap:/etc/mailcap:/usr/etc/mailcap:\e
3932 /usr/local/etc/mailcap
3933 .sp 1n
3934 .ft
3935 .fi
3936 .RE
3937 .br
3938 For security reasons, some special characters (i.e. ( ) ` \e ;)
3939 are escaped in the argument before passing it to
3940 .BR system() .
3941 .RE
3942 .TP
3943 .SB BROWSER
3944 Determines the web browser used to open external links (i.e. all URLs
3945 that don't start with the
3946 .RI ` file: '
3947 scheme and are not relative links in the local DVI file), and to open links
3948 for which no viewer has been specified in the
3949 .B mailcap
3950 files. The value of this variable is a colon-separated list of commands. Xdvi
3951 will try each of them in sequence until one succeeds (i.e. doesn't immediately
3952 return with status 0). This allows you to
3953 specify your favourite browser at the beginning,
3954 and fallback browsers at the end. Every occurrence of
3955 .I %s
3956 in the string is replaced by the target URL; every occurrence of
3957 .I %%
3958 is replaced by a single
3959 .IR % .
3960 If no
3961 .I %s
3962 is present, the URL string is added as an extra argument.
3963 .br
3964 An example setting is:
3965 .RS 7
3966 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3967 .TP 7
3968 .SB "netscape -raise -remote 'openURL(%s,new-window)':xterm -e lynx %s:xterm -e wget %s:lynx %s:wget %s"
3969 .TP
3970 See
3971 .TP
3972 .SB http://www.catb.org/~esr/BROWSER/
3973 .PP
3974 for more details on the
3975 .B BROWSER
3976 environment variable.
3977 .RE
3978 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3979 .TP
3980 .SB GS_LIB
3981 A colon-separated list of directories to search for
3982 .B Fontmap
3983 files, etc., as used for Ghostscript. It has the same meaning as it does
3984 when running Ghostscript. In
3985 .BR xdvik ,
3986 it is used when searching for font files when the map file does not give a
3987 file name for the font (this should be quite rare). The command
3988 .B gs \-h
3989 will list the default value that Ghostscript uses. See also the
3990 .SB XDVI_GS_LIB
3991 environment variable (below).
3992 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3993 .TP
3994 .SB XDVI_GS_LIB
3995 This has the same effect as
3996 .SB GS_LIB
3997 but affects only
3998 .BR xdvi .
3999 Use this when you want to use a different value for
4000 .SB GS_LIB
4001 when running
4002 .BR xdvi ,
4003 but use either the compiled-in default value or some other value when running
4004 Ghostscript. If both
4005 .SB GS_LIB
4006 and
4007 .SB XDVI_GS_LIB
4008 are set, then
4009 .B xdvi
4010 uses
4011 .SB XDVI_GS_LIB.
4012 To use the default value compiled in to
4013 .B xdvi
4014 while still retaining the ability to set
4015 .SB GS_LIB
4016 for use with Ghostscript, you can set
4017 .SB XDVI_GS_LIB
4018 to the empty string.
4019 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4020 .TP
4021 .SB TMPDIR
4022 The directory to use for storing temporary files created when uncompressing
4023 PostScript files.
4024 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4025 .TP
4026 .SB XEDITOR
4027 Determines the editor command used for source special `reverse
4028 search', if neither the
4029 .I \-editor
4030 command-line option
4031 nor the
4032 .I .editor
4033 resource are specified. See the description of the
4034 .I \-editor
4035 command line option for details on the format.
4036 .TP
4037 .SB VISUAL
4038 Determines an editor to be opened in an xterm
4039 window if neither of
4040 .IR -editor ,
4041 .IR .editor ,
4042 or
4043 .I XEDITOR
4044 is specified.
4045 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4046 .TP
4047 .SB EDITOR
4048 Determines an editor to be opened in an xterm
4049 window if neither of
4050 .IR -editor ,
4051 .IR .editor ,
4052 .I XEDITOR
4053 or
4054 .I VISUAL
4055 is specified.
4056 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4057 .TP
4058 .SB WWWBROWSER
4059 Obsolete; use
4060 .B BROWSER
4061 instead.
4062 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4063 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4064 .SH LIMITATIONS
4065 .B xdvi
4066 accepts many but not all types of PostScript specials accepted by
4067 .BR dvips .
4068 For example, it accepts most specials generated by
4069 .B epsf
4070 and
4071 .BR psfig .
4072 It does not, however, support
4073 .B bop\-hook
4074 or
4075 .BR eop\-hook ,
4076 nor does it allow PostScript commands to affect the rendering of things that
4077 are not PostScript (for example, the ``NEAT'' and rotated ``A'' examples in the
4078 .B dvips
4079 manual). These restrictions are due to the design of
4080 .BR xdvi ;
4081 in all likelihood they will always remain.
4082 .PP
4083 La\*(Te\&2e rotation specials are currently not supported.
4084 .PP
4085 .B MetaPost
4086 files containing included text are not supported.
4087 .PP
4088 .BR Xdvi 's
4089 color handling doesn't support the
4090 .B \ecolorbox
4091 and
4092 .B \efcolorbox
4093 macros; this is not likely to change in the near future. This also
4094 means that e.g. colored tables (as created by the
4095 .I colortbl
4096 package) may render incorrectly: Text in colors different from the
4097 default foreground color may not be displayed. When the page is
4098 redrawn (e.g. after using the magnifier), the background color of the
4099 cells may overdraw the text.
4100 .SH FILES
4101 .TP
4102 .SB $HOME/.xdvirc
4103 A file that holds all settings that the user changed via the keys, the `Options'
4104 and the Xaw `Modes' menu and the dialogs, as X resources. These resources override the
4105 settings in
4106 .BR $HOME/.Xdefaults .
4107 This file is ignored if the
4108 .B \-q
4109 option is used or the
4110 .B noInitFile
4111 X resource is set.
4112 .TP
4113 .SB config.xdvi
4114 An optional configuration file for the Type 1 font setup, which specifies
4115 .BR dvips \-style
4116 map files specific to
4117 .BR xdvik .
4118 If used, it should be present in the directory determined by the
4119 .B TEXCONFIG
4120 environment variable. Its format is similar to configuration files for
4121 .BR dvips ,
4122 except that it is only scanned for the names of map files
4123 .RB ( p
4124 and
4125 .B p+
4126 directives).
4127 .SH SEE ALSO
4128 .BR X (1),
4129 .BR dvips (1),
4130 .BR mktexpk (1),
4131 .BR ps2pk (1),
4132 .BR gsftopk (1),
4133 .BR t1mapper (1),
4134 .BR mailcap (4),
4135 the
4136 .B Kpathsea
4137 documentation,
4138 .BR https://ctan.org/pkg/xdvi/ ,
4139 and the Xdvik home page at
4140 .BR http://xdvi.sourceforge.net/ .
4141 .SH AUTHORS
4142 Eric Cooper, CMU, did a version for direct output to a QVSS. Modified
4143 for X by Bob Scheifler, MIT Laboratory for Computer Science. Modified
4144 for X11 by Mark Eichin, MIT SIPB. Additional enhancements by many
4145 others.
4146 .PP
4147 The current maintainer of the original
4148 .B xdvi
4149 is Paul Vojta, U.C. Berkeley.
4150 .PP
4151 Code for the xdvik variant has been contributed
4152 by many people, whose names are scattered across the
4153 source files.
4154 .PP
4155 For the most up-to-date information, please visit:
4156 .PP
4157 .B http://xdvi.sourceforge.net
4158 .PP
4159 Please report all bugs to the SourceForge bug tracker:
4160 .PP
4161 .nf
4162 .B http://sourceforge.net/tracker/?func=add&group_id=23164&atid=377580
4163 .PP