% Copyright (c) 1986-1991 The Regents of the University of California.
% All rights reserved.
%
% Permission is hereby granted, without written agreement and without
% license or royalty fees, to use, copy, modify, and distribute this
% software and its documentation for any purpose, provided that the
% above copyright notice and the following two paragraphs appear in
% all copies of this software.
% 
% IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
% DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT
% OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
% CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
%
% THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
% INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
% AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
% ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
% PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
%
% DOCSTR Wed Sep 14 17:33:54 1988

\input docmac.tex

\startdoc

\docstr{abort-character}
\type{\it integer}
\defa{\tt 0x7}
\desc{This is the character that is recognized as the ``interrupt''
character.  The default is control-G.
Each character typed is compared to this value, and
if it matches, the current action is aborted.
While this value is
interpreted as a character, it is stored as an integer.
Thus to change your \em{abort-character} to the character `A',
you should set \em{abort-character} to 65.}

\docstr{border-width}
\type{\it integer}
\defa{\tt 3}
\desc{This is the width in pixels of the box that will be drawn around
the page image.  This box is only drawn if the boolean
\em{draw-borders} is true.}
\seea{{\it draw-borders}}

\docstr{cached-pages}
\type{\it integer}
\defa{\tt 3}
\desc{This is the number of \lit{DVI} pages that \lit{dvitool} will
cache.  A cached page does not have to be reread from the file 
if it is viewed again, so redisplaying it is fast.  However,
there is a
substantial performance penalty due to swapping if \lit{dvitool}
attempts to cache too many pages, so it behooves you to keep
this variable small.  You can see the effects of various settings
by searching for some non-existant string in a long \lit{DVI}
file while watching various performance indicators (see 
\em{perfmeter(1)}).  An empirical test
(searching for a non-existant string in a 200 page document)
showed an average reduction in total search time of 49 percent
when a 2 page cache was used compared with a 10 page cache.
A cache size of 2--4 pages seems optimal for most circumstances.}

\docstr{cwd}
\type{\it string}
\desc{This string is the exact analog to the shell's current working
directory.  Though it can be altered via the \em{set} command,
a more appropriate means of changing it is the \em{cd} command
because \em{cd} expects an argument of type \em{filename} which
can be completed on.  To \em{set}, \em{cwd} is just a string.}
\seea{{\it cd}, {\it set}}

\docstr{draw-borders}
\type{\it boolean}
\defa{\tt on}
\desc{This variable controls whether a border of \em{border-width}
pixels is drawn around the page image.}
\side{Makes the page image larger, and thus costs some memory (about
4000 bytes for a 3 pixel border).  You may wish to turn this
off in a memory--starved environment.}
\seea{{\it border-width}}

\docstr{enable-ansi-keys}
\type{\it boolean}
\defa{\tt on}
\desc{This variable controls the way the function keys are interpreted.
When true, the ANSI sequences generated by the function (and left
and right) keys are interpreted and functions are run based on
bindings that are changeable only at compile time.  When false,
all the function keys simply print out an innocuous message.
N.B. This information is only valid when the function 
\em{ansi-keys} is bound to the string ``\lit{\\e[}''.}
\seea{{\it ansi-keys}}

\docstr{font-path}
\type{\it string}
\defa{\tt {\input fontpath }}
\desc{This is a list of places to look for the font files (more correctly,
for pk or pxl files) that \lit{dvitool} uses.  It is in the
same format as the PATH of \em{csh(1)}, i.e. \lit{path:path...} where
each path element may contain the \lit{\~} character to reference
a user's home directory or \$NAME to reference any environment
variable.  It is an error to reference an undefined environment
variable.

\lit{Dvitool} looks for both types (PK and PXL) of 
font files when it goes searching for a font unless the directory
of the pathname (one of the \em{path}'s above) contains the
substring ``\lit{pk}'' or the substring ``\lit{pixel}.''
If one of those two substrings are found, then \lit{dvitool} 
will only look for that type of font file in that directory.
So if you have some PXL and some PK files, it makes
good sense to use a \em{font-path} something like this:
{\break\indent\indent\tt /usr/local/lib/fonts/pk:/usr/local/lib/fonts/pixel}}

\docstr{init-cursor-file}
\type{\it string}
\defa{\tt null}
\desc{If set, this string points to a file that contains an image
to be used as the default cursor for \lit{dvitool}.  The
named file may contain a \lit{\~} reference and it is presumed
to be the output of \em{iconedit(1)}.  As with all the 
\em{init-} variables, this variable can only be set in
the user's \lit{.dvitoolrc} file.}
\seea{{\it dvitoolrc}, {\it init-cursor-xhot}, {\it init-cursor-yhot}, {\it init-icon-file}}

\docstr{init-cursor-xhot}
\type{\it integer}
\defa{\tt 9}
\desc{This is the horizontal offset in pixels from the upper left 
corner of the cursor to consider the ``hot spot'' of the
cursor.  The hot spot of the cursor is the point considered
to be the focal point of the cursor; it is a means of describing
which of the {$16^2$} pixels in the cursor image is the pixel 
actually being pointed to.  The default is for the circle cursor;
it should be changed if you load your own cursor with 
\em{init-cursor-file}.}
\seea{{\it init-cursor-file}, {\it init-cursor-yhot}}

\docstr{init-cursor-yhot}
\type{\it integer}
\defa{\tt 9}
\desc{The vertical analog to \em{init-cursor-xhot}.}
\seea{{\it init-cursor-file}, {\it init-cursor-xhot}}

\docstr{init-icon-file}
\type{\it string}
\defa{\tt null}
\desc{This string names a file to be used to create the icon image
for \lit{dvitool}.  It is assumed to be the output of
\em{iconedit(1)}.}
\seea{{\it init-cursor-file}, {\it init-icon-x}, {\it init-icon-y}}

\docstr{init-icon-x}
\type{\it integer}
\defa{\tt 1000}
\desc{This is the horizontal position of the
pixel at which the upper left hand corner of the
\lit{dvitool} icon will be painted.}
\seea{{\it close-window}, {\it init-icon-y}, {\it init-icon-file}}

\docstr{init-icon-y}
\type{\it integer}
\defa{\tt 0}
\desc{This is the vertical position of the pixel at which the upper
left hand corner of the \lit{dvitool} icon will be painted.}
\seea{{\it close-window}, {\it init-icon-x}, {\it init-icon-file}}

\docstr{init-iconic}
\type{\it boolean}
\defa{\tt off}
\desc{When this variable is turned on, \lit{dvitool} appears in iconic
form when it is first painted.  This variable provides exactly the
same functionality as the \em{suntools(1)} flag \lit{-Wi}.  The most
common use of \em{init-iconic} is when \lit{dvitool} is invoked from a
\em{suntools(1)} menu (which doesn't allow the \lit{-Wi} flag).  When
\lit{dvitool} is started from a \lit{.suntools} file it is better to
specify the \lit{-Wi} flag on the command line so that when
\lit{dvitool} is invoked some other way, it will come up non-iconic.}
\seea{{\it close-window}, {\it init-icon-file}, {\it init-icon-x}, {\it init-icon-y}}

\docstr{init-scrollbars-on}
\type{\it boolean}
\defa{\tt on}
\desc{This variable controls whether or not \lit{dvitool} will be created
with scrollbars.}

\docstr{init-win-height}
\type{\it integer}
\defa{\tt 400}
\desc{This is the height in pixels that \lit{dvitool} will have 
when it is first created.}
\seea{{\it full-screen}, {\it init-win-width}, {\it zoom-tool}}

\docstr{init-win-width}
\type{\it integer}
\defa{\tt 1064}
\desc{This is the width in pixels that \lit{dvitool} will have when it is
first created.  The default value creates a window that is wide
enough to see the entire width of an 8.5 X 11 inch page with a 
3 pixel wide border and 1 inch margins.}
\seea{{\it full-screen}, {\it init-win-height}, {\it zoom-horizontal}}

\docstr{init-win-x}
\type{\it integer}
\defa{\tt 88}
\desc{This is the horizontal position of the pixel that the upper
left hand corner of \lit{dvitool} will be initially drawn at.}
\seea{{\it init-win-y}}

\docstr{init-win-y}
\type{\it integer}
\defa{\tt 200}
\desc{This is the vertical position of the pixel that the upper
left hand corner of \lit{dvitool} will be initially drawn at.}
\seea{{\it init-win-x}}

\docstr{kern-threshold}
\type{\it integer}
\defa{\tt 150}
\desc{This variable controls how \lit{dvitool} interprets the stream
of \lit{DVI} commands that it sees as ASCII characters.  
Recall that a \lit{DVI} file consists of an arbitrary combination
of ``set character'' commands interspersed with horizontal and
vertical movement commands.  \lit{Dvitool} must have some way of
deciding whether a horizontal movement is an interword movement,
or a horizontal kern.  The prior command should be interpreted as
an ASCII space, while the latter should not.  \em{Kern-threshold}
is the break--point for that decision: horizontal movements greater
than \em{kern-threshold} are considered to be ASCII spaces.
The value compared with the horizontal movements is actually the
width of the widest page mulitplied by the \em{kern-threshold}
and a constant.
Thus for large point sizes or small page widths, 
\em{kern-threshold} may need to be increased.
The default value works well for 10 point text.}
\seea{{\it ascii-of-selection}, {\it extend-selection}, {\it line-break-threshold}, {\it select-char}}

\docstr{left-margin}
\type{\it dimension}
\defa{\tt 1in}
\desc{This is the width of the left margin.
Characters may be typeset in the margins, but it is an error 
to attempt to set a character to the left of the area allocated
by \em{left-margin} which is ``off the page.'' 
\lit{Dvitool} will automatically make the load image bigger when
asked to set any characters in the margins (left, right, top or
bottom), but will complain if asked to set a character outside them.
If you really want to see those characters, you must change
\em{page-height} and \em{page-width}.
As with all variables
of type \em{dimension}, this value may be specified in either
inches (in), scaled points (sp), points (pt), or centimeters
(cm).}
\seea{{\it page-height}, {\it page-width}, {\it show-load-image}, {\it top-margin}}

\docstr{line-break-threshold}
\type{\it integer}
\defa{\tt 110}
\desc{This value is a threshold over which vertical movements will be 
considered line breaks.  A line break is considered a space in
the search algorithm.  See \em{kern-threshold}.}
\seea{{\it ascii-of-selection}, {\it extend-selection}, {\it kern-threshold}, {\it select-char}}

\docstr{log-filename}
\type{\it string}
\defa{\tt null}
\desc{When this string is non-null, it is the name of a log file in
which a copy of all of the messages \lit{dvitool} produces in it's
message window will be placed.  When the file is first openned, it is
truncated.  It is an error for the user not to be able to open the
file.  To turn message logging off, set \em{log-file} to the 
null string by entering \lit{$<$return$>$} as the first character.}

\docstr{page-height}
\type{\it dimension}
\defa{\tt 11in}
\desc{The minimum height of the page image.  See \em{left-margin}.}
\seea{{\it left-margin}, {\it page-width}, {\it top-margin}}

\docstr{page-width}
\type{\it dimension}
\defa{\tt 8.5in}
\desc{The minimum width of the page image.  See \em{left-margin}.}
\seea{{\it left-margin}, {\it page-height}, {\it top-margin}}

\docstr{show-load-image}
\type{\it boolean}
\defa{\tt off}
\desc{When true, \lit{dvitool} will draw a 1 pixel wide box around
the load image.  Each page has its own load image,
while there is only 1 global page image.  The box reveals exactly
which pixels are kept, or cached, for each page.}

\docstr{top-margin}
\type{\it dimension}
\defa{\tt 1in}
\desc{The height of the top margin.  See \em{left-margin}.}
\seea{{\it left-margin}, {\it show-load-image}}

\enddoc
\bye
