mg@CAD.USNA.MIL (Mike Gigante, RMIT/Australia GUEST) (08/05/90)
A new version of the TeX previewer for the Iris will be put on the info-iris
archive. (host brl.mil, directory ~ftp/pub/info-iris) It wont be until
the keepers of the archive return from SIGGRAPH so expect some confirmation
after the 12th August.
Texsgi Version 1.1 has most of the bugs fixed and some new functionality:
1) a startup file .texsgirc (home directory, then local directory)
2) *MUCH* faster to display documents that have many fonts
3) faster startup
4) correct font selection
4) resizable window (with customizable defaults in .texsgirc)
5) many more fonts and font magnifications have been included
6) reversed keybindings (now ^P and u move the point up the page
instead of moving the page up) -- by popular demand
There are still some things that need to be fixed soon, but this release
is a major improvement over the currently available version.
Specifically, the previewer still uses GF fonts. This is my top priority
to fix, hopefully I'll get time to do it by the end of September after
Ausgraph is over.
Further planned improvements include pica rules, 2up mode, faster display
etc etc. Stay tuned... If you plan to work on the sources, *please* contact
me first so that we don't duplicate effort. Also I'd appreciate any fixes,
improvements etc!!
Also on popular demand, the distribution has been split out --
texsgi no longer is bundled with a complete TeX distribution.
I recommend that you obtain the University of Toronto TeX distribution --
it is well setup, contains many useful ancillary programs and compiles
seamlessly on Irises and other platforms. It is also extremely simple
to install. Particularly nice is the genfonts utility.
The distribution contains:
/usr/local/src/texsgi - the sources to the previewer
/usr/local/bin/texsgi - a compiled binary for you convenience
/usr/local/share/fonts/gf/gf300/*gf - a set of 118dpi and 300dpi
GF fonts used by the previewer.
The font locations are an oddity, sorry about that - but as this distribution
is the last one that supports GF fonts, we left it partly compatible with
the old structure. With the next release, the entire set of GF fonts can be
deleted.
Those that have been using the old texsgi will notice the much wider range of
fonts and magnifications.
Thanks to Dave Rogers who provided the resources for me to work on texsgi this
trip and also for being the guinea pig for this version while he was trying to
meet publication deadlines. Thanks also go to Dave Rogers for his comments
on the program from a serious user's perspective.
Non-internet sites can contact either mg@godzilla.cgl.rmit.oz.au or
in the US, contact dfr@cad.usna.navy.mil for details on how to get the
distribution
finally, here is a man page...
\" NB: make sure tabs in two tables below have not be turned into blanks
\" Look for the lines beginning ".ta 1.2in"
.TH TeXsgi 1L "June 1989"
.SH NAME
TeXsgi \- TeX DVI previewer for the Silicon Graphics Iris
.SH SYNOPSIS
.na
\fBtexsgi\fP
[\fB\-d#\fP]
[\fB\-f\fP\fIfontsubfile\fP]
[\fB\-l\fP]
[\fB\-m#\fP]
[\fB\-q\fP]
[\fB\-x#\fP\fIunits\fP]
[\fB\-y#\fP\fIunits\fP]
\fBdvifile1\fP
.ad
.SH DESCRIPTION
TeXsgi only runs on the workstation console and only on the 4D series.
It expects the name of the DVI file on the command line, and the
extension \fI.dvi\fP can always be omitted.
As the \fI.dvi\fP file is processed, a list of errors is printed on
the standard error unit, \fIstderr\fP; this list is also saved in a
file with suffix \fI.dvi-err\fP This file is not created if there are
no errors. The \fB\-q\fP (quiet) option can be given to suppress error
messages, as can the \fBQ\fP runtime command. As each page is
displayed, the physical page number and the TeX page number(s) are
printed on a status line at the bottom of the screen.
TeXsgi uses the 118 dpi and 300 dpi \fBgf\fP fonts.
.SH OPTIONS
The order of command options and DVI file name is \fInot\fP significant.
Letter case is \fIignored\fP in option switches
.TP
.B \-d#
Produce debugging output on \fIstderr\fP if a non-zero value is given.
Multiple \fB\-d\fP switches may be specified, and one may also add
values of the following possible options to obtain the switch value:
.RS
.TP
.I 2
display page coordinates and metrics of
each output character, and print each
character bitmap in hexadecimal;
.TP
.I 8
print filename and open mode of
each
\fIsuccessful\fP
file opening;
.TP
.I 16
print filename and open mode of
each
\fIunsuccessful\fP
file opening;
.TP
.I 32
show discarded off-page text;
.TP
.I 128
trace character setting (\fIlots\fP of output).
.RE
.PP
.RS
For example, either \fB\-d8 \-d16\fP or
\fB\-d24\fP will trace all attempted file openings.
.RE
.TP
.B \-f\fIfontsubfile\fP
Define an alternate font substitution file which
is to be used instead of the default ones (see below).
.TP
.B \-l
Inhibit logging.
.TP
.B \-m#
Reset magnification to #. The default is \fB\-m603\fP.
.TP
.B \-q
Quiet mode. Status displays to \fIstderr\fP are suppressed, unless
warning or error messages are issued. A most useful option for
the current version of the previewer.
.TP
.B \-x#\fIunits\fP
The \fB\-x\fP options specify the left margin of the TeX page on the
output page in any of the indicated units. Letter case is not
significant in the units field, which must \fInot\fP be separated from
the number by any space. \fI#\fP may be fractional. For example,
\fB\-x1.0in\fP, \fB\-x2.54cm\fP, \fB\-x72.27pt\fP, and \fB\-x6.0225pc\fP
all specify a one-inch left margin. Negative values are permissible, and
may be used to shift the output page left (possibly truncating it on the
left) in order to display a wide TeX page.
The \fIunits\fP field is mandatory, and may be one of
.RS
.TP
.B bp
big point (1in = 72bp)
.TP
.B cc
cicero (1cc = 12dd)
.TP
.B cm
centimeter (1in = 2.54cm)
.TP
.B dd
didot point (1157dd = 1238pt)
.TP
.B in
inch
.TP
.B mm
millimeter (10mm = 1cm)
.TP
.B pc
pica (1pc = 12pt)
.TP
.B pt
point (72.27pt = 1in)
.TP
.B sp
scaled point (65536sp = 1pt)
.RE
.TP
.B \-y#\fIunits\fP
The \fB\-y\fP options specify the top margin of the TeX page on the
output page. Letter case is not significant in the units field, which
must \fInot\fP be separated from the number by any space. # may be
fractional. For example, \fB\-y1.0in\fP, \fB\-y2.54cm\fP,
\fB\-y72.27pt\fP, and \fB\-y6.0225pc\fP all specify a one-inch top
margin. Negative values are permissible, and may be used to shift the
output page up (possibly truncating it on the top) in order to display a
long TeX page.
By decree of the Stanford TeX Project, the default TeX page origin
is always 1 inch over and down from the top-left page corner, even
when non-American paper sizes are used. This corresponds to the switch
settings \fB\-x1in \-y1in\fP; these values are assumed unless
overridden.
.SH FONT SUBSTITUTION
If no \fB\-f\fP\fIfontsubfile\fP option is given, and font substitution
is required, if the current DVI file is \fIfoo.dvi\fP, then the
files \fIfoo.sub\fP, \fItexfonts.sub\fP, and
\fItexinputs/texfonts.sub\fP will be tried in order. The first two
will be found on the current directory, and the last is the
system default. This gives the option of document-specific,
user-specific, and system-specific substitutions, and the
\fB\-f\fP option allows all of these to be overridden.
Font substitution lines have the form:
.nf
.ta (\w'oldname.oldmag'u+2n) +(\w'->'u+2n) +(\w'subname.submag'u+2n)
% comment
oldname.oldmag -> subname.submag % comment
oldname oldmag -> subname submag % comment
oldname -> subname % comment
.fi
The first two forms request substitution of a particular font and
magnification. The third form substitutes an entire font family; the
closest available magnification to the required one will be used. Any
dots in the non-comment portion will be converted to spaces, and
therefore, cannot be part of a name field.
The first matching substitution will be selected, so
magnification-specific substitutions should be given first,
before family substitutions.
Comments are introduced by percent and continue to end-of-line,
just as for TeX. One whitespace character is equivalent to
any amount of whitespace. Whitespace and comments are optional.
.SH SCREEN CONTROL
All switches, including the page selection (\fB\-o\fP) and page
origin (\fB\-x\fP and \fB\-y\fP) switches, work normally. In order
to avoid unnecessary waste of screen space, you probably will
want to specify \fB\-x0in\fP and \fB\-y0in\fP to remove the default
one-inch left and top margins. The \fB\-q\fP option is probably also
advisable to avoid warning messages, such as from font substitutions.
At the beginning of a page, a status line is displayed at
the bottom of the screen. When the end-of-page command is reached
in the DVI file, or as soon as keyboard input is available, the
driver will enter the end-of-page routine. Any keyboard input
command is then read and acted upon; unrecognized input is
discarded with a warning beep. The advantage of checking for
keyboard input during the main DVI reading loop is that unwanted
display can be avoided. This is valuable if you are
repositioning the page, or skimming a document.
The input can select
.RS
.TP \w'\(bu'u+2n
\(bu
redisplay of the current page, possibly shifting it up,
down, left, or right, or to see more of it.
.TP
\(bu
continuation to the next page;
.TP
\(bu
backing up to the previous page (useful if you overshoot);
.TP
\(bu
display of an arbitrary page by typing its sequence number;
.TP
\(bu
termination of execution.
.RE
Here is the current command list. Input is immediate; no
terminating carriage return is necessary. Consequently, typing
error correction is supported only for the digit string command;
ending with the letter \fBg\fP (goto).
.RS
.TP
.B ^D
Move the display down by 1/32 of screen size.
.TP
.B "d \fRor\fP Ctl-N"
Move the display down by 1/16 of screen size.
.TP
.B D
Move the display down by 1/8 of screen size.
.TP
.B ^U
Move the display up by 1/32 of screen size.
.TP
.B "u \fRor\fP Ctl-P"
Move the display up by 1/16 of screen size.
.TP
.B U
Move the display up by 1/8 of screen size.
.TP
.B ^L
Move the display left by 1/32 of screen size.
.TP
.B "l \fRor\fP Ctl-B"
Move the display left by 1/16 of screen size.
.TP
.B L
Move the display left by 1/8 of screen size.
.TP
.B ^R
Move the display right by 1/32 of screen size.
.TP
.B "r \fRor\fP Ctl-F"
Move the display right by 1/16 of screen size.
.TP
.B R
Move the display right by 1/8 of screen size.
.TP
.B "SPACE \fRor\fP + \fRor\fP Ctl-V"
Display next page.
.TP
.B "- \fRor\fP b \fRor\fP Alt-V"
Redisplay previous page.
.TP
.B nnn g
nnn is a digit string; DELETE/RUBOUT and BACKSPACE keys correct
typing errors in it. Goto to \fBnnn\fP-th page, where document
pages are numbered 1, 2, .\|.\|.. The TeX page numbers are
displayed in the status window. This is a recursive display; if
you respond at end-of-page with a \fInext-page\fP command,
display will revert to the page sequence you were viewing when
you first issued the \fBnnn\fP command.
.TP
.B i
inverse \- swap foreground/background colors.
.TP
.B Q
quiet \- toggle the suppression of warnings and error messages. Especially useful to
supress the font substitution messages.
.TP
.B h/H
home \- return to home position (top left corner)
.TP
.B ?
help \- print a short command summary.
.TP
.B m
magnify \- Zoom up one magstep (1.2 times larger) from current size.
.TP
.B s
shrink \- Zoom down one magstep (1.2 times smaller) from current size.
.TP
.B M
magnify \- Zoom up five magsteps from current size.
.TP
.B S
shrink \- Zoom down five magsteps from current size.
.TP
.B "ESC \fRor\fP q \fRor\fP x"
Quit or exit.
The \fBM\fP and \fBS\fP commands can be used quite effectively as
a pair. From the default magnification (590), \fBM\fP will cause
the 300dpi fonts to be used exactly and the \fBS\fP command will return
to exactly 118dpi fonts.
It is likely that some font magnifications will be unavailable
for zooming, so do not be alarmed if some characters are
displayed as blanks when you do this. You can use the font
substitution mechanism (\fB\-f\fP option above) to work around
this, or you can ask your font administrator to generate the
required magnifications. When font substitution happens because
of an unavailable magnification, characters of an incorrect size
are used with the spacing required for the font which TeX used,
so output is likely to look peculiar.
.RE
.SH SPECIALS
The TeX \fB\\special{}\fP command is intended to allow the
specification in a \fI.tex\fP file of a request to the DVI
driver, usually for the insertion of graphical material at that
point in the document. It is currently not implemented
and will simply issue a warning message.
.SH ENVIRONMENT VARIABLES
The behavior of the previewer can be influenced by
environment variables. Compiled-in
internal defaults will be provided for any of these which are not
defined. They \fImust\fP be entirely in upper-case, since that
is conventional on Unix systems. The names currently recognized
are as follows:
.TP \w'TEXINPUTS'u+2n
TEXFONTS
This defines the directory path for finding font files. Its value is
\fIprepended\fP to the name of a \TeX font to get a full file
specification. A typical value for \fITEXFONTS\fP would be
\fI/usr/local/lib/tex/fonts/gf/\fP.
.TP
TEXINPUTS
This defines the directory path for finding files which
are not in the current working directory.
It is \fIprepended\fP to file names. A typical value
would be \fI/usr/local/lib/tex/inputs/\fP.
.SH FILES
There is a startup file \fI.texsgirc\fP used to set defaults. The file, if it
exists, is read from the users home directory and then the current directory.
This allows a document specific override to the defaults.
The format of the file is simple, one command per line, arguments seperated by
spaces. Here is an example file:
.nf
prefposition 489 1279 0 1023
inverse
quiet
.fi
The allowable commands are:
.nf
prefposition <left> <right> <bottom> <top> % in screen coordinates
prefsize <horizontal> <vertical> % in pixels
keepaspect <y> <x> % y is to x in integers
quiet % supress messages
inverse % run white on black
magnification <mag>
.fi
By default, the user can sweep a window without constraints, any of
prefposition, prefsize, keepaspect will constrain the resultant window
by varying amounts.
The default runmag is 590, which correponds to 118dpi (118 * 5 = 590).
The most useful magnifications are those which are in the series
(590 645 710 845 1020 ... ) which corresponds to magsteps in the 118dpi
family. Note that the number of fonts that are available reduces as the
magstep increases (since we haven't generated all the fonts at the higher
magsteps). Probably more useful is the use of magstep 1500, this will force
the use of the 300dpi fonts that are also used for dvi2ps. This will
significantly magnify the size of the fonts; great for detail work.
The values of \fItexinputs\fP and \fItexfonts\fP below are
system-dependent. Typical values are
\fI/usr/local/tex/inputs/\fP and \fI/usr/local/tex/fonts/gf/\fP.
.TP \w'texinputs:texfonts.sub'u+2n
.I *.dvi
TeX DeVice Independent output file
.TP
.I *.dvi-err
TeXsgi error log
.TP
.I *.sub
DVI file-specific font substitution file
.SH "SEE ALSO"
dvitype(1),
latex(1),
tex(1),
tr2tex(1),
\fILocal LaTeX Guide\fP,
.SH BUGS
Bugs in either the software or its documentation
should be reported by electronic or postal mail to
.nf
Mike Gigante
Applied Computer Graphics Lab
Royal Melbourne Institute of Technology
124 Latrobe Street,
Melbourne, Australia 3001
+61 3 660 2935
Email: mg@cidam.oz.au
.fi
or to
.nf
Prof David F. Rogers
Aerospace Engineering Dept.
U.S. Naval Academy
Annapolis, MD 21402, USA
(301) 267 3283/4/5
Email: dfr@usna.navy.mil
who has offered to act as the US distribution point.
.fi
.SH AUTHORS
This previewer is derived from Nelson Beebe's dviXXX family (available
from science.utah.edu), with some ideas from Dick Grundwald's TeXsun.
Mike Gigante of RMIT ported the dvixxx family to the Iris and wrote all of the
Iris specific code.
Thanks go to Dave Rogers for being the guinea pig and for discussions about
where the design is heading.
.SH BUGS
Well, the biggest bug is that is isn't finished. The code is very naive,
re-reading the raster descriptions from the GF file for every character.
This will dissapear in the swap over to the PK fonts. Hopefully not too
far from now.
There is plenty of stuff in the pipeline for a better UI, including two-up
mode, pica rules, real-time panning etc. Now I just have to get time to
work on it...