20060303-partial

1 files changed, 274 insertions, 0 deletions

diff --git a/man/1/wm-sh b/man/1/wm-sh
new file mode 100644
index 00000000..0db61f04
--- /dev/null
+++ b/man/1/wm-sh
@@ -0,0 +1,274 @@
+.TH WM-SH 1
+.SH NAME
+sh, mash \- Window frames for the Inferno shells
+.SH SYNOPSIS
+.B wm/sh
+[
+.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 -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)