UsingPSTerm

		A user guide for the new psterm program

				by Eric Messick

 @(#)$Header: /u/eric/client/psterm/RCS/UsingPSTerm,v 2.2 88/11/10 17:25:18 eric Update $

	Starting psterm.

If you're using psterm, chances are quite good that you are in NeWS.
This probably means that the directory /usr/NeWS/bin has found its way
into your $PATH.  If not, it's time it migrated in there, because
that's the directory where you'll find the psterm binary.  Just
starting psterm from the shell (your command interpreter) will get you
a reasonable set of default starting conditions.  With no command line
options, the following things will happen:

	psterm will look at various portions of your environment and
will question your tty driver and build up a picture of what your
current terminal type is and how big it is.

	psterm will then try to talk to your news_server.  Hopefully,
it will succeed.

	psterm next opens a window on your screen.  This window will
have its lower left corner in the lower left corner of your screen.
Text in the window will be presented in 12 point /Screen font by
default.  The window will be sized so that precisely the proper number
of rows and columns of text appear inside the window borders.

	A shell is then started, and the shell's prompt should appear
in the terminal window.

	Moving the NeWS cursor into the terminal window will allow you
to type to the shell.

	Typing the ``exit'' command into the window's shell will cause
the window to go away.


Now, let's take a look at the command line options that are available
to change the behavior of psterm.  If you enter an illegal option on
the command line, psterm will print a usage line that looks something
like this:

Usage: psterm [-bg] [-C] [-co columns] [-F font] [-f] [-fg] [-fl framelabel] \
        [-fs fontsize] [-ic] [-il iconlabel] [-ixy x y] [-li lines] \
        [-ls] [-pm] [-r] [-sl savelines] [-t termtype] [-ui userinit] [-w] \
        [-xy x y] [command]

As you can see, psterm has quite a few options.  Let's take a closer
look at them.

-bg	Forces psterm to fork, even when not connected to a tty.
		Normally, psterm will not bother to fork unless
		connected to a tty.

-C	Redirects the console output to the psterm window.  Note:
		this does not work under A/UX.

-co columns
	Overrides the termcap entry and tty driver for deciding how
		many columns the emulated terminal has.

-F font	Overrides the default terminal font.

-f	Ignored.  For compatability with older versions.

-fg	Forces psterm not to fork, thus leaving you in the forground.
		Normally, psterm will fork if its stdin is connected
		to a tty, and not bother otherwise.

-fl framelabel
	Sets the frame label.  Default is either the host name if -ls
		is specified, or a string indicating the terminal
		type.

-fs fontsize
	Overrides the default terminal font point size.

-ic	Forces psterm to come up iconic instead of as an open window.

-il iconlabel
	Sets the icon label.  Default is the host name.

-ixy x y
	Sets the position of the icon.  Similar to -xy x y.

-li lines
	Similar to -co.

-ls	Creates a login shell instead of a normal shell.  Sets a few
		environment variables and executes your .login file.

-pm	Turns on page mode.  Causes psterm to stop output when a full
		page has been displayed since the last input.  Space
		and return are munched when output is stopped and any
		character continues output.

-r	Forces psterm to reload the psterm.ps file and the .pstermrc
		file.  Normally, psterm checks and if the dictionary
		PSTermDict exists in systemdict, it does not bother
		reloading the PostScript files.  If you make a change
		in psterm.ps or your .pstermrc, you will probably have
		to use this option to get your changes to be loaded.

-sl savelines
	Specifies the number of lines to save in memory.  If this is
		non-zero, a scrollbar will appear, allowing you to
		scroll through the saved lines.

-t termtype
	Overrides the environment variable $TERM in specifying what
		kind of terminal psterm will emulate.  psterm looks in
		the file /etc/termcap to find a description of the
		terminal that it is trying to emulate, and does that
		the best that it can.  Some types work well, others do
		not.  The terminal type ``psterm'' was designed
		specifically for use with psterm, and works perfectly.

-ui userinit
	psterm will execute userinit as a 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 -ui StretchOpen which
		requests a sizing box on window creation instead of a
		fixed size window.  See the example .pstermrc file for
		more code that can be called from here.

-w	wait around after the shell exits before deleting the window.

-xy x y	Sets the lower left corner of the window position.


Following the other command line options, you can specify a command
and arguments to be executed in lieu of your shell.  Several commands
that are very useful are:

	psterm /bin/login -p username

which opens a psterm window and prompts for username's password.  The
-p tells login to pass the environment through, so your shell will
know what kind of terminal you're on.  If you leave off the username: 

	psterm /bin/login -p

it will prompt for it.  You can also connect to another host via tip:

	psterm tip hostname

and when you get out of tip, the window will go away.




	Starting psterm from a Menu

The default root menu has entries for starting a psterm.  These just
consist of a string of options on a command line that is sent to the
forkunix NeWS function.  NeWS forks a process to execute the psterm,
and redirects its stdin stdout and stderr, generally to /dev/null.
When psterm sees that it has been started this way, it doesn't bother
to fork itself (see -fg and -bg, above).  You can create your own menu
entries to do this in your user.ps file.  See the example files.



	Starting a psterm on a Remote Machine

Ok, let's get some terms streight.  You're sitting in front of a
screen connected to a computer.  That computer is your local system.
Programs run there are run locally.  Your computer is connected to a
network that has other machines hooked up to it.  You want to run a
psterm on one of those machines.  The other machine is the remote
machine, and the psterm running on the remote machine is the remote
psterm.  Your news_server is running on your local machine.  Ok?

If psterm is started on a remote system, it will do it's best to find
the news_server that it was started from and connect to it.  This
gives you a transparent way to access other machines.  There are a few
things that may confuse or thwart it in its efforts for you.  You
should be aware of these if you have a computer network.  First, you
need to know that under SysV the remote execution command is called
remsh, while under other systems it is called rsh.  Next, you should
be sure that you have your .rhosts file set up correctly so that you
can start remote programs on the remote machine in the first place.
Once your local system has connected to the remote system, it needs to
be able to get to the psterm program.  Does it exist on the remote
system?  Will the path set in your .cshrc file find the right binary?
Does the remote system use a different binary format than your local
one?  If so, you may need a way to change your $PATH in a way that
depends on which remote system you are starting the psterm on.  You
also need to make certain that the terminal type that you've asked for
exists in the remote machine's /etc/termcap file (setting your
$TERMCAP variable in your .cshrc file could take care of this also).
If your local machine is running multiple news_servers, a remote
psterm may have trouble determining which one you are on.  Currently,
it picks the first one.  Once it figures out which news_server it
wants to talk to, you need to make sure that the news_server is
willing to talk back.  You have to either get the remote host into the
list of hosts that your local server will talk to, or set
/NetSecurityWanted to false in your user.ps.  See the example
files.



	Getting Around in psterm

Ok, you've started your psterm.  Now what?  Well, you can type into
your shell, and get responses back out, but you knew that already.
Remember that the cursor has to be in the window that you are typing
into (unless you have set click to type).  But let's find out what
other nifty things you can do.

When using the mouse, what matters is where you click it.  Let's talk
about the different places that you can click on.

First, there's the ``frame''.  It's the border just outside of where
the window text actually goes.  It looks like the frame around a
picture.  The frame holds three things.  Most importantly, it holds
the terminal canvas, which is where the window text goes.  This area
is big and obvious -- right in the center, with a border line going
all the way around it.  Next, there's the close gadget.  It's in the
upper left hand corner of the frame, and it looks like two arrows
pointing at each other.  Finally, there's the stretch gadget.  It's in
the lower right hand corner of the frame.  If your frame borders are
very narrow, you may not be able to see the stretch gadget (it looks
like part of an arrow facing down and to the right), but it is still
there and you can still hit it with the mouse, although you will have
to be very accurate with your mouse placement.

Ok, so what happens when we click on these things?  Well, that depends
on what mouse button you use.  Unless you've changed them, the three
mouse buttons, called the PointButton, AdjustButton, and MenuButton,
will be set to the LeftMouseButton, MiddleMouseButton, and
RightMouseButton, respectively.  On the Mac, the LeftMouseButon means
that you have to hold down the ``option'' key when you press the mouse
button.  Likewise, the MiddleMouseButton on the Mac is generated by
holding down the ``point of interest'' key (it looks like a clover,
and is just to the right of the option key) when clicking on the
mouse.  So, on the Mac, PointButton means option, AdjustButton means
point of interest, and MenuButton means normal.  Got that?

The close gadget and stretch gadget have special behavior on the Mac.
You can use any of the mouse buttons on them to activate them.  On the
Sun, use the PointButton.  Clicking on the close gadget turns the
window into an icon.  The icon will be a tiny copy of the screen that
you're displaying on the full size window.  Each character in the icon
will be represented by a single pixel (actually, a 1pt by 1pt square).
You can still type into the window (if the cursor is inside the icon),
and you will be able to see the response (although reading it is
likely to be difficult).  The MenuButton will bring up the icon's
menu, which is standard.  The AdjustButton will drag the icon around
the screen, also standard. Finally, the PointButton turns the icon
back into a window, also standard.

Now that you're back with a window again, what does the stretch gadget
do?  Clicking down on the stretch gadget allows you to ``pick up'' the
lower right hand corner of the window and stretch it around.  When
you're done playing, and release the mouse button, the window will
resize itself to fit inside of the rectangle you specified.
Generally, this will mean changing the number of rows and columns in
the window.  Whenever this happens, psterm makes sure that your tty
driver finds out about this, so that smart programs can repaint
themselves to the new size.  Note that many programs won't be able to
deal with this very well.  That's about it for the gadgets.

Let's turn to the frame itself next.  The PointButton clicked in the
frame will bring the window to the front of the screen.  Handy.  The
AdjustButton lets you drag the window around.  The MenuButton brings
up the standard frame menu.  There.  That wasn't so hard.

Now for the terminal canvas itself.  The PointButton and the
AdjustButton work together here to allow you to select pieces of text
that appear on the window.  The PointButton always starts a new
selection, while the AdjustButton extends the current selection, or
starts a new one if there isn't a selection going on right now.
That's the only difference between them.  Now, how do they work?  More
clicking and dragging here, folks.  Push and hold the PointButton and
a new selection is started.  What you have selected so far will have a
line drawn around it.  Dragging the mouse around changes the size of
the text selected.  When you release the mouse, the selection area
stops changing in response to your mouse movements.  After the
selection has been reported to the server, its hilighting is changed
to reverse video.  If one of the ends of your selection is not quite
what you want, use the AdjustButton to adjust it.  Just click down and
drag the mouse to the spot you want.  It's quite easy when you get
used to it.

So, what do you use the selected text for?  Here we come to using the
MenuButton in the terminal canvas.  It brings up the terminal menu.
There are three entries in the terminal menu.  The first is ``Stuff''.
Stuff takes whatever text is selected and stuffs it into your
terminal.  Basically, it pretends to type it for you.  It doesn't
matter which window you've selected text in, stuff can find it.  It's
real easy to grab some text in one window and move it to another with
stuff.  Once you've made a selection, it remains the current selection
even if it's not on the screen anymore.  Neat stuff.

The second entry in the terminal menu is ``Frame...''  Under here is a
copy of the standard frame menu.

The third entry in the terminal menu is ``Config...''  Here things get
fun.  Each of the submenus under Config... also has a submenu.  We
will deal with them individually.

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.

Config... Points...  This menu sets the font point size.  By default,
this will change the window size to fit.

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.

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.

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.

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.

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.

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.


Well, we've wound our way all the way through the menu tree, and that
completes what you can do with the mouse in psterm.  Getting around in
psterm can be quite amusing... have fun.



	Customizing psterm

It's easy to feed new PostScript code to psterm.  Just put the code
inside a file in your home directory called ``.pstermrc''.  psterm
will automatically load the contents of this file whenever it starts
up freshly (or you specify -r).  You can use this to override defaults
for all of your terminal sessions, or to set up custom code to be run
only for certain sessions (via the -ui userinit option).  See the
example .pstermrc files and the top of psterm.ps for more information.