From b04c2e1a42573e9735547702356c7b9a769a6855 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 7 Apr 2013 18:26:53 +0000 Subject: texmf -> texmf-dist: doc git-svn-id: svn://tug.org/texlive/trunk@29714 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/man/man1/xdvi.1 | 4075 +++++++++++++++++++++++++++++++++ 1 file changed, 4075 insertions(+) create mode 100644 Master/texmf-dist/doc/man/man1/xdvi.1 (limited to 'Master/texmf-dist/doc/man/man1/xdvi.1') diff --git a/Master/texmf-dist/doc/man/man1/xdvi.1 b/Master/texmf-dist/doc/man/man1/xdvi.1 new file mode 100644 index 00000000000..32933b9d63f --- /dev/null +++ b/Master/texmf-dist/doc/man/man1/xdvi.1 @@ -0,0 +1,4075 @@ +.\" Copyright (c) 1990-2004 Paul Vojta and others +.\" +.\" This is Paul's license, included here only for reference, it does not apply +.\" to all parts of the k version. +.\" ---- +.\" Permission is hereby granted, free of charge, to any person obtaining a copy +.\" of this software and associated documentation files (the "Software"), to +.\" deal in the Software without restriction, including without limitation the +.\" rights to use, copy, modify, merge, publish, distribute, sublicense, and/or +.\" sell copies of the Software, and to permit persons to whom the Software is +.\" furnished to do so, subject to the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included in +.\" all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +.\" PAUL VOJTA OR ANY OTHER AUTHOR OF THIS SOFTWARE BE LIABLE FOR ANY CLAIM, +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +.\" DEALINGS IN THE SOFTWARE. +.\" ---- +.\" This is the xdvik license: +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" following is UGLY ... use La\*(Te\& instead: +.\" .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 +.\" .if n .ds La LaTeX +.if t .ds Te T\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X +.if n .ds Te TeX +.\" # small and boldface (not all -man's provide it) +.de SB +\&\fB\s-1\&\\$1 \\$2\s0\fR +.. +.TH XDVI 1 "2012-04-01" "Xdvik 22.85" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +xdvi \- DVI Previewer for the X Window System +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.B xdvi +.nh +[\fB+\fP[\fIpage\fP]] +[\fB\--help\fP] +[\fB\-allowshell\fP] +[\fB\-altfont\fP \fIfont\fP] +[\fB\-bg\fP \fIcolor\fP] +[\fB\-browser\fP \fIWWWbrowser\fP] +[\fB\-copy\fP] +[\fB\-cr\fP \fIcolor\fP] +[\fB\-debug\fP \fIbitmask\fP|\fIstring[,string ...]\fP] +[\fB\-display\fP \fIhost:display\fP] +[\fB\-dvipspath\fP \fIpath\fP] +[\fB\-editor\fP \fIcommand\fP] +[\fB\-expert\fP] +[\fB\-expertmode\fP \fIflag\fP] +[\fB\-fg\fP \fIcolor\fP] +[\fB\-findstring\fP \fIstring\fP] +[\fB\-text-encoding\fP \fIencoding\fP] +[\fB\-font\fP \fIfont\fP] +[\fB\-fullscreen \fP] +[\fB\-gamma\fP \fIg\fP] +[\fB\-geometry\fP \fIgeometry\fP] +[\fB\-gsalpha\fP] +[\fB\-gspalette\fP \fIpalette\fP] +[\fB\-h\fP] +[\fB\-help\fP] +[\fB\-hl\fP \fIcolor\fP] +[\fB\-anchorposition\fP \fIanchor\fP] +[\fB\-hush\fP] +[\fB\-hushchars\fP] +[\fB\-hushchecksums\fP] +[\fB\-warnpecials\fP] +[\fB\-hushstdout\fP] +[\fB\-hushbell\fP] +[\fB\-icongeometry\fP \fIgeometry\fP] +[\fB\-iconic\fP] +[\fB\-install\fP] +[\fB\-interpreter\fP \fIpath\fP] +[\fB\-keep\fP] +[\fB\-l\fP] +[\fB\-license\fP] +[\fB\-linkcolor\fP \fIcolor\fP] +[\fB\-linkstyle\fP \fI0|1|2|3\fP] +[\fB\-margins\fP \fIdimen\fP] +[\fB\-mfmode\fP \fImode-def\fP[\fB:\fP\fIdpi\fP]] +[\fB\-mgs\fP[\fIn\fP] \fIsize\fP] +[\fB\-mousemode\fP \fI0|1|2\fP] +[\fB\-nocolor\fP] +[\fB\-nofork\fP] +[\fB\-noghostscript\fP] +[\fB\-nogrey\fP] +[\fB\-nogssafer\fP] +[\fB\-noinstall\fP] +[\fB\-nomakepk\fP] +[\fB\-nomatchinverted\fP] +[\fB\-noomega\fP] +[\fB\-noscan\fP] +[\fB\-not1lib\fP] +[\fB\-notempfile\fP] +[\fB\-offsets\fP \fIdimen\fP] +[\fB\-p\fP \fIpixels\fP] +[\fB\-paper\fP \fIpapertype\fP] +[\fB\-pause\fP] +[\fB\-pausespecial\fP \fIspecial-string\fP] +[\fB\-postscript\fP \fIflag\fP] +[\fB\-rulecolor\fP \fIcolor\fP] +[\fB\-rv\fP] +[\fB\-S\fP \fIdensity\fP] +[\fB\-s\fP \fIshrink\fP] +[\fB\-safer\fP] +[\fB\-sidemargin\fP \fIdimen\fP] +[\fB\-sourceposition\fP \fIline\fP[\fB:\fP\fIcol\fP][\ ]\fIfilename\fP] +[\fB\-statusline\fP] +[\fB\-thorough\fP] +[\fB\-topmargin\fP \fIdimen\fP] +[\fB\-unique\fP] +[\fB\-version\fP] +[\fB\-visitedlinkcolor\fP \fIcolor\fP] +[\fB\-warnspecials\fP] +[\fB\-watchfile\fP \fIsecs\fP] +[\fB\-wheelunit\fP \fIpixels\fP] +[\fB\-xoffset\fP \fIdimen\fP] +[\fB\-yoffset\fP \fIdimen\fP] +[\fIdvi_file\fP] +.hy +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.B Xdvi +is a program for previewing +.I dvi +files, as produced e.g. by the +.BR tex (1) +program, under the X window system. +.PP +.B Xdvi +can show the file shrunken by various +integer factors, and it has a ``magnifying glass'' for viewing +parts of the page enlarged (see the section MAGNIFIER below). This version +of +.B xdvi +is also referred to as +.B xdvik +since it uses the kpathsea library to locate and generate font files. +In addition to that, it supports the following features: +.RS 2 +.TP 2 +- +hyperlinks in DVI files (section HYPERLINKS), +.TP +- +direct rendering of Postscript Type1 fonts (section T1LIB), +.TP +- +source specials in the DVI file (section SOURCE SPECIALS), +.TP +- +string search in DVI files (section STRING SEARCH), +.TP +- +saving or printing (parts of) the DVI file (sections PRINT DIALOG and SAVE DIALOG). +.RE +.PP +.B Xdvi +can be compiled with the Motif toolkit or the Xaw (Athena) toolkit +(and variants of it), and the Motif version has a slightly different GUI; +these differences are noted below. +.PP +Before displaying a page of a DVI file, +.B xdvi +will check to see if the file has changed since the last time it was +displayed. If this is the case, it will reload the file. This +feature allows you to preview many versions of the same file while +running +.B xdvi +only once. Since it cannot read partial DVI files, +.B xdvik +versions starting from 22.74.3 will create a temporary copy of the +DVI file being viewed, to ensure that the file can be viewed without +interruptions. (The +.B \-notempfile +can be used to turn off this feature). +.PP +.B Xdvi +can show PostScript specials by any of three methods. +It will try first to use Display PostScript, then NeWS, then it +will try to use Ghostscript to render the images. All of these options +depend on additional software to work properly; moreover, some of them +may not be compiled into this copy of +.BR xdvi . +.PP +For performance reasons, +.B xdvi +does not render PostScript specials in the magnifying glass. +.PP +If no file name has been specified on the command line, +xdvi will try to open the most recently opened file; if the file +history (accessible via the +.B File > Open Recent +menu) is empty, or if none of the files in the history are valid DVI files, +it will pop up a file selector for choosing a file name. +(In previous versions, which didn't have a file history, the file selector +was always used; you can set the X resource +.B noFileArgUseHistory +to +.I false +to get back the old behaviour.) +.PP +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH OPTIONS +In addition to specifying the +.I dvi +file (with or without the +.B .dvi +extension), +.B xdvi +supports the following command line options. If the option begins with a +.RB ` + ' +instead of a +.RB ` \- ', +the option is restored to its default value. By default, these options can +be set via the resource names given in parentheses in the description of +each option. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI + page +Specifies the first page to show. If +.B + +is given without a number, the last page is assumed; the first page is +the default. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-allowshell +.RB ( .allowShell ) +This option enables the shell escape in PostScript specials. +(For security reasons, shell escapes are disabled by default.) +This option should be rarely used; in particular it should not be used just +to uncompress files: that function is done automatically if the file name +ends in +.BR .Z , +.BR .gz , +or +.BR .bz2 . +Shell escapes are always turned off if the +.B \-safer +option is used. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-altfont " font" +.RB ( .altFont ) +Declares a default font to use when the font in the +.I dvi +file cannot be found. This is useful, for example, with PostScript fonts. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-background " color" +.RB ( .background ) +Determines the color of the background. Same as +.BR -bg . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-bg " color" +.RB ( .background ) +Determines the color of the background. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-browser " browser" +.RB ( .wwwBrowser ) +Defines the web browser used for handling external URLs. The value of this +option or resource has the same syntax as the +.B BROWSER +environment variable; see the explanation of that variable in the +section `ENVIRONMENT' below for a detailed description. +If neither the option nor the X resource +.I wwwBrowser +is specified, the environment variables +.B BROWSER +and +.B WWWBROWSER +(in that order) are used to determine the browser command. If these are +not set either, the following default value is used: +\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 +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-copy +.RB ( .copy ) +Always use the +.I copy +operation when writing characters to the display. +This option may be necessary for correct operation on a color display, but +overstrike characters will be incorrect. +If greyscale anti-aliasing is in use, the +.B \-copy +operation will disable the use of colorplanes and make overstrikes come +out incorrectly. +See also +.BR \-thorough . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-cr " color" +.RB ( .cursorColor ) +Determines the color of the mouse cursor. The default is the same as +the foreground color. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-debug " bitmask|string[,string ...]" +.RB ( .debugLevel ) +If nonzero, prints additional information on standard output. The +argument can be either a bitmask specified as a decimal number, or +comma-separated list of strings. +.br +For the bitmask representation, multiple values can +be specified by adding the numbers that represent the individual bits; +e.g. to debug all all file searching and opening commands, use 4032 +(= 2048 + 1024 + 512 + 256 + 128 + 64). Use -1 to turn on debugging +of everything (this will produce huge output). +.br +For the string representation, use the strings listed in the following +table, with a comma to separate the values; e.g. to debug +all file searching and opening commands, use +.BR search,expand,paths,hash,stat,open . +(The option `kpathsea' is provided as a shorthand for these.) +Note that such a list may need to be quoted to prevent the shell +from interpreting commas or spaces in the list. +.br +The individual numbers and strings have the following meanings: +.nf +.sp 1n +.ta 1L +8L +12L + 1 bitmap Bitmap creation + 2 dvi DVI translation + 4 pk PK fonts + 8 batch Batch mode: Exit after + reading the DVI file + 16 event Event handling + 32 ps PostScript interpreter calls + 64 stat Kpathsea stat(2) calls + 128 hash Kpathsea hash table lookups + 256 open Kpathsea file opening + 512 paths Kpathsea path definitions + 1024 expand Kpathsea path expansion + 2048 search Kpathsea searching + 4032 kpathsea All Kpathsea options + 4096 htex Hypertex specials + 8192 src Source specials + 16384 client Client/server mode (see -unique + and -sourceposition options) + 32768 t1 Type1 font library messages + 65536 t1_verbose Verbose Type1 library messages + 131072 gui GUI elements +.sp 1n +.fi +Some of the Kpathsea debugging options are actually provided by Kpathsea; +see the Debugging section in the Kpathsea manual for more information on +these. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-density " density" +.RB ( .densityPercent ) +Determines the density used when shrinking bitmaps for fonts. +A higher value produces a lighter font. The default value is 40. +If greyscaling is in use, this argument does not apply; use +.B \-gamma +instead. +See also the +.RB ` S ' +keystroke. +Same as +.BR \-S . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-display " host" : display +Specifies the host and screen to be used for displaying the +.I dvi +file. By default this is obtained from the environment variable +.SB DISPLAY. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-dvipspath " path" +.RB ( .dvipsPath ) +Use +.I path +as the +.B dvips +program to use when printing. The default for this is +.BR dvips . +The program or script should read the DVI file from standard input, +and write the Postscript file to standard output. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-editor " editor" +.RB ( .editor ) +Specifies the editor that will be invoked when the +.I source-special() +action is triggered to start a reverse search (by default via Ctrl-Mouse 1). +The argument to this option is a format string in which occurrences of +.RB `` %f '' +are replaced by the file name, occurrences of +.RB `` %l '' +are replaced by the line number within the file, and optional +occurrences of +.RB `` %c '' +are replaced by the column number within the line. +.sp +If neither the option nor the X resource +.I .editor +is specified, the following environment variables are checked +to determine the editor command: +.BR XEDITOR , +.BR VISUAL , +and +.B EDITOR +(in this sequence). If the string is found as the value +of the +.SB VISUAL +or +.SB EDITOR +environment variables, then +.RI `` "xterm -e "'' +is prepended to the string; if the editor is specified by other means, then +it must be in the form of a shell command to pop up an X window with an +editor in it. If none of these variables is set, a warning message is displayed +and the command +.RI `` "xterm -e vi +%l %f"'' +is used. +.sp +If no +.RB `` %f '' +or +.RB `` %l '' +occurs in the string, the missing format strings are appended automatically. +(This is for compatibility with other programs when using one of the environment +variables). +.sp +A new instance of the editor is started each time this command is used; +therefore it is preferable to use an editor that can be invoked in +`client' mode to load new files into the same instance. Example +settings are: +.RS 7 +.TP 7 +.SB emacsclient --no-wait +(older Emacsen) +.TP +.SB gnuclient -q +(XEmacs and newer Emacsen) +.TP +.SB gvim --servername xdvi --remote +(VIM v6.0+; the `--servername xdvi' option will cause gvim to run a +dedicated instance for the files opened by xdvi.) +.TP +.SB nc +(nedit) +.PP +.sp +Note that those strings need to be enclosed +into quotes when using them on the command-line +to protect them from the shell; when using them +as argument for the +.I .editor +resource in an X resource file, no quotes should be used. +.sp +.B NOTE ON SECURITY: +The argument of this option isn't executed as a shell command, +but via +.I exec() +to prevent evil tricks with the contents of source specials. +.RE +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-expert +This option is only supported for backwards compatibility; +it is equivalent to +.BR "\-expertmode 0" , +which should be preferred. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-expertmode " flag" +.RB ( .expertMode ) +With an argument of +.IR 0 , +this option switches off the display of the buttons, scrollbars, +the toolbar (Motif only), +the statusline and the page list. These GUI elements +can also be (de)activated separately, by combining the +appropriate values in the +.I flag +argument. This acts similar to the +.B \-debug +option: The integer +.I flag +is treated as a bitmap where each bit represents one +element. If the bit has the value +.IR 1 , +the element is switched on, if it has the value +.IR 0 , +the element is switched off. The meaning of the bits +is as follows: +.nf +.sp 1n +.ta 1L +8L +12L + 1 statusline + 2 scrollbars + 4 Motif: pagelist, Xaw: buttons and pagelist + 8 toolbar (Motif only) + 16 menubar (Motif only) +.sp 1n +.fi +For example, to turn on only the statusline and the scrollbars, +use 3 (= 1 + 2). +See also the +.RB ` x ' +keystroke, where the bits are addressed by their positions, from 1 to +3 (Xaw) or 5 (Motif), respectively. +.PP +If the statusline is not active, all messages +that would normally be printed to the statusline will be printed to +.IR stdout , +unless the +.B \-hushstdout +option is used. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-fg " color" +.RB ( .foreground ) +Determines the color of the text (foreground). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-text-encoding " encoding" +.RB ( .textEncoding ) +Use +.I encoding +as text encoding of the string in the "Find" window. Usually, +this shouldn't be needed since the encoding is determined from the locale settings. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-findstring\fP \fIstring\fP +This option triggers a search for +.I string +in the DVI file mentioned on the command-line, similar to forward search +(see the description of the +.B sourceposition +option): +If there is already another +instance of +.B xdvi +running on the displaying that DVI file, it will cause that instance +to perform the search instead. The search starts at the top of the current +page of the DVI file. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-font " font" +.RB ( *font ) +Sets the font used in menus, buttons etc., as described in the +.I X(7x) +man page. The font for child windows can be set separately, +e.g.: +.RS 7 +.nf +.ft 3 +.sp 1n +xdvi*statusline*font: \e + -*-helvetica-medium-r-*-*-12-*-*-*-*-*-*-* +.sp 1n +.ft +.fi +.RE +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-foreground " color" +Same as +.BR -fg . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-fullscreen +When this option is used, xdvi will (try to) run in fullscreen mode, with +no window decorations. +This option is not guaranteed to work with all windowmanagers/desktops; +if you're experiencing problems with it, please use the +.B \-geometry +option instead, and a suitable window manager setting to remove +the window decorations. +When using this option for presentations, you might want +to get rid of all the control widgets as well, using the +.B -expertmode +option. This option can also be toggled at runtime using the +.B fullscreen +action (by default bound to Ctrl-l). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-gamma " gamma" +.RB ( .gamma ) +Controls the interpolation of colors in the greyscale anti-aliasing color +palette. Default value is 1.0. For 0 < +.I gamma +< 1, the fonts will be lighter (more like the background), and for +.I gamma +> 1, the fonts will be darker (more like the foreground). Negative +values behave the same way, but use a slightly different algorithm. +For color and grayscale displays; for monochrome, see +.BR \-density . +See also the +.RB ` S ' +keystroke. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-geometry " geometry" +.RB ( .geometry ) +Specifies the initial geometry of the main window, +as described in the +.I X(7x) +man page. The geometry of child windows can be set +separately, e.g.: +.br +.I xdvi*helpwindow.geometry: 600x800 +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-gsalpha +.RB ( .gsAlpha ) +Causes +.B Ghostscript +to be called with the +.B x11alpha +driver instead of the +.B x11 +driver. The +.B x11alpha +driver enables anti-aliasing in PostScript specials, for a nicer appearance. +It is available on newer versions of +.BR Ghostscript . +This option can also be toggled with the +.RB ` V ' +keystroke. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-gspalette " palette" +.RB ( .palette ) +Specifies the palette to be used when using Ghostscript for rendering +PostScript specials. Possible values are +.BR Color , +.BR Greyscale , +and +.BR Monochrome . +The default is +.BR Color . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BR \-h , " \-help" , " \--help" +Prints a short help text with an overview of the command-line options +to standard output. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-hl " color" +.RB ( .highlight ) +Determines the color of the page border, of the ruler in `ruler mode', +and of the highlighting markers in forward search and string search. +The default is the foreground color. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-anchorposition " anchor" +Jump to +.I anchor +after opening the DVI file. This is only useful when invoking +.B xdvi +from other applications. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-hush +.RB ( .Hush ) +Causes +.B xdvi +to suppress all suppressible warnings. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-hushchars +.RB ( .hushLostChars ) +Causes +.B xdvi +to suppress warnings about references to characters which are not defined +in the font. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-hushchecksums +.RB ( .hushChecksums ) +Causes +.B xdvi +to suppress warnings about checksum mismatches between the +.I dvi +file and the font file. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-hushstdout +.RB ( .hushStdout ) +Suppresses printing of status messages to +.IR stdout . +Note that errors or warnings will still be printed to +.I stderr +even if this option is used. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-hushbell +.RB ( .hushBell ) +Don't sound the X bell when an error occurs. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-icongeometry " geometry" +.RB ( .iconGeometry ) +Specifies the initial position for the icon. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-iconic +.RB ( .iconic ) +Causes the +.B xdvi +window to start in the iconic state. The default is to start with the +window open. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-install +.RB ( .install ) +If +.B xdvi +is running under a +.B PseudoColor +visual, then (by default) it will check for +.B TrueColor +visuals with more bits per pixel, and switch to such a visual if one exists. +If no such visual exists, it will use the current visual and colormap. If +.B \-install +is selected, however, it will still use a +.B TrueColor +visual with a greater depth, if one is available; otherwise, it will +install its own colormap on the current visual. If the current visual is not +.BR PseudoColor , +then +.B xdvi +will not switch the visual or colormap, regardless of its options. +The default value of the +.B install +resource is the special value, +.BR maybe . +There is no +.B +install +option. See also +.BR \-noinstall , +and the GREYSCALING AND COLORMAPS section. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-interpreter " filename" +.RB ( .interpreter ) +Use +.I filename +as the Ghostscript interpreter. By default it uses +.BR gs . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-keep +.RB ( .keepPosition ) +Sets a flag to indicate that +.B xdvi +should not move to the home position when moving to a new page. See also the +.RB ` k ' +keystroke. This flag is honored by all page switching actions and by +.B up-or-previous() / +.BR down-or-next() , +although the latter only honor the horizontal postion, not the vertical one. +This allows for a "continuous" scrolling back an forth through a document with +a display window narrower than a page width. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-l +.RB ( .listFonts ) +List the names of all fonts used. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-license +Prints licensing information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-linkcolor +.RB ( .linkColor ) +Color used for unvisited hyperlinks (`Blue2' by default). Hyperlinks +are unvisited before you click on them, or after the DVI file has been reloaded. +The value should be either a valid X color name (such as +.IR DarkGoldenrod4 ) +or a hexadecimal color string (such as +.IR #8b6508 ). +See also +.B \-visitedlinkcolor +and +.BR \-linkstyle . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-linkstyle +.RB ( .LinkStyle ) +Determines the style in which hyperlinks are displayed. Possible +values and their meanings are: +.nf +.sp 1n +.ta 1L +8L + 0 No highlighting of links + 1 Underline links with \fIlink color\fR + 2 No underlining, color text with \fIlink color\fR + 3 Underline and display text colored with + \fIlink color\fR +.sp 1n +.fi +The values for \fIlink color\fR are specified by the options/resources +.BI \-linkcolor +and +.BI \-visitedlinkcolor +(which see). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-margins " dimen" +.RB ( .Margin ) +Specifies the size of both the top margin and side margin. +This determines the ``home'' position of the page within the window as +follows. If the entire page fits in the window, then the margin settings +are ignored. If, even after removing the margins from the left, right, +top, and bottom, the page still cannot fit in the window, then the page +is put in the window such that the top and left margins are hidden, and +presumably the upper left-hand corner of the text on the page will be +in the upper left-hand corner of the window. +Otherwise, the text is centered in the window. +The dimension should be a decimal number optionally followed by +any of the two-letter abbreviations for units accepted by \*(Te\& +.RB ( pt , +.BR pc , +.BR in , +.BR bp , +.BR cm , +.BR mm , +.BR dd , +.BR cc , +or +.BR sp ). +By default, the unit will be +.BR cm " (centimeters)". +See also +.BR \-sidemargin ", " \-topmargin , +and the keystroke +.RB ` M .' +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-mfmode " mode-def" +.RB ( .mfMode ) +Specifies a +.I mode-def +string, which can be used in searching for fonts (see ENVIRONMENT, below). +Generally, when changing the +.IR mode-def , +it is also necessary to change the font size to the appropriate value +for that mode. This is done by adding a colon and the value in dots per inch; +for example, +.BR "\-mfmode ljfour:600" . +This method overrides any value given by the +.B pixelsPerInch +resource or the +.B \-p +command-line argument. +The metafont mode is also passed to +.B metafont +during automatic creation of fonts. +By default, it is +.BR "unspecified" . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-mgs " size" +Same as +.BR \-mgs1 . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-mgs[ n ] " size" +.RB ( .magnifierSize\fR[\fIn\fR] ) +Specifies the size of the window to be used for the ``magnifying glass'' +for Button +.IR n . +The size may be given as an integer (indicating that the magnifying glass +is to be square), or it may be given in the form +.IR width x height . +See the MOUSE ACTIONS section. Defaults are 200x150, 400x250, 700x500, +1000x800, and 1200x1200. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-mousemode " " [ 0 | 1 | 2 ] +.RB ( .mouseMode ) +Specifies the default mode of xdvi at startup: Magnifier (0), Text Selection Mode (1) +or Ruler Mode (2). See the section +.BR MODES , +below, for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-nocolor +.RB ( .color ) +Turns off the use of color specials. This option can be toggled with the +.RB ` C ' +keystroke. +(Note: +.B \-nocolor +corresponds to +.BR color:off ; +.B +nocolor +to +.BR color:on .) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-nofork +.RB ( .fork ) +With the +.B \-sourceposition +and +.B \-unique +options, the default behavior is for +.B xdvi +to put itself into the background (like a daemon) if there +is no appropriate instance of +.B xdvi +already running. +This argument makes it run in the foreground instead. This is useful +for debugging, or if your client application cannot deal well with +a program self-backgrounding itself in this way -- e.g., the IPC functions +in +.B emacs +are known to have problems with this. +If no +.B \-sourceposition +or +.B \-unique +argument is given, then this option has no effect. +(Note: +.B \-nofork +corresponds to +.BR fork:off ; +.B +nofork +to +.BR fork:on .) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-noghostscript +.RB ( .ghostscript ) +Inhibits the use of Ghostscript for displaying PostScript specials. +(Note: +.B \-noghostscript +corresponds to +.BR ghostscript:off ; +.B +noghostscript +to +.BR ghostscript:on .) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-nogrey +.RB ( .grey ) +Turns off the use of greyscale anti-aliasing when printing shrunken bitmaps. +(Note: +.B \-nogrey +corresponds to +.BR grey:off ; +.B +nogrey +to +.BR grey:on .) +See also the +.RB ` G ' +keystroke. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-nogssafer +.RB ( .gsSafer ) +Normally, if Ghostscript is used to render PostScript specials, the Ghostscript +interpreter is run with the option +.BR \-dSAFER . +The +.B \-nogssafer +option runs Ghostscript without +.BR \-dSAFER . +The +.B \-dSAFER +option in Ghostscript disables PostScript operators such as +.BR deletefile , +to prevent possibly malicious PostScript programs from having any effect. +If the +.B \-safer +option is specified, then this option has no effect; in that case Ghostscript +is always run with +.BR \-dSAFER . +(Note: +.B \-nogssafer +corresponds to +.BR gsSafer:off ; +.B +nogssafer +to +.BR gsSafer:on .) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-noinstall +.RB ( .install ) +Inhibit the default behavior of switching to a +.B TrueColor +visual if one is available with more bits per pixel than the current visual. +(Note: +\-noinstall +corresponds +.BR install:off ; +there is no +.B +noinstall +option.) +See also +.BR \-install , +and the GREYSCALING AND COLORMAPS section. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-nomakepk +.RB ( .makePk ) +Turns off automatic generation of font files that cannot be found by other +means. +(Note: +.B \-nomakepk +corresponds to +.BR makePk:off ; +.B +nomakepk +to +.BR makePK:on .) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-nomatchinverted +.RB ( .matchInverted ) +Don't highlight string search matches in inverted color; instead, draw a rectangle in +.I highlight +color (see the +.B \-hl +option) around the match. This option is activated automatically if +the display isn't running in TrueColor. +(Note: +.B \-nomatchinverted +corresponds to +.BR matchInverted:off ; +.B +nomatchinverted +to +.BR matchInverted:on .) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-noomega +.RB ( .omega ) +This will disable the use of Omega extensions when interpreting DVI files. +By default, the additional opcodes +.I 129 +and +.I 134 +are recognized by xdvi as Omega extensions and interpreted as requests +to set 2-byte characters. The only drawback is that the virtual font +array will require 65536 positions instead of the default 256 positions, +i.e. the memory requirements of xdvi will be slightly larger. If you find +this unacceptable or encounter another problem with the Omega extensions, +you can switch this extension off by using +.B \-noomega +(but please do send a bug report if you find such problems - see the bug +address in the +.B AUTHORS +section below). +.br +(Note: +.B \-noomega +corresponds to +.BR "omega: off" ; +.B +noomega +to +.BR "omega: on" .) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-noscan +.RB ( .prescan ) +By default, +.B xdvi +does a preliminary scan of the +.I dvi +file to process any +.B papersize +specials; this is especially important at startup since the paper size may be +needed to determine the window size. +If PostScript is in use, then prescanning is also necessary in order to +properly process header files. +In addition, prescanning is needed to correctly determine the background color +of a page. +This option turns off such prescanning. +(Prescanning will be automatically be turned back on if +.B xdvi +detects any of the specials mentioned above.) +(Note: +.B \-noscan +corresponds to +.BR prescan:off ; +.B +noscan +to +.BR prescan:on .) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-not1lib +.RB ( .t1lib ) +This will disable the use of T1Lib to display PostScript fonts. +Use this option as a workaround when you encounter problems with the +display of T1Lib (but please don't forget to send a bug report in +this case, to the URL mentioned in the section AUTHORS below). +.br +(Note: +.B \-not1lib +corresponds to +.BR t1lib:off ; +.B +not1lib +to +.BR t1lib:on .) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-notempfile +.RB ( .tempFile ) +As mentioned in the section +.B DESCRIPTION +above, xdvi will create a temporary copy of the DVI file so that it +can be accessed without interruptions even while the file is being +rewritten by +.BR TeX . +Since this introduces the overhead of copying the file every time +it has changed, the +.B \-notempfile +allows you to turn off this behaviour. In this case, exposing parts of the +window while the DVI file is being written by \*(Te\& will erase the current +window contents until the DVI file can be completely reread. +.br +(Note: +.B \-notempfile +corresponds to +.BR tempFile:off ; +.B +notempfile +to +.BR tempFile:on .) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-offsets " dimen" +.RB ( .Offset ) +Specifies the size of both the horizontal and vertical offsets of the +output on the page. By decree of the Stanford \*(Te\& Project, +the default \*(Te\& page origin is always 1 inch over and down from +the top-left page corner, even when non-American paper sizes are used. +Therefore, the default offsets are 1.0 inch. +The argument +.I dimen +should be a decimal number optionally followed by any of the two-letter +abbreviations for units accepted by \*(Te\& +.RB ( pt , +.BR pc , +.BR in , +.BR bp , +.BR cm , +.BR mm , +.BR dd , +.BR cc , +or +.BR sp ). +By default, the unit will be +.BR cm " (centimeters)". +See also +.B \-xoffset +and +.BR \-yoffset . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-p " pixels" +.RB ( .pixelsPerInch ) +Defines the size of the fonts to use, in pixels per inch. The +default value is 600. This option is provided only for backwards +compatibility; the preferred way is to set both the resolution +and the Metafont mode via the +.B \-mfmode +option (which see). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-paper " papertype" +.RB ( .paper ) +Specifies the size of the printed page. Note that in most cases it's +best to specify the paper size in the TeX input file via the line +.sp +.B \eusepackage[dvips]{geometry} +.sp +which will be recognized by both dvips and xdvi; in that case the +use of a `-paper' option should be unnecessary. +.br +The paper size may be specified in the form +\fIwidth\fBx\fIheight\fR optionally followed by a unit, where +.I width +and +.I height +are decimal numbers giving the width and height of the paper, respectively, +and the unit is any of the two-letter abbreviations for units accepted +by \*(Te\& +.RB ( pt , +.BR pc , +.BR in , +.BR bp , +.BR cm , +.BR mm , +.BR dd , +.BR cc , +or +.BR sp ). +By default, the unit is +.BR cm " (centimeters)"\fR. +.br +There are also synonyms which may be used: +.B us +(8.5x11in), +.B legal +(8.5x14in), +.B foolscap +(13.5x17in), +as well as the ISO sizes +.BR a1 - a7 , +.BR b1 - b7 , +.BR c1 - c7 . +Each of these also has a landscape or `rotated' variant: +.B usr +(11x8.5in), +.BR a1r - a7r , +etc. For compatibility with +.BR dvips , +the formats +.B letter +(8.5x11in), +.B ledger +(17x11in) +and +.B tabloid +(11x17in) +are also supported (these don't have rotated variants). +.br +Any of the above sizes may be preceded by a plus sign +.RB (` + '); +this causes the paper size given here to override any paper size given in the +.I dvi +file. The default paper size is 21 x 29.7 cm (A4 size). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-pause +.RB ( .pause ) +This option provides a simple implementation of incremental +(stepwise) display, which can be used for presentations. +When this option is used, +.B xdvi +will pause the display of the current page whenever it encounters a +special +.I special-string +.RI ( xdvi:pause +by default; the string can be customized via +.IR \-pausespecial , +see below), and the cursor will change its shape. The action +.B unpause-or-next() +(by default bound to the +.B Space +key) will display the next portion of the page up to the following +.IR special-string , +or until the end of the page is reached. +When the option is not used, specials containing +.I special-string +will be ignored. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-pausespecial " special-string" +.RB ( .pauseSpecial ) +Sets the special string that causes xdvi to pause when the +.I -pause +option is active. The default value of +.I special-string +is +.IR xdvi:pause . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-postscript " flag" +.RB ( .postscript ) +If +.I flag = 0, +rendering of PostScript specials is disabled; instead, bounding +boxes will be displayed (if available). A value of +.I 1 +(the default) switches PostScript specials on. With a value of +.IR 2 , +the PostScript specials are displayed along with their +bounding boxes; this allows you to visually check the correctness +of the bounding boxes. The values can also be toggled at runtime +with the +.RB ` v ' +keystroke and the corresponding numerical prefix arguments 0, 1 and 2. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-ps2pdfpath " path" +.RB ( .ps2pdfPath ) +Use +.I path +as a conversion program from Postscript to PDF. The program or script +should accept two command-line arguments: The Postscript file as first +argument, and the PDF output file as second argument. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-rulecolor " color" +.RB ( .ruleColor ) +Determines the color of the rules used for the the magnifier +(default: foreground color). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-q +.RB ( .noInitFile ) +Ignore the +.I $HOME/.xdvirc +startup file (i.e. don't read it at startup, and don't write it +at exit). This forces the defaults defined in +.I $HOME/.Xdefaults +to be used. See +.B FILES +for more information on +.IR $HOME/.xdvirc . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-rv +.RB ( .reverseVideo ) +Causes the page to be displayed with white characters on a black background, +instead of vice versa. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-S " density" +.RB ( .densityPercent ) +Same as +.B \-density +(which see). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-s " shrink" +.RB ( .shrinkFactor ) +Defines the initial shrink factor. The default value is 8. If +.I shrink +is given as 0, then the initial shrink factor is computed so that the +page fits within the window (as if the `s' keystroke were given without +a number). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-safer +.RB ( .safer ) +This option turns on all available security options; it is designed for use when +.B xdvi +is called by a browser that obtains a +.I dvi +or \*(Te\& file from another site. +This option selects +.B +nogssafer +and +.BR +allowshell . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-sidemargin " dimen" +.RB ( .sideMargin ) +Specifies the side margin (see +.BR \-margins ). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-sourceposition " line" [: col "][ ]" filename +This option makes +.B xdvi +search in the +.I dvi +file for the place corresponding to the indicated line (and, optionally, +column) in the .tex source file, and highlight the place found by drawing a +rectangle in the +.I highlight +color (see the +.B \-hl +option) around the corresponding text. In addition, when run with this +argument (and the +.B \-nofork +option is not given, which see), +.B xdvi +will always return immediately: if it finds another instance of +.B xdvi +already showing +.I dvi_file, +then it will cause that instance to raise its window and move to the given +place in the +.I dvi +file; otherwise it will start up its own instance in the background. +If several instances of xdvi are displaying the respective +.I dvi +file, the instance which was last raised to the foreground will be used. +.sp +The space before +.I filename +is only needed if the filename starts +with a digit. When the space is used, the argument +needs to be enclosed in quotes to prevent the shell from +misinterpreting the space as argument separator. +.sp +This option requires that +.I dvi_file +be prepared with source special information. See the section on SOURCE SPECIALS +for details on how to do this. +.sp +Here is a more detailed description of how the filename in the +.I \-sourceposition +argument is matched with the filename in the source specials: +.RS 7 +.TP 3 +1. +If neither of the filenames contains a path name component, the filenames +are compared ignoring the +.RI ` .tex ' +extensions in both filenames. +.TP +2. +Otherwise, if one of the filenames does contain a path component (e.g.: +.IR ./test.tex , +.IR ../test.tex , +.IR /my/homedir/tex/test.tex +or any combination of these), both filenames are expanded to a full path, +with any occurrences of +.I ../ +and +.I ./ +expanded, and multiple slashes removed. +.br +The pathname in the +.I \-sourceposition +is expanded relative to the current working directory of the +.I xdvi \-sourceposition +invocation, and the pathnames in the source specials are expanded +relative to the path of the current DVI file being viewed. +.br +The path names are then compared ignoring the +.RI ` .tex ' +extensions in both path names. +.RE +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-statusline\fP +.RB ( .statusline ) +This option is obsolete; use +\fB\-expertmode \fP \fIflag\fP +instead (which see). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-thorough +.RB ( .thorough ) +.B Xdvi +will usually try to ensure that overstrike characters (e.g., +.BR \enotin ) +are printed correctly. On monochrome displays, this is always possible +with one logical operation, either +.I and +or +.IR or . +On color displays, however, this may take two operations, one to set the +appropriate bits and one to clear other bits. If this is the case, then +by default +.B xdvi +will instead use the +.I copy +operation, which does not handle overstriking correctly. The +.B \-thorough +option chooses the slower but more correct choice. See also +.BR \-copy . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-topmargin " dimen" +.RB ( .topMargin ) +Specifies the top and bottom margins (see +.BR \-margins ). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-unique +.RB ( .unique ) +This option will make another instance of xdvi running on the same display +act as a `server'. For example, the invocation +.sp +.B xdvi -unique +5 file.dvi +.sp +will cause this other instance to load +.I file.dvi +on page 5 in place of the file that it is currently displaying. If there is +already another instance of xdvi already displaying the file +.IR file.dvi , +then it will just jump to page 5. +If the other instance of xdvi is displaying a different file, it will load +.I file.dvi +instead. Otherwise, if no other instance of +xdvi is currently running on the display, this option instead +starts a new instance of xdvi in the background (unless the +.I \-nofork +option is specified, which see) displaying page 5 of +.IR file.dvi . +.br +The filename and the +.B +n +option for the page number are the only options available for +controlling a remote instance of xdvi like this; all other options are +currently ignored. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-useTeXpages +Use logical \*(Te\& pages (the values of the +.I \ecount0 +register) instead of physical pages for the pagelist labels and +when jumping to a page in a document with the `g' keystroke (or the +.B goto-page() +action). +This option can be toggled via the +.RB ` T ' +keystroke. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-version +Print information on the version of +.BR xdvi . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-visitedlinkcolor +.RB ( .visitedLinkColor ) +Color used for visited hyperlinks (`Purple4' by default). Hyperlinks become +visited once you click on them. As for +.BR linkColor , +the value should be either a valid X color name or a hexadecimal color string. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B \-warnspecials +.RB ( .warnSpecials ) +Causes +.B xdvi +to print warnings about +.B \especial +strings that it cannot process to stderr. These warnings are suppressed by default. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-watchfile " n" +.RB ( .watchFile ) +If this option is set to a value larger than 0, xdvi will check +the DVI file for changes every +.I n +seconds. If the DVI file has been completely written by TeX, it will +be reloaded automatically. Fractional values (e.g. `2.5') are +possible. The default for this option is 0, i.e. no watching. +.br +Since xdvi cannot handle partial DVI files, it tries not to reload +the file while it is being rewritten. However, use of the magnifier +or switching of pages requires reading (a part of) the DVI file, and +if the +.B tempfile +option is switched off, this will erase the current contents of the window +until the DVI file can be read entirely. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-wheelunit " pixels" +.RB ( .wheelUnit ) +Sets the number of pixels that a motion of a wheel mouse will move the +image up, down, left, or right. (See the +.B wheel +and +.B hwheel +actions, below, for more information on this.) +If set to zero, the wheel mouse functionality is (essentially) disabled. +The default value is 80. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-xoffset " dimen" +.RB ( .xOffset ) +Specifies the size of the horizontal offset of the output on the page. See +.BR \-offsets . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BI \-yoffset " dimen" +.RB ( .yOffset ) +Specifies the size of the vertical offset of the output on the page. See +.BR -offsets . +.PP + + + +.SH KEYSTROKES +.B Xdvi +recognizes the following keystrokes when typed in its window. +Each may optionally be preceded by a (positive or negative) number, a +`prefix argument', whose interpretation will depend on the particular keystroke. +This prefix argument can be discarded by pressing the ``Escape'' key. +If present, the ``Help'', ``Prior'' and ``Next'' keys are synonyms for +.RB ` ? ', +.RB ` b ', +and +.RB ` f ' +keys, respectively. +.PP +The key bindings listed here are those that +.B xdvi +assigns by default. The names appearing in brackets at the beginning +of the descriptions are the names of the actions associated with the +keys; these can be used to customize the key bindings, as explained in +more detail in the section +.B CUSTOMIZATION +below. If only a lowercase binding is listed, both upper- and lowercase +keys will work for that binding. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.\" SPECIAL KEYS +.\" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BR ESC " key" +.RB [ discard-number() ] +The escape key discards the numerical prefix for all actions +(useful when you mistyped a number). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BR Return " key" +.RB [ forward-page() ] +Moves to the next page (or to the +.IR n th +next page if a number is given). Synonyms are +.RB ` n ', +.RB ` f ' +and Line Feed. +.TP +.BR Backspace " key" +.RB [ back-pagee() ] +Moves to the previous page (or back +.I n +pages). Synonyms are +.RB ` p ', +.RB ` b ' +and +.BR Ctrl-h . +.TP +.BR Delete " key" +.RB [ up-or-previous() ] +Moves up two-thirds of a window-full, or to the top of the previous page +if already at the top of the page. With a float argument, moves up the +corresponding fraction of a window-full. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BR Space " key" +.RB [ unpause-or-next() ] +Moves down two-thirds of a window-full, or to the next page if already at +the bottom of the page. +.br +When the option +.BI \-pause " special-string" +is used and the display is currently paused, this key will instead +display the next portion of the page until the next +.I special-string +or the end of the page is encountered. See the description of the +.B \-pause +option for details. The action +.RB [ down-or-next() ] +does a similar thing, but without pausing; it is not bound to a key +by default. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BR Ctrl-Home " (Xaw), " Ctrl-osfBeginLine " (Motif)" +.RB [ goto-page(1) ] +Moves to the first page of the document. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BR Ctrl-End " (Xaw), " Ctrl-osfEndLine " (Motif)" +.RB [ goto-page() ] +Moves to the last page of the document. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BR Home " (Xaw), " osfBeginLine " (Motif)" +.RB [ home-or-top() ] +Move to the ``home'' position of the page, or to the top of the page if +the +.I keep +flag is set (in this case, the page doesn't scroll horizontally). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BR End " (Xaw), " osfEndLine " (Motif)" +.RB [ end-or-bottom() ] +Move to the ``end'' position of the page (the lower right-hand corner), +or to the bottom of the page if the +.I keep +flag is set (in this case, the page doesn't scroll horizontally). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.\" ARROW KEYS +.\" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Down arrow +.RB [ down(0.015) ] +Scrolls page down. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Up arrow +.RB [ up(0.015) ] +Scrolls page up. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Right arrow +.RB [ right(0.015) ] +Scrolls page right. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Left arrow +.RB [ left(0.015) ] +Scrolls page left. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.\" ORDINARY KEYS. Note that the special symbols ([ ] + - etc.) are not in +.\" strict ASCII order (found that more intuitive). Sequence for each letter +.\" is: Alt-Ctrl, Ctrl, uppercase, lowercase. +.\" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Alt-Ctrl-+ +.RB [ change-density(25) ] +Increase the darkness of the fonts in the DVI window by adding to the gamma value +(see also the +.RB ` S ' +keystroke). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Alt-Ctrl-- +.RB [ change-density(-25) ] +Decrease the darkness of the fonts in the DVI window by subtracting from the gamma value +(see also the +.RB ` S ' +keystroke). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctrl-+ +.RB [ set-shrink-factor(+) ] +Increase the shrink factor (see also the +.RB ` s ' +keystroke). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctrl-- +.RB [ set-shrink-factor(-) ] +Decrease the shrink factor (see also the +.RB ` s ' +keystroke). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctr-[ +.RB [ pagehistory-delete-backward() ] +Delete the current item in the page history and move to the history +item before the deleted one. With a prefix argument +.BR n , +delete +.B n +previous history items. See +.B PAGE HISTORY +for details. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B [ +.RB [ pagehistory-back() ] +Move back in the page history (see +.B PAGE HISTORY +for details). With a prefix argument +.BR n , +move back +.B n +history items. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctr-] +.RB [ pagehistory-delete-forward() ] +Delete the current item in the page history and move to the history +item after the deleted one. With a prefix argument +.BR n , +delete +.B n +next history items. See +.B PAGE HISTORY +for details. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B ] +.RB [ pagehistory-forward() ] +Move forward in the page history (see +.B PAGE HISTORY +for details). With a prefix argument +.BR n , +move forward +.B n +history items. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.BR ^ +.RB [ home() ] +Move to the ``home'' position of the page. This is normally the upper +left-hand corner of the page, depending on the margins as described in the +.B \-margins +option, above. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B ? +.RB [ help() ] +Same as the +.B h +key (which see). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B B +.RB [ htex-back() ] +This key jumps back to the previous hyperlink anchor. See the +section +.B HYPERLINKS +for more information on navigating the links. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B b +.RB [ back-page() ] +Moves to the previous page (or back +.I n +pages). Synonyms are +.RB ` p ', +.B Ctrl-h +and +.BR Backspace . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B C +.RB [ set-color() ] +This key toggles the use of color specials. The key sequences +.RB ` 0C ' +and +.RB ` 1C ' +turn interpretation of color specials off and on, respectively. +See also the +.B \-nocolor +option. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B c +.RB [ center() ] +Moves the page so that the point currently beneath the mouse cursor is moved to +the middle of the window, and warps the mouse cursor to the same place. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B D +.RB [ toggle-grid-mode() ] +This key toggles the use of a grid on the displayed page. +If no number is given, the grid mode is switched on or off. +By prepending a number from 1 to 3, 3 different grid levels can be set. +The units of the grid are inches or centimeters, depending +on whether the paper format is letter (in) or a4 (cm). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B d +.RB [ down() ] +Moves page down two thirds of a window-full. With a float argument to ``down'', +moves down the corresponding fraction of a window-full. +.\" Therefore, a more +.\" ``smooth'' scrolling using the ``Up'' and ``Down'' keys can be +.\" achieved by the the following setting: +.\" .sp +.\" xdvi.mainTranslations: #override\e +.\" .br +.\" Up:up(0.01)\en\e +.\" .br +.\" Down:down(0.01)\en +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctrl-f +.RB [ find() ] +Pop up a window to search for a string in the DVI file. See the section +.BR "STRING SEARCH" , +below, for more details. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B f +.RB [ forward-page() ] +Moves to the next page (or to the +.IR n th +next page if a number is given). Synonyms are +.RB ` n ', +Return, and Line Feed. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B G +.RB [ set-greyscaling() ] +This key toggles the use of greyscale anti-aliasing for displaying shrunken +bitmaps. In addition, the key sequences +.RB ` 0G ' +and +.RB ` 1G ' +clear and set this flag, respectively. See also the +.B \-nogrey +option. +.sp +If given a numeric argument that is not 0 or 1, greyscale anti-aliasing is +turned on, and the gamma resource is set to the value divided by +100. E.g., +.RB ` 150G ' +turns on greyscale and sets gamma to 1.5. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctrl-g +.RB [ find-next() ] +Find the next match string in the DVI file; this can be used instead +of pressing the `Find' button in the search window. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B g +.RB [ goto-page() ] +Moves to the page with the given number. If no page number is given, xdvi jumps to the last page. +.br +If the option/resource +.B useTeXpages +is active, the numbers correspond to the actual page numbers in the TeX file; +otherwise, absolute page numbers (starting from 1) are used. In the latter case, +the page numbers can be changed with the +.RB ` P ' +keystroke, below. +Note that with the +.B useTeXpages +option it is possible that the same page number occurs multiple +times; in such a case, xdvi will use the first page number that matches. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B h +Pops up a help window with a short explanation of the most important key +bindings and concepts. +.\" +.\" Ummh, surely nobody will use the following ... +.\" +.\" For I18n purposes, the help texts and menu entries are configurable +.\" via the following X resources: +.\" .BR helpGeneral , +.\" #ifhyper +.\" .BR helpHypertex , +.\" #endif +.\" .BR helpOthercommands , +.\" .BR helpMarking , +.\" .BR helpPagemotion , +.\" .BR helpMousebuttons , +.\" .BR helpRulermode , +.\" .BR helpSearch and +.\" .BR helpSourcespecials . +.\" The values of this resource should be a text string, the first line of +.\" which should contain two fields separated by `\en'. The first field is +.\" used as list entry for the list of help topics on the left of the help +.\" window, and the second field is used as the heading on the right-hand side. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B k +.RB [ set-keep-flag() ] +Normally when +.B xdvi +switches pages, it moves to the home position as well. The +.RB ` k ' +keystroke toggles a `keep-position' flag which, when set, will keep +the same position when moving between pages. Also +.RB ` 0k ' +and +.RB ` 1k ' +clear and set this flag, respectively. See also the +.B \-keep +option. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctrl-l +.RB [ fullscreen(toggle) ] +Toggles fullscreen mode (see the description of the +.B \-fullscreen +option for more information on this). This is even more flaky than +using the command-line option: There is no universal standard +how a window could change its own geometry or window decorations at +run-time, so this will not work with most window managers or +desktops. Generally, it's better to use the window manager controls to +change the size or decorations of the xdvi window. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B l +.RB [ left() ] +Moves page left two thirds of a window-full. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B M +.RB [ set-margins() ] +Sets the margins so that the point currently under the mouse cursor defines +the upper left-hand corner of the text in the page. Note that the command +does +.I not +move the image, but only determines the margins +for the page switching commands. For details on how the margins +are used, see the +.B \-margins +option. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B m +.RB [ toggle-mark() ] +Toggles the mark for the current page in the page list. When a page +is marked, it is displayed with a small star `*' next to the page number. +The marked pages can then be printed or saved to a file. +A page or several pages can also be marked by clicking or dragging +.B Mouse-2 +in the page list. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctrl-n +.RB [ toggle-mark()forward-page() ] +Toggles the mark for the current page in the page list, and moves to +the next page. This lets you quickly mark a series of subsequent pages. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B n +.RB [ forward-page() ] +Moves to the next page (or to the +.IR n th +next page if a number is given). Synonyms are +.RB ` f ', +Return, and Line Feed. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctrl-o +.RB [ select-dvi-file() ] +Read a new +.I dvi +file. A file-selection widget is popped up for you to choose the DVI +file from. If a prefix argument +.I n +is given, the +.I n th +file from the file history is opened instead. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B P +.RB [ declare-page-number() ] +``This is page number +.IR n .'' +This can be used to make the +.RB ` g ' +keystroke refer to a different page number than the physical page. +(If you want to use `logical' or \*(Te\& page numbers instead of physical pages, +consider using the option +.B \-useTeXpages +instead.) +The argument +.I n +should be given as prefix to this key. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctrl-p +.RB [ print() ] +Opens a popup window for printing the DVI file, or parts of it. +See the section +.B PRINT DIALOG +for an explanation of the options available, and the resources to customize +the default behaviour. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B p +.RB [ back-page() ] +Moves to the previous page (or back +.I n +pages). Synonyms are +.RB ` b ', +.B Ctrl-h +and +.BR Backspace . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B q +.RB [ quit() ] +Quits the program. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctrl-r +.RB [ forward-page(0) ] +Redisplays the current page. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B R +.RB [ reread-dvi-file() ] +Forces the +.I dvi +file to be reread. This allows you to preview many versions of the same +file while running +.B xdvi +only once. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B r +.RB [ right() ] +Moves page right two thirds of a window-full. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctrl-s +.RB [ save() ] +Opens a popup window for saving the DVI file, or parts of it. See the section +SAVE DIALOG below for more information on this. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B S +.RB [ set-density() ] +Sets the density factor to be used when shrinking bitmaps. This should +be a number between 0 and 100; higher numbers produce lighter characters. +If greyscaling mode is in effect, this changes the value of gamma instead. +The new value of gamma is the given number divided by 100; negative values +are allowed. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B s +.RB [ set-shrink-factor() ] +Changes the shrink factor to the given number. If no number is given, the +smallest factor that makes the entire page fit in the window will be used. +(Margins are ignored in this computation.) +.\" NOTE: following only works in action string, not interactively!!! +.\" Two special values are +.\" .B + +.\" and +.\" .B - +.\" which zoom in and out respectively, by decrementing/incrementing the +.\" shrinkfactor by one step. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B T +.RB [ use-tex-pages() ] +Use logical \*(Te\& pages (the values of the +.I \ecount0 +register) instead of physical pages for the pagelist labels and +when jumping to a page in a document via +.BR goto-page() . +See also the +.B \-useTeXpages +option. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B t +.RB [ switch-magnifier-units() ] +Switches the units used for the magnifier tick marks, and for reporting +the distance between the mouse pointer and the ruler centre in +ruler mode (see the section +.BR MODES ). +The default value is specified by the X resource +.B tickUnits +(`mm' by default). The units toggle through the following +values; except for `px', they all correspond to \*(Te\&'s units: +.I mm +(millimeters) +.I pt +(\*(Te\& points), +.I in +(inches), +.I sp +(scaled points, the unit used internally by \*(Te\&) +.I bp +(big points or `Postscript points'), +.I cc +(cicero points), +.I dd +(didot points), +.I pc +(pica), and +.I px +(screen pixels). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctrl-u +.RB [ back-page()toggle-mark() ] +Moves to the previous page, and toggles the mark for that page. This +is the dual action to +.BR Ctrl-n . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B u +.RB [ up() ] +Moves page up two thirds of a window-full. With a float argument to ``up'', +moves up the corresponding fraction of a window-full. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctrl-v +.RB [ show-source-specials() ] +Show bounding boxes for every source special on the current page, and print +the strings contained in these specials to stderr. With prefix 1, +show every bounding box on the page. This is for debugging purposes mainly. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B V +.RB [ set-gs-alpha() ] +This key toggles the anti-aliasing of PostScript specials when +.B Ghostscript +is used as renderer. In addition the key sequences +.RB ` 0V ' +and +.RB ` 1V ' +clear and set this flag, respectively. See also the +.B \-gsalpha +option. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B v +.RB [ set-ps() ] +This key toggles the rendering of PostScript specials between 3 states: +.RS 7 +.TP 0 +.SB - specials (like EPS graphics) are displayed; +.TP +.SB - specials are displayed along with their bounding box (if available); +.TP +.SB - only the bounding box is displayed. +.PP +.sp +The states can also be selected directly by using +.RB ` 1v ', +.RB ` 2v ' +and +.RB ` 0v ' +respectively. +See also the +.B \-postscript +option. +.RE +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Ctrl-x +.RB [ source-what-special() ] +Display information about the source special next to the mouse cursor in the +statusline. This is the same special that would be found by +.IR source-special() , +but without invoking the editor. For debugging purposes. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B x +.RB [ set-expert-mode() ] +Toggles expert mode, in which +the statusline, the scrollbars, the menu buttons, the toolbar (Motif only) +and the page list are not shown. +Typing +.RB ` 1x ' +toggles the display of the statusline at the bottom of +the window. Typing +.RB ` 2x ' +toggles the scrollbars (if available). For Xaw, +.RB ` 3x ' +toggles the menu buttons and the page list, for Motif, +it toggles the page list. In Motif, the additional bindings +.RB ` 4x ' +toggle the toolbar, and +.RB ` 5x ' +the menu bar. +.br +Without a prefix argument, all of the mentioned GUI elements are either +switched on (if they had been invisible before) or off. +.br +Toggling the scrollbars may behave erratically with the +Xaw widgets; e.g. the scrollbars may reappear after +resizing the window, and at certain window sizes one of the +scrollbars may fail to disappear. +.br +See also the option +.B \-expertmode +(the numbers above correspond to the bits in the argument to +.BR \-expertmode ). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH MOUSE ACTIONS IN THE MAIN WINDOW +The mouse actions can be customized by setting the X resource +.BR mouseTranslations . +Since there are three different mouse modes (see the section +.B MODES +below), there is a special action +.B mouse-modes +which lists the actions for each of the three modes: +\fBmouse-modes("ACTIONS-FOR-MODE1", "ACTIONS-FOR-MODE2", "ACTIONS-FOR-MODE3")\fR. +If only one argument is specified, this action is used for all modes. +The default bindings are as follows: +.RS 5 +.nf +.ft 3 +.sp 1n +xdvi.mouseTranslations: \e +Shift:mouse-modes("drag(+)")\en\e +Shift:mouse-modes("drag(|)")\en\e +Shift:mouse-modes("drag(-)")\en\e +Ctrl:mouse-modes("source-special()")\en\e +: mouse-modes("do-href()magnifier(*2)", "text-selection()", "ruler()")\en\e +: mouse-modes("do-href-newwindow()magnifier(*2)", "text-selection()", "ruler()")\en\e +: mouse-modes("magnifier(*3)")\en\e +: mouse-modes("wheel(-0.2)")\en\e +: mouse-modes("wheel(0.2)")\en\e +: mouse-modes("hwheel(-0.2)")\en\e +: mouse-modes("hwheel(0.2)")\en\e +.sp 1n +.ft +.fi +.RE +All of these actions are described in more detail below. +Note the use of quote symbols around the action strings, which are necessary +to group them into one argument. +Buttons 4, 5, 6, and 7 refer to wheel movements (wheel up/down/left/right) +on wheel mice. Not all mice support horizontal scrolling. +.PP +The X Toolkit routines that implement translations do not support event +types of +.B Btn6Down +or +.BR Btn7Down . +Because of this, +.B xdvi +implements its own parser for translations given in +.BR mouseTranslations . +This parser is more limited than the parser built in to the X Toolkit. +The string given in +.B mouseTranslations +should not begin with +.RB `` #replace '', +.RB `` #augment '', +or +.RB `` #override ''. +Modifiers of the form +.BI @ keysym +are not supported, and the event type must be of the form +.B BtnDown +or +.BI Btn n Down\fR,\fP +where +.I n +is a positive integer without leading zeroes. Also, some limitations apply +to the action field. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B do-href() +.TP +.B do-href-newwindow() +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +Usually, if a binding specifies more then one action, all actions +are executed in a sequence. The hyperlink bindings +.B do-href() +and +.B do-href-newwindow() +are special in that they are used as an +.I alternative +to other actions that might follow them +.I if +the mouse is currently located on a hyperlink. +In this case, none of the other actions will be executed; +otherwise, only the other actions are executed. +.br +The action +.B do-href() +jumps to the link target in the current xdvi +window (eventually switching to another page), and +.B do-href-newwindow() +opens a new instance of xdvi for the link target. +In both cases, the location of the target is +indicated by a small arrow drawn in the same color +as a visited link +in the left corner of the window. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B magnifier(n x m) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B magnifier(*n) +This action will pop up a ``magnifying glass'' which shows the unshrunk +image of the region around the mouse pointer. The magnifier disappears when +the mouse button is released. Moving the mouse cursor while holding the button down will move the +magnifier. +.br +Different mouse buttons produce different sized +windows, as indicated by the +the argument of the +.I magnifier() +action. Its argument is either a string of the form +.IR width x height , +as in the +.BI \-mgs n +command-line option, or one of the strings +.B *1 +through +.BR *5 , +referring to the value specified by the corresponding +.BI \-mgs n +option. +.\" Note that in order to assign magnifier actions to +.\" the buttons 4 or 5, you need to use the resource +.\" .B wheelTranslations +.\" (more about this resource below), e.g.: +.\" .sp +.\" xdvi.wheelTranslations: : magnifier(*4)\en\e +.\" : magnifier(*5)\en +.\" .sp +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B drag(+) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B drag(|) +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B drag(-) +Drags the page with the mouse. This action should have one parameter, the character +.RB `` | '', +.RB `` - '', +or +.RB `` + '', +indicating vertical dragging only, horizontal dragging only, or dragging in all +directions. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B source-special() +This action starts a ``reverse search'', +opening the editor at the location in the \*(Te\& file corresponding +to the pointer location in the DVI file. +See the section on SOURCE SPECIALS, below, for more information on this. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B wheel() +This action can be used to scroll the image with a wheel mouse, where it +is usually bound to mouse button 4 (wheel up) or 5 (wheel down). +The action takes one parameter, giving the distance to scroll the +image. If the parameter contains a decimal point, the distance is +given in wheel units; otherwise, pixels. A negative value scrolls up, +a positive value scrolls down. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B hwheel() +This action can be used to scroll the image horizontally with a wheel mouse, +where it is usually bound to mouse button 6 (wheel left) or 7 (wheel right). +The action takes one parameter, giving the distance to scroll the +image. If the parameter contains a decimal point, the distance is +given in wheel units; otherwise, pixels. A negative value scrolls left, +a positive value scrolls right. Not all mice support horizontal scrolling; +this is mostly for touchpads, trackpads, etc. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B text-selection() +This action allows you to mark a rectangular region of text in the DVI file. +The text is put into the X selection buffer and can be pasted into other +applictions (e.g. text editors). This works similar to the Plain text option +in the +.B Save +dialog; see the discussion there for more information on encoding issues. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B ruler() +This action creates a cross-shaped ruler. Moving the mouse and holding +the button down drags the ruler and lets you measure distances on the page. +See the section +.B Ruler Mode +for more information on this. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH UNBOUND ACTIONS +The following actions are not bound to a key by default, but are available +for customization. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B quit-confirm() +Pops up a confirmation window to quit xdvi. To bind it to the +.RB ` q ' +key instead of the default `quit()' action, put the following into your +.I ~/.Xdefaults +file: +.sp +xdvi.mainTranslations: #override\e +.br +q: quit-confirm()\en +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B down-or-next() +Similar to +.IR unpause-or-next() : +Moves down two-thirds of a window-full, or to the next page if already +at the bottom of the page. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B shrink-to-dpi() +This action takes one (required) argument. It sets the shrink factor to +an integer so as to approximate the use of fonts with the corresponding +number of dots per inch. If +.B xdvi +is using fonts scaled for +.I p +dots per inch, and the argument to +.B shrink-to-dpi +is +.IR n , +then the corresponding shrink factor is the ratio +.IR p / n , +rounded to the nearest integer. +.PP +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH CUSTOMIZATION +Key and mouse button assignments can be changed by setting the +.B mainTranslations +resource to a string of translations as defined in the documentation for the +X toolkit. The actions should take the form of action names listed in the +KEYSTROKES and MOUSE ACTIONS sections. +.PP +An exception to this are the Motif keys +.IR osfPageUp " (" PgUp ), +.IR osfPageDown " (" PgDown ), +.IR osfBeginLine " (" Home ) +and +.IR osfEndLine " (" End ) +which are currently not customizable in the Motif version. +.PP +Key actions will usually be without arguments; if they are passed an argument, +it represents the optional number or `prefix argument' typed prior to the action. +.PP +Some key actions may take special arguments, as follows: The argument of +.B goto-page +may be the letter +.RB ` e ', +indicating the action of going to the end of the document. +The argument of +.B set-shrink-factor +may be the letter +.RB ` a ', +indicating that the shrink factor should be set to the smallest value such that +the page will fit in the window, or one of the signs +.RB ` + ' +or +.RB ` - ', +indicating that the shrink factor should be increased or decreased, respectively. +Finally, actions that would perform a toggle, such as +.BR set-keep-flag , +may receive an argument +.RB ` t ', +indicating that the action should toggle regardless of the current prefix argument. +.PP +Mouse actions should refer only to +.B ButtonPress +events (e.g., +.BR ":magnifier(*1)" ). +The corresponding motion and release events will be handled internally. +A key action may be bound to a mouse event, but not vice versa. +.PP +Usually the string of translations should begin with +.RB `` #override '', +indicating that the default key and mouse button assignments should not +be discarded. +.PP +When keys or mouse buttons involving modifiers (such as Ctrl or Shift) +are customized together with their non-modified equivalents, the modified +keys should come first, for example: +.RS 5 +.nf +.ft 3 +.sp 1n +xdvi.mainTranslations: #override \e +Shifts: select-dvi-file()\en\e +Ctrls: save()\en\e +s: find()\en +.sp 1n +.ft +.fi +.RE +.PP +Because +.B xdvi +needs to capture pointer motion events, and because the X Toolkit +translations mechanism cannot accommodate both motion events and double-click +events at the same time, it is not possible to specify double-click +actions in +.B xdvi +customizations. For information on this and other aspects of translations, +see the X Toolkit Intrinsics documentation. +.PP +There is no command-line option to set the +.B mainTranslations +resource, since changing this resource on the command line would be cumbersome. +To set the resource for testing purposes, use the +.B -xrm +command-line option provided by the X toolkit. For example, +\fBxdvi \-xrm 'XDvi.mainTranslations: #override "z":quit()' ...\fR +or +.B "xdvi \-xrm 'XDvi.mainTranslations: #override z:quit()' ..." +will cause the key +.RB ` z ' +to quit +.BR xdvi . +.PP +Some resources are provided to allow customization of the geometry of +the Xaw command buttons. Again, they are not changeable via command-line +options, other than via the +.B \-xrm +option. All of these resources take integer values. +.TP +.B buttonSideSpacing +The number of pixels to be placed on either side of the buttons. +The default value is 6. +.TP +.B buttonTopSpacing +The number of pixels between the top button and the top of the window. +The default value is 50. +.TP +.B buttonBetweenSpacing +The number of pixels between the buttons. +The default value is 20. +.TP +.B buttonBetweenExtra +The number of pixels of additional space to be inserted if the +.B buttonTranslations +resource string contains an extra newline character. +The default value is 50. +.TP +.B buttonBorderWidth +The border width of the button windows. The default value is 1. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH PAGE LIST +The scrollable page list on the right of the main window allows you to +jump directly to a page in the DVI file. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Mouse-1 +Jumps to the page the mouse is located on. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B Mouse-2 +.RB [ toggle-mark() ] +Toggle the mark of the current page. The marks are used by the `Print' +and `Save to file' dialogs to select only marked pages from the DVI file. +.PP +When the mouse pointer is inside the page list, the mouse wheel switches +to the next or previous page. +.PP +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SCROLLBARS +The scrollbars (if present) behave in the standard way: pushing Button 2 +in a scrollbar moves the top or left edge of the scrollbar to that point +and optionally drags it; +pushing Button 1 moves the image up or right by an amount equal to the distance +from the button press to the upper left-hand corner of the window; pushing +Button 3 moves the image down or left by the same amount. +.PP +The scrollbars can be removed via the +.I -expertmode +flag/keystroke (which see). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH MAGNIFIER +By default, the mouse buttons 1 to 5 will pop up a ``magnifying glass'' +that shows an unshrunken image of the page (i.e. an image at the resolution +determined by the option/X resource +.B pixels +or +.BR mfmode ) +at varying sizes. When the magnifier is moved, small ruler-like +tick marks are displayed at the edges of the magnifier (unless +the X resource +.B delayRulers +is set to false, in which case the tick marks will always be displayed). +The unit of the marks is determined by the X resource +.B tickUnits +(mm by default). This unit can be changed at runtime via the action +.BR switch-magnifier-units() , +by default bound to the keystroke +.RB ` t ' +(see the description of that key, and of switch-magnifier-units() for +more details on the units available). +.br +The length of the tick marks can be changed via the X resource +.B tickLength +(4 by default). A zero or negative value suppresses the tick marks. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH PAGE HISTORY +.B Xdvi +keeps a history of viewed pages, and you can move through the history +and delete items using the keys +.B [ +.RI ( pagehistory-back() ), +.B ] +.RI ( pagehistory-forward() ), +.B Ctr-[ +.RI ( pagehistory-delete-backward() ) +and +.B Ctr-] +.RI ( pagehistory-delete-forward() ). +.PP +When one of the history commands is used, the page history is displayed +in the status line at the bottom of the window, with the current list +item marked by square brackets `[', `]' and a left and right context of +at most 10 items. File boundaries are marked by `#'. +.PP +The size of the history can be customized with the X resource +.B pageHistorySize +(the default size is 1000 items). If the size is set to 0, the +history commands are disabled. +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH HYPERLINKS +The actions +.B do-href() +and +.B do-href-newwindow() +(by default bound to Mouse-1 and Mouse-2 if the pointer is currently located +on a hyperlink) can be used to open the link target in the same window +.RB ( do-href() ) +or in a new window +.RB ( do-href-newwindow() ). +.PP +If the link target is not a file on the local disk, +xdvi tries to launch a web browser (as specified by the +.B -browser +command line option, the +.B BROWSER +environment variable or the +.B wwwBrowser +X resource, in this order) to retrieve the document. See the description +of the +.B BROWSER +environment variable, below, for an example setting. +.PP +If the file is a local file, xdvi tries to determine if it is a DVI +file. If it is, xdvi will try to display the file; otherwise it will +try to determine the MIME type of the file, and from that an +application suitable for opening the file. +This is done by parsing the files specified by the environment variable +.B EXTENSIONMAPS +for a mapping of filename extensions to MIME types, +and the files determined by the environment variable +.B MAILCAPS +for a mapping of MIME types to application programs. +See the descriptions of these variables in the section +.BR ENVIRONMENT , +below, for a more detailed description and the default values of these +variables. If no suitable files are found, a set of built-in default +MIME types and applications is used. +.PP +.B Xdvi +currently uses no heuristics apart from the filename suffix +to determine the mime type of a file. If a filename has no suffix, +the value of the resource +.B noMimeSuffix +is used (by default +.IR application/x-unknown ). +If the suffix doesn't match any of the suffixes in +.BR mime.types , +the value of the resource +.B unknownMimeSuffix +is used (by default +.IR application/x-unknown ). +If the +.B mailcap +entries do not list a viewer for a given mime type, xdvi will show +a warning popup. If you want to avoid this warning, and for example +want to always use the netscape browser for unknown MIME types, +you could add the following line to your ~/.mailcap file: +.RS 4 +.nf +.ft 3 +.sp 1n +application/xdvi-unknown; \e + netscape -raise -remote 'openURL(%s,new-window)' +.sp 1n +.ft +.fi +.RE +.\" As an example, consider the following settings, which are the default +.\" settings for buttons 1 and 2: +.\" .RS 5 +.\" .nf +.\" .ft 3 +.\" .sp 1n +.\" xdvi.mainTranslations: #override \e +.\" : do-href()magnifier(*1)\en\e +.\" : do-href-newwindow()magnifier(*2)\en\e +.\" : magnifier(*3)\en +.\" .sp 1n +.\" .ft +.\" .fi +.\" .RE +.\" .PP +.\" If a link points to a file which is not a DVI file (e.g. HTML, or +.\" PostScript), the files +.\" .B mime.types +.\" and +.\" .B mailcap +.\" are parsed to determine a suitable viewer; if no suitable +.\" .B mailcap +.\" entry was found, if the +.\" .SB WWWBROWSER +.\" environment variable is set, or +.\" .B \-browser +.\" was specified on the command line, the browser is launched to load the file. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH STRING SEARCH +The keystroke +.I Ctrl-f +or the menu entry +.I File > Find ... +(or the `Binoculars' symbol in the toolbar, for Motif) +opens a dialog window to search for a text string or +a regular expression in the DVI file. +The keystroke +.I Ctrl-g +jumps to the next match (like pressing the `Find' button in the search window). +.PP +By default, the matches are highlighted in inverted color. +If the display isn't running in TrueColor, or if the X resource +.B matchHighlightInverted +is set to false or the command-line option +.B \-nomatchinverted +is used, xdvi will instead draw a rectangle in +.I highlight +color (see the +.B \-hl +option) around the match. +.PP +If a match crosses a page boundary, only the part on the +first page is highlighted. +.B Xdvi +will scan up to 2 adjacent pages to match strings crossing page +boundaries; but note that header or footer +lines, or intervening float pages will be treated as parts of the +scanned text. Such text will usually cause multi-page matching to fail. +.PP +This emphasizes the fact that searching in the +formatted text (the DVI output) works differently from +searching in the source text: Searching in the DVI file makes it easier to +skip formatting instructions, and makes it possible to search for e.g. +hyphenation and equation numbers; but sometimes the +formatting results can also get in the way, e.g. in the case of +footnotes. In these cases it's better to search in the \*(Te\& source +instead. The use of +.I source specials +will make switching between the +xdvi display and the editor with the \*(Te\& source easier; see the +section +.B SOURCE SPECIALS +below for more information on this. +.PP +The text extracted from the DVI file is in encoded in UTF-8 +(you can view that text by saving the file in UTF-8 format via the +.I File > Save as ... +menu item). +If xdvi has been compiled with locale, +.I nl_langinfo() +and +.I iconv +support, the search term is converted from the character set +specified by the current locale into UTF-8. (See the output of +.B locale -a +for a list of locale settings available on your system). +If +.I nl_langinfo() +is not available, but +.I iconv +is, you can specify the input encoding for +.I iconv +via the X resource +.I textEncoding +(see the output of +.B iconv -l +for a list of valid encodings). If +.I iconv +support is not available, only the encodings +.I ISO-8859-1 +and +.I UTF-8 +are supported (these names are case-insensitive). +.PP +Ideographic characters from CJKV fonts are treated specially: All white space +(spaces and newlines) before and after such characters is ignored in +the search string and in the DVI file. +.PP +To match a newline character, use \fI\en\fR in the search string; +to match the string \fI\en\fR, use \fI\e\en\fR. +.PP +If the checkbox +.I Regular Expression +is activated, the string is treated as a regular expression in +extended POSIX syntax, with the following properties: +.RS 2 +.TP 2 +- +\fIa?\fR matches \fIa\fR zero or one times. +.TP +- +\fIa*\fR matches \fIa\fR zero or more times. +.TP +- +\fIa+\fR matches \fIa\fR one or more times. +Note that \fI*\fR and \fI+\fR are greedy, i.e. they match the longest possible substring. +.TP +- +The pattern \fI.\fR matches any character except for newline. To also match a newline, use `\fI(.|\en)\fR'. +.TP +- +\fIa{n}\fR matches \fIa\fR exactly n times. +.TP +- +\fIa{n,m}\fR matches \fIa\fR at least n and no more than m times. +.TP +- +\fIa|b\fR matches \fIa\fR or \fIb\fR. Brackets can be used +for grouping, e.g.: \fI(a|b)|c\fR. +.TP +- +The string matched by the nth group can be referenced by \fI\en\fR, e.g. \fI\e1\fR refers to the +first match. +.TP +- +The characters \fI^\fR and \fI$\fR match the beginning and the end of a line, respectively. +.TP +- +\fI[abc]\fR matches any of the letters a, b, c, and \fI[a-z]\fR matches all characters from a to z. +.TP +- +Each item in a regular expression can also be one of the following POSIX +character classes: +.br +.nf +.I [[:alnum:]] [[:alpha:]] [[:blank:]] [[:cntrl:]] [[:digit:]] +.I [[:graph:]] [[:lower:]] [[:print:]] [[:space:]] [[:upper:]] +.fi + + +These can be negated by inserting a \fI^\fR symbol after the first bracket: +.I [^[:alpha:]] + +For more details on POSIX regular expressions, see e.g. the +.B IEEE Std 1003.1 +standard definition available online from: + +.nf +http://www.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap09.html +.fi +.TP +- +As a non-standard extension, the following Perl-like abbreviations +can be used instead of the POSIX classes: +.nf +.sp 1n +.ta 1L +8L +30L +Symbol Meaning POSIX Class + + \fI\ew\fR an alphanumeric character \fI[[:alnum:]]\fR + \fI\eW\fR a non-alphanumeric character \fI[^[:alnum:]]\fR + \fI\ed\fR a digit character \fI[[:digit:]]\fR + \fI\eD\fR a non-digit character \fI[^[:digit:]]\fR + \fI\es\fR a whitespace character \fI[[:space:]]\fR + \fI\eS\fR a non-whitespace character \fI[^[:space:]]\fR +.sp 1n +.fi +.TP +- +The following characters are special symbols; they need to be escaped +with \fI\e\fR in order to match them literally: \fI ( ) [ ] . * ? + ^ $ \e\fR. +.TP +- +Matches of length zero are silently skipped. +.RE +.PP +The dialog also provides checkboxes to: +.RS 2 +.TP 2 +- +search backwards; +.TP +- +match in a case-sensitive manner (the default is to ignore case, i.e. a search +string +.I Test +will match both the strings +.I test +and +.I TEST +in the DVI file); +.TP +- +ignore line breaks and hyphens: This removes all hyphens at the ends +of lines and the following newline characters, and replaces all +remaining newline characters by white spaces. So hyphenated words will +appear as one word to the search, and a search for two words with a space +in between will also match the words if they are separated by a linebreak. +.br +Note that the hyphen removal may cause unwanted side effects for compound words +containing hyphens that are wrapped after the hyphen, and that replacing the +newlines affects the interpretation of regular expressions as follows: +The \fI.\fR pattern will also match newlines, and \fI^\fR and \fI$\fR won't match +begin and end of lines any more. (Since currently there is no option for turning +off the greediness of \fI*\fR and \fI+\fR, turning on this option will usually +result in matches that are longer than desired.) +.RE +.PP +The current checkbox settings are saved in the +.I ~/.xdvirc +file. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH PRINT DIALOG +The print dialog window allows you to print all pages, marked pages +(click or drag Mouse-2 in the page list to mark them), or a range +of pages. Note that the page numbers always refer to physical pages, +so if you're using the option `use TeX pages', you may want to disable +it to make it easier to determine the correct page numbers (or avoid this +problem altogether by marking the pages to be printed). +.PP +The value of the +.B Printer +text filed is passed to +.B dvips +via the +.B -o! +mechanism, as a single argument after the `!'. Any arguments +listed in the +.B Dvips options +field are segmented at whitespaces and passed as separate arguments to dvips. +If you e.g. want to print the file 2-up, you should enter +the following string into the +.B Printer +field: +.RS 5 +.nf +.sp 1n + \fIpsnup -2 -q | lpr -Plp\fP +.sp 1n +.fi +.RE +.PP +There are several resources for customizing the behaviour and the default entries +of the print dialog: +.TP +.B dvipsPrinterString +.TP +.B dvipsOptionsString +These can be used to provide default entries for the +.B Printer +and the +.B Dvips options +text fields, respectively. If no paper size is specified in the DVI file +(via e.g. \eusepackage[dvips]{geometry} - this is the preferred method), +the input field is initialized with the current value of the +command line option/X resource +.BR paper . +E.g., the option +.I -paper a4r +is translated into the dvips options +.IR "-t a4 -t landscape" . +Note that no check is performed whether dvips actually understands these +options (it will ignore them if it can't); currently not all options +used by xdvi are also covered by dvips. +.TP +.B dvipsHangTime +.TP +.B dvipsFailHangTime +These specify the time (in milliseconds) that the printing progress window will +stay open after the +.B dvips +process has terminated. The value of +.BR dvipsHangTime +is used if the process terminates successfully; +.B dvipsFailHangTime +is used if it terminates with an error. The default values are 1.5 and 5 seconds, respectively. +If both values are negative, the window will stay open until it is closed by the user. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SAVE DIALOG +This dialog allows you to save all or selected/marked pages in the current +DVI file. You can save in one of the following formats: +.RS 2 +.TP 2 +- +Postscript (uses +.B dvips +to convert the DVI file to a Postscript file, just like when printing +to a Postscript file). +.TP +- +PDF (first uses +.B dvips +to convert the DVI file to a Postscript file, then uses +.B ps2pdf +to convert the Postscript file to PDF). +.TP +- +Plain text in ISO-8859-1 or UTF-8 encoding. The latter will preserve more +of the special LaTeX characters e.g. from mathematical mode. Note however +that e.g. only few of LaTeX's mathematical symbols can be rendered correctly +as text; so this funcionality works best for plain text documents. +If a character cannot be displayed in the selected +charset, it is replaced by `\e' followed by the hexadecimal character code. +If a character is not recognized at all, it is replaced by `?'. +.RE +.PP +The programs for Postscript and PDF conversion can be customized via +the command line options or X resources +.BR -dvipspath / .dvipsPath +and +.BR -ps2pdfpath / .ps2pdfPath , +respectively; see the explanation of these options above for more details. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH MODES +The keystroke +.B Ctrl-m +[\fBswitch-mode()\fR] +switches between three different mouse bindings, +which can also be activated via the +.B Modes +menu (in Motif, this is a submenu of the +.B Options +menu called +.BR "Mouse Mode" ). +The default mode at startup can be customized via the X resource +.B mouseMode +or the command-line option +.BR \-mousemode . +The default startup mode is Magnifier Mode. +.PP +.B Note: +The modes are implemented by changing the +.I magnifier() +action. Switching the mode will not work if +.B Mouse-1 +has been customized to an action sequence that does +not contain the magnifier() action. +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B "Magnifier Mode" +In this mode, the mouse buttons 1 to 5 pop up a ``magnifying glass'' +that shows an unshrunken image of the page (i.e. an image at the resolution +determined by the option/X resource +.B pixels +or +.BR mfmode ) +at varying sizes. When the magnifier is moved, small ruler-like +tick marks are displayed at the edges of the magnifier (unless +the X resource +.B delayRulers +is set to false, in which case the tick marks are always displayed). +The unit of the marks is determined by the X resource +.B tickUnits +(mm by default). This unit can be changed at runtime via the action +.BR switch-magnifier-units() , +by default bound to the keystroke +.RB ` t ' +(see the description of that key, and of switch-magnifier-units() for +more details on the units available). +.br +The length of the tick marks can be changed via the X resource +.B tickLength +(4 by default). A zero or negative value suppresses the tick marks. +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B "Text Selection Mode" +This mode allows you to select a rectangular region of text in the DVI +file by holding down +.B Mouse-1 +and moving the mouse. The text is put into +the X primary selection so that it can be pasted into other X applications +with +.B Mouse-2 +as usual. +.br +If xdvi has been compiled with locale, +.I nl_langinfo() +and +.I iconv +support, the selected text is converted into the character set of the +current locale (see the output of +.B locale -a +for a list of locale settings available on your system). +If +.I nl_langinfo() +is not available, but +.I iconv +is, you can specify the input encoding for +.I iconv +via the X resource +.I textEncoding +(see the output of +.B iconv -l +for a list of valid encodings). If +.I iconv +support is not available, only the encodings +.I ISO-8859-1 +and +.I UTF-8 +are supported (these names are case-insensitive). +.br +Note that UTF-8 is +the only encoding that can render all characters (e.g. mathematical +symbols) of a DVI file. If ISO-8859-1 is active, characters that cannot be displayed +are replaced by `\e' followed by the hexadecimal character code. +For other encodings, such characters may trigger iconv error messages. +If a character is not recognized at all, it is replaced by `?'. +.br +To extract larger portions of text, you can alternatively +save selected pages or the entire file in text format via the +.B File > Save as ... +menu. +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.B "Ruler Mode" +This mode provides a simple way of measuring distances on the page. +.br +When this mode is activated, the mouse cursor changes into a +thin cross, and a larger, cross-shaped ruler is drawn in the +highlight color at the mouse location. The ruler doesn't have +units attached to it; instead, the current distance between the +ruler and the mouse cursor is continuously printed to the +statusline. +.br +When activating Ruler Mode, the ruler is at first attached to +the mouse and can be moved around. It can then be positioned at +a fixed place by clicking +.BR Mouse-1 . +After that, the mouse cursor +can be moved to measure the horizontal +.RI ( dx ), +vertical +.RI ( dy ) +and direct (shortest) +.RI ( dr ) +distance between the ruler center point and the mouse. +.br +Clicking +.B Mouse-1 +again will move the ruler to the current mouse +position, and holding down +.B Mouse-1 +will drag the ruler around. +.br +In Ruler Mode, the following special keybindings extend or +replace the default bindings: +.RS 7 +.TP 7 +.B o +.RB [ ruler-snap-origin() ] +Snap the ruler back to the origin coordinate (0,0). +.TP +.B t +\fR[overrides \fBswitch-magnifier-units()\fP] +Toggle between various ruler units, which can be specified by the X +resource +.B tickUnits +(`mm' by default). +.TP +.B P +\fR[overrides \fBdeclare-page-number()\fP] +Print the distances shown in the statusline to standard output. +.RE +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH TOOLBAR (Motif only) +The Motif toolbar can also be customized. The XPM file used for the +toolbar icons can be specified via the resource +.BR toolbarPixmapFile , +which should contain a filename that can be found in one of +.B XFILESEARCHPATH +or +.B XDVIINPUTS +(see the section +.B FILE SEARCHING +below for more information on these variables). +.B Xdvi +will try to split this pixmap horizontally into +.I n +pieces, where each piece is as wide as the pixmap is high +and is treated as an image for toolbar button +.IR n . +This means that each icon should be a square, and that the entire +pixmap should have width +\fIn\fR x \fIh\fR if \fIh\fR is the height of the pixmap. +.PP +The resource +.B toolbarTranslations +can be used to map icons/buttons to specific actions. +The resource should contain a string separated by newline characters, +similar to the resources +.B mainTranslations +and +.BR menuTranslations . +Every line must contain either a spacer definition, or an icon definition: +.PP +A spacer definition is a string \fBSPACER(\fIn\fB)\fR, +where +.I n +is the number of pixels inserted as separator to the following button. +.PP +An icon definition is a colon-separated list containing the following elements: +.RS 2 +.TP 2 +.SB - the index of an icon in the pixmap file (starting from zero); +.TP +.SB - a long tooltip string, displayed in the status area; +.TP +.SB - a short tooltip string, displayed as popup; +.TP +.SB - a sequence of actions to be performed when the corresponding toolbar button is pushed. +.RE +.PP +To illustrate this, the default value of +.B toolbarTranslations +looks as follows: +.RS 5 +.nf +.ft 3 +.sp 1n +xdvi.toolbarTranslations: \e + SPACER(5)\en\e + 0:Open a new document (Key\e\e: Ctrl-f):\e + Open file:select-dvi-file()\en\e + SPACER(10)\en\e + 1:Reread this document (Key\e\e: R):\e + Reread file:reread-dvi-file()\en\e + SPACER(10)\en\e + 2:Go to the first page of this document (Key\e\e: 1g):\e + Go to first page:goto-page(1)\en\e + 3:Go to the previous page of this document (Key\e\e: p):\e + Go to previous page:back-page(1)\en\e + 4:Go to the next page of this document (Key\e\e: n):\e + Go to next page:forward-page(1)\en\e + 5:Go to the last page of this document (Key\e\e: g):\e + Go to last page:goto-page()\en\e + SPACER(10)\en\e + 6:Enlarge the display (Key\e\e: Ctrl-+):Zoom in:\e + set-shrink-factor(+)\en\e + 7:Shrink the display (Key\e\e: Ctrl--):Zoom out:\e + set-shrink-factor(-)\en\e + SPACER(10)\en\e + 8:Jump back to the previous hyperlink (Key\e\e: B):\e + Back hyperlink:htex-back()\en\e + SPACER(10)\en\e + 10:Print this document:Print:print()\en\e + SPACER(10)\en\e + 11:Toggle marks for odd pages (Key\e\e: 1m):\e + Toggle odd:toggle-mark(1)\en\e + 12:Toggle marks for even pages (Key\e\e: 2m):\e + Toggle even:toggle-mark(2)\en\e + 13:Toggle mark for current page (Key\e\e: 2m):\e + Toggle current:toggle-mark()\en\e + 14:Unmark all pages (Key\e\e: 0m):\e + Unmark all:toggle-mark(0)\en\e + SPACER(10)\en\e + 18:Display fonts darker (Key\e\e: Alt-Ctrl-+):\e + Fonts darker:change-density(5)\en\e + 19:Display fonts lighter (Key\e\e: Alt-Ctrl--):\e + Fonts lighter:change-density(-5)\en +.sp 1n +.ft +.fi +.RE +.PP +When the mouse remains over a toolbar button for a certain period, a `tooltip' +window is shown, describing what the button does using the +.I short tooltip string +from the above resource. At the same time, the +.I long tooltip string +is displayed in the statusline. +The appearance and behaviour of these tooltips can be customized via +the following resources: +.TP +.B tipShell.background +Background color of the tooltip window. +.TP +.B tipShell.fontSet +Font used for the tooltip. +.TP +.B tipShell.waitPeriod +The time (in milliseconds) the mouse pointer needs to be over +the button before the tooltip is shown. Set it to a negative value +to suppress the tooltips altogether. + +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH GREYSCALING AND COLORMAPS +The greyscale anti-aliasing feature in +.B xdvi +will not work at its best if the display does not have enough colors available. +This can happen if other applications are using most of the colormap +(even if they are iconified). If this occurs, then +.B xdvi +will print an error message and turn on the +.B -copy +option. This will result in overstrike characters appearing wrong; +it may also result in poor display quality if the number of available +colors is very small. +.PP +Typically this problem occurs on displays that allocate eight bits +of video memory per pixel. To see how many bits per pixel your display +uses, type +.B xwininfo +in an +.B xterm +window, and then click the mouse on the root window when asked. The +``Depth:'' entry will tell you how many bits are allocated per pixel. +.PP +Displays using at least 15 bits per pixel are typically +.B TrueColor +visuals, which do not have this problem, since their colormap is +permanently allocated and available to all applications. (The visual +class is also displayed by +.BR xwininfo .) +For more information on visual classes see the documentation for the +X Window System. +.PP +To alleviate this problem, therefore, one may (a) run with more bits +per pixel (this may require adding more video memory or replacing the video +card), (b) shut down other applications that may be using much of the colormap +and then restart +.BR xdvi , +or (c) run +.B xdvi +with the +.B \-install +option. +.PP +One application which is often the cause of this problem is +.BR Netscape . +In this case there are two more alternatives to remedying the situation. +One can run +.RB `` "netscape -install" '' +to cause +.B Netscape +to install a private colormap. This can cause colors to change in +bizarre ways when the mouse is moved to a different window. +Or, one can run +.RB `` "netscape -ncols 220" '' +to limit +.B Netscape +to a smaller number of colors. A smaller number will ensure that +other applications have more colors available, but will degrade the +color quality in the +.B Netscape +window. + +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH HANDLING OF POSTSCRIPT FIGURES +.B Xdvi +can display Encapsulated PostScript (EPS) files included in the +.I dvi +file. Such files are first searched for in the directory where the +.I dvi +file is, and then using normal +.B Kpathsea +rules. There is an exception to this, however: if the file name begins +with a backtick +.RB ( ` ), +then the remaining characters in the file name give a shell command (often +.BR zcat ) +which is executed; its standard output is then sent to be interpreted as +PostScript. +Since the execution of arbitrary shell commands with the user's +permissions is a huge security risk, evaluation of these backtick +commands is disabled by default. It needs to be activated via the +.B \-allowshell +command-line option. +.B NOTE: +You should never use this option when viewing documents that you +didn't compile yourself. The backtick specials are not needed for +uncompressing gzipped Postscript files, since +.B xdvi +can do that on the fly if the filename ends with +.I .eps.gz +or +.I .eps.Z +(and if the first bytes of the file indicate that the file is indeed +compressed). This is both safer and more flexible than the backtick +approach, since the default file searching rules will apply to such +filenames too. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH T1LIB +Using T1Lib, a library written by Rainer Menzner +(see ftp://sunsite.unc.edu/pub/Linux/libs/graphics/), +.B xdvi +can render Postscript Type1 fonts directly, without the +route via \*(Te\& pixel (pk) +fonts. The advantage of this is that only one size of each font needs +to be stored on disk. +Unless the +.B -not1lib +option is used, +.B xdvi +will try to render every font using T1Lib. Only as a fallback it will +invoke an external program (like +.BR mktexpk , +which in turn may invoke utilities like +.B ps2pk +or +.BR gsftopk ) +to generate a pixel font from the Type1 source. The direct rendering +of the +.B Computer Modern +fonts should work out-of-the box, whereas other Type1 fonts such as +the 35 `standard' Postscript fonts resident in printers may need +to be made accessible for use with xdvi, unless your system +administrator or TeX distribution has already done so (which is the case +e.g. for current teTeX systems). The +.B xdvik +distribution comes with a utility called +.B t1mapper +to make these fonts available for xdvi; +see the manual page for t1mapper(1) for usage details. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SPECIALS (GENERALLY) +Any of the specials used by +.B xdvi +may be preceded by the characters +.RB `` xdvi: ''. +Doing so does not change the behavior of the special under +.BR xdvi , +but it tells other dvi drivers (such as e.g. dvips) to ignore the special. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SOURCE SPECIALS +Some \*(Te\& implementations or macro packages provide the facility to +automatically include so-called `source specials' into a DVI file. +These contain the line number, eventually a column number, and the +filename of the .tex source. This makes it possible to jump from a .dvi +file to the corresponding place in the .tex source and vice versa (also +called `inverse search' - jumping from the DVI file to the TeX file is +also known as `reverse search', and jumping from the TeX file to the +DVI file as `forward search'). +.P +To be usable with +.BR xdvi , +source specials in the +.I dvi +file must have one of the following formats: +.RS 5 +.nf +.sp 1n + \fBsrc:\fP\fIline\fP[ ]\fIfilename\fP + \fBsrc:\fP\fIline\fP\fB:\fP\fIcol\fP[ ]\fIfilename\fP + \fBsrc:\fP\fIline\fP + \fBsrc:\fP\fIline\fP\fB:\fP\fIcol\fP + \fBsrc::\fP\fIcol\fP +.sp 1n +.fi +.RE +If +.I filename +or +.I line +are omitted, the most recent values are used. The first source special on +each page must be in one of the first two forms, since defaults are not +inherited across pages. +.sp +You will need a \*(Te\& implementation that provides an appropriate +switch (e.g. +.IR -src ) +or a macro package +(such as +.I srcltx.sty +or +.IR srctex.sty , +available from CTAN:macros/latex/contrib/supported/srcltx/) +to insert such source specials into the DVI file. +.sp +For reverse search, the combination +.I Ctrl-Mouse 1 +will make xdvi open an editor (the value of the +.I \-editor +command line option) with the file and the line number of the .tex +source. See the description of the +.I \-editor +option for more information +and example settings. +.P +For forward search, +.B xdvi +has a +.I \-sourceposition +option that makes +.B xdvi +jump to the page in +the DVI file corresponding to the given line (or the closest +line having a source special) of the specified file and highlight +the found region. See the description of the +.I \-sourceposition +option for more details. +.PP +More information on setting up various editors for use with source +specials can be found at: +.RS 5 +.nf +.sp 1n +http://xdvi.sourceforge.net/inverse-search.html +.sp 1n +.fi +.RE +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH PAPERSIZE SPECIALS +.B xdvi +accepts specials to set the paper size for the document. These specials +should be of the form +.RS 5 +.nf +.sp 1n + \fBpapersize=\fP[\fB*\fP]\fIwidth\fP,\fIheight\fP +.sp 1n +.fi +.RE +.PP +where +.I width +and +.I height +give the width and height of the paper, respectively. Each of these should +appear in the form of a decimal number followed by any of the two-letter +abbreviations for units accepted by \*(Te\& +.RB ( pt , +.BR pc , +.BR in , +.BR bp , +.BR cm , +.BR mm , +.BR dd , +.BR cc , +or +.BR sp ). +If an asterisk +.RB ( * ) +appears just before the width, then the measurements refer to the document +dimensions (e.g., +.B pt +as opposed to +.BR truept ). +This allows a macro package to vary the page size according to elements +of the document; e.g., +.RS 5 +.ft 3 +.nf +.sp 1n +\especial{xdvi: papersize=*\enumber\ewd\emybox sp, + \enumber\eht\emybox sp} +.sp 1n +.ft +.fi +.RE +.PP +Except for the asterisk, this format is compatible with +.BR dvips . +.P +The last +.B papersize +special on a page determines the size of that page. If there is no such +special on a given page, the most recent +.B papersize +is used, or, if there are no +.B papersize +specials on any preceding page, then the value of the +.B paper +resource (or +.B \-paper +option on the command line) is used. Thus the paper size may vary for +different pages of the +.I dvi +file. +.P +If the +.B paper +resource (or +.B \-paper +command-line option) begins with a plus sign +.RB (` + '), +then all +.B papersize +specials in the +.I dvi +file are ignored. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH COLOR SPECIALS +The color specials supported by +.B xdvi +are the same as those supported by +.BR dvips , +except that the literal PostScript color specification (as in the +.B AggiePattern +example in the +.B dvips +documentation) is not supported. +There are also some restrictions due to the way xdvi's drawing routines +are implemented; e.g. the +.B \ecolorbox +and +.B \efcolorbox +macros don't work with +.BR xdvi . +See the section LIMITATIONS below for more information on these restrictions. +.B Xdvi +supports the same list of named colors as +.B dvips +does, namely: +.P +.BR Apricot , +.BR Aquamarine , +.BR Bittersweet , +.BR Black , +.BR Blue , +.BR BlueGreen , +.BR BlueViolet , +.BR BrickRed , +.BR Brown , +.BR BurntOrange , +.BR CadetBlue , +.BR CarnationPink , +.BR Cerulean , +.BR CornflowerBlue , +.BR Cyan , +.BR Dandelion , +.BR DarkOrchid , +.BR Emerald , +.BR ForestGreen , +.BR Fuchsia , +.BR Goldenrod , +.BR Gray , +.BR Green , +.BR GreenYellow , +.BR JungleGreen , +.BR Lavender , +.BR LimeGreen , +.BR Magenta , +.BR Mahogany , +.BR Maroon , +.BR Melon , +.BR MidnightBlue , +.BR Mulberry , +.BR NavyBlue , +.BR OliveGreen , +.BR Orange , +.BR OrangeRed , +.BR Orchid , +.BR Peach , +.BR Periwinkle , +.BR PineGreen , +.BR Plum , +.BR ProcessBlue , +.BR Purple , +.BR RawSienna , +.BR Red , +.BR RedOrange , +.BR RedViolet , +.BR Rhodamine , +.BR RoyalBlue , +.BR RoyalPurple , +.BR RubineRed , +.BR Salmon , +.BR SeaGreen , +.BR Sepia , +.BR SkyBlue , +.BR SpringGreen , +.BR Tan , +.BR TealBlue , +.BR Thistle , +.BR Turquoise , +.BR Violet , +.BR VioletRed , +.BR White , +.BR WildStrawberry , +.BR Yellow , +.BR YellowGreen , +.BR YellowOrange . +.P +Note that these names are case sensitive. +.P +The documentation of the La\*(Te\& +.B color +package provides more details on how to use such specials with +La\*(Te\&; see the +.B dvips +documentation for a detailed description of the +syntax and semantics of the color specials. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SIGNALS +When +.B xdvi +receives a +.SB SIGUSR1 +signal, it rereads the +.I dvi +file. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ENVIRONMENT +.B Xdvik +uses the same environment variables and algorithms for searching for +font files as \*(Te\& and friends. See the documentation for the +.B Kpathsea +library, +.BR kpathsea.dvi , +for a detailed description of these. +.PP +In addition, +.B xdvik +accepts the following variables: +.TP +.SB DISPLAY +Specifies which graphics display terminal to use. +.TP +.SB KPATHSEA_DEBUG +Trace +.B Kpathsea +lookups; set it to +.B -1 +(= all bits on) for complete tracing. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.SB EXTENSIONMAPS +A list of files to be searched for mime types entries (as for Acrobat Reader). +Earlier entries in one of these files override later ones. +If this variable is not set, the following default path is used: +.RS 7 +.nf +.ft 3 +.sp 1n +$HOME/.mime.types:/etc/mime.types:\e + /usr/etc/mime.types:/usr/local/etc/mime.types +.sp 1n +.ft +.fi +.RE + +.TP +.SB MAILCAPS +A list of files to be searched for mailcap entries, as defined by RFC +1343. See this RFC or the +.BR mailcap (4) +manual page for a detailed description of the mailcap file format. +Currently, only the following mailcap features are supported: +.RS 7 +.TP 7 +.BI test= command +The entry is only used if +.I command +can be executed via the +.B system() +call and if the system() call returns with value 0 (success). +The +.I command +string may contain the format string +.IR %s , +which will be replaced by the file name. +.TP +.BI needsterminal +If this flag is used, the command will be executed in a new xterm +window by prepending +.RI `` "xterm -e "'' +to the command string. +.RE +.PP +.RS 7 +All other fields in the mailcap entry are ignored by xdvi. +Earlier entries in one of these files override later ones. +If the variable is not defined, the following default path is used: +.RS 4 +.nf +.ft 3 +.sp 1n +$HOME/.mailcap:/etc/mailcap:/usr/etc/mailcap:\e + /usr/local/etc/mailcap +.sp 1n +.ft +.fi +.RE +.br +For security reasons, some special characters (i.e.: ( ) ` \e ;) +are escaped in the argument before passing it to +.BR system() . +.RE +.TP +.SB BROWSER +Determines the web browser used to open external links (i.e., all URLs that don't +start with the +.RI ` file: ' +scheme and are not relative links in the local DVI file), and to open links +for which no viewer has been specified in the +.B mailcap +files. The value of this variable is a colon-separated list of commands. Xdvi +will try each of them in sequence until one succeeds (i.e. doesn't immediately +return with status 0). This allows you to +specify your favourite browser at the beginning, +and fallback browsers at the end. Every occurrence of +.I %s +in the string is replaced by the target URL; every occurrence of +.I %% +is replaced by a single +.IR % . +If no +.I %s +is present, the URL string is added as an extra argument. +.br +An example setting is: +.RS 7 +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP 7 +.SB "netscape -raise -remote 'openURL(%s,new-window)':xterm -e lynx %s:xterm -e wget %s:lynx %s:wget %s" +.TP +See +.TP +.SB http://www.catb.org/~esr/BROWSER/ +.PP +for more details on the +.B BROWSER +environment variable. +.RE +.TP +.SB TMPDIR +The directory to use for storing temporary files created when uncompressing +PostScript files. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.SB XEDITOR +Determines the editor command used for source special `reverse +search', if neither the +.I \-editor +command-line option +nor the +.I .editor +resource are specified. See the description of the +.I \-editor +command line option for details on the format. +.TP +.SB VISUAL +Determines an editor to be opened in an xterm +window if neither of +.IR -editor , +.IR .editor , +or +.I XEDITOR +is specified. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.SB EDITOR +Determines an editor to be opened in an xterm +window if neither of +.IR -editor , +.IR .editor , +.I XEDITOR +or +.I VISUAL +is specified. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TP +.SB WWWBROWSER +Obsolete; use +.B BROWSER +instead. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LIMITATIONS +.B xdvi +accepts many but not all types of PostScript specials accepted by +.BR dvips . +For example, it accepts most specials generated by +.B epsf +and +.BR psfig . +It does not, however, support +.B bop\-hook +or +.BR eop\-hook , +nor does it allow PostScript commands to affect the rendering of things that +are not PostScript (for example, the ``NEAT'' and rotated ``A'' examples in the +.B dvips +manual). These restrictions are due to the design of +.BR xdvi ; +in all likelihood they will always remain. +.PP +La\*(Te\&2e rotation specials are currently not supported. +.PP +.B MetaPost +files containing included text are not supported. +.PP +.BR Xdvi 's +color handling doesn't support the +.B \ecolorbox +and +.B \efcolorbox +macros; this is not likely to change in the near future. This also +means that e.g. colored tables (as created by the +.I colortbl +package) may render incorrectly: Text in colors different from the +default foreground color may not be displayed. When the page is +redrawn (e.g. after using the magnifier), the background color of the +cells may overdraw the text. +.SH FILES +.TP +.SB $HOME/.xdvirc +A file that holds all settings that the user changed via the keys, the `Options' +and the Xaw `Modes' menu and the dialogs, as X resources. These resources override the +settings in +.BR $HOME/.Xdefaults . +This file is ignored if the +.B \-q +option is used or the +.B noInitFile +X resource is set. +.TP +.SB xdvi.cfg +A configuration file for the T1 font setup which needs to be supplied +in the directory determined by the +.B XDVIINPUTS +environment variable. Please see the file +.B http://xdvi.sourceforge.net/README.t1fonts +if that file is missing. +.SH SEE ALSO +.BR X (1), +.BR dvips (1), +.BR mktexpk (1), +.BR ps2pk (1), +.BR gsftopk (1), +.BR t1mapper (1), +.BR mailcap (4), +the +.B Kpathsea +documentation, +and the Xdvik home page at +.BR http://xdvi.sourceforge.net/ . +.SH AUTHORS +Eric Cooper, CMU, did a version for direct output to a QVSS. Modified +for X by Bob Scheifler, MIT Laboratory for Computer Science. Modified +for X11 by Mark Eichin, MIT SIPB. Additional enhancements by many +others. +.PP +The current maintainer of the original +.B xdvi +is Paul Vojta, U.C. Berkeley. +.PP +Code for the xdvik variant has been contributed +by many people, whose names are scattered across the +source files. Xdvik is hosted on +.B CTAN:dviware/xdvik +and on SourceForge; for the most up-to-date information, please +visit: +.PP +.B http://xdvi.sourceforge.net +.PP +Please report all bugs to the SourceForge bug tracker: +.PP +.nf +.B http://sourceforge.net/tracker/?func=add&group_id=23164&atid=377580 +.PP + -- cgit v1.2.3