ref: 7ae7351ace73a70cbbaf5a2da016005485d0d43b
dir: /man/1/wm-sh/
.TH WM-SH 1
.SH NAME
sh, mash \- Window frames for the Inferno shells
.SH SYNOPSIS
.B wm/sh
[
.B -b
] [
.B -w
.I width
] [
.B -h
.I height
] [
.B -f
.I font
]
.I sh-args
.br
.B wm/mash
.I mash-args
.br
.SH DESCRIPTION
Both
.B wm/sh
and
.B wm/mash
provide a graphical framework to their respective shells.
Both wrappers manage the input and output of the shell.
They provide facilities for scrolling and editing the output buffer
and for constructing input to be sent to the shell.
.PP
.B Wm/sh
invokes the shell
.IR sh (1)
with the arguments
.B -n
.IR sh-args ;
.B wm/mash
invokes
.IR mash (1)
with the arguments
.IR mash-args .
.B Wm/sh
accepts the following additional options, which are
not passed through to
.IR sh :
.HP
.B -b
.br
Inverts the default background and text color scheme.
.HP
.B -w
.I width
.br
The window should be at least
.I width
pixels wide.
.HP
.B -h
.I height
.br
The window should be at least
.I height
pixels high.
.HP
.B -f
.I font
.br
Specify the font to use in the window.
.I Font
should be the name of a valid
.IR font (6)
file.
.PP
.B Wm/sh
and
.B wm/mash
both provide their own versions of
.B /dev/cons
and
.B /dev/consctl
files in the namespace of the invoked shell
(see
.IR cons (3)
for the originals) and attach the standard input
of the invoked shell to the virtualised
.B /dev/cons
file.
Output from the shell, or of any commands run by the shell, is displayed in
a scrollable text window, appearing at the
.IR "output position" ,
which is at the end of any previously output text, before
any as-yet-unread user input text.
.PP
Any text displayed on the console can be edited.
Typed text is always inserted at the position of the input cursor.
The input cursor can be moved to any point in the text by
clicking mouse button-1 at the desired position.
Selections can be made by dragging the mouse with button-1 held down.
Typing into a selection copies its text to the Snarf buffer, the
selected text is deleted and the typed character inserted.
.PP
Text typed beyond the output point will be made available
to commands reading from
.BR /dev/cons .
Normally this text is made available when newline is typed,
but typing ESC turns on
.I hold
mode (the text turns blue), deferring the availability of the text until ESC is
typed again, turning hold mode off. This allows simple
multi-line editing of the standard input to a command.
.PP
Writing
.B rawon
to
.B /dev/consctl
changes the above behaviour, making each character typed beyond
the output point available to commands as soon as it is typed;
the character is not automatically echoed. Writing
.B rawoff
to
.B /dev/consctl
reverses this behaviour.
.PP
In addition to dragging out selections, they can be made by double clicking
mouse button-1.
Double clicking over a word selects the whole word.
Double clicking next to a brace or bracket selects the text between it and its matching
brace or bracket.
If there is no match then no selection is made.
.PP
Clicking mouse button-2 displays a pop-up menu of editing commands:
.TP
.B Cut
Copy the current selection to the Snarf buffer and then delete
the selected text.
This command has no effect if there is no selected text, the Snarf buffer
is not cleared.
.TP
.B Paste
When there is no text selected, the contents of the Snarf buffer are
inserted at the current input cursor.
If a selection exits, its text is replaced by that of the Snarf buffer.
The new text is then selected.
The contents of the Snarf buffer remain unaltered.
.TP
.B Snarf
Copy the selected text to the Snarf buffer.
This command has no effect if there is no selected text.
.TP
.B Send
If there is any text selected it is copied to the Snarf buffer.
The contents of the Snarf buffer is then
appended to the end of the current shell input line, forwarding
any NewLine completed lines to the shell's input stream.
.PP
Mouse chording is implemented as in
.IR acme (1).
Dragging a selection with button-1 held down and then also clicking
button-2 cuts the selected text into the Snarf buffer.
Clicking button-3 instead of button-2 replaces the selected text with the contents
of the Snarf buffer.
.PP
Clicking mouse button-3 plumbs the word or selection under the click point.
See
.IR plumber (8)
for more information on plumbing.
.PP
.I Wm/sh
also serves the file
.BR /chan/shctl .
The following commands may be written to this file:
.HP
.B cwd
.I dir
.br
Causes any plumbing request generated by
.I wm/sh
to be created with
.I dir
as its ``current directory''. This is shown in the
title bar of the window.
Note that it is up to the command running inside
.I wm/sh
to keep this up to date (for instance, see EXAMPLES,
below).
.HP
.B button
.I "title sendtext"
.br
A Tk button is created at the top of the shell window, labeled
with
.IR title .
When activated,
.I sendtext
will be sent to the shell window as if it had been typed.
.HP
.B action
.I "title sendtext"
.br
A button is created as for the
.B button
command, except that activation of the button causes
.I sendtext
to be sent to any process reading from
.BR /chan/shctl .
.HP
.B clear
.br
Delete any buttons that have been created.
.PP
Arguments to commands sent to
.B /chan/shctl
follow
.IR sh (1)
quoting rules (the same as implemented by
.I quoted
and
.I unquoted
in
.IR string (2)).
A process reading from
.B /chan/shctl
will block until an
.B action
button is activated, whereupon it will yield the
.I sendtext
associated with the button.
.SH PLUMBING
Both
.B wm/sh
and
.B wm/mash
plumb text selected by button 3;
an empty selection plumbs the white-space bounded text
surrounding the selection.
.SH EXAMPLES
Define a
.IR sh (1)
function to update the current directory automatically:
.PP
.EX
fn cd {builtin cd $*; echo cwd `{pwd} >/chan/shctl}
.EE
.PP
Note that this will not work in all cases, as it is possible to
change the current directory without using the
.I cd
command.
.PP
Create a button to automate a
.I mount
command (note the newline in the argument string):
.PP
.EX
echo ${quote button mount 'mount kremvax /n/remote
'} > /chan/shctl
.EE
.PP
Create a new
.I wm/sh
window with the above button already created:
.PP
.EX
wm/sh -ic {
echo ${quote button mount 'mount kremvax /n/remote
'} > /chan/shctl
}
.EE
.SH SOURCE
.B /appl/wm/sh.b
.br
.B /appl/wm/mash.b
.br
.SH "SEE ALSO"
.IR sh (1),
.IR mash (1),
.IR wm (1),
.IR plumber (8)