IanDarwin.OpenLookCDROM/NeWS/gterm/UsingGTerm

				UsingGTerm

		A user guide for the new gterm program

		    by Eric Messick & Hugh Daniel

 @(#)$Header: /it/grass/gterm/RCS/UsingGTerm,v 2.6 1991/04/23 06:51:51 hugh Grass2 $


	Starting gterm.

If you're using gterm, chances are quite good that you are in NeWS.
This probably means that the directory /usr/NeWS/bin or one of the
other places that NeWS and gterm hides 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 gterm binary.  Just
starting gterm 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:

	gterm 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.

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

	gterm 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 gterm.  If you enter an illegal option on
the command line, gterm will print a usage line that looks something
like this:

Usage: gterm [-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, gterm has quite a few options.  Let's take a closer
look at them.

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

-C	Redirects the console output to the gterm 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.

-display hostname
	Sets the NEWSSERVER enviornment variable to host before gterm
	trys to connect to a NeWS display.

-F font	Overrides the default terminal font.

-f	Ignored.  For compatability with older versions.

-fg	Forces gterm not to fork, thus leaving you in the forground.
		Normally, gterm 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.

-fontsize fontsize
-fs fontsize
	Overrides the default terminal font point size.

-ic	Forces gterm 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 gterm 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 gterm to reload the gterm?XXXX.psh file and the .gtermrc
		file.  Normally, gterm checks and if the dictionary
		GTermDict_? exists in systemdict, it does not bother
		reloading the PostScript files.  If you make a change
		in gterm.ps or your .gtermrc, 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 gterm will emulate.  gterm 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 gterm, and works perfectly.
		gterm by default will use the psterm termcap if no '-t'
		option use used.  Note that gterm will run MUCH faster
		if the psterm termcap is used.  Expect to see a gterm
		termcap in the future.

-ui userinit
	gterm 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 .gtermrc 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:

	gterm /bin/login -p username

which opens a gterm 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: 

	gterm /bin/login -p

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

	gterm tip hostname

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




	Starting gterm from a Menu

Different window managers have very different ways of dealing with
menus, both in creating them and doing what the user has asked for.
Here are some usefull hints on creating your own menu entrys for
the LiteWindows and olwm window managers.
  For LiteWindows (NeWS 1.1 based systems) you can edit your user.ps
file to add menus for gterm.  Here is an example:

/mymenu [
	(Gterm)		{ (gterm) forkunix }
	(Ecotone Login)	{
(remsh ecotone -l hugh /usr/openwin/bin/gterm -ls /bin/login)
			forkunix }
] /new DefaultMenu send def
0 (Gterms...) mymenu /insertitem rootmenu send

Note that the example above is for a AT&T System V unix where you
need to use remsh insted of rsh to get a remote shell.

  For OpenWindows (OpenWindows 2.0) user menus are customized by
createing a .openwin-menu file in your home directory.  You might
start out by copying the ${OPENWINHOME:-/usr/openwin}/lib/openwin-menu
file and adding to it.  Here are two  compleat sub menus that you
could add to your .openwin-menu file just before the Programs meun:

"Gterms"	MENU
"80x34..."	DEFAULT	exec gterm -sl 512
"80x66..."		exec gterm -sl 512 -li 66
"96x48..."		exec gterm -sl 512 -li 48 -co 96
"Login"			exec gterm -sl 512 /bin/login -p
"Gterms"	END PIN

"Hosts"	MENU
"Ecotone..."	DEFAULT	exec rsh ecotone  /usr/openwin/bin/gterm -ls
"Swampgas..."		exec rsh ecotone  /usr/openwin/bin/gterm -ls
"Pondscum..."		exec rsh pondscum /usr/NeWS/bin/gterm -ls
"Ecotone Login..."	exec rsh ecotone  /usr/openwin/bin/gterm -ls /bin/login -p
"Hosts" END PIN

Note the Login windows, these are VERY usefull in a workplace where
other users might need to use your display for a short time.  It lets
them login to a machine with out disturbing any of your windows.

Note also that gterm is command line compatable with psterm, so you
can move psterm to say psterm.old and put in a symlink to gterm. To
do this cd to $OPENWINHOME/bin, $NEWSHOME/bin, /usr/NeWS/bin or
/usr/openinw/bin, and ishue these commands:
	mv psterm psterm
	ln -s gterm psterm


	Starting a gterm 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
gterm on one of those machines.  The other machine is the remote
machine, and the gterm running on the remote machine is the remote
gterm.  Your news_server is running on your local machine.  Ok?

If gterm 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 gterm 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 gterm 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
gterm 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.

To make life got a little simpler the -display option has been added
to gterm.  This takes the name of the host that you want gterm to 
display on (the name of the machine that is running NeWS).  This is
an example:
	rsh hoptoad /usr/openwin/bin/gterm -display ecotone
no matter where the rsh comes from the display will be on ecotone.




	Getting Around in gterm

Ok, you've started your gterm.  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, gterm 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 gterm 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 gterm 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,
gterm 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 .gtermrc 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 gterm 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 gterm.  Getting around in
gterm can be quite amusing... have fun.



	Customizing gterm

It's easy to feed new PostScript code to gterm.  Just put the code
inside a file in your home directory called ``.gtermrc''.  gterm
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 .gtermrc files and the top of gterm?XXX.psh for more information.