⟦319b806fe⟧

TextFile

head     1.1;
access   ;
symbols  ;
locks    ;
comment  @@;


1.1
date     85.09.15.22.50.24;  author root;  state Exp;
branches ;
next     ;


desc
@@



1.1
log
@Initial revision
@
text
@.TH VSH 1
.SH NAME
Vsh \- visual shell
.SH SYNOPSIS
.B vsh
[
.B "-"
] [
.B "-f"
]
.SH DESCRIPTION
.I Vsh
is a highly interactive, visually oriented shell
which eases many programming activities.
Most commands involve only a single keypress.
These commands cause directories to be displayed,
editors to be entered,
and compilers to be invoked.
Beginners should find
.I vsh
easier to learn then the conventional shell.
.PP
On entry to
.I vsh,
the current directory is plotted on the screen.
Each member of the directory is labeled with a letter.
To select a member,
one presses its corresponding letter.
What happens after selection depends on the nature of the member.
If the member is a directory,
.I vsh
changes to that directory.
Text files are edited.
Full details are given later in this manual.
.PP
.I Vsh
displays up to twenty files at a time on a standard 80x24 CRT.
Directories which are larger are broken into
pages of twenty files each.
There are as many pages as are required to display the entire
current directory.
To select a page, one presses a digit
.B 0-9.
Pages are numbered starting at one with
.B 0
selecting the last page.
.PP
A well integrated feature of
.I vsh
is its connection between compilers and editors.
To start a compile, one presses
.B M.
.I Vsh
then calls on
.IR make (1).
The output of this compile step is saved,
and one can later review for compile-time errors.
.I Vsh
numbers each error.
One can select an error by typing in its number.
After selection,
.I vsh
calls an editor,
sending one to the proper file at the offending line.
One can jump between the editor and
.I vsh
until one is ready for another compile.
.PP
.SH ENVIRONMENT PARAMETERS
.PP
.de UX
.B UNIX
..
.I Vsh
takes the following parameters from the global environment:
.TP 18
.B HOME
The home directory.  This parameter is automatically set by
.UX
when one logs in.
.TP
.B SHELL
The user's login shell.
.UX
also sets this parameter.
When it is necessary to escape to a shell,
this parameter selects the program to use.
.TP
.B EDITOR
The user's choice of editor. This parameter defaults to
.I vi(1).
.TP
.B PATH
The list of directories searched for commands.
.TP
.B TERM
The terminal type.
The terminal must be cursor addressable.
.PP
The user must set the
.B TERM
parameter himself.
As an example, to indicate your terminal is an adm3a, from
.IR csh (1)
type:
.PP
.B \ \ \ \ \ %\ setenv\ TERM\ adm3a
.PP
From
.IR sh (1)
type:
.PP
.B \ \ \ \ \ $\ TERM=adm3a;\ \ export\ TERM
.PP
See
.IR termcap (5)
for more information about the TERM parameter.
.PP
Based on
.I termcap,
.I vsh
determines whether the terminal is a CRT capable of
running
.I vsh.
.I Vsh
recognizes two command line options,
.TP 18
.B -
If not a useable CRT, exec the shell instead. Useful if
.I vsh
is your login shell.
.TP
.B -f
Try to run
.I vsh
even if
.I termcap
says that the terminal is incapable. Useful for running
.I vsh
in command scripts.
.ne 10v
.SH FILE SELECTION
.PP
As indicated before, one selects a file by pressing
its corresponding letter.
What happens after selection depends on the nature of the file.
.TP 18
.B File type
.B Action
.sp
.TP
.B Directory
Change to new directory.
.TP
.B Archive
Print archive directory.  This works for both
.IR ar (1)
and
.IR cpio (1)
formatted archives.
.TP
.B Object program
Print name list (external symbols).
.TP
.B Core
Invoke the debugger.
.TP
.B Compressed file
The file is tested if it has been compressed by several
of the common compression programs, including
.I pack,
.I compact,
and
.I compress.
The appropriate decompressor is then invoked. However no check
is made if the resulting output is text or binary data.
.TP 
.B Device
Selection fails.
.TP
.B Others, text
A quick test is performed to guess if the file is ASCII text. If the test
succeeds, EDITOR is invoked (but see the discussion of the parameter
.I entertext
for alternatives).
.br
.ne 10v
.SH DIRECTORY OPERATIONS
.PP
This is a list of the directory commands.
Before doing anything else, the user should become
familiar with commands which allow him to
select files and display directories.
In directories larger than twenty files,
the user should be able to display each page with the commands given below.
.br
.ne 10v
.TP 18
.B Command
.B Action
.sp 1
.TP
.B ^D
:sh
Leave
.I vsh.
.TP
.B a-z
Select corresponding file.
.TP
.B 1-9
Select page 1-9.
.TP
.B 0
Select the last page.
.TP
.B +
Select next page.
.TP
.B ^F,\ ^D
Same as
.B +.
.TP
.B \-
Select previous page.
.TP
.B ^U
Same as
.B -.
.TP
.B ^\ (Home)
Change to home directory.
.TP
.B /
Change to root directory.
.sp
.ta 18n
.in .5i
\fB\\\fP	Change to previous directory.
.in
.DT
.TP
.B ?
Display help file.
.TP
.B !
Escape to SHELL.
.TP
.B %
Chain to SHELL (does not return to
.I vsh
).
.TP
.B .
Find page with files beginning with a certain character (prompted for).
.TP
.B $
Escape to the Bourne shell.
.TP
.B -Line\ Feed-
Change to previous (parent) directory.
.TP
.B ^L
Repaint the display.
.PP
.br
.ne 12v
.ti -5
These are convenience commands.
.TP 18
.B D
Display date.
.TP
.B T
Display a text file using the
.I vsh
pager.
.I Vsh
prompts for a file and displays it as ascii text.
This is faster than a selection which calls the editor.
.TP
.B P
Process status.  Call /bin/ps.
.TP
.B W
Who.  Display who is logged in.
.TP
.B X
Execute a shell command (prompted for).
.TP
.B Y
Re-execute previous shell command (entered via
.B X
).
.PP
.ti -5
These are advanced commands.
.TP 18
.B F
Select file by name.
.I Vsh
prompts for a file name.
.I Vsh
then selects the specified file.
.TP
.B C
Create a new file.
.I Vsh
prompts for a file name and file type.
One may create text files and directories.
One may also copy, rename and link from existing files.
.TP
.B L
Long format file listing.
Next to each file,
.I vsh
displays protection information in the same manner as
.IR ls (1).
.TP
.B O
Option listing.
The contents of command and parameter tables are displayed.
.I Vsh
then prompts for commands which modify parameters and which
create, modify, and delete commands.
.SH REMOVE MODE
.PP
Press
.B R
to enter
.I Remove\ mode.
In
.I Remove\ mode,
selecting a file causes it to be marked for removal
with two slashes, "//."
Files selected a second time are unmarked.
Pressing
.B R
a second time causes all marked files to be removed.
The following commands are available in
.I Remove\ mode:
.TP 18
.B Command
.B Action

.TP
.B -Return-
Exit
.I Remove\ mode
with out removing marked files.
.TP
.B ^D
Same as
.B -Return-
.TP
.B a-z
Select corresponding file for removal.
.TP
.B *
Select all files on current page for removal.
.TP
.B 0\-9,\ +,\ \-
Select and display another page.
These commands are described earlier in the manual in
the section on directory operations.
.TP
.B ?
Display help file.
.TP
.B R
Remove marked files and exit
.I Remove\ mode.
If
.I vsh
cannot remove a file,
.I vsh
displays the reason and waits for a response.
Press
.B -Return-
to continue removing marked files.
Press
.B ^D
to immediately exit from
.I Remove\ mode.
.SH MAKE, GREP, AND SHOWFILE
.PP
.I Vsh
interfaces to
.IR make (1)
and
.IR grep (1).
.I Vsh
saves output from these programs and allows one to examine the
results in
.I showfile\ mode.
From the directory page, the following commands control
.I make,\ grep,
and
.I showfile.
.sp 1
.TP 18
.B G
.IR grep (1).
.I Vsh
prompts for a pattern and file names, and then run
.I grep
with these parameters.
The results are saved in the file
.I .grepout
and displayed in
.I showfile\ mode.
.TP
.B S
Show previous
.I grep.
The output of the last
.I grep
is displayed in
.I showfile\ mode.
.TP
.B M
.IR Make (1)
.I Vsh
runs
.I make.
Execution is controlled by the
.I makefile
in the current directory.
Output is both displayed on the screen and saved in the file
.I .makerror.
When
.I make
terminates,
.I vsh
displays
.I .makerror
in
.I showfile\ mode.
.TP
.B N
.IR make (1)
running independently.
.I Make
is run but
.I vsh
does not wait for termination.
Output is saved in
.I .makerror,
but is not displayed on the screen.
When
.I make
terminates,
the bell on your terminal rings twice.
Use
the
.B E
command to review the output in
.I .makerror.
.TP
.B E
Review errors.
The results of the last
.I make
are displayed in
.I showfile\ mode.
.br
.ne 10v
.SH SHOWFILE MODE
.PP
.I Showfile
displays the results of a
.I make
or
.I grep.
It is called by the
.B E
and
.B S
commands.
.I Showfile
is called automatically in the course of an
.B M
or
.B G
command.
.I Showfile
is essentially a special editor.
It has commands which allow one to display a file.
One can also command
.I showfile
to examine a line of the file.
.I Showfile
scans this line and attempt to extract a file name
and line number.
.I Showfile
then runs the editor,
starting it at the specified line.
.PP
.br
.ne 10v
These are the
.I showfile
commands.
It is not necessary to press -Return- after these commands.
When a complete command is sensed,
it is run immediately.
.TP 18
.B Command
.B Action
.sp
.TP
.B number\ p
Print file starting at specified line.
.TP
.B number\ e
Examine line for a file name and line number.
If a file name is found, run the editor on this file.
.TP
.B -Return-
Display next twelve lines.
.TP
.B number\ -Return-
Same as
.B "number e"
.TP
.B ^D
Leave
.I showfile.
.TP
.B q
Leave
.I showfile.
.TP
.B ?
Display help file.
.PP
All commands from the directory page which might be useful
are available in
.I showfile\ mode.
They include
.B ^, /, !,
and
.B A
through
.B Z
except
.B L
and
.B R.
Particularly useful are
.B M
and
.B G
which allow new iterations of
.I make
and
.I grep,
.B !,
the escape to the shell,
and
.B F,
which allows one to edit files not found in the
file being shown.
.SH CONTROL COMMANDS
.PP
The operation of
.I vsh
is controlled by its parameter and command tables.
The contents of these tables can be displayed via the
.B O
command.
These tables can be modified with control commands.
When
.I vsh
is invoked, it searches for the file
.I .vshrc
in your home directory.
Control comands are then read from this file,
allowing one to create a personalized environment.
The
.B O
command also prompts for control commands,
allowing for interactive modification of the tables.
.PP
These control commands should be presented in the same
lexical grammar as shell commands.
Spaces and tabs separate tokens.
Unquoted newlines terminate each statement.
A character may be quoted by preceding it with a
.B
\\.
All characters inside single quotes (' ') are quoted except the
single quote.
Inside double quotes (" "),
.B
\\
quotes another double quote and
.B
\\newline
is ignored.
Grave accents (` `) are treated as any other character.
The lexical grammar is compatible with that of
.IR sh (1).
The grammar is somewhat different from that of
.IR csh (1).
.PP
.br
.ne 20v
To change a parameter, use the following format in
.I .vshrc
or to the
.B O
command:
.PP
.B
\ \ \ \ \ PARAMETER\-NAME\ \  PARAMETER\-VALUE
.PP
.B PARAMETER\-NAME
can be any of the following:

.TP 18
.B Parameter
.B Usage
.sp
.TP
.B EDITOR
Preferred editor.  Default is
.I vi.
.TP
.B HOME
Home directory. Default is $HOME.
.TP
.B TERM
Terminal type.
.TP
.B PATH
Command search list. Default is $PATH.
.TP
.B SHELL
Shell for escapes. Default is $SHELL.
.TP
.B MAIL
File to check for new mail. Default is /usr/spool/mail/$USER or $MAIL.
.TP
.B make
Make program.  Default is
.I /bin/make.
.TP
.B makerror
File for error output of
.B make.
Default is .makerror .
.TP
.B grep
grep program.  Default is
.I /bin/grep.
.TP
.B grepout
File for output of
.B grep.
Default is .grepout .
.TP
.B quitchar
Character command to leave
.I vsh.
Default is
.I control-D.
.B quitchar
is expressed as the desired ASCII character plus octal 0100.
Thus
.I control-D
is expressed as D and
.I escape
is expressed as [.
.TP
.B pagechar
An alternate character command for '+', to advance the file display.
.B pagechar
is also expressed as the desired ASCII character plus octal 0100.
Default is ';' which is expressed as '{'.
.TP
.B rmhelp
Remove mode help file. Default is /usr/lib/vsh/rmhelp.
.TP
.B showhelp
Show mode help file. Default is /usr/lib/vsh/showhelp.
.TP
.B vshmode
.I Vsh
operating mode. Default is
.I enter.
In
.I entermode,
.I vsh
immediately enters a selected file.
The other alternative is
.I selectmode,
in which
.I vsh
places an arrow beside the selected file and waits for another
key press to determine the operation to perform on the selected file.
.TP
.B entertext
Determine how
.I vsh
should enter text files. The default is
.I $EDITOR
where
.I vsh
invokes
.I $EDITOR
on the text file. Another alternative is
.I display,
where
.I vsh
invokes the internal text pager (similar to
.I more(1)
) on the text file.
If
.B entertext
is neither of these two alternatives, its value is interpreted
as a program name which should be invoke on the text file.
.TP
.B helpfile
File name of a help file to display on the right side of the screen.
Default is $HOME/.vshelp . If
.B helpfile
is not defined or the named file non-existant, no help menu is displayed.
.TP
.B window
Number of screen lines to use for the file display. The default is the
entire screen up to 26+4 lines.
.TP
.B column
Number of columns of files to use in the file display. The default is one.
Each column occupies 19 spaces - thus an 80 column screen can have at most
four columns. It is permissible to specify more columns than possible.
.TP
.B noargprompt
If defined, causes
.I vsh
to ignore missing arguments when executing commands. Default is to
prompt for missing arguments.
.TP 
.B VImotion
Use
.I vi(1)
style cursor motions
.I hjkl
to move the select pointer around the file display. Pre-empts the meaning
of
.I hjkl
as file letter selectors and only meaningful when
.B vshmode
is
.I select.
.TP
.B moresize
Set memory size for the
.I vsh
internal pager. Default is 10000. Governs amount of text which can be
scrolled through in reverse.
.TP
.B enterpath
List of directories to search for a file entered via
the
.I vsh
.B file
command (default bound to
.B F
).
Default is ':', just the current directory.
.sp
.br
.ne 10v
.PP
To define a command, use the following format in
.I .vshrc
or to the
.B O
command:
.PP
.B
\ \ \ \ \ CHARACTER\ \  KEYWORD\ \  [PARAMETERS\ ...]
.PP
CHARACTER is the character which calls the new command.
Valid characters are
.B
! " # $ % & ' ( ) : * = ^ ~ [ ] { } < > , . / ?
and
.B A\-Z.
.br
.ne 15v
.PP
These are the valid keywords:
.TP 18
.B Keyword
.B Purpose
.sp
.TP 18
.B date
Display date.
.TP
.B showerror
Show errors from previous
.I make.
.TP
.B showgrep
Show output from previous
.I grep.
.TP
.B file
Select a file.  If parameter is present,
the parameter is selected.  Otherwise,
.I vsh
will prompt for a file name.
.TP
.B home
Change to home directory.
.TP
.B grep
Run
.I grep.
.I Vsh
will prompt for parameters.
.TP
.B wmake
Run
.I make.
Wait for termination.
.TP
.B fmake
Run
.I make.
Do not wait for termination.
.TP
.B remove
Enter
.I Remove\ mode.
.TP
.B longlist
Print long format listing of files on the current page.
.TP
.B display
Display the contents of a file.
If no parameter is present,
.I vsh
will prompt for a file name.
.TP
.B options
Display
.I vsh
options (parameter and command tables).
Accept commands which modify parameters and
which create, modify, and delete commands.
.TP
.B exec
Execute a program directly with the exec system call.
The first parameter must be the program name.
Directories are not successively searched as in the shell.
Any other parameters become parameters to the program.
If it is necessary to redirect files, to expand macros,
or to expand file regular expressions, use the
.B shell
or
.B xecute
keyword instead.
.TP
.B pexec
Like
.B exec
but the command's output is processed through the
.I vsh
internal pager (similar to
.I more(1)
).
.TP
.B shell
If no parameter is present, an interactive shell is spawned.
If one parameter is present, it is passed to the shell
and run as a command.  Do not specify more than one parameter.
Instead, enclose the entire shell command in quotes
to provide
.I vsh
with only one parameter.
.TP
.B create
.I Vsh
prompts for a new file name.  The file is created.
If the file already exists,
.B create
will refuse to overwrite it unless a ! precedes the file name.
.TP
.B xecute
Execute one shell command (like
.B shell
), prompt if no command is given.
.TP
.B rexecute
Re-execute previous
.B xecute
command.
.TP
.B chain
Chain (exec without fork) to a new command (never returns to
.I vsh
).
.TP
.B null
Undefines a command.
.SH ADVANCED USAGE
.SH SELECT MODE
The default mode for
.I vsh
described above is called
.I entermode.
In this mode, files are
.I entered
immediately upon selection via a single keypress of
.I a-z.
The operation performed on the selected file is determined by the
file type.
.I Vsh
has another, more advanced mode of operation,
.I selectmode.
This mode is enabled when the parameter
.B vshmode
is set to
.I select.
When
.I vsh
is in
.I selectmode,
two keypresses are required to initiate an operation. The first, as in
.I entermode,
selects the desired file,
.I a-z.
An arrow appears next to the file selected.
The second keypress then determines the operation to be performed on the
selected file. If the same file (keypress)
.I a-z
or ` or
.I "carriage return"
is chosen, the file is
.I entered
in a manner identical to
.I entermode,
i.e. based on file type.
If another file
.I a-z
is selected, that file becomes the current selected file, and the arrow
appears next to that file instead. If a command character is pressed
(
.I A-Z,
or others), that command is invoked and the selected file is available as
an argument to that command. Whether the invoked command actually uses the
selected file or not depends on whether the command was defined to use it.
.PP
The following predefined commands (see above) are interfaced to
.I selectmode,
.TP 18
.B Keyword
.B Effect
.sp
.TP 18
.B display
Display the contents of the selected file.
.TP
.B create
Create a new file. The selected file may be used for rename, copy or link
operations.
.PP
The following commands are interfaced to
.I selectmode
by the token $ which is replaced by the name of the selected file.
.TP 18
.B grep
Search for pattern in named file(s). The named file may be '$' which specifies
the selected file.
Wherever a $ token appears in a command definition using the following
program execution keywords, it is replaced by the name of the selected file.
.TP
.B exec
Execute a program.
.TP
.B pexec
Like exec but filters the standard output
through the
.I vsh
internal pager (similar to
.I more(1)
).
.TP
.B xecute
Execute one shell command (like
.B shell
), prompt if no command is given.
.TP
.B rexecute
Re-execute previous
.B xecute
command.
.PP
Thus to define the letter
.I v
as a command to invoke
.I /bin/vi
on a selected file, one types
.PP
	v exec /bin/vi $
.PP
to the
.I options
command, or in
.I .vshrc
In addition, for
.B exec
and
.B pexec,
each argument beginning with ?? is printed as a prompt message and
a string is obtained from the terminal to place that argument.
.SH MULTICOLUMN DISPLAYS
Instead of a single column of files per screen,
.I vsh
can display multiple columns of files each column corresponding to a
.I vsh
page. This type of display is not compatible with the help menu display
enable by the
.B helpfile
parameter. Multicolumn displays are enabled by setting the parameter
.B column
to the number of desired columns. Each occupies 19 spaces. 
.I Emacs
cursor commands are available to move the
.I selectmode
arrow around the multicolumned file display. The
.I vi
commands
.B hjkl
are also available but the option
.B VImotion
should be set to avoid conflict with the
.I a-z
interpretation of these keys in file selection.
.SH INTERNAL PAGER
.I Vsh
has an internal pager similar to
.I more(1)
that is used with the
.B display
and
.B pexec
commands.
The following commands are available when in the pager.
.TP 18
.B "1,<"
Go to the first line.
.TP
.B "G,>"
Go to the last line.
.TP
.B "?,^R"
Reverse search
.TP
.B "/,^S"
Forward search
.TP
.B "e,v"
Invoke $EDITOR
.TP
.B "-,^P,k"
Previous line
.TP
.B "<CR>,^N,j"
Next line
.TP
.B "^U"
Previous half page.
.TP
.B "^D"
Next half page.
.TP
.B "^B,^"
Previous full page.
.TP
.B "^L"
Repaint screen.
.TP
.B "!"
Fork a subshell.
.TP
.I "(anything else)"
Next full page.
.PP
The forward and reverse searches prompt for a string pattern which
supports only the ^ . $ regular expression operators. A forward
search can cause a file to hit EOF. In this case, the wraparound can
fail if the more buffer size is insufficient to hold the entire file
(see the parameter
.B moresize
).
Reverse searches do not wraparound. If no pattern is entered, the previous
pattern is used.
.SH HINTS
.PP
When typing in a file name (e.g. to the
.B file
command), ! means the last file name typed in.
.PP
If the program name invoked by
.B exec
or
.B xecute
begins with ; the screen is updated immediately after the program
terminates. This feature facilitates screen/command interactions
(i.e. cleans up the screen and doesn't slow you down).
.PP
A ~ in the beginning of a file name is replaced with a user's login
directory, as in
.I csh(1).
.PP
It is generally preferable to use
.I selectmode
and define
.B entertext
as
.I display.
Used this way
.I vsh
can speedily examine the contents of text files without the overhead
of invoking a separate editor. Use the invoke editor command within
the pager to invoke an editor and also define a separate command which
invokes your favorite editor on a selected file.
.PP
The best way to change directories is with the
.B file
keyword. It is particularly efficient to bind
.B file
to / since / often appears at the beginning of pathnames and is usually
a non-shifted key.
.PP
The
.I vsh
display works best with terminals that support the
.I termcap
CS capability (change scrolling regions). All VT100 emulators and other
ANSI-like terminals should have this feature. With the CS capability,
it is then optimal on a 80x24 terminal to set
.B window
to 11 (a-g plus two lines each on top and bottom). Then one can use the
.I vi
.B hjkl
without ambiguity and have a reasonably large pager region. With larger
VT100-like terminals, such as the CIT-500 and the Bitgraph, one can set
.B window
to as large as 30 (26 + 4).
.PP
Using the
.B O
command for changing options and parameters is best for making temporary
changes to the configuration for
.I vsh.
When making permanent changes to one's
.I vsh
configration, it is best to alter
.I .vshrc.
It is convenient to define a
.I vsh
command to
.B chain
to
.I vsh
itself. Then to make a permanent change to the
.I vsh
configuration, one simply edits
.I .vshrc
and then uses the
.B chain
to
.I vsh
to overlay the current
.I vsh
with one which has read in the new
.I .vshrc.
.SH FILES
.ta 2i
$HOME/.vshrc	initialization file.
.br
/etc/termcap	terminal capability database necessary for addressing cursor.
.br
/bin/pwd	for determining the path name of the working directory.
.br
/dev/null	data sink.
.br
/usr/lib/vsh/*	supporting documentation and help files.
@
DataMuseum.dk

ICL Comet 32

⟦319b806fe⟧ TextFile

Derivation

TextFile
