XTROFF(1) X Version 11(1 May 1988) XTROFF(1)
NAME
xtroff - Device Independent Troff Previewer for X Windows version 11.
SYNOPSIS
xtroff [ X Toolkit options ] [ -scrollbars ] [ -full ] [ -F fontdirectory
] [ -debug options ] [ -trofftype type ] [ -command "Troff Command Pipe"
] [file]
DESCRIPTION
Xtroff reads (device independent) troff(L) output files and displays an
approximation of the typeset output in a window. (In this document,
wherever we refer to troff, we mean ditroff, not the Sun supplied troff
which drives a CAT typesetter directly. Ditroff is part of the
Documenter's WorkBench, and is also supplied with the Research Editions
of Unix - v8, etc) Using the mouse the user can pan each page image
within the window, and move to other pages, look at different files and
finally send the file to lpr(1) for typesetting.
The program can be used in three different ways. Perhaps the most
efficient way to use this program is to execute xtroff in the command
mode. In the command mode, the -command option is used to specify a
troff command string that includes all the processing steps (eqn, tbl,
pic, ideal, troff) that are needed to transform a user's document into
troff output. Then whenever a change is made in the document a
"rerasterize" command can be used to rerun the command string and show
the new document on the screen. The "rerasterize" command is an option
available on a menu that pops up when the right mouse button is pressed
or by pressing the 'r' key.
Alternatively, the output from troff can be saved in a file and used as
input to this program by omitting the -command option and specifying a
file argument. In this case, each time the document changes it is up to
the user to rerun the troff pipe to regenerate the file. The user must
then indicate to xtroff that the file has changed. This can be easily
done using the "rerasterize" command.
A third possibility is to treat xtroff as a filter and feed the output of
the troff command string to it. It will read from the standard input if
neither a -command option nor a file argument is specified.
Fonts used by xtroff are rough approximations to those that will be
printed in the final typesetter output. The best fonts available are the
X Windows fonts provided with the MIT distribution courtesy Adobe,
Bitstream and DEC. These fonts approximate the fonts in a PostScript
printer very well indeed.
COMMANDS
Xtroff can be controlled using a combination of mouse, menu and typed
commands. Within the main text window when the middle button of the mouse
is pressed the cursor is changed into the shape of a hand that grabs the
text. As the mouse is moved around inside the window the displayed text
(and the hand) move accordingly. When the right button is pressed a menu
10/89 Page 1
XTROFF(1) X Version 11(1 May 1988) XTROFF(1)
pops up that contains options for moving to different pages, print parts
of the document, and rerasterizing the input.
OPTIONS
-full Display full page on screen.
-nopixmap
Write directly to the X window instead of to a backing pixmap.
This makes scrolling slower, but uses less X server memory, making
it possible to run xtroff on X terminals with very little memory.
-scrollbars
Disable scrollbar display.
-F fontdir
Specify an alternate font directory where ditroff font description
files are stored. This directory is usually /usr/lib/font. (This
default is set when xtroff is compiled)
-trofftype type
Specifies type as one of ditroff, berkeley or groff to tell the
xtroff parser which of these troff variants is driving it. (Only
the first character of the type is looked at). In particular, note
that groff produces output incompatible with ditroff. (See
groffout(5))
-debug options
options is a string that indicates the modules to produce debugging
trace for. This option produces a lot of output and is only of
interest to people maintaining, debugging or enhancing xtroff. a
turns on all debugging, c turns on per-character debugging, d
traces some drawing operations, f traces font operations, m is for
miscellaneous tracing (input file name, etc), s traces the seek
pointers for troff pages, t traces the typesetter loading and w
traces some window and toolkit operations. For example, -debug sf
will trace the seek operations on the input and buffer files and
all font loading operations. When debugging is on, fatal errors in
xtroff call abort() instead of exit(1) so they result in a core
dump.
ACTIONS
There are a number of actions defined in the main window. They can be
invoked in a number of ways, using different bindings. (keys, or mouse
buttons, or a combination of both). Most actions can also be invoked from
the menu that pops up when the right mouse button is pressed in the main
window.
Move Around within Page
Use the middle mouse button. When it is first pressed a
hand will appear on the page and effectively grab the
text. As the mouse (and hand) move the page will move
within the frame.
Page 2 10/89
XTROFF(1) X Version 11(1 May 1988) XTROFF(1)
Another way to do this is to use the scrollbars on the
right and bottom of the page.
Advance by a viewing section
A viewing section is the part of the page that can be
displayed on the screen. Advancing to the next section
will move the page so that the next section of the page is
visible, or advance to the next page if at the end of a
page. This command is bound by default to the SPACE bar,
the mouse left button, and the cursor-down arrow key.
Previous Section
This is the opposite of the previous command. It backs up
to the previous section of the page, or to the previous
page. It is bound to the cursor-up arrow key, and to the
shifted left mouse button.
Next Page This rasterizes and displays the next page in the
document. A clock cursor is displayed while the
rasterizing is done, which can take a few moments. This is
bound to the cursor-right arrow, the 'n', and 'f' keys,
and RETURN and LINEFEED.
Previous Page This rasterizes and displays the previous page in the
document. A clock cursor is displayed while the
rasterizing is done, which can take a few moments. This is
bound to the cursor-left arrow, the 'p', and 'b' keys, and
DELETE and BACKSPACE.
Go To Another Page
This goes to a specific page number. Type the desired
page number to the main xtroff window followed by the 'g'
key. If you make a mistake in the page number, just hit
ESC and type it again. This is not available on the menu.
Search for a Pattern
To find a pattern in the output enter the desired search
pattern in the input window at the bottom when prompted.
Note, the only valid characters in a search pattern are
printable ascii characters and the space character.
Forward and backward searches are performed using the
appropriate button in the menu. A search ignores the
current page and will find the next page that contains the
desired words.
Print Part of Document
Either a single page ('P' key - shifted 'p') or the entire
document can be printed using entries in the right mouse
button's pop-up menu. The printer name is "PostScript",
or from the PRINTER variable in the environment. The
command used for printing can be changed using the "Set
Printer" item on the menu.
10/89 Page 3
XTROFF(1) X Version 11(1 May 1988) XTROFF(1)
Set Printer This reads the command to be used to print pages or the
document from the input window at the bottom. It leaves
the current default value in the input window for editing.
Change Command This changes xtroff to command mode, and requests the
command to use to generate ditroff output to preview. The
current command, if any, is displayed in the input window
for editing. This may be used even if xtroff was started
in file mode.
Change File This changes xtroff to file mode, and requests the name of
a file containing ditroff output from the input window.
The current file, if any, is displayed there for editing.
Filename completion is enabled. This may be used even if
xtroff was originally started in command mode. Note
however that there is no way to get xtroff to read from
the standard input.
Rerasterize After changes are made to a document it is necessary to
tell xtroff to rerasterize the file. This can be done by
hitting the 'R' key, or selecting from the menu. Note
that this is only really useful if you run xtroff using
the -command option. If used with a file, it can still be
used, provided the command to create the troff file is run
again. If neither the file nor the command is used, and
xtroff is reading from standard input, then rerasterize
will not work, and the whole command must be run again.
Quit This exits the program. It is bound to the 'q' key.
EXAMPLES
To preview a file that has already been processed by troff
xtroff file-containing-troff-output
When the "rerasterize" command is issued then the indicated file will be
reopened and its new contents displayed.
To typeset and preview a document use the following command
xtroff -command "eqn troff-input-file | troff -ms"
The "rerasterize" command will close any open files (or pipes) and open a
new pipe. The indicated command will be run on the input side of the
pipe to provide xtroff with its input. The command providing input to
xtroff can contain any combination of programs as long as the final
output is troff output. If it contains pipes '|', or shell
metacharacters, remember to enclose it within quotes.
The latter is the most common usage of xtroff. Typically, the user would
start xtroff on a document, preview it, iconfiy xtroff, or put it under
the other windows, and edit the document, fixing and adjusting things,
and then deiconify or raise xtroff, and rerasterize to see the effect of
the changes.
Page 4 10/89
XTROFF(1) X Version 11(1 May 1988) XTROFF(1)
RESOURCES
Xtroff supports the general X Toolkit resource specifications. Here are
the names and classes of the widgets used in xtroff.
Name,Class
Comment
xtroff,XTroff
The toplevel shell that encloses the application.
form,Form The frame that manages the geometry of the widgets.
canvas,Window
The main xtroff window name if -full is NOT specified.
full,Window
The main xtroff window name if -full is specified.
popupShell,Shell
The shell that encloses the pop-up menu.
vscroll,Scrollbar
The vertical scrollbar
hscroll,Scrollbar
The horizontal scrollbar
In addition to the widgets' resources, xtroff also gets the following
resources for the main program:
Name,Class
Comment
scrollbars,ScrollBars
scrollbar,ScrollBar
to determine whether the user wants the scrollbars or not. This
is of the form xtroff.scrollbar:on or off. It corresponds to
the command line argument -scrollbar.
full,Full to determine whether the user wants a full screen display of
not. This is of the form xtroff.full:on or off. It corresponds
to the command line argument -full.
backingPixmap,BackingPixmap
to determine whether the user wants characters displayed
immediatly. This is of the form xtroff.image:on or off. It
corresponds to the command line argument -noimage.
10/89 Page 5
XTROFF(1) X Version 11(1 May 1988) XTROFF(1)
fontMap,FontMap
describes the font mapping from ditroff name to X font names.
The X font names should be patterns of the same type as
accepted by xlsfonts(1). The default mapping is:
XTroff.fontMap: \
R -*-times-medium-r-normal--*-*-75-75-*-*-iso8859-1\n\
I -*-times-medium-i-normal--*-*-75-75-*-*-iso8859-1\n\
B -*-times-bold-r-normal--*-*-75-75-*-*-iso8859-1\n\
BI -*-times-bold-i-normal--*-*-75-75-*-*-iso8859-1\n\
TR -*-times-medium-r-normal--*-*-75-75-*-*-iso8859-1\n\
TI -*-times-medium-i-normal--*-*-75-75-*-*-iso8859-1\n\
TB -*-times-bold-r-normal--*-*-75-75-*-*-iso8859-1\n\
TD -*-times-bold-i-normal--*-*-75-75-*-*-iso8859-1\n\
C -*-courier-medium-r-normal--*-*-75-75-*-*-iso8859-1\n\
CO -*-courier-medium-o-normal--*-*-75-75-*-*-iso8859-1\n\
CB -*-courier-bold-r-normal--*-*-75-75-*-*-iso8859-1\n\
CD -*-courier-bold-o-normal--*-*-75-75-*-*-iso8859-1\n\
H -*-helvetica-medium-r-normal--*-*-75-75-*-*-iso8859-1\n\
HO -*-helvetica-medium-o-normal--*-*-75-75-*-*-iso8859-1\n\
HB -*-helvetica-bold-r-normal--*-*-75-75-*-*-iso8859-1\n\
HD -*-helvetica-bold-o-normal--*-*-75-75-*-*-iso8859-1\n\
nc -*-newcenturyschoolbook-medium-r-normal--*-*-
75-75-*-*-iso8859-1\n\
nC -*-newcenturyschoolbook-medium-i-normal--*-*-
75-75-*-*-iso8859-1\n\
Nc -*-newcenturyschoolbook-bold-r-normal--*-*-
75-75-*-*-iso8859-1\n\
NC -*-newcenturyschoolbook-bold-i-normal--*-*-
75-75-*-*-iso8859-1\n\
A -*-charter-medium-r-normal--*-*-75-75-*-*-iso8859-1\n\
AI -*-charter-medium-i-normal--*-*-75-75-*-*-iso8859-1\n\
AB -*-charter-bold-r-normal--*-*-75-75-*-*-iso8859-1\n\
AD -*-charter-bold-i-normal--*-*-75-75-*-*-iso8859-1\n\
S -*-symbol-medium-r-normal--*-*-
75-75-*-*-adobe-fontspecific\n\
SS -*-symbol-medium-r-normal--*-*-
75-75-*-*-adobe-fontspecific
printer,Printer
sets the name of the printer to be used when printing parts of
the document within xtroff. The default is PostScript.
lprcommand,LprCommand
sets the command to be used to print parts of the document
within xtroff. The default is lpr -n -P%s. The command may
contain a %s which will be substituted by the printer name.
debug,Debug
It corresponds to the -debug command-line option.
Page 6 10/89
XTROFF(1) X Version 11(1 May 1988) XTROFF(1)
troffType,TroffType
Corresponds to the -trofftype command-line option.
TOOLKIT OPTIONS
xtroff also accepts the standard Toolkit command options viz. "+rv",
"-background", "-bd", "-bg", "-borderwidth", "-bordercolor", "-bw",
"-display", "-fg", "-fn", "-font", "-foreground", "-geometry", "-iconic",
"-name", "-reverse", "-rv", "-synchronous", "-title", "-xrm". Some of
the options are meaningless for xtroff.
FILES
WIDTHDIR/* - troff width tables
FONTDIR/* - bitmap fonts for xtroff
XAPPLOADDIR/XTroff - default resources
SEE ALSO
Using and Specifying X Resources
X(x),x11(x),troff(L)
A Typesetter-independent TROFF by Brian W. Kernighan, Bell Labs Computing
Science Technical Report No. 97.
BUGS
Ligatures look a little displaced.
AUTHOR
Credit for this program goes to a number of people including
Brian Kernighan (Bell Labs) for first developing Device Independent
Troff,
Bill Reeves at the University of Toronto for developing the original vcat
program.
Richard L. Hyde, Purdue University, and David Slattengren, U.C. Berkeley,
wrote the original version of this program to rasterize troff output for
the Suns.
Malcolm Slaney, Schlumberger Palo Alto Research, rewrote most of the code
to make it run under Sun-3 Unix and to extend the user interface.
Support for X11 was added by Mark Moraes, University of Toronto,
(moraes@cs.toronto.edu).
Dave Cahlander (dac@cray.com) reworked the X11 drawing functions to draw
words, use the X11R3 fonts and draw special characters.
SUPPORT
This command was developed as an independent project to satisfy a need of
the author. This program may contain bugs and the user is cautioned to
independently verify that the program is suitable for the user's intended
purpose. The program is made available on an ``as is'' basis with all
faults and without any implied or expressed warranties or support from
any of the authors or organizations listed above in the AUTHOR section.
10/89 Page 7