.\" @(#)psterm.1 9.2 88/01/19 Copyright 1987 Sun Micro
.\" @(#)$Header: psterm.1,v 2.3 88/10/04 05:59:48 gnu Release $
.TH PSTERM 1  "28 July 1988"
.SH NAME
psterm \(em NeWS terminal emulator
.SH SYNOPSIS
.B psterm
[
options
]
[
command
]
.IX psterm#(1) "" "\fLpsterm\fP(1) \(em NeWS terminal emulator"
.SH DESCRIPTION
.I psterm
is a
.IR termcap -based
terminal emulator program for NeWS.  When invoked,  it reads the
.I /etc/termcap
entry for the terminal named
.I psterm
or the termcap named by the
.B -t
option, and arranges to emulate the behavior of that
terminal.  It forks an instance of
.I command
(or, by default,  the program specified by the
.B SHELL
environment variable, or
.I csh 
if this is undefined),
routing keyboard input to the program and displaying its output.
.LP
It responds to (most of) the particular escape sequences that
.I termcap
defines for that terminal.
.SH OPTIONS
.TP
.B \-bg
causes
.I psterm
to place itself in the background by
disassociating itself from the parent process and the controlling terminal.
If
.I psterm
is invoked with
.IR rsh (1),
this option will cause the
rsh command to complete immediately, rather than hang around until
.I psterm
exits.
This is the default if
.I psterm
is invoked with
.I stdin
not connected to a
.I tty.
.TP
.B \-C
route
.I /dev/console
messages to this window, if supported by the operating system.
.TP
.B \-co "\fIcolumns\fP
specifies the width of the window in characters.
.TP
.B \-F font
overrides the default terminal font.
.TP
.B \-f
Ignored.  For compatibility with older versions.
.TP
.B \-fg
forces 
.I psterm
not to fork, thus leaving you in the forground.
.TP
.B \-fl "\fIframe label\fP"
Use the specified string for the frame label.
.TP
.B \-fs fontsize
overrides the default terminal font point size.
.TP
.B \-ic
forces 
.I psterm
to come up iconic instead of as an open window.
.TP
.B \-il "\fIicon label\fP"
Use the specified string for the icon label.  The icon label normally defaults
to the name of the host on which
.I psterm
is running.
.TP
.B \-ixy x y
sets the initial icon location.
Similar to 
.B \-xy x y.
.TP
.B \-li "\fIlines\fP"
specifies the height of the window in characters.
.TP
.B \-ls
causes
.I psterm
to invoke the shell as a login shell.  In addition, any
specified
.I command
will be passed to the shell with a
.B \-c
option,
rather than being invoked directly, so that the shell can establish any
environment variables that may be needed by the command.  Further, if
.I psterm
is invoked via
.IR rsh (1),
the host at the other end of the
.I rsh
socket will be used as the server, unless a NEWSSERVER
environment variable is present.
.TP
.B \-pm
specifies that a 
.I psterm
should enable 
.IR "page mode" .
When page mode is enabled and a command produces
more lines of output that can fit on the screen at once,
.I psterm
will stop scrolling, hide the cursor, and wait until the
user types a character before resuming output.  
When 
.I psterm
is blocked with a screenfull of data,
typing a carriage return or space will cause
scrolling to proceed by one line or one screenful, respectively; any other
character will cause the next screenfull
to appear and be passed through as normal
input.  
This mode can also be enabled or disabled interactively, using the
.I "Page Mode"
menu item.
.TP
.B \-r
forces 
.I psterm
to reload the 
.I psterm.rc
file and the
.I .pstermrc
file.
Normally, 
.I psterm
checks and if the dictionary
.B PSTermDict
exists in 
.B systemdict,
it does not bother reloading the
.I PostScript
files.
.TP
.B \-sl savelines
specify the length of the scroll region.
Defaults to 0, which turns scrollbars off.
.TP
.B \-t term
specify a particular terminal type to override the
.B TERM
environment variable.
Some types work well, others do not.
The terminal type ``psterm'' was designed specifically for use with
.I psterm,
and works quite well.
.TP
.B \-ui userinit
.I psterm
will execute 
.I userinit
as a
.I PostScript
function before creating the terminal window.
This allows the overriding of terminal characteristics on an
individual window basis.
The only function currently defined for this purpose is
.I \-ui StretchOpen
which requests a sizing box on window creation instead of a fixed size window.
See the example
.I \.pstermrc
file for more code that can be called from here.
.TP
.B \-w
wait around after the
.I command
terminates.
.TP
.B \-xy "\fIx y\fP"
specifies the location of the lower left hand corner of the
window (in screen pixel coordinates).

.SH "SELECTION"
.LP
Clicking the left mouse button over a character selects that character.
Dragging the mouse extends the selection.
Clicking or dragging beyond the end of the line
selects the newline at the end of that line.
Clicking the middle mouse button over a character
when a selection does not exist in that window
selects that character.
Clicking the middle mouse button over a character
when a selection does exist in that window
extends or shrinks the selection to that character.
Dragging the mouse still extends the selection.
.LP
Clicking and dragging with a shift key down selects a
.I rectangle
of text, padded with spaces if necessary.
.LP
The Copy key (L6) copies the 
selection to the
.IR shelf .
The Paste key (L8) copies the contents of the
.I shelf
to the
.I "insertion point".
.LP
Copy and Paste of selections
works across separate invocations of
.I psterm.
They do not work between
.I psterm
and SunView.
However, a mechanism does exist for transferring a SunView
selection to the \*(Sd shelf, and vice versa. See the description
of 
.I Selection Transfer
in 
.IR news_server (1).
.SH "MENU ITEMS"
.I psterm
creates a client menu with entries to
.I stuff
the current selection to the insertion point,
get at the normal
.I frame
menu, and get at a
.I config
menu for changing some parameters of a running 
.I psterm.
Under the
.I config
menu, are other sub-menus changing various parameters.
.LP
Config... Lines x Cols...  This menu sets the terminal size to the
indicated number of lines and columns.  By default, this will change
the window size to fit.
.LP
Config... Points...  This menu sets the font point size.  By default,
this will change the window size to fit.
.LP
Config... Fonts...  This menu sets the terminal font to one of the
standard fixed width fonts.  This is likely to change the size of the
characters, and behaves as thought the font size had been changed.
Note that /Screen font (the default) only scales to a few
predetermined sizes.  Selecting a new point size is likely to have no
effect until a fully scalable font is selected.  Several other fonts
exibit this behavior.  See More Fonts!... below.
.LP
Config... More Fonts!...  This menu lists all fonts known to the
system at the time the psterm was started.  Note that some of these
are likely to be silly.  The width of the letter ``m'' in the font is
used to determine the spacing between characters.  Some fonts have no
``m'' character.  See Config... Toggles... Var Width Fonts below.
.LP
Config... Resizing stuff...  This menu is strange.  Under it are three
pairs of toggles.  These toggles control the behavior of psterm when
one of three parameters is changed.  Basically, there are three
parameters used to determine the way the terminal is displayed, and
they are all interdependant.  The three parameters are Font Size,
Lines/Cols, and Window Size.  Fixing values for any two of these
determines the third value.  When you change one of these parameters,
psterm consults this menu to determine which of the other two
parameters should stay the same, and which should change.  The
parameter with the ``*'' next to it will be the one which changes.
Select the menu entry for the unstarred parameter to cause it to
become the new starred parameter.  Remember that you choose among
three independant pairs of values.  Now, go play.
.LP
Config... Save Lines...  This menu selects the number of lines saved.
If you select a value other than zero, a scrollbar will appear
allowing you to scroll through the saved region.  Selecting zero will
remove the scrollbar.  Saving a large number of lines takes a lot of
memory, and possibly several seconds to set up.
.LP
Config... Toggles...  This menu controls the on/off state of several
items.  Select the item to toggle it.  If there is an ``*'' next to an
item, it is on now, and selecting it will turn it off.  The first item
is Page Mode.  See the -pm option above.  The second item is Auto
Margins.  The initial state of this item is determined from the
termcap entry for the terminal being emulated.  If Auto Margins is on,
when the terminal's cursor is in the rightmost column and another
character needs to be displayed, a newline will automatically be
inserted.  If Auto Margins is off, the cursor will ``stick'' to the
right of the window.  The third item is Var Width Fonts, and defaults
to on.  This item is only of importance if the current font is not a
fixed width font.  Basically, if it is off, all fonts are forced to be
fixed width.  With Var Width Fonts on, normal output will be more
readable under a variable width font, like /Times-Roman, but columns
of text will not line up properly, and cursor motion and selection of
text can produce wierd effects.  This should be fun to play with.
The fourth item is Fast Repaint, defaulting to on.  If you turn it off,
then every repaint will be seen, even if another is already in progress.
The fifth item is Scrolling Allowed, defaulting to on.  This is here
in case your server can repaint faster than it can do a copyarea.
On a Silicon Graphics, you might want to turn this off by default.
Just set DefaultUseCopyArea to false in your .pstermrc file.
.LP
Config... Set Labels...  This menu allows you to set the value of the
frame label, the icon label, or both.  Label values are set to the contents
of the current selection.  You can also set the frame label to a string
indicating what version of psterm you are running.
.SH FILES
.PD 0
.TP 1.5i
.I /etc/termcap
to find the terminal description.
.TP
.IB /usr/NeWS/lib/psterm.ps
containing most of the PostScript code.
.TP
.IB ~/.pstermrc
to customize the terminal on startup.
.PD
.SH "SEE ALSO"
.IR news_server (1)
.LP
.I "NeWS Manual"
.SH BUGS
.LP
A bug in liteUI causes keyboard events to be distributed to the wrong
place.
This may cause characters that you type to not go to the terminal that
your mouse pointer is inside of.  To redirect the keyboard properly,
move the mouse out of the window, and back in.
This is often necessary when initially starting
.I psterm.
.LP
Another obscure bug in liteUI can cause NeWS to think that your shift
key is permanently stuck down.  It is triggered by holding the shift
key down, and clicking on the mouse while dragging it across canvas
boundries as you might while making rectangular selections.
If this happens, you will have to exit NeWS to reset it.
As an emergency measure, it is suggested that you have an alias
in your .cshrc file to set the
.I lcase
tty parameter.
.LP
alias STTY stty lcase
.LP
will work for this.
.LP
Emulating some terminal types works better than others, largely because
there are incomplete
.I /etc/termcap
entries for them.
.LP
A large number of
.I termcap
fields have yet to be implemented.
.LP
.I "Page Mode"
gets easily confused.
.LP
See the BUGS and README files distributed with the source.