openbsd-ports/plan9/wily/files/wily.1

.TH WILY 1
.SH NAME
wily, win, awd \- interactive text windows
.SH SYNOPSIS
.B wily
[
.B -f
.I varfont
]
[
.B -F
.I fixfont
]
[
.B -c
.I ncol
]
.LP
.B win
[
.I command
]
.LP
.B awd
[
.I label
]
.SH DESCRIPTION
.I Wily
manages windows of text that may be edited interactively or by external programs.
The interactive interface uses a different interface.
.PP
Any named
.I files
are read into
.I wily
windows before
.I wily
accepts input.
Plain files display as text; directories display as columnated lists of the
names of their components, as in
.B "ls -p directory|mc
except that the names of subdirectories have a slash appended.
.PP
The
.B -f
.RB ( -F )
option sets the default variable-pitch (fixed-pitch)
font; the default is
.B /lib/font/bit/lucidasans/euro.8.font
.RB ( \&.../lucm/unicode.9.font ).
Tab intervals are set to the width of 4(8) numeral zeros in the variable-pitch font.
.PP
.SS Windows
.I Wily
windows are in two parts: a short
.I tag
above a multi-line
.IR body .
The body typically contains an image of a file, as in
.IR sam (1),
or the output of a
program, as in an
.IR 8½ (1)
window.
The tag contains a number of
blank-separated words, followed by a vertical bar character, followed by anything.
The first word is the name of the window, typically the name of the associated
file or directory, and the other words are commands available in that window.
Any text may be added after the bar; examples are strings to search for or
commands to execute in that window.
.PP
If a window holds a directory, the name (first word of the tag) will end with
a slash.
.SS Scrolling
Each window has a scroll bar to the left of the body.
The scroll bar behaves much as in
.IR sam (1)
or
.IR 8½ (1)
except that scrolling occurs when the button is pressed, rather than released,
and continues
as long as the mouse button is held down in the scroll bar.
For example, to scroll slowly through a file,
hold button 3 down near the top of the scroll bar.  Moving the mouse
down the scroll bar speeds up the rate of scrolling.
.SS Layout
.I Wily
windows are arranged in columns.  By default, it creates two columns when starting;
this can be overridden with the
.B -c
option.
Placement is automatic but may be adjusted
using the
.I layout box
in the upper left corner of each window and column.
Pressing and holding any mouse button in the box drags
the associated window or column.
For windows, just
clicking in the layout box grows the window in place: button 1
grows it a little, button 2 grows it as much as it can, still leaving all other
tags in that column visible, and button 3 takes over the column completely,
temporarily hiding other windows in the column.
(They will return
.I en masse
if any of them needs attention.)
The layout box in a window is normally white; when it is black in the center,
it records that the file is `dirty':
.I Wily
believes it is modified from its original
contents.
.PP
Tags exist at the top of each column and across the whole display.
.I Wily
pre-loads them with useful commands.
Also, the tag across the top maintains a list of executing long-running commands.
.SS Typing
The behavior of typed text is similar to that in
.IR 8½ (1)
except that the characters are delivered to the tag or body under the mouse; there is no
`click to type'.
The usual backspacing conventions apply.
As in
.IR sam (1)
but not
.IR 8½ ,
the ESC key selects the text typed since the last mouse action,
a feature particularly useful when executing commands.
A side effect is that typing ESC with text already selected is identical
to a
.B Cut
command
.RI ( q.v. ).
.PP
All text, including the names of windows, may be edited uniformly.

.SS "Directory context
Each window's tag names a directory: explicitly if the window
holds a directory; implicitly if it holds a regular file
(e.g. the directory
.B /adm
if the window holds
.BR /adm/users ).
This directory provides a
.I context
for interpreting file names in that window.
For example, the string
.B users
in a window labeled
.B /adm/
or
.B /adm/keys
will be interpreted as the file name
.BR /adm/users .
The directory is defined purely textually, so it can be a non-existent
directory or a real directory associated with a non-existent file
(e.g.
.BR /adm/not-a-file ).
File names beginning with a slash
are assumed to be absolute file names.
.SS Errors
Windows whose names begin with
.B -
or
.B +
conventionally hold diagnostics and other data
not directly associated with files.
A window labeled
.B +Errors
receives all diagnostics produced by
.I wily
itself.
Diagnostics from commands run by
.I wily
appear in a window named
.IB directory /+Errors
where
.I directory
is identified by the context of the command.
These error windows are created when needed.
.SS "Mouse button 1
Mouse button 1 selects text just as in
.IR sam (1)
or
.IR 8½ (1) ,
including the usual double-clicking conventions.
.SS "Mouse button 2
By an
action similar to selecting text with button 1,
button 2 indicates text to execute as a command.
If the indicated text has multiple white-space-separated words,
the first is the command name and the second and subsequent
are its arguments.
If button 2 is `clicked'\(emindicates a null string\(em\c
.I wily
.I expands
the indicated text to find a command to run:
if the click is within button-1-selected text,
.I wily
takes that selection as the command;
otherwise it takes the largest string of valid file name characters containing the click.
Valid file name characters are alphanumerics and
.B _
.B .
.B -
.B +
.BR / .
This behavior is similar to double-clicking with button 1 but,
because a null command is meaningless, only a single click is required.
.PP
Some commands, all by convention starting with a capital letter, are
.I built-ins
that are executed directly by
.IR wily :
.TP
.B Cut
Delete most recently selected text and place in snarf buffer.
.TP
.B Del
Delete window.  If window is dirty, saves a backup of the file.
.TP
.B Delcol
Delete column and all its windows, after checking that windows are not dirty.
.TP
.B Quit
Exit
.I wily
after checking that windows are not dirty.
.TP
.B Font
With no arguments, change the font of the associated window or column from fixed-spaced to
proportional-spaced or
.I vice versa\f1.
Given a font name argument, change the font of the window to the named font.
Other existing windows are unaffected.
.TP
.B Get
Load file into window, replacing previous contents (after checking for dirtiness as in
.BR Del ).
With no argument, use the existing file name of the window.
Given an argument, use that file but do not change the window's file name.
.TP
.B Kill
Send a
.B kill
note to
.IR wily -initiated
commands named as arguments.
.TP
.B Look
Search in body for occurrence of literal text indicated by the argument or,
if none is given, by the selected text in the body.
.TP
.B New
Make new window.  With arguments, load the named files into windows.
.TP
.B Newcol
Make new column.
.TP
.B Paste
Replace most recently selected text with contents of snarf buffer.
.TP
.B Put
Write window to the named file.
With no argument, write to the file named in the tag of the window.
.TP
.B Putall
Write all dirty windows whose names indicate existing regular files.
.TP
.B Redo
Complement of
.BR Undo .
.TP
.B Send
Append selected text or snarf buffer to end of body; used mainly with
.IR win .
.TP
.B Snarf
Place selected text in snarf buffer.
.TP
.B Sort
Arrange the windows in the column from top to bottom in lexicographical
order based on their names.
.TP
.B Split
Create a copy of the window containing most recently selected text.
.TP
.B Undo
Undo last textual change or set of changes.
.PP
A common place to store text for commands is in the tag; in fact
.I wily
maintains a set of commands appropriate to the state of the window
to the left of the bar in the tag.
.PP
If the text indicated with button 2 is not a recognized built-in, it is executed as
a shell command.  For example, indicating
.B date
with button 2 runs
.IR date (1).
The standard
and error outputs of commands are sent to the error window associated with
the directory from which the command was run, which will be created if
necessary.
For example, in a window
.B /adm/users
executing
.B pwd
will produce the output
.B /adm
in a (possibly newly-created) window labeled
.BR /adm/+Errors ;
in a window containing
.B /sys/src/cmd/sam/sam.c
executing
.B make
will run
.IR make (1)
in
.BR /sys/src/cmd/sam ,
producing output in a window labeled
.BR /sys/src/cmd/sam/+Errors .
.SS "Mouse button 3
Pointing at text with button 3 instructs
.I wily
to locate or acquire the file, string, etc. described by the indicated text and
its context.
This description follows the actions taken when
button 3 is released after sweeping out some text.
In the description,
.I text
refers to the text of the original sweep or, if it was null, the result of
applying similar expansion rules that apply to button 2 actions.
.PP
If the text names an existing window,
.I wily
moves the mouse cursor to the selected text in the body of that window.
If the text names an existing file with no associated window,
.I wily
loads the file into a new window and moves the mouse there.
.PP
If the text begins with a colon, it is taken to be an address, in
the style of
.IR sam (1),
within the body of the window containing the text.
The address is evaluated, the resulting text highlighted, and the mouse moved to it.
Thus, in
.IR wily ,
one must type
.B :/regexp
or
.B :127
not just
.B /regexp
or
.BR 127 .
(There is an easier way to locate literal text; see below.)
.PP
If the text is a file name followed by a colon and an address,
.I wily
loads the file and evaluates the address.  For example, clicking button 3 anywhere
in the text
.B file.c:27
will open
.BR file.c ,
select line
27, and put the mouse at the beginning of the line.  The rules about Error
files, directories, and so on all combine to make this an efficient way to
investigate errors from compilers, etc.
.PP
If the text is not an address or file, it is taken to
be literal text, which is then searched for in the body of the window
in which button 3 was clicked.  If a match is found, it is selected and the mouse is
moved there.  Thus, to search for occurrences of a word in a file,
just click button 3 on the word.  Because of the rule of using the
selection as the button 3 action, subsequent clicks will find subsequent
occurrences without moving the mouse.
.PP
In all these actions, the mouse motion is not done if the text is a null string
within a non-null selected string in the tag, so that (for example) complex regular expressions
may be selected and applied repeatedly to the
body by just clicking button 3 over them.
.SS "Chords of mouse buttons
Several operations are bound to multiple-button actions.
After selecting text, with button 1 still down, pressing button 2
executes
.B Cut
and button 3 executes
.BR Paste .
After clicking one button, the other undoes
the first; thus (while holding down button 1) 2 followed by 3 is a
.B Snarf
that leaves the file undirtied;
3 followed by 2 is a no-op.
These actions also apply to text selected by double-clicking because
the double-click expansion is made when the second
click starts, not when it ends.
.PP
Commands may be given extra arguments by a mouse chord with buttons 2 and 1.
While holding down button 2 on text to be executed as a command, clicking button 1
appends the text last pointed to by button 1 as a distinct final argument.
For example, to search for literal
.B text
one may execute
.B Look text
with button 2 or instead point at
.B text
with button 1 in any window, release button 1,
then execute
.BR Look ,
clicking button 1 while 2 is held down.
.PP
When an external command (e.g.
.IR echo (1))
is executed this way, the extra argument is passed as expected and an
environment variable
.B $wilyaddr
is created that holds, in the form interpreted by button 3,
the fully-qualified address of the extra argument.
.SS "Support programs
.I Win
creates a new
.I wily
window and runs a
.I command
(default
.BR $SHELL )
in it, turning the window into something analogous to an
.IR 8½ (1)
window.
Executing text in a
.I win
window with button
2 is similar to using
.BR Send .
.PP
.I Awd
loads the tag line of its window with the directory in which it's running, suffixed
.BI - label
(default
.BR rc );
it is
intended to be executed by a
.B cd
function for use in
.I win
windows.  An example definition is
.EX
	fn cd { builtin cd $1 && awd $sysname }
.EE
.SH FILES
.TF $home/.wilybak
.TP
.B $home/.wilybak
default directory for backup files.
.SH SEE ALSO
.IR wily (4)
.br
Rob Pike,
.I
Acme: A User Interface for Programmers.
.SH BUGS