FreeBSD-5.3/usr.sbin/pcvt/userkeys/vt220keys.1

.\" $FreeBSD: src/usr.sbin/pcvt/userkeys/vt220keys.1,v 1.10 2003/01/01 18:49:02 schweikh Exp $
.\"
.Dd January 16, 2001
.Dt VT220KEYS 1
.Os
.Sh NAME
.Nm vt220keys
.Nd "define SHIFTED function keys on VT220 terminal"
.Sh SYNOPSIS
.Nm
.Op Fl cil
.Op Ar keyname keystring ...
.Sh DESCRIPTION
The
.Nm
utility sets up a
.Dq "vt220 terminal"
in vt200 mode to allow user
definition of the SHIFTED function keys.
Each
.Ar keyname
specified on the command line will be loaded with
the corresponding
.Ar keystring .
A
.Ar keyname
is one of the following words:
.Cm F6 F7 F8 F9 F10 F11 ESC
.Cm F12 BS F13 LF F14 HELP
.Cm DO F17 F18 F19 F20 .
.Ar Keystrings
must be quoted if spaces, tabs, or shell metacharacters are included.
.Pp
The
.Nm
utility expects to receive some combination of option flags and/or
argument pair(s), otherwise a usage message
is printed.
.Pp
The options are:
.Bl -tag -width indent
.It Fl c
Clears all SHIFTED function key definitions before setting them to user
defined strings.
.It Fl i
Read the initialization file
.Pa $HOME/.vt220rc
for SHIFTED function key definitions.
This is done before any
argument pair specified on the command line is processed.
Each line in the file must consist of two fields (separated by spaces
or tabs) where the first field is the
.Ar keyname
and the second field is the
.Ar keystring .
The second field extends to the end of the line, thus a
.Ar keystring
may include spaces or tabs.
A newline (return) may be specified
within the string by using the C Language notation for newline (\\n).
.It Fl l
Locks the function keys from further definition.
Locking occurs after processing the initialization file (if the
.Fl i
option is specified) and any argument
pairs.
The only way
to unlock is by turning the power off.
.El
.Sh EXAMPLES
.Bd -literal
vt220keys -ci
vt220keys F6 'nroff -ms '
vt220keys -i F20 'cc -O -c '
vt220keys -l HELP man
.Ed
.Sh "OTHER FEATURES"
Pressing the function keys without using the shift key, generates
a string of characters.
With
.Xr csh 1
this string can be aliased to some command.
For example:
.Pp
.Dl alias\ ^[[17~\ "ls\ -CR\ |\ more"
.Pp
where
.Ql "^[[17~"
is what is generated by pressing the F6 key.
Therefore
F6 can perform two commands, depending if pressed with/without the SHIFT
key.
.Pp
The
.Nm
utility can be called from your
.Pa .login
or
.Pa .profile
file.
Typically an user
will create an initialization file and include a line like
.Pp
.Dl "vt220keys -ci"
OR
.Dl "vt220keys -cil"
.Pp
in the above mentioned files.
This way the SHIFTED function keys
will be set to your favorite commands when logging in.
.Sh CAVEATS
If the SHIFTED function keys are unlocked, redefinition of a SHIFTED
function key will rewrite the old string.
.Pp
There are 256 bytes available for the SHIFTED function keys.
Space is
supplied on a first\-come/first\-serve basis.
After the 256 bytes are
used, you can't define any more keys unless space is cleared.
This
can be done by redefining a key to contain a string of fewer bytes.
.Pp
All key definitions are stored in volatile RAM, and are lost when
terminal power is lost.
.Pp
The ESC key (unshifted) no longer generates the proper escape character.
This
is of particular importance since many editors require use of the
ESC key.
Here are some available alternatives:
.Bl -bullet
.It
The escape character can be generated by typing
.Ql ^[
(control\-[).
.It
Use
.Nm
as follows (note
.Ql ^[
is control\-[)
.Pp
.Dl "vt220keys ESC '^['"
.Pp
This will require you
to press the SHIFT key and ESC to generate the escape sequence.
.It
Some editors, allow other character(s) to be substituted for the
escape character.
For example with
.Xr emacs 1
include this line in your
.Pa .emacs_pro :
.Pp
.Dl (bind-to-key\ "ESC-prefix"\ "\\033[23~")
.Pp
Thus when the ESC key is pressed,
.Nm emacs
will allow the characters generated
.Pq Li ^[[23~
to perform the same function as the escape
character.
.El
.Sh FILES
.Bl -tag -width $HOME/.vt220rc
.It Pa $HOME/.vt220rc
initialization file
.El
.Sh SEE ALSO
.Rs
.%B "VT220 Programmer Reference Manual"
.Re
.Rs
.%B "VT220 Programmer Pocket Guide"
.Re