A tile structures (since tile lists are themselves tiles).
Note that self is not used in anywhere in the tile code,
as the the tile list may be a member of a super-tile-list running
the other way.
<tile list elements>= (<-U) [D->]
Tile self;
The array of tiles it contains.
<tile list elements>+= (<-U) [<-D->]
Tile **tiles;
The range to which the tile list elements are limited.
<tile list elements>+= (<-U) [<-D->]
int min, max;
The number of tiles currently in the array, and the maximum
size of the tile array.
<tile list elements>+= (<-U) [<-D->]
ushort count, maxtiles;
hidden is used to determine how many tiles
are hidden "to the left of" the tiles actually displayed (as a result of
a B3, for instance).
<tile list elements>+= (<-U) [<-D]
ushort hidden;
};
<typedefs>= (U->)
typedef struct TileList TileList;
Operations
There really are only a few operations that involve tiles.
- Adding a tile to a tile list (e.g., as a result of a New), either
arbitrarily or near a desired location.
- Removing a tile from its tile list (e.g., as a result of a Del).
- Moving a tile within a tile list. This might look better
than simply deleting and adding it, especially if the tile
is not really moving (i.e., it is just growing or shrinking).
- Making a tile big enough to be visible (necessary to make sure
that new output is visible, for instance).
- Locating a tile in a tile list given a location (to figure out
where typing should go).
- Growing a tile "some" (for B1 clicks), "lots" (for B2 clicks),
or "way lots" (for B3 clicks).
- Resizing. This should only occur as a result of wily's
X window being resized.
The only policy that tiles and tile collections are responsible for is
how to handle B1, B2, and B3 clicks, and what to do when a window is
deleted. The operator to add a tile will take hints as to where to place
a tile (with respect to a location).
Growing a Tile
Growing a tile proceeds in two simple steps: Make the tile the desired
size, and then push everything else out of the way. With a B3,
it would also be desirable to mark everything else as hidden instead
of adjusting the windows unnecessarily).
Since the tile growth is rather blind at times, tile_list_reshaped
is called without a specific "untouchable" tile, thereby fixing a prior bug.
<public tile functions>= (U->) [D->]
void
tile_grow(Tile *tile, Growth grow) {
TileList *list = tile->list;
<tile_grow locals>
<tile consistency checks>
switch (grow) {
case Gsome:
<grow tile a little>
break;
case Gmost:
<grow tile lots>
break;
case Gall:
<grow tile way lots>
break;
default:
assert(grow != grow);
}
tile_list_reshaped(list, 0);
}
<public function declarations>= (U->) [D->]
void tile_grow(Tile *, Growth);
This is probably too small
, especially when a column is
being grown, but it will work for now. Also, it does not check
boundary conditions.
<grow tile a little>= (<-U)
tile->min -= tile->step;
tile->max += tile->step;
The B2 implementation of this code relies slightly on the way
tile_list_reshaped is currently implemented, as it relies
on it not to hide any windows until it has tried shrinking
them all. Since this is good user interface policy anyhow, this
assumption presents little problem.
<grow tile lots>= (<-U)
space = list->min;
for (i = list->hidden; i < list->count; i++) {
if (list->tiles[i] == tile) {
tile->min = space;
space = 0;
continue;
}
space += list->tiles[i]->base;
}
tile->max = list->max - space;
<tile_grow locals>= (<-U)
int i, space;
To grow a tile way lots, the remaining tiles are added to the "hidden"
list. For the moment, the tiles are added in order by simply
swapping the selected tile to the end of the array, but heuristics
should be added so that the "least hidden" tile is the one the user
is most likely to want to see next.
A little trickery here -- the code only counts up to count - 1.
This is because the tile being expanded way lots gets swapped to the end
position in the array during the loop. If the tile being expanded is already
at the end, then there is no problem. Of course, if the caller
called with an array where tile was not in list, then there
is a problem.
<grow tile way lots>= (<-U)
for (i = list->hidden; i < list->count - 1; i++) {
if (list->tiles[i] == tile) {
list->tiles[i] = list->tiles[list->count - 1];
list->tiles[list->count - 1] = tile;
continue;
}
list->tiles[i]->min = list->tiles[i]->max;
}
list->hidden = list->count - 1;
tile->min = list->min;
tile->max = list->max;
L
ocating a Tile
This funtion simply relies on index_for_place to find the right
tile and then looks the tile up in the array.
<public tile functions>+= (U->) [<-D->]
Tile *
point2tile(TileList *list, int spot) {
int i = index_for_place(list, spot);
check_list_consistency(list);
return (i >= 0) ? list->tiles[i] : 0;
}
<public function declarations>+= (U->) [<-D->]
Tile *point2tile(TileList *, int);
M
aking a Tile Visible
As a gross heuristic,
the tile size is set to base+3step. If there is not enough room for
that, make the tile simply take the whole list over.
Of course, if the tile is already showing, there is no reason to expand it.
<public tile functions>+= (U->) [<-D->]
void
tile_show(Tile *tile) {
TileList *list;
<tile consistency checks>
list = tile->list;
check_list_consistency(list);
if (TILESIZE(tile) == 0) {
<expose the hidden tile tile>
}
if (TILESIZE(tile) >= tile->base + tile->step)
return;
tile->max = tile->min + tile->base + 3 * tile->step;
if (tile->max > list->max) {
tile->max = list->max;
tile->min = tile->max - (tile->base + 3 * tile->step);
if (tile->min < list->min)
tile->min = list->min;
}
tile_list_reshaped(list, tile);
}
<public function declarations>+= (U->) [<-D->]
void tile_show(Tile *);
Hidden tiles present a small problem -- they first
must be "unhidden" so they can be displayed. For
lack of a better place to put it,, the tile is added at
the end of the tile list. +Errors windows probably belong at
the bottom anyhow.
<expose the hidden tile tile>= (<-U)
int i;
for (i = 0; i < list->count && tile != list->tiles[i]; i++)
;
while (++i < list->count)
list->tiles[i-1] = list->tiles[i];
list->tiles[i] = tile;
list->hidden--;
M
oving a Tile Within a Tile List
Just add and delete it for now.
<public tile functions>+= (U->) [<-D->]
void
tile_move(Tile *tile) {
tile_del(tile);
tile_add(tile->list, tile);
}
<public function declarations>+= (U->) [<-D->]
void tile_move(Tile *);
A
dding a Tile to a Tile List
This function uses the minimum coordinate of the new
tile to determine where it should go.
What if the caller doesn't care?
If the caller does not know how large it wants the tile, it should
specify a tile with a size of 0.
<public tile functions>+= (U->) [<-D->]
void
tile_add(TileList *list, Tile *tile) {
<local variables for adding a tile>
<tile consistency checks>
check_list_consistency(list);
<make sure tile shape is reasonable>
<determine where to place the new tile in the list>
<add the tile to the list>
tile->list = list;
tile_list_reshaped(list, tile);
}
<public function declarations>+= (U->) [<-D->]
void tile_add(TileList *, Tile *);
The tile location must be constrained to its collection.
If the tile is so deformed after this reshaping that its size
exceeds the bounds of its container, it is simply shrunk to zero
size.
<make sure tile shape is reasonable>= (<-U)
assert(tile->min < tile->max);
if (tile->min < list->min) {
tile->max += list->min - tile->min;
tile->min = list->min;
}
if (tile->max > list->max) {
tile->max = list->max;
}
if (tile->max - tile->min < tile->base)
tile->min = tile->max = 0;
To determine where the tile should go in the list, we perform a
binary search on the tiles in the tile list to find the tile
containing tile->min. This will be useful enough to warrant
a separate function. The program must then determine whether the
new tile will go before or after the tile it is being placed on.
The tile is placed so that the tile it is supplanting is moved as little
as possible.
<determine where to place the new tile in the list>= (<-U)
if (list->count == list->hidden) {
i = list->hidden;
tile->min = list->min;
tile->max = list->max;
} else {
i = index_for_place(list, tile->min);
if ((<distance to move current tile up>) <
(<distance to move current tile down>)) {
i++;
}
}
<local variables for adding a tile>= (<-U) [D->]
ushort i;
Moving a tile up means just moving it by the distance from its
bottom to the desired top of the new window. Figuring out how
far a tile down would move down is more complicated, but essentially
works out to the distance from the top of the displaced tile to the
bottom of the new tile.
<distance to move current tile up>= (<-U)
list->tiles[i]->max - tile->min
<distance to move current tile down>= (<-U)
tile->max - list->tiles[i]->min
Once we know where in the array the tile goes, the other tiles
need to be shuffled out of the way.
<add the tile to the list>= (<-U)
<make sure tile list has room for one more>
for (j = ++list->count; j > i; j--)
list->tiles[j] = list->tiles[j-1];
list->tiles[i] = tile;
<local variables for adding a tile>+= (<-U) [<-D]
ushort j;
R
emoving a Tile from a List
This is pretty dull, actually -- the remaining elements
of the tile list are shuffled down in the array, and then
the tiles are resized to fit the new tile list.
One bug found: I was passing tile into tile_list_reshaped,
of all the silly things.
<public tile functions>+= (U->) [<-D->]
void
tile_del(Tile *tile) {
TileList *list = tile->list;
int i;
for (i = 0; i < list->count; i++) {
if (list->tiles[i] == tile) {
while (++i < list->count) {
list->tiles[i-1] = list->tiles[i];
}
list->count--;
tile_list_reshaped(list, 0);
return;
}
}
assert(0);
}
<public function declarations>+= (U->) [<-D->]
void tile_del(Tile *);
Adjusting tile sizes
When there is not enough room for the collection's tiles as they
stand, this function is called to fix the tiles. The tile argument
is used to indicate the tile that should not be adjusted.
Specifying a tile of zero prevents any tile from being treated
as special.
Adjusting the tiles, then, is split into two phases -- adjusting
the tiles above tile, and adjusting those below it. tileidx is
used in the next chunk of code. It is initially set to a location
not in the tile list.
<public tile functions>+= (U->) [<-D->]
void
tile_list_reshaped(TileList *list, Tile *tile) {
int i;
int tileidx = -1;
<tile_list_reshaped locals>
if (!tile)
adjust_sizes_in_range(list, list->hidden, list->count,
list->max - list->min);
else {
<tile consistency checks>
for (i = 0; list->tiles[i] != tile; i++) {
assert(i < list->count);
}
tileidx = i;
adjust_sizes_in_range(list, list->hidden, i, tile->min - list->min);
adjust_sizes_in_range(list, i + 1, list->count, list->max - tile->max);
}
<repair tile locations>
check_list_consistency(list);
}
<public function declarations>+= (U->) [<-D->]
void tile_list_reshaped(TileList *, Tile *);
Once the tiles all fit, their locations must be updated
(adjust_sizes_in_range does not do this). This is merely
a matter of sticking the tiles end-to-end.
<repair tile locations>= (<-U)
for (prevmax = list->min, i = list->hidden; i < list->count; i++) {
if (i != tileidx) {
list->tiles[i]->max -= list->tiles[i]->min - prevmax;
list->tiles[i]->min = prevmax;
}
prevmax = list->tiles[i]->max;
}
<tile_list_reshaped locals>= (<-U)
int prevmax;
The tiles in a particular range are adjusted through a simple
series of steps. Note that this only adjusts the sizes
of the tiles -- it does not adjust the tiles' locations.
Bugs found:
- T
he expansion code was seriously broken. Rethinking
it in terms of computing an amount to shrink the tile
dramatically simplified and improved the code.
- The expansion code did not work when there were no
tiles to adjust. Optimizing out an empty range is probably
worthwhile anyhow.
<static tile functions>= (U->) [D->]
static void
adjust_sizes_in_range(TileList *list, int start, int max, int available) {
<local variables for tile adjustment>
if (start == max)
return;
<determine amount of space needed>
if (0 && needed < 0) {
<expand tiles to fill slack>
return;
}
<shrink tiles until space available>
}
Determining the space required is easy -- determine the difference
between the heights of the tiles and the collection they appear in.
<determine amount of space needed>= (<-U)
needed = -available;
for (i = start; i < max; i++)
needed += TILESIZE(list->tiles[i]);
<local variables for tile adjustment>= (<-U)
int i;
int needed;
At this point, tiles are shrunk in a fairly arbitrary manner. The tile at
the top gets shrunk first, and on down until the necessary space
has been acquired. Tiles should be removed from view completely
if adequate space is not available.
A small ugly here -- there may be a gap right before
the "fixed" tile.
<shrink tiles until space available>= (<-U)
for (i = start; needed && i < max; i++) {
int base = list->tiles[i]->base;
int step = list->tiles[i]->step;
int shrink = TILESIZE(list->tiles[i]) - base;
shrink = ((shrink - base) / step) * step + base;
if (shrink > needed)
shrink = needed;
needed -= shrink;
list->tiles[i]->max -= shrink;
}
For the moment, expanding to fill a gap is handled is a relatively arbitrary
manner -- the last tile is grown to fill the gap.
What about any fuzz?
<expand tiles to fill slack>= (<-U)
list->tiles[max-1]->max -= needed;
Useful Macros
A
ccessing Tile Elements
Abstracting access via tile structures can very much simplify
the code. The first one returns the tile representing the column in
the global column list. The second one returns the column in which
a window resides. It is not actually defined as a macro in order to
improve type checking.
<public function declarations>+= (U->) [<-D->]
#define COLTILE(t) (&(t)->tiles.self)
static Col *WINCOL(Win *w) {return (Col *) w->tile.list;}
I
teration
There is no reason that every file dealing with tile lists need care
about the internals of the list. This also substantially helps if
the algorithm needs to be rearranged.
<public function declarations>+= (U->) [<-D->]
#define FOR_ALL_TILES(t, l)\
{ int __fral;\
for (__fral = 0; __fral < (l)->count && (t = (l)->tiles[__fral]); __fral++)
#define FOR_ALL_SHOWING_TILES(t, l)\
{ int __fral;\
for (__fral = (l)->hidden; __fral < (l)->count && (t = (l)->tiles[__fral]); __fral++)
#define END_ALL }
C
omputing a Tile's Height
This is a trivial computation, but occurs frequently enough to
warrant its own macro.
<public function declarations>+= (U->) [<-D->]
#define TILESIZE(tile) ((tile)->max - (tile)->min)
I
nternal Functions
TileList Management
For the moment, the only code we have to worry about is the
stuff that makes sure adding a tile goes cleanly. The array in
the tile list grows exponentially. It never shrinks, as it should
never get very large anyhow.
<make sure tile list has room for one more>= (<-U)
if (list->count == list->maxtiles) {
list->maxtiles *= 2;
list->tiles = realloc(list->tiles, list->maxtiles * sizeof(list->tiles[0]));
}
Finding a Tile
Finding a tile given a location is useful on at least a couple of
occassions. This function returns the index of the tile in the supplied
list, or -1 if no such tile exists.
This is a little extra-clever because we can search through the
tiles binarily instead of just slogging through them linearly.
We see that this terminates because, on every iteration, either
start is increased by at least 1 or end is decreased by at
least one (because of C's rounding, start + (end - start / 2
is always less than start + (end - start)).
<static tile functions>+= (U->) [<-D]
static int
index_for_place(TileList *list, int spot) {
int start = list->hidden;
int end = list->count;
int mid;
Tile *tile;
while (start < end) {
mid = start + (end - start) / 2;
tile = list->tiles[mid];
if (spot < tile->min)
end = mid;
else if (spot > tile->max)
start = mid + 1;
else
return mid;
}
return -1;
}
A
ssertions
There will be some useful assertions to make at various points in the code.
Some are catastrophic, others are merely aeshetic problems.
<public tile functions>+= (U->) [<-D]
void
check_tile_consistency(Tile *tile) {
<tile consistency checks>
}
void
check_list_consistency(TileList *list) {
int i;
Tile *t;
<tile list consistency checks>
FOR_ALL_TILES(t, list) {
check_tile_consistency(t);
} END_ALL;
}
<public function declarations>+= (U->) [<-D]
void check_list_consistency(TileList *);
C
atastrophic problems include:
- The tile list is null.
<tile list consistency checks>= (<-U) [D->]
assert(list);
- T
here are more tiles than there is space for them.
<tile list consistency checks>+= (<-U) [<-D->]
assert(list->count <= list->maxtiles);
- T
here are hidden tiles but no visible tiles.
<tile list consistency checks>+= (<-U) [<-D->]
assert(list->count == 0 || list->count > list->hidden);
- T
he first or last element of the tile list is off-screen.
<tile list consistency checks>+= (<-U) [<-D->]
assert(list->count == 0 || list->tiles[list->hidden]->min >= list->min);
assert(list->count == 0 || list->tiles[list->count - 1]->max <= list->max);
- T
he max edge of one tile is not equal to the min
edge of the following tile.
<tile list consistency checks>+= (<-U) [<-D]
for (i = list->hidden + 1; i < list->count; i++)
assert(list->tiles[i-1]->max == list->tiles[i]->min);
- T
he tile's tag is not at tile.r.min.
- The tile's tag is wider than the tile.
- The information in
struct tile is not consistent with
the information in the enclosing structure.
- The tile has negative height.
<tile consistency checks>= (<-U <-U <-U <-U <-U)
assert(tile->min <= tile->max);
The code is ugly if:
- The right side of the rightmost column should be
equal to
screen.r.max.y.
- The bottom of the bottommost window is further than
font->height above screen.r.max.x.
- The tile's tag is narrower than the tile.
Slamming It All Together
Not much cleverness here....
<tiletypedef.h>=
<typedefs>
<tiletype.h>=
<data structures>
<tileproto.h>=
<public function declarations>
<tile.c>=
#include "wily.h"
<static tile functions>
<public tile functions>
- <add the tile to the list>: U1, D2
- <data structures>: D1, D2, U3
- <determine amount of space needed>: U1, D2
- <determine where to place the new tile in the list>: U1, D2
- <distance to move current tile down>: U1, D2
- <distance to move current tile up>: U1, D2
- <expand tiles to fill slack>: U1, D2
- <expose the hidden tile
tile>: U1, D2
- <grow
tile a little>: U1, D2
- <grow
tile lots>: U1, D2
- <grow
tile way lots>: U1, D2
- <local variables for adding a tile>: U1, D2, D3
- <local variables for tile adjustment>: U1, D2
- <make sure tile list has room for one more>: U1, D2
- <make sure tile shape is reasonable>: U1, D2
- <public function declarations>: D1, D2, D3, D4, D5, D6, D7, D8, D9, D10, D11, U12
- <public tile functions>: D1, D2, D3, D4, D5, D6, D7, D8, U9
- <repair tile locations>: U1, D2
- <shrink tiles until space available>: U1, D2
- <static tile functions>: D1, D2, U3
- <tile consistency checks>: U1, U2, U3, U4, U5, D6
- <tile elements>: U1, D2, D3, D4, D5
- <tile list consistency checks>: U1, D2, D3, D4, D5, D6
- <tile list elements>: U1, D2, D3, D4, D5, D6
- <tile.c>: D1
- <
tile_grow locals>: U1, D2
- <
tile_list_reshaped locals>: U1, D2
- <tileproto.h>: D1
- <tiletypedef.h>: D1
- <tiletype.h>: D1
- <typedefs>: D1, U2
on every iteration, either
start is increased by at least 1 or end is decreased by at
least one (because of C's rounding, start + (end - start / 2
iswily-0.13.42/Doc/old/pythonpaper.html 0000644 0236657 0000012 00000051460 10333201523 0017224 0 ustar 00oz staff 0000433 0000002
Wily + Python > Emacs + Lisp?
DRAFT ONLY
This is a draft of a document which will be submitted to the 4th International
Python Conference to be held at June 4-6, 1996 at the Lawrence
Livermore labs in California.
This document describes aspects of Wily which are not yet released for beta
testing.
Wily + Python > Emacs + Lisp?
Gary Capell
<gary@cs.su.oz.au>
Basser Department of Computer Science,
University of Sydney, 2006
Australia
Wily is an editing environment which can be extended with Python
programs. Instead of using an embedded Python interpreter, Wily talks
a simple message protocol, and a module lets Python speak the same
protocol. This approach is general (one can use any language)
and clean (the editor is responsible for only a small set of functions).
The message interface promotes a clear separation of functions, with the
Wily editing environment providing a standard way of interacting with
client programs. The main disadvantage may be that the looser binding
between programming language and editor is less efficient, but this is
not expected to be a significant problem.
The editor itself is simple, clean, and efficient, with a few features
which combine consistently. It abandons backwards compatibility with
the virtual terminals of yesteryear, to take full advantage of a bitmapped
terminal and three button mouse.
Table of Contents
This documet describes:
An appendix defines the Python interface in
more detail.
This is necessarily very brief, and Wily and Acme are very different
from what most people are used to. Please read
Rob Pike's paper
for a better and more complete description of the interface.
Wily's main attractions are that it is very simple (the User Manual
describing the whole user interface is about seven pages), very quick to
use, and integrates well with other Unix tools.
History
Wily emulates in the Unix and X Windows environment the Acme editor
from Plan 9.
Acme couldn't easily be ported to Unix because it is written
in Alef
(a concurrent programming language not widely available) and uses
non-portable features of Plan 9 . Also, a port of Acme would not be
freely distributable.
The name ``Wily'' derives from Wile E. Coyote, an avid consumer of
Acme products.
Modern Aesthetics
The screen is divided into columns, which are divided into windows.
A window may represent a file, a directory, or the output from some
program. The screen, columns and windows each have a narrow horizontal
``tag'' at the top, which contains some useful text, and for windows
contains the name of the window and a "file is modified" indicator.
Text is displayed in a propotionally spaced font by default. There
is a built in function to toggle with a monospace font, but there are
very few occasions when this is necessary or desirable. In most cases
limiting a text editor to monospace fonts is blindly following the
hardware limitations of the 1960s.
Text is read and written as UTF8-encoded
Unicode,
providing some support for editing multi-lingual and scientific text,
but remaining backwardly compatible with plain 7-bit ASCII text.
Everything is text
All actions in Wily are through creating and interacting with text on
the screen, using the three-button mouse and the keyboard. B1 (mouse button
one) selects text, B2 executes text and B3 attempts to ``goto'' the text.
When executing text, there are some built in operations, such as
``Quit'', or ``Del'' which are executed by Wily itself. Otherwise, the
command is executed in a subprocess, with output redirected to a window
within Wily and input from /dev/null. It is also possible
to use the current selection (currently selected text) as input for
and/or output of some child program. For example |fmt
formats the current selection, >spell checks its
spelling and <date replaces it with the current time.
The goto operation used with B3 is polymorphic in that it
recognises three different patterns:
- name
- If name is a file or directory, open it, otherwise search
for the literal name
- :address
- Search for address in the current window. The
address may be a line number, a character number, a regular expression,
or two of these, separated by a comma.
- file:address
- Open file and search in it for address
Wily's power derives in part from its general treatment of text.
Whether text is found in a file, or directory listing, created by
Wily, output by some other program, or typed by the user, it can all
be treated the same way. A simple text file may be used as a menu of
commands or a simple form of hypertext. Previously typed commands or
``usage'' messages can be edited and executed. There is no need for
dialogs, menus, modes, buttons or accelerator keys, just operations on
text on the screen.
No wasted user actions
Wily minimizes the number of unnecessary mouse or keyboard
actions the user must make. For instance, placing newly created windows
is done without needing the user's help, although the user can easily
rearrange things if Wily's heuristics aren't acceptable. Wily also makes
cutting, pasting, executing and searching for text so easy to do with
the mouse that there is no need to retype text already on the screen.
Cutting and pasting text is made particularly convenient using
combinations of mouse buttons. To cut text, select it with B1,
and while still holding B1, also click B2: this is a B1-B2 chord.
To paste text use a B1-B3 chord. This style is unusual, but once it becomes
familiar other methods of cutting and pasting seem unbearably slow.
Another chord (B2-B1) is used to execute some text with
an argument.
To avoid having to position the mouse accurately, a mouse selection of
zero length (i.e. a mouse click) is expanded in a ``reasonable'' manner.
Clicking with B2 in a word expands to that word, which is then executed.
Clicking with B3 in an address (e.g. foo.c:45) expands to that
address. Double-clicking with B1 just inside paired braces, brackets or
quotes selects the region thus delimited.
Wily's general approach to text as commands and addresses
is compounded because these basic functions can be accessed so
conveniently. Most operations can be achieved with a single mouse click
or mouse combination.
Synergy
The consistent and general use of text for input and output
in Wily makes the combination of its features more than the
sum of its parts.
Stepping through an example session might best illustrate this:
Susan has fetched the file frob.tar.Z. She clicks with B1 in
the file name, and with B2 in the word untarz. The utility
untarz uncompresses and untars the file, verbosely printing
file names as it goes. She clicks with B3 on one of the file names,
INSTALL, which opens the file. The INSTALL file
suggests that she run configure then make. She clicks
B2 in each of these words to run the suggested programs, but there's a
problem. The make fails when gcc quits with the error message
keyboard.c:4: strings.h: No such file or directory.
She clicks with B3 in the first part of the error message, which
opens the file and selects the line. On Susan's system there is a
string.h but no strings.h. She removes the last
s with a B1-B2 chord. When she modifies the file, Wily sets
the ``file modified'' indicator, and adds the word ``Save'' to the tag
for this window. Susan clicks B2 on the word Save to write the
file, clicks B2 on make again, and she's done.
This whole process uses about ten mouse clicks and no typing.
Wily waits for a program to connect to it using a socket, and then sends
and receives messages. The messages can be RPC requests and replies,
or ``event'' messages generated by Wily when certain actions happen in
windows which a remote program has asked to monitor.
The interface is deliberately at a rather high level. The intent is that Wily
will take care of of the details of interaction, with other programs providing the
semantics of executing a command, opening a window or searching for an address.
This promotes a consistent set of tools and an efficient division of labour, but necessarily
at the loss of some generality.
The requests allow the remote program to
- list the windows currently open
- create a new window with a given name, which may or may not
correspond to an existing file or directory
- ask to be sent some subset of the events which happen in a
particular window
- change the name of a window
- read the text from some part of a window
- modify the text in a window
- act as if some string were selected with B2 or B3 in a window
(useful for searching for text, or accessing built in functions)
A program may ask to be notified when events happen in a particular
window. These events are generated when:
- text is selected with B2 or B3 (i.e. the user is trying to execute or ``goto''
some text)
- text has been modified
- the window is destroyed
When a program is being sent B2 or B3 events, Wily doesn't act on them,
merely sends them on. The program may opt to ``send back'' some events which
Wily will then act on. Events which modify text, on the
other hand, are always handled by Wily, which then may inform the
remote program what has happened. In other words, the remote program
cannot stop the user modifying any piece of text, although it can repair
the text later if it wishes.
Wilymodule.c
This is a very simple interface between Python
and the Wily message protocol. It establishes a connection,
provides remote procedure calls and queues events until they are requested.
A Connection is initialized with no arguments, and
represents the connection to Wily. All the other functions are methods of
a connection object.
The Connection has methods to return a list of windows
representing all the windows currently open in Wily, to create a new
window, and to return the next event from Wily.
Windows are represented as integers, which correspond to window
identifiers with Wily, and events are represented as tuples.
The Connection has a number of methods which provide
operations on Wily windows. These operations allow a program, once it
has an identifier for a window, to change its event mask, its name or
its ``tools'' (useful text in the window's tag), read or modify some of
its text, or simulate a B2 or B3 action.
Wilywin.py
This is a small Python module which provides a friendlier
interface to Wily's functionality.
Example Program Fragment
# Create a window called "hello",and fill it with
# the text "Hello, world"
import wily
con = wily.Connection()
win = con.win("hello")
con.replace(win, 0,0, "Hello, world\n")
These are small tools written as proof of concept, to test and refine
the message interface, and as templates for other applications.
News reader
This uses Python classes for threading, talking NNTP and reading and
writing .newsrc files, and Wily for displaying newsgroups and
articles. The program acts on B3 actions on article numbers, and B2
actions on some special function names (e.g. Catch-up, Follow-up) which
it also places in the correct tags.
Session save and restore
There are two programs to save and restore the ``state'' of an editing
session. The ``save'' program determines from Wily what windows are
open, what the current selection is for each, and the full text of
windows which don't represent a file or directory. The ``restore''
program connects to Wily and uses the saved information to create and
massage windows to hopefully return the session to the original state.
Terminal
There are some useful programs which require the traditional ``prompt
and read a line of input'' interface. Examples include gdb,
/bin/sh or /bin/mail. To use these programs, but from
within the Wily editing environment, a simple terminal program was
written, in C. It is called win.
Win provides standard input and output for its client program,
and creates and monitors a Wily window, maintaining an input
point. When win sees a carriage return entered after the input
point, it sends the text between the input point and the carriage return
to the client program. Output coming back from the client program is
inserted just before the input point.
Win does not attempt to provide a pseudo tty or work with any
programs which attempt to use curses-style screen addressing. However,
it works fine for programs such as those mentioned above, and was written with
only 230 lines of commented C.
Wily's approach to extending the editor is to communicate
with other processes using a socket or pipe. Here we examine
some alternative strategies, and why Wily doesn't use them.
Build an interpreter into the editor
This is by far the most common design for an extensible editor.
There are a few advantages to this approach.
Letting the extension language share the address space of the editor
is more efficient than using IPC. The language can also be tailored
to provide a close match to the editing requirements.
There are two reasons why this approach was rejected for Wily.
The first reason is that it restricts users to a single language,
and it often means designing a new (possibly half-baked) language.
The second reason is that embedding a language interpreter in the editing
environment seemed an unnecessary step towards monolithism
and code bloat.
For comparison, below are the sizes of three stripped, dynamically
linked executables on the author's sun4d Solaris system:
| 167264 | wily
|
| 234272 | vi
|
| 1873336 | xemacs
|
Link code dynamically
Another approach is to dynamically link extension code with the editor.
This is more general and more
efficient than the built in interpreter design.
CodeWright®
from Premia uses this approach in the Microsoft Windows environment.
One problem with this
approach is that dynamic linking is not standard on all UNIXes. Another
is that one errant code fragment dynamically linked
in might damage the integrity of the editor. The result might be lost
data, or even worse, data quietly modified in some subtle manner.
When this approach becomes ubiquitously available and more secure, it
will be re-examined.
ILU or CORBA
It would seem that
ILU
and
CORBA
both provide a ready-made solution to turn an editor into
a distributed object server. However, both seemed too
heavy-weight for this simple task.
There is a strong belief amongst Wily's users and developers that ``creeping
featurism'' is evil. Most of the ongoing work will be towards refining
existing features, and improving the clarity and correctness of the
code. Retaining the ``look and feel'' of Acme is also an important
consideration.
There is still room for innovation, though. The message interface
is still very young, and may change with the demands of application
writers. The author hopes that the Python community will be able to
make good use of an editor programmable in Python. Although there is no
need for cursor keys to navigate around Wily, they may be added
later, although they are a low priority.
Networking and security
Currently programs connect to Wily by writing to a UNIX named pipe.
Wily's security relies on this pipe being writable only by its owner.
This means Wily can't accept connections directly from remote machines,
which would be desirable for some applications. A design which avoids
this limitation securely and efficiently has not been decided upon.
Wily is freely available.
The prime source for information about Wily is the WWW page at
http://www.cs.su.oz.au/~gary/wily/
The wily
distribution contains wilymodule.c, and can be obtained at
ftp://ftp.cs.su.oz.au/gary/wily.tgz
The early design and source of Wily owe a lot to Bill Trost.
Wily and this paper have also been
improved by patches, suggestions and bug reports from
Assar,
Davor Cubranic,
Kyle Dean,
Stephen Gallimore,
Mark H. Wilkinson,
Bjorn Helgaas,
Steve Kilbane,
Beirne Konarski,
Bob Krzaczek,
Alberto Nava,
Arnold Robbins,
Rich Salz,
Scott Schwartz,
Chris Siebenmann,
and Richard Wolff.
Wily builds on the Sam distribution by Rob Pike and Howard
Trickey, and originally used libtext by James Farrow. James
Farrow also makes available a set of Unicode fonts for X at
ftp.cs.su.oz.au/matty/unicode/
con = wily.Con()
Connection
Connection objects have no attributes and suport the following methods:
- list()
- Returns a list of names and Win objects
representing the windows currently open.
- win(name)
- Return a new window called name
- event()
- Return the next Event. Note that this method
will block until an event is available.
- eventwouldblock()
- Indicates whether calling
Connection.event() would block.
- returnevent(event)
- Send event back to Wily, probably
because we have no use for it.
The following methods of a connection object act on a window.
- attach(id,mask)
- Request events for this window.
- detach(id)
- Cancel request for events for this window.
- setname(id,string)
- Set the name of this window.
- settools(id,string)
- Set the toolbar for this window.
- read(id,from,to)
- Read some range from this window, returns a UTF8 string.
- replace(id,from,to, string)
- Replace some range of window with some other text.
- run(id, command)
- Makes wily act as if command
had been selected with B2 in this window. This can be used to access
Wily's built in functions. For example, to delete w, call
con.run(w_id, "Del")
- goto(id,address)
- Makes wily act as if address had
been selected with B3 in this window. Returns a tuple identifying the
window and position which are the result of the search.
Events
Events are returned as tuples. Every event has at least two elements,
which are a window identifer, and an event type identifier (which is one of
wily.GOTO, wily.EXEC, wily.REPLACE
or wily.DEL). All of these event types except DEL
also have a from, to and string attribute.
e always handled by Wily, which then may inform the
remote program what has happened. In other words, the remote program
cannot stop the user modifying any piece of text, although it can repair
the twily-0.13.42/Doc/old/auug.tex 0000644 0236657 0000012 00000030320 10333201523 0015440 0 ustar 00oz staff 0000433 0000002 \documentclass[twocolumn]{article}
\usepackage{times,a4wide,epsfig}
\title{The Wily User Interface (Acme for Unix)}
\author{Gary Capell\\
Basser Department of Computer Science,\\
University of Sydney, 2006\\
Australia\\
gary@cs.su.oz.au}
%\keywords{text editor, window manager, user interface}
\begin{document}
\maketitle
\begin{abstract}
The Wile E. Interface (wily) provides much of the feel of
Acme [Pike95] in the Unix/X environment.
This paper gives a brief overview of wily's interface, explains
the implementation, and includes a brief note on window management.
\end{abstract}
\section{History}
Wily is a reimplementation of Acme \cite{acme}
for the Unix/X environment. Acme itself was
heavily inspired by the Oberon \cite{oberon} user
interface. A port was not possible because the
Acme implentation relies on Alef \cite{alef}(a
concurrent programming language not widely
available) and non-portable features of Plan 9
\cite{9BLabs}.
The name "wily" derives from Wile E. Coyote, an avid user of
Acme products.
\section{The Interface}
This is a sketch of the interface, for details
refer to \cite{acme} or \cite{wilyu}.
\subsection{Why Wily?}
Wily attempts to take maximum advantage of a
bitmapped display and three-button mouse, and to
require a minimum of effort from its users to
achieve common tasks. Common editing operations
that with other editors require incantations of
control keys or selecting from lists of menu
items can be done with with very little effort
using the mouse. There have been no user studies,
but subjectively, wily seems to substantially
streamline the editing and debugging process.
The interface integrates some of the functions of editor,
window manager, file browser and shell, as well as providing
an interface for external programs such as mail and news
readers and debuggers.
The interface is not obvious or familiar, but is composed of
a few principles consistently applied, and does not take long to
learn. Once learnt, the interface is sufficiently addictive that
the author re-implemented Acme to work under Unix, rather
than coping with other editors.
\subsection{Appearance}
\begin{figure}
\epsfig{file=pane2.ps,width=8cm}
\caption{Wily windows}{}
\end{figure}
Wily appears as one or more vertical columns,
divided into windows of scrolling text. Each column or window is
headed by a thin horizontal tag which includes the
name of the file or directory the window represents, some
commands, and a marker indicating if the file contains
changes not yet written to disk. The text in a window may represent
a directory, a file, an interface to some external program such as
a news reader, or the output from some command.
\subsection{Mouse Actions}
\emph{Any} text on the screen can be selected by dragging
with a mouse button. The actions of the different buttons are:
\begin{description}
\item[Button 1] highlights the text for later actions
\item[Button 2] executes the text as a command, e.g. selecting
the word 'make' will run the make command as if it were typed
to the shell. There is a small set of built-in functions that
are searched for first.
\item[Button 3] attempts to \emph{open} the selected text.
What this means depends on the text selected.
If the text is the name of a file or a search pattern for
a part of some file, the file is opened if necessary, and
the pattern is searched for. Otherwise, the text is treated
as a string to be searched for in the current window.
\end{description}
Panes and columns can be moved and reshaped by clicking
or dragging in the \emph{buttons} to the left of their tags.
There are no menus, and five special keys
(page up, page down, kill word, kill line, select
recently typed text). All functions
are accessed through mouse actions on text.
\subsection{Context}
Commands and file names are interpreted with respect to
the directory of the window
in which they originate, so for example selecting \texttt{foo.h}
with button 3 in file \texttt{/src/wily/bar.c} will open the file
\texttt{/src/wily/foo.h}. Similarly selecting
\texttt{make} in the tag of \texttt{/src/wily/bar.c}
will run \texttt{make} in \texttt{/src/wily/},
with any output
sent to a window labelled \texttt{/src/wily/+Errors} (which
will be created if necessary).
\subsection{Short Cuts}
Double-clicking with button 1 selects either a word, a line or a
piece of text delimited by parentheses, quotes or brackets.
If buttons 2 or 3 make a selection of
zero length (i.e. a click) the selection is expanded to a whole word or
a file name with optional address (respectively).
Mouse \emph{chords} are used for cutting and pasting. To move
some text from one place to another, it first is selected by dragging with button 1.
While holding button 1 down, if button 2 is pressed, the text is \emph{cut}.
The text can later be pasted into place by holding button 1 and then clicking
button 3. This action is easier done than said, and is much quicker than searching
for a menu entry.
A mouse chord is also used as a short-hand for the idiom of executing a command
with some argument. While clicking with button 2 in the command, if button 1
is then pressed, the text most recently selected with button 1 is given
as an argument to the command. For example, one could click with button 1
in a program variable, chord buttons 2 and 1 on the name of a script to grep
through source files, and get a list of all occurrences of that variable.
Clicking with button 3 on any of the occurrences on that list will open the relevant
file at the correct line.
The mouse cursor is often warped to where the program predicts the next
action is likely to take place. For example, after opening a file at a particular
address, the cursor is warped to that position of that file.
The escape key selects any text typed since the last cursor movement, making
it easier to select with the mouse.
\subsection{Miscellanea}
Wily by default displays text proportionally spaced, which is much more pleasant
to read than constant width text. A builtin function lets the font be
switched temporarily to constant
width when necessary.
Wily provides a full Undo/Redo history for each window.
Newly created windows are placed by the program, not the user.
While it is possible for the user to reposition or resize the window after
it is created, window-positioning heuristics generally make
such positioning unnecessary.
\subsection{A Short Example}
Gary has been using wily to develop a program called wily.
He clicks button 2 in the word \texttt{make} which he's left in the
tag of the window for his source directory. A new window
pops up labelled \texttt{/src/wily/+Errors}, containing
amongst other things the line \texttt{builtins.c:78: parse error before `)'}.
He clicks button 3 anywhere in \texttt{builtins.c:78:}. A new window
labelled \texttt{/src/wily/builtins.c} appears, with line 78 highlighted,
and the cursor warps to this line.
Gary sees that the last \texttt{)} on that line is unnecessary. He
selects it with button 1, and while holding button 1 down, clicks button
2 to cut out the offending parenthesis. The button of the window
changes, to indicate that the window represents a file which is "dirty".
Gary clicks button 2 in the word "Put" in the window's tag, to write
the file to disk. He selects \texttt{make} in the tag of the window
of the directory, and the cycle begins again.
This whole interaction required six mouse clicks and much less
time than the time to read about it.
\section{The Implementation}
Wily is a single-threaded event-driven server process. The events it
waits for are keyboard and mouse actions, and output arriving
on pipes shared with child processes. Text display is handled
by text widgets.
\subsection{Child Processes}
To execute a command that isn't built in, the wily server forks a child, modifies
the child's execution environment, and the child \texttt{exec}s the required command.
The current directory is set to that which
the command was invoked from. The child's file descriptors are set so that
\texttt{stdin} is redirected from \texttt{/dev/null},
\texttt{stdout} and \texttt{stderr} are redirected to a file
descriptor the server listens to for output, and file descriptor 3 is a socket open
to pass messages between the server and child.
The child also inherits some environment variables which are helpful for writing
scripts: \texttt{WILYLABEL} is the context the command was invoked from,
and \texttt{WILYARGLABEL} is the context of the argument to the command,
if any.
The parent adds the file descriptors passed to the child to a list of
file descriptors that it monitors for output, and remembers which directory
that stream is associated with, so that output will appear in an appropriate window.
More sophisticated client processes can communicate
with the server through a message
protocol. The message protocol is still being designed, but basically
when the user interacts with a wily window, wily sends messages to
the client program to let it know what the user has done. For example
a news reading client might display an overview of a news group, and
wait for a message from wily to indicate that the user has clicked
with button 3 to indicate that they want to "open" a particular news item.
Wrappers for the shell and Python\cite{python}
have been written to make writing programs
using wily as their interface even easier. For example, here is a simple mail interface
written in \texttt{rc}:
\begin{verbatim}
#!/bin/rc
id= `{wnew} # create a new window
wcmd $id Label $home/Mail/inbox
wcmd $id Tag inc scan rmm repl
wout $id scan # display scan's output
\end{verbatim}
On the author's system,
Wily's binary (not including X shared libraries) is one-fourteenth the size
of Xemacs'. The source code for wily (not including libtext, libframe, libXg) takes
3045 lines (measured by \texttt{wc -l *.[ch]}).
\section{Window Management}
One of the reasons wily was written was to experiment with alternatives for window
management. Acme's tiling windows are occasionally quite annoying. An earlier implementation
of wily used one window (and one process) per pane, which communicated using two
X cut buffers and named pipes. Window management was then passed on to
the X window manager. This had the benefits of providing
overlapping windows, multiple work spaces (using the virtual root window), and the
option of iconifying windows.
Unfortunately, this arrangement turned out to be much more annoying than
the tiling window management of Acme, when used with the large numbers of
windows that come into play when, for example, developing software using wily.
Sadder but wiser, a tiling window manager was added to wily.
\section{Strengths, Weaknesses and Further Work}
The things the author misses most when using another editor are:
mouse chording for cut and paste (alternatives seem very awkward),
opening a file to a particular line with a single mouse click, and editing
in a proportional font.
Some of wily's strengths may also be seen as weaknesses: heavy exploitation
of bitmapped terminal and three button mouse mean wily is unusable on glass
and paper ttys. The terse mouse command language is opaque and even intimidating
for new users. Occasionally it seems that arrow keys would be helpful.
Wily doesn't yet provide all the features of Acme. Notably missing
are sophisticated window arrangement and regular expression searching.
These features are towards the top of the wily To Do list, along with
minimizing portability problems, simplifying the code, and firming up the messaging
interface.
Built-in functions may soon be provided to allow selected text to
be piped through, to be replaced by the output of, or to be used as the input for
some executed command.
The display of text may also be experimented with. One possibility is
to provide an \emph{outline} mode where subtrees of a hierarchy may be
hidden.
\section{Availability}
Wily is available for anonymous FTP from \texttt{ftp.cs.su.oz.au} in directory
\texttt{gary/wily}. The author welcomes comments, suggestions and
fixes to portability problems.
\section{Acknowledgements}
Many suggestions on wily and this paper, and much of the code were received
from Bill Trost \texttt{trost@cloud.rain.com}. Libraries
used include libXg and libframe, part of the Sam distribution by Rob Pike and
Howard Trickey, and libtext by James Farrow.
\bibliography{wily}
\bibliographystyle{plain}
\end{document}
wily-0.13.42/Doc/old/python.sgml 0000644 0236657 0000012 00000007422 10333201523 0016171 0 ustar 00oz staff 0000433 0000002
Wily/Python Interface
<author>
<htmlurl url="http://www.cs.su.oz.au/~gary/" name="Gary Capell">
<date>v0.11.0 April 1996
<abstract>
This document describes the Python interface to <htmlurl
url="http://www.cs.su.oz.au/~gary/wily/" name="Wily">, which
is implemented in <tt/wilymodule.c/. It defines three classes:
<tt/Connection/, <tt/Win/ and <tt/Event/. A <tt/Connection/ is
initialized with no arguments, and represents the connection to Wily.
A <tt/Win/ object is created by the <tt/Connection/, and is usually
initialized with the name for a new window. The <tt/Connection/ has
methods to return a list of windows representing all the windows
currently open at Wily, to create a new window, and to return the next
<tt/Event/ from Wily. A <tt/Win/ has methods to change its event mask,
name or ``tools'' (useful text in the window's tag), read or modify
some of its text, or simulate a B2 or B3. <tt/Event/ objects have
attributes to identify the window to which they refer, the event type,
and other optional attributes depending on the event type. B2 and B3
events include the text selected, and where it was located in the text.
Text modifying events indicate where the change took place, and what
new text was added. See also the <htmlurl url="msg.html" name="Wily
Messaging Interface"> for C programs, the <htmlurl url="user.html"
name="Wily User's Guide"> and <htmlurl url="pythonpaper.ps"
name="Wily+Python>Emacs+Lisp"> This document is also available in
<htmlurl url="python.ps" name="Postscript">.
</abstract>
<toc>
<sect>Connection<P>
<sect1>Creating<P>
<verb>
import wily
con = wily.connection()
</verb>
<sect1>Attributes
None
<sect1>Methods<P>
<descrip>
<tag/win(name)/
Returns a new window, with the given <tt/name/
<tag/list()/
Returns a list of <tt/win/s representing the windows currently open in
wily.
<tag/event()/
Returns the next Event. Note that this function will block until it receives
an event.
<tag/event_wouldblock()/
Indicates whether <tt/event()/ would block.
</descrip>
<sect>win<P>
<sect1>Creating<P>
<tt/win/ objects are returned by <tt/connection.win(name)/ or
as part of <tt/connection.list()/
<sect1>Attributes<P>
<descrip>
<tag/id/
window id
<tag/name/
name
<tag/dot/
a (from,to) tuple representing the currently selected portion of the
window.
</descrip>
<sect1>Methods<P>
<descrip>
<tag/attach()/
Request events for this window.
<tag/detach()/
Cancel request for events for this window.
<tag/setname(s)/
Set the name of this window.
<tag/settools(s)/
Set the toolbar for this window.
<tag/read((from,to))/
Read some range from this window.
<P>Called with a tuple representing the range to read, returns a UTF
string.
<tag/replace((from,to),s)/
Replace some range of window with some other text.
<P>Called with a tuple representing the range to replace, and a string
to replace it with. Insertion and deletion are special cases of
<tt/replace/, with null range or replacement string respectively.
<tag/run(s)/
Execute some text in this window. Makes wily act as if <tt/s/ had
been selected with button 2 in this window. This can be used to
access Wily's built-in functions. For example, to delete <tt/w/, call
<tt/w.run("Del")/
<tag/goto(s)/
"Goto" some text in this window. Makes wily act as if <tt/s/ had been
selected with button 3 in this window. This can be used to open a new
window, or search for some regular expression. Returns a <tt/win/ if the
Goto resulted in a successful search in this window.
</descrip>
<sect>Event
<sect1>Attributes
<P><descrip>
<tag/id/
of the window the event occurred in
<tag/t/
Message type: one of <tt/wily.GOTO/, <tt/wily.EXEC/ or <tt/wily.REPLACE/.
<tag/r/
(from,to) tuple
<tag/s/
string
</descrip>
<sect1>Methods
<P><descrip>
<tag/returnevent/
Send this event back to Wily to interpret
</descrip>
</article>
of <tt/win/s representing the windows currently open in
wily.
<tag/event()/
Returns the next Event. Note that this function will block until it receives
an event.
<tag/event_wouldblock()/
Indicates whether <tt/event()/ would block.
</deswily-0.13.42/Doc/old/wily.bib 0000644 0236657 0000012 00000013264 10333201523 0015427 0 ustar 00oz staff 0000433 0000002 @INPROCEEDINGS{hello,
author = "Rob Pike and Ken Thompson",
title = "{Hello World}",
editor = "",
booktitle = "Proc. of the Winter 1993 USENIX Conf." ,
number = "",
series = "",
pages = "43-50",
month = "",
year = 1993,
address = "San Diego",
organization = "",
publisher = "",
note = "",
}
@INPROCEEDINGS{8.5,
author = "Rob Pike",
title = "{8$1/2$, the Plan 9 Window System}",
editor = "",
booktitle = "Summer 1991 USENIX" ,
number = "",
series = "",
pages = "257-265 ",
month = "June",
year = 1991,
address = "Nashville",
organization = "",
publisher = "",
note = "",
}
@INPROCEEDINGS{9BLabs,
author = "Rob Pike and Dave Presotto and Ken Thompson and
Howard Trickey",
title = "{Plan 9 from Bell Labs}",
editor = "",
booktitle = "Summer 1990 UKUUG Conference" ,
number = "",
series = "",
pages = "1-9",
month = "July",
year = 1990,
address = "London",
organization = "",
publisher = "",
note = "",
}
@INPROCEEDINGS{9Dsys,
author = "Dave Presotto and Rob Pike and Ken Thompson and
Howard Trickey",
title = "{Plan 9, A Distributed System}",
editor = "",
booktitle = "Spring 1991 EurOpen Conference" ,
number = 17,
series = "",
pages = "43-50",
month = "May",
year = 1991,
address = "Troms",
organization = "",
publisher = "",
note = "",
}
@INPROCEEDINGS{9Mstream,
author = "Dave Presotto",
title = "{Multiprocessor Streams for Plan 9}",
editor = "",
booktitle = "Summer 1990 UKUUG Conference",
number = "",
series = "",
pages = "11-19",
month = "July",
year = 1990,
address = "London",
organization = "",
publisher = "",
note = "",
}
@INPROCEEDINGS{9Sleep,
author = "Dave Presotto and Rob Pike and Ken Thompson and
Gerard Holzmann",
title = "{Process Sleep and Wakeup on a Shared-Memory Multiprocessor}",
editor = "",
booktitle = "Spring 1991 EurOpen Conference" ,
number = "",
series = "",
pages = "161-166",
month = "May",
year = 1991,
address = "Troms",
organization = "",
publisher = "",
note = "",
}
@INPROCEEDINGS{9net,
author = "Dave Presotto and Phil Winterbottom",
title = "{The Organization of Networks in Plan 9}",
editor = "",
booktitle = "USENIX Winter '93" ,
number = "",
series = "",
pages = "271-287",
month = "",
year = 1993,
address = "San Diego, CA",
organization = "",
publisher = "",
note = "",
}
@INPROCEEDINGS{acid,
author = "Phil Winterbottom",
title = "{ACID: A Debugger Built From A Language}",
editor = "",
booktitle = "USENIX " ,
number = "",
series = "",
pages = "",
month = "January ",
year = 1994,
address = "San Francisco, California",
organization = "",
publisher = "",
note = "",
}
@INPROCEEDINGS{alef,
author = "Phil Winterbottom: ",
title = "{Alef language Reference Manual}",
editor = "",
booktitle = "Plan 9 Programmer's Manual, Volume Two, 2nd Ed." ,
number = "",
series = "",
pages = "",
month = "",
year = 1995,
address = "",
organization = "AT \& T Bell Labs",
publisher = "Harcourt Brace and Company",
note = "",
}
@INPROCEEDINGS{acme,
author = "Rob Pike ",
title = "{Acme: A User Interface for Programmers (\texttt{http://plan9.att.com/plan9/doc/acme.html}}",
editor = "",
booktitle = "USENIX" ,
number = "",
series = "",
pages = "",
month = "January",
year = 1994,
address = "San Franciso, California",
organization = "",
publisher = "",
note = "",
}
@INPROCEEDINGS{help,
author = "Rob Pike ",
title = "{A minimalist Global User Interface}",
editor = "",
booktitle = "Graphics Interface '92" ,
number = "",
series = "",
pages = "282-293",
month = "January",
year = 1992,
address = "Vancouver",
organization = "",
publisher = "",
note = "",
}
@Article{oberon,
author = "N. Wirth and J. Gutknecht",
title = "{The Oberon System}",
editor = "",
journal = "Software - Practice and Experience" ,
number = "9",
volume="19",
pages = "857-894",
month = "Sep",
year = 1989,
address = "",
organization = "",
publisher = "",
note = "",
}
@INPROCEEDINGS{rc,
author = "Tom Duff",
title = "{Rc - A Shell for Plan 9 and UNIX Systems}",
editor = "",
booktitle = "Summer 1990 UKUUG Conference",
number = "",
series = "",
pages = "21-33",
month = "July",
year = 1990,
address = "London ",
organization = "",
publisher = "",
note = "",
}
@Article{worm,
author = "Sean Quinlan",
title = "{A Cached WORM File System}",
OPTcrossref = "",
OPTkey = "",
journal = "Software-Practice and Experience",
year = "1991",
volume = "21",
number = "12",
pages = "1289-1299",
month = "December",
OPTnote = "",
OPTannote = ""
}
@Misc{wilyu,
author = "Gary Capell",
title = "{Wily User Manual}",
OPTcrossref = "",
OPTkey = "",
journal = "",
year = "1995",
volume = "",
number = "",
pages = "",
month = "",
OPTnote = "",
OPTannote = ""
}
@TechReport{python,
author = "Guido van Rossum",
title = "{Python Tutorial}",
institution = "CWI",
year = "1995",
number = "CS-R9526",
address = "",
}
@TechReport{ilu,
author = "Xerox Corporation",
title = "{ILU homepage \texttt{ftp://ftp.parc.xerox.com/pub/ilu/ilu.html}}",
institution = "Xerox",
year = "1996",
number = "",
address = "",
}
@TechReport{corba,
author = "Object Management Group",
title = "{What is CORBA? \texttt{http://ruby.omg.org/corba.html}}",
institution = "OMG",
year = "1996",
number = "",
address = "",
}
wily-0.13.42/Doc/old/wily.1 0000644 0236657 0000012 00000030566 10333201523 0015037 0 ustar 00oz staff 0000433 0000002 .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
ayout 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 thatwily-0.13.42/Doc/old/user.sgml 0000644 0236657 0000012 00000043052 10333201523 0015625 0 ustar 00oz staff 0000433 0000002 <!doctype linuxdoc system>
<article>
<title>Wily User Manual
<author><htmlurl url="http://www.cs.su.oz.au/~gary/"
name="Gary Capell">
<date>v0.12.7 June 1996
<abstract>
Use the <em/left/ mouse button to <em/select/ text,
use the <em/middle/ mouse button to <em/execute/ text, and
use the <em/right/ mouse button to <em/goto/ text.
Use a left/middle mouse button combination to <em/cut/ text,
use a left/right mouse button combination to <em/paste/ text, and
use a middle/left mouse button combination to <em/execute/ text with an <em/argument/.
The <em/resize box/ indicates if a file is dirty, and can be
clicked or dragged with various mouse buttons to resize and reposition
windows.
<htmlurl url="user.ps" name="A Postscript version of this file is available">
</abstract>
<toc>
<sect>Invocation, Environment variables
<P><tt/wily [-d] [-v] [-f font] [-F fixedfont] [-t tabsize][file name...]/
<descrip>
<tag/-d/
Enable debugging output
<tag/-v/
Print version number and exit
<tag/-f font/
(or X resource <tt/p9font/) set the default
proportional font.
<tag/-F font/
(or X resource <tt/p9fixed/) set the monospace font.
<tag/-t tabsize/
set the maximum width of tabs (as multiple of the
width of the character '0') for the proportional font.
Defaults to 4.
<tag/-T tabsize/
set the maximum width of tabs (as multiple of the
width of the character '0') for the monospace font.
Defaults to 8.
<tag/file name.../
Start wily with the named files and directories
open.
</descrip>
<sect1>Environment variables<P>
<descrip>
<tag/SHELL/
External commands are sent to the shell for evaluation.
<tag/HISTORY/
If set, commands are written to this file before execution.
<tag/WILYBAK/
Wily uses <tt/$WILYBAK/ or <tt>$HOME/.wilybak</tt>
as the directory for backups.
<tag/WILYFIFO, DISPLAY, TMPDIR/
Wily communicates with some other programs using a fifo at
a well-known location.
<P>The name of the fifo will be <tt/$WILYFIFO/
if this variable is set, otherwise it will be
<tt>/tmp/wilyUSER$DISPLAY</tt>, where USER
is calculated from the password file. If <tt/$TMPDIR/
is defined, it is used instead of <tt>/tmp</tt>.
<P>Wily also sets <tt/$WILYFIFO/ so any children
it creates will know how to talk to it.
</descrip>
<sect>Appearance<P>
foo
<sect1>Scrollbars and scrolling<P>
Scrollbars are proportional, i.e. the size and position of the
scrollbar's "thumb" indicates the size and position of the visible
portion of the text.
Each of the three mouse buttons does something different when
clicked in the scrollbar.
The <em/right/ mouse button moves the text next to the mouse pointer
<em/up/ to the top of the window.
The <em/left/ mouse button moves the text at the
top of the window <em/down/ so it is next to the pointer.
Both of these rules
have the effect that clicking near the top of the scrollbar causes small
movements, and clicking near the bottom causes large movements.
The <em/middle/ button moves the visible part of the text to a point in the
text proportional to how far down the scrollbar the pointer is.
That is, clicking at the bottom of the scrollbar with button 2 jumps
to the end of the text, clicking at the top of the scrollbar with button 2
jumps to the beginning of the text.
All of these movements repeat if the mouse button is held down
in the scroll bar.
The <em/PageUp/ and <em/PageDown/ keys scroll up or down
by about half a page. The <em/Home/ and <em/End/ keys
scroll to the top or bottom of the file.
<sect1>Context<P>
All text in wily has a <em/context/, which is just the
name of a directory associated
with that text.
For text in a window, the context is the name of the window, up to
and including the last <TT>/</TT>. So if three windows
have the names
<TT>/usr/gary/+Errors</TT>, <TT>/usr/gary/guide</TT>
and <TT>/usr/gary/</TT>, they will all have the same context:
<TT>/usr/gary/</TT>. Note that the context need not be a directory
which actually exists.
For column tags and the top-level tag, the context is the
name of the directory where wily was started.
When text is <EM/executed/, wily uses the context of the text
as the directory in which to run the program.
Output from the
command will appear in the window <tt>{context}/+Errors</tt>.
When trying to <em/Goto/ some text, the text will be interpreted
relative to its context. For example, the text <tt>foo.c:14</tt> in
a window with context <tt>/usr/gary/src/fish/</tt> will be
interpreted to mean the address <tt>/usr/gary/src/fish/foo.c:14</tt>
<sect>Mouse actions<P>
<sect1>Double-click<P>
Double-clicking with the left mouse button can select a word, a line,
or the text delimited by quotation marks, braces, brackets or parentheses.
<sect1>Selection expansion<P>
A null selection (single click) with the middle or right mouse
button will be expanded to some of the surrounding
text.
A click inside an existing selection will be expanded to that selection.
This means you can select (with the left button)
some complicated command once,
and click the middle button inside
this selection many times to execute the command repeatedly.
This rule is also helpful when searching through multiple occurrences
of a piece of text, as clicking with the right button in the most recently found
instance searches for the next instance.
A click that is not inside an existing selection will be expanded depending
on which mouse button was used.
Clicks with the middle button
are expanded to select commands, i.e. strings of alphanumeric characters,
|, > or <.
Clicks with the right button
are expanded to select addresses, i.e. strings of alphanumeric characters,
:, ",".
<sect1>Combinations of Mouse Buttons (mouse chords)<P>
Pressing more than one mouse button at a time is called a mouse chord,
and can be used for some special short cuts.
<sect1>Cut,Paste mouse chords<P>
To cut some text into the clipboard, select the text with the left
button, and <em>while holding it down</em>, click the middle button.
The selected text will be cut from the window and copied to the
clipboard.
Similarly, select some text with the left mouse button, and while
holding it down also click the right button, and the selected text will
be replaced by the contents of the clipboard. The clipboard will be
unaltered.
Note that so long as you hold the left button down, you can alternately
cut and paste the selected text by pressing the middle and right
buttons. A cut immediately followed by a paste in this way leaves the
file unmodified.
<sect1>Execute with argument<P>
A command can be called with an argument using another mouse chord.
Sweep the command with the middle button, and while holding it down,
click the left button. The command is invoked with the text most
recently selected with the left button as argument. For example, one
might select <tt>main.c</tt> with the left button, then chord the
middle and left buttons on the word <tt>wc</tt> to run <tt>wc
main.c</tt>.
When an argument is selected in this manner, the context of the
argument becomes the context of the command. One idiom is to select
some text in one window, and <tt>Look</tt> for it in another window
using this chord.
<sect>Execute<P>
If text is selected with the middle mouse button, it is executed.
If you press the middle button in some text, then decide you
<em/don't/ want to execute it, press the right mouse button
to abort.
If the text is the name of one of the builtin functions, that function
will be executed.
If the text begins with |, > or <, the most recent selection will
be piped through the command, piped to the command, or replaced by the
output of the command, respectively.
The command is executed by
<tt>$SHELL -c command [argument]</tt>.
If <tt>$SHELL</tt> is not defined, <tt>/bin/sh</tt> is used.
Standard output from the command will appear in a window in wily.
Standard input for the command will be from <tt>/dev/null</tt>.
The main wily tag indicates which programs are currently
running.
Wily tends to be more useful if <TT>.</TT> is in <tt>$PATH</tt>
<sect1>Builtin Functions<P>
These commands are looked for first. Some of them operate differently
if called with an argument (using the Middle/Left mouse chord).
<descrip>
<tag>Put,Get,Putall</tag>
Put and Get write the window to disk, or fetch from disk, respectively.
If called with an argument, they will use the argument this as the
filename, instead of the name of the window.
Putall writes all dirty files to disk.
<tag>New, Del</tag>
Create a new window, or delete a window, respectively. If New
is called with an argument, it will use the argument as the name
of a file to create.
<tag>Look</tag>
Searches in the window containing Look for literal text: either the argument,
if it is given one, or the current selection in the window containing Look
<tag>Undo, Redo</tag>
Undo or redo an action. With an argument, undo(redo) until the window
reflects the state of the file on disk.
<tag>Newcol, Delcol</tag>
Create or delete a column
<tag>Cut, Paste, Snarf</tag>
Cut the currently selected text to the X selection buffer,
replace the currently selected text with the X selection buffer,
or copy the currently selected text to the X selection buffer, respectively.
The <em/currently selected text/ is defined as the selection in
the most recently selected window. This should be indicated by
that window having a slightly thicker border.
<tag>Quit</tag>
Exit wily. Any dirty files will be backed up.
<tag>Kill</tag>
Kill some process which was started from wily. Kill must be given
as an argument the name of the process to kill. The
topmost tag always contains the list of long-running programs
started from within wily.
To kill one of these, click in the name of the process in the
tag, then do a middle/left mouse chord in 'Kill'.
<tag>Font</tag>
Toggle between fixed and proportional fonts. Depending
on where Font is clicked, changes the font for a window, a column,
or for all the windows on the screen.
<tag>Dotfiles</tag>
Toggles whether or not dot files are displayed in directories. Directories
will not be re-read automatically, though.
<tag>Anchor</tag>
Puts an address in the tag of the most recently selected window. The
address is from the current position to '.'. This can be used to select
large chunks of text. Click at the beginning position, execute Anchor,
click at the end position, then click with the right mouse button in the
address in the tag. The anchor may also be used as a bookmark.
<tag>Split</tag>
Split the most recently selected window into two. Editing actions in
one window will be visible in the other.
</descrip>
<sect>Goto Text<P>
Wily will attempt to <em/goto/ text selected with the right mouse
button. What this means depends on the text selected.
<P>The <em/goto/ operation used with B3 is polymorphic in that it
recognises three different patterns:
<DESCRIP>
<tag/name/
If <TT/name/ is a file or directory, open it, otherwise search
for the literal <TT/name/
<tag/:address/
Search for <TT/address/ in the current window, where
the form of an address is defined below.
<tag/file:address/
Open <TT/file/ and search in it for <TT/address/
</DESCRIP>
<sect1>Addresses<P>
Wily uses the address and regular expression code from
<htmlurl url="http://plan9.bell-labs.com/plan9/doc/sam.html"
name="Sam">.
Please refer to the
<htmlurl url="http://plan9.bell-labs.com/magic/man2html/1/sam"
name="Sam manual">
for a better explanation.
The following description was cut and pasted from the
<htmlurl url="http://plan9.bell-labs.com/magic/man2html/1/sam"
name="Sam manual">
<sect2>Simple Addresses<P>
<descrip >
<tag/#n/
The empty string after character n; #0 is the beginning of the file.
<tag/n/
Line n; 0 is the beginning of the file.
<tag>/regexp/ ?regexp? </tag>
The substring that matches the regular expression, found by
looking toward the end (/) or beginning (?) of the file, and
if necessary continuing the search from the other end to the
starting point of the search. The matched substring may straddle
the starting point. When entering a pattern containing a literal
question mark for a backward search, the question mark should be
specified as a member of a class.
<tag/$/
The null string at the end of the file.
<tag/./
Dot. The current selection in a window.
</descrip>
<sect2>Compound Addresses<P>
In the following, a1 and a2 are addresses.
<descrip >
<tag/ a1+a2 /
The address a2 evaluated starting at the
end of a1.
<tag/a1-a2 /
The address a2 evaluated looking in
the reverse direction starting at the
beginning of a1.
<tag/a1,a2/
The substring from the beginning of a1
to the end of a2. If a1 is missing, 0
is substituted. If a2 is missing, $ is
substituted.
<tag/a1;a2 /
Like a1,a2 but with a2 evaluated at the end
of, and dot set to, a1.
</descrip>
The operators + and - are high precedence, while ,
and ; are low precedence.
In both + and - forms, if a2 is a line or
character address with a missing number, the
number defaults to 1. If a1 is missing, . is
substituted. If both a1 and a2 are present and
distinguishable, + may be elided. a2 may be a
regular expression; if it is delimited by ?'s, the
effect of the + or - is reversed.
It is an error for a compound address to represent
a malformed substring. Some useful idioms: a1+-
%(a1-+) selects the line containing the end
(beginning) of a1. 0/regexp/ locates the first
match of the expression in the file. (The form
0;// sets dot unnecessarily.) ./regexp/// finds
the second following occurrence of the expression,
and .,/regexp/ extends dot.
<sect1>Cursor Warping<P>
After a successful search, the text that was found is highlighted, and
the cursor is warped there, so that to search for the next instance of
the search text, no cursor movement is required, it is only necessary
to click the rightmost mouse button again.
Window re-arranging operations warp the cursor to the resize box of the
window that moved, so the move can be easily refined.
<sect>Miscellaneous<P>
<sect1>Window Reshaping<P>
Wily windows are placed automatically using heuristics. Hopefully most
of the time the window will be placed somewhere useful. However,
windows and columns can be moved and reshaped. The resize box (the
little box on the far left of the tag) of a pane or a column may be
manipulated to move or reshape a window.
Dragging the resize box (with any mouse button) moves the column or
window to the desired location.
Clicking in a pane's button with different mouse buttons has these
different effects:
<descrip >
<tag/Left button/
the window grows a bit, first taking up any blank space
in the column
<tag/Middle button/
Every window except the desired one is shrunk so that only their tags
are visible, leaving more space for the desired window.
<tag/Right button/
The window expands to take up the whole column, obscuring all the other
windows in that column. Clicking with
any mouse button in the window's resize box will undo this effect.
</descrip>
<sect1>Back-up files<P>
Whenever a window is to be deleted which represents a file and which
contains text which hasn't been written to disk, a backup is made.
This is an experimental alternative to the familiar (and
often-annoying) "are you <em/sure/ you want to close this
window?" dialog. A warning message is printed when this happens,
alerting the user, and allowing her to easily recover the modified
file, or compare the old and new files.
This seems not only quicker but safer than forcing a dialog, as
occasionally the user might give the wrong answer to a dialog, whereas
with this system a backup is always there.
Backup files are kept in directory <tt>$WILYBAK</tt> if it
exists, or <tt>$HOME/.wilybak</tt>. In this directory the file
<tt>TOC</tt> is a table of contents showing what real file each backup
file maps to.
<sect1>Remote Control<P>
A programming interface is provided to wily, for writing more complex
programs such as mailers, news readers, terminals, code browsers, etc.
See the <htmlurl url="msg.html" name="Wily Message Interface guide">
for more details.
<sect1>Fonts<P>
(Taken from font(4))
External fonts are described by a plain text file that can be read
using <em/rdfontfile/. The format of the file is a header followed by
any number of subfont range specifications. The header contains two
numbers: the height and the ascent. The height is the inter-line
spacing and the ascent is the distance from the top of the line to the
baseline. These numbers are chosen to display consistently all the
subfonts of the font. A subfont range specification contains two
numbers and a font name. The numbers are the inclusive range of
characters covered by the subfont, and name specifies the name of an X
font suitable for <em/getsubfont/. The minimum number of a covered
range is mapped to the first defined character of the corresponding
subfont. Each field must be followed by some white space. Each
numeric field may be C-format decimal, octal, or hexadecimal.
Here is the start of the font file the author uses for a monospace font:
<tscreen><verb>
17 14
0x0000 0x00FF lucm.latin1.9
0x0100 0x017E lucm.latineur.9
0x0180 0x01F0 matty.latinext.9
0x0250 0x02E9 lucm.ipa.9
0x0300 0x0308 matty.gendiacritics.9
0x0370 0x0372 matty.greekpunc.9
0x0386 0x03F5 lucm.greek.9
0x0400 0x0475 misc.cyrillic.9
</verb></tscreen>
<sect1>Entering non-ASCII characters<P>
Refer to the Plan 9
<htmlurl url="http://plan9.bell-labs.com/magic/man2html/6/keyboard"
name="keyboard(6)"> manual page, which is <em/mostly/ how
it works in wily.
</article>
wily-0.13.42/Doc/old/msg.sgml 0000644 0236657 0000012 00000025065 10333201523 0015441 0 ustar 00oz staff 0000433 0000002 <!doctype linuxdoc system>
<article>
<title>Wily Messaging Interface
<author><htmlurl url="http://www.cs.su.oz.au/~gary/" name="Gary Capell">
<date>v0.11.0 April 1996
<abstract>
This document explains <htmlurl
url="http://www.cs.su.oz.au/~gary/wily/msg.h" name="msg.h">
There are five sections. The first two describe the Msg struct and the
list of message types, with a brief explanation of each.
The last three detail functions to establish a connection to wily; to
pack and unpack messages for sending to the network; and to access a
"cooked" RPC-style interface.
A <htmlurl url="msg.ps" name="Postscript version"> is available.
</abstract>
<toc>
<sect>The Msg Struct<P>
This is the "in-memory" representation of the messages which flow
between Wily and remote programs. The representation of messages
as they flow across the network is deliberately hidden.
<tscreen><verb>
struct Msg {
Mtype t;
Id m; /* message */
Id w; /* window */
Range r;
uchar flag;
char *s;
};
</verb></tscreen>
<P><tt/s/ is a null-terminated UTF string, and must be a complete UTF
sequence.
<P><tt/t/ identifies the type of the message. The possible values of
<tt/t/ are enumerated in the next section.
<P><tt/m/ identifies the message within a sequence of messages.
<P><tt/w/ identifies a particular window.
<P><tt/r/ specifies a contiguous set of runes within a window.
The range <tt/r.p0, r.p1/ means all the characters with offset not
less than <tt/r.p0/, and strictly less than <tt/r.p1/
<P><tt/flag/ is used to modify the meaning of some types of message,
and can be used to hold a true/false value, or a bit mask.
<P>The client sends request messages to Wily. For every request message,
Wily sends back either a reply message (if the request was fulfilled
successfully) or an error message. In either case, the message sent
in response will have the same message id (<tt/m.m/) as the request
message. Each reply message has a <tt/Mtype/ value one greater than
the corresponding request message.
<P>Wily may also send event messages to the client, if the client
has asked for them.
<sect>The Mtype enum
<P>For each of the message types defined, there is a brief description,
and an indication of which fields of the <tt/Msg/ struct are significant
for this type of message.
<P>The names of request messages start with <tt/WM/,
those of response messages with <tt/WR/, and those of events with
<tt/WE/
<sect1>Requests/Responses
<P><descrip>
<tag/WRerror(s)/ Message type returned by wily if there's an
error in decoding or fulfilling some request.
<tt/s/ contains an error
message.
<tag/WMlist/
Asks wily to send a list of windows currently displayed.
<tag/WRlist(s)/
<tt/s/ contains a list of lines terminated by newlines. Each line
contains a name and an id (as a textual number) separated by whitespace.
<tag/WMnew(s,flag), WRnew(w)/
Asks wily to create a window with a given label (which may be an
existing file). The new window will be treated as a normal file,
with backups kept for it, If and only if <tt/flag/ is set.
<P><tt/w/ is set to the id of the newly created window.
<tag/WMattach(w,flag), WRattach/
Set the event mask for <tt/w/ to <tt/flag/. Used to start or stop
the flow of events for a particular window. See the
<em/Events/ section for details on what values the <tt/mask/
can have.
<tag/WMsetname(w,s), WRsetname/
Change <tt/w/'s name to <tt/s/.
<tag/WMsettools(w,s), WRsettools/
Change the tools for this window. Tools are simply words appearing in
the tag of a window, after the window name and before the 'pipe' symbol.
They are (will be) automatically maintained, i.e. they will be replaced
if accidentally deleted.
<tag/WMread(w,r),WRread(s)/
Read the text from <tt/w/ in range <tt/r/.
<P><tt/s/ is the requested text, as a UTF string.
<tag/WMreplace(w,r,s), WRreplace/
Replace the text from <tt/w/ in range <tt/r/ with UTF string <tt/s/
<tag/WMexec(w,s),WRexec/
Act as if <tt/s/ had been clicked with B2 in <tt/w/. Note that this can
be used to access Wily's built in functions.
<tag/WMgoto(w,r,flag,s), WRgoto(w,r)/
Act as if <tt/s/ had been clicked with b3 in <tt/w/ at <tt/r/, possibly
opening a file or directory, or searching for some combination of
line address, character address or regular expression. If and only if
<tt/flag/ is set do we select the range found, and set "dot". In either
case, we return the window and text range to which we would have jumped.
<P>This request will return an error if it tries to search for something
which isn't there.
<P>The response message contains the window and range we went to.
<tag/WMfencepost/
Not used for any message. Receiving a message with
Mtype greater than <tt/WMfencepost/ indicates some horrible error.
</descrip>
<sect1>Events
<P>These are the messages sent by Wily to clients who request
to be notified of events in a particular window using <tt/WMattach/
<P>The event types are used to form a mask to be given as a parameter to
the <tt/WMattach/ request. For example, to request only exec and goto
events, set <tt>m.f = WEexec|WEgoto</tt> before sending message <tt/m/
<descrip>
<tag/WEexec(w,s)/
<tt/s/ was selected with B2 somewhere in <tt/w/
<tag/WEgoto(w,r,s)/
<tt/s/ was selected with B3 at <tt/r/ in <tt/w/
<tag/WEdestroy(w)/
<tt/w/ has been destroyed.
<tag/WEreplace(w,r,s)/
The text at <tt/r/ in <tt/w/ was replaced by <tt/s/ Note that insertion.
and deletion are simply special cases of replacement .
<tag/WEfencepost/
Never actually used. Any message with <tt/Mtype/ greater than
<tt/WEfencepost/ is a request or response. Any message with <tt/Mtype/
less than <tt/WEfencepost/ is an event.
</descrip>
<P>If a client is sent an event which it doesn't want to use,
it can send the event back to wily. Wily will act on the event,
but not send a confirmation back to the client.
<sect>Establishing a Connection
<P>Simply call <tt/client_connect()/, which returns a file descriptor
open for reading and writing to Wily, or a negative number if
there's been some error.
<P>Wily and client programs both use the environment variable
<tt/$WILYFIFO/ to establish communications, and Wily sets
this variable for any children it creates.
<sect>Packing and Unpacking Messages<P>
<descrip>
<tag/int msg_size (Msg *m);/
Returns the size of buffer that will be needed to "flatten" <tt/m/
<tag/void msg_flatten (Msg*m, char*buf);/
"Flatten" <tt/m/ into <tt/buf/, which must have enough storage space
allocated.
<tag/ulong msg_bufsize (char*buf);/
Returns the total size of the flattened message starting at <tt/buf/.
Assumes that at least <tt/HSIZE/ bytes are stored in <tt/buf/.
<P>A useful macro is
<verb>
#define FULLMSG(ptr,n) ( (n) >= HSIZE && (n) >= msg_bufsize(ptr) )
</verb>
<tag/int msg_init (Msg*m, char*buf);/
The reverse of <tt/msg_flatten/. Fills in the fields of 'm'
using the flat representation starting at <tt/buf/
<tt/Msg_init/ assumes that <tt/buf/ holds the complete message.
<tt/m->s/ will point to an area within <tt/buf/, but <tt/buf/
itself is not modified.
<tag/void msg_print (Msg *m);/
Print a human-readable form of <tt/m/ to <tt/stderr/
</descrip>
<sect>RPC-style interface
<P>These functions aren't necessary to interact with Wily.
However, they are convenient, and provide some type-checking
to help make sure you send the right messages.
<sect1>Opening, Closing and Checking the RPC interface
<P><descrip>
<tag>Handle* rpc_init (int fd);</tag>
Create a new RPC handle to use file descriptor <tt/fd/, which was
probably returned from <tt/client_connect/
<tag>Bool rpc_isconnected(Handle*h);</tag>
Indicate whether or not <tt/h/ is still connected.
<P>If the RPC library starts receiving gibberish messages, it will cut
the connection, and will return a "not connected" error message for
every request.
<tag>void rpc_free(Handle*h);</tag>
Release any resources used by <tt/h/, and free <tt/h/ itself.
</descrip>
<sect1>Requests
<P>If there's any sort of failure, all of these functions return
a pointer to an error message, which is stored in a static buffer
and only guaranteed to remain valid until the next <tt/rpc_*/
function is called. After a failure, it's possible that the connection
to wily has been lost. This should be checked using <tt/rpc_isconnected/
<P>If successful, these functions return NULL.
<descrip>
<tag>char* rpc_list (Handle*h, char **bufptr);</tag>
If successful, allocates a string, stores the window list in the string,
and stores a pointer to the string in <tt/bufptr/. Don't forget to
<tt/free(*bufptr)/ when you're finished.
<tag>char* rpc_new (Handle*h, char *s, Id*id);</tag>
Create window with name <tt/s/, setting <tt/id/ if successful.
<tag>char* rpc_attach (Handle*h, Id w, ushort mask);</tag>
Request events associated with <tt/w/ and matching
event <tt/mask/. This will fail if <tt/w/ doesn't
exist, or is already sending its events somewhere else.
<tag>char* rpc_detach (Handle*h, Id w);</tag>
Cancel request for events associated with <tt/w/
<tag>char* rpc_setname (Handle*h, Id w, char *s);</tag>
Set the name of <tt/w/ to <tt/s/
<tag>char* rpc_settools (Handle*h, Id w, char *);</tag>
Set the tools section of <tt/w/ to <tt/s/
<tag>char* rpc_read (Handle*h, Id w, Range r, char*buf);</tag>
Read range <tt/r/ from <tt/w/ into <tt/buf/, which must
have enough space (<tt/UTFmax * RLEN(r)/). Fails if <tt/r/
is not contained in window <tt/w/
<tag>char* rpc_replace (Handle*h, Id w, Range r, char*s);</tag>
Replace range <tt/r/ in <tt/w/ with UTF string <tt/s/
<tag>char* rpc_exec (Handle*h, Id w , char *s);</tag>
Cause Wily to act as though <tt/s/ were selected in <tt/w/ with button
2.
<tag>char* rpc_goto (Handle*h, Id *w , Range *r, char*s, Bool setdot);</tag>
Make Wily act as though <tt/s/ were selected in <tt/w/ with button 3.
<P>Sets <tt/*w/ and <tt/*r/ with the window and range found by the search
operation. Actually jumps to and selects some text if and only if <tt/setdot/
is true. This request will return an error if it tries to search for something
which isn't there.
</descrip>
<sect1>Events<P>
<descrip>
<tag>int rpc_event (Handle*h, Msg *m);</tag>
Block until an event is received by <tt/h/ and fill
in <tt/m/. Returns 0 for success, -1 for failure.
After a successful call to <tt/rpc_event/,
<tt/m->s/ will need to be freed.
<tag>char *rpc_bounce(Handle *h, Msg *m)</tag>
Returns <tt/m/, which must be an event filled
in by <tt/rpc_event/, back to wily, and frees <tt/m->s/.
Useful for events which we receive but we'd rather wily
took the default action on.
<tag>Bool rpc_wouldblock(Handle*h);</tag>
Returns <tt/true/ if <tt/rpc_event/ would block.
Only useful if your program
is reading from other input sources as well. (e.g. see <tt/win.c/)
</descrip>
</article>
equence.
<P><tt/t/ identifies the type of the message. The possible values of
<tt/t/ are enumerated in the next section.
<P><tt/m/ identifies the message within a sequence of messages.
<P><tt/w/ identifies a particular window.
<P><tt/r/ specifies a contiguous set of runes within a window.
The range <tt/r.p0, r.p1/ means all the characters with offset not
less than <tt/r.p0/, and strictly less than <tt/r.p1/
<P><tt/flag/ is used to modify the meaning ofwily-0.13.42/Doc/old/wily.html 0000644 0236657 0000012 00000046445 10333201523 0015646 0 ustar 00oz staff 0000433 0000002 <HTML><HEAD> <TITLE>Wily
Wily
Gary Capell
This document
Appearance, Unicode -
Mouse Actions -
Example -
Extensions -
Implementation -
Availability -
History -
Other documents
Note for Sydney-ites
I'd be keen to demonstrate/explain Wily for interested folks in Sydney
Abstract:
Wily is an emulation for the Unix/X environment of Acme [Pike95] from Plan 9. It combines most of the
features of text editor, window manager, file manager
and general user interface.
It exploits a three-button mouse and bitmapped display
to provide a smooth, simple and powerful
environment for interacting with text of all kinds.
Wily differs from most other editors in a number of areas. Nearly
all operations are through mouse actions on text on the screen: there
are no menus, few "key bindings" and no "function keys". Text is
usually displayed in a proportionally-spaced font, and is interpreted as
UTF8-encoded Unicode. Mouse "chords" (combinations of mouse buttons)
are used extensively. Wily's core functionality is almost totally
unconfigurable. However, it is quite simple to extend Wily
using other programs, written in any language, both for simple
text-manipulation tasks, and to use Wily as a front-end for other
programs such as mail or news readers, or terminals.
It is possible
(and intended) to "live" in wily as with other, more complicated
editors.
The learning curve is steep, but short. Once learnt, the interface
is sufficiently addictive that the author re-implemented Acme to work
under Unix, rather than coping with other editors. Wily and Acme have a
small but growing number of addicts.
Wily appears as one or more vertical columns, divided into windows
of scrolling text. Each column or window is headed by a thin horizontal
tag. The leftmost text of the tag is the name of the file or
directory the window represents. Other text in the tag are some words
useful as commands.
The small square-ish box to the left of the tag is called the
resize box. If the resize box is filled, this indicates that the
text in the associated window has been modified since it was last read
from or written to disk.
The text in the body of the window may represent a directory,
a file, the interface to some program like a news reader, or the output
from some program like make.
Proportionally spaced, Unicode text
Text is displayed in a propotionally spaced font by default. There
is a built in function to toggle with a monospace font (seen in the bottom-left
window in the example pictured), but there are
very few occasions when this is necessary or desirable. In most cases
limiting a text editor to monospace fonts is blindly following the
hardware limitations of the 1960s.
Text is read and written as
UTF8-encoded
Unicode,
providing some support for editing multi-lingual and scientific text,
but remaining backwardly compatible with plain 7-bit ASCII text.
See 9term for an example of another program with Unicode support,
with some screen shots.
Any text on the screen can be selected by dragging
with a mouse button. Briefly, the left, middle and right mouse
buttons are used to select, execute or goto text. In more detail:
- Left button
- highlights the text for later actions
- Middle button
- executes the text as a command, e.g. selecting
the word 'make' will run the make command as if it were typed
to the shell. There is a small set of built-in functions
(e.g. Undo, Redo, ) that
are searched for first. Wily arranges for text representing these functions
to be on the screen when and where appropriate, although they can always
be typed anywhere anytime. Output from programs is captured and displayed
in windows in Wily.
- Right button
- attempts to goto the selected text.
What this means depends on the text selected, but may
involve opening a file or directory, or searching for a line
number, regular expression or literal text.
Wily tries to parse the selected text as filename:address,
where address may be a line number or /regexp.
Either or both of the filename and the :address may be recognized.
If Wily cannot recognise any of these forms, it searches for the
next occurrence of the selected text in the current window.
Panes and columns can be moved and reshaped by clicking
or dragging in the resize box to the left of their tags.
There are no menus, and few special keys
(page up, page down, arrow keys, Home, End, kill word, kill line, select
recently typed text). All functions
are accessed through mouse actions on text.
Sally has been using wily to develop a program called wily.
- She clicks the middle mouse button in the word
make somewhere in the tag of the window for her source
directory, /src/wily/. Clicking the middle mouse
button in some text tells wily to execute that text. In this
case wily runs make in another process. The output
and errors from this process will appear in a window labelled
/src/wily/+Errors. (The window will be created if
necessary). Unfortunately there is an error: the output includes the
line builtins.c:78: parse error before `)'.
- She clicks the right mouse button anywhere in the text
builtins.c:78:. Clicking in some text with the rightmost
mouse button tells wily to goto that text. A new window labelled
/src/wily/builtins.c is created if necessary, with line 78
centred and highlighted, and the cursor warps to this line. Sally sees
that the last ) on that line is unnecessary.
- She selects it with the left mouse button, and while holding
this button down, also clicks the middle mouse button to cut out
the offending parenthesis. Cutting and pasting text in
wily can be done with combinations of mouse keys. This is very
quick and easy. The resize box of the window is filled in, to indicate
that the file has been modified.
- She clicks the middle mouse button in the word "Put" in the
window's tag. Wily recognizes this as the name of the builtin function
to write the file to disk, and does so. The resize box is cleared, to
indicate that the file is "clean".
- She clicks the middle mouse button in the word
make, and the cycle begins again.
This whole interaction requires six mouse clicks and much less
time than the time to read about it.
Combinations of mouse buttons
The system does some things so that the user doesn't need to place
the mouse accurately. Double-clicking with the left mouse button
selects a word, a line or a piece of text delimited by quotes, braces or
brackets. With the middle or right button, a click inside a selection
will be expanded to that selection, or a click inside a word that can be
recognised as a command or address will be expanded to that word.
Simultaneous combinations of mouse buttons
(Mouse chords) are used for cutting and pasting. To move some
text from one place to another, it first is selected by dragging with
the left mouse button. While holding this button down, if the middle
button is also pressed, the text is cut. The text can later be
pasted into place by holding the left button and then clicking the right
button. This action is easier done than said, and is much quicker than
searching for a menu entry.
A mouse chord is also used as a short-hand for the idiom of
executing a command with some argument. While clicking with the
middle button in the command, if the leftbutton is then pressed,
the most recently selected text is given as an argument to the
command. For example, one could point to a program variable,
click the middle and left buttons on the name of some simple
program, and get a list showing all the places that variable
occurs. Clicking with the right button on any of the occurrences
on that list will open the relevant file at the correct line.
The mouse cursor is often warped to where the program predicts the next
action is likely to take place. For example, after opening a file at a particular
address, the cursor is warped to that position of that file.
The escape key selects any text typed since the last cursor movement,
making it easier to select with the mouse.
Undo/Redo
Wily provides a full Undo/Redo history for each window.
Window Positioning
Newly created windows are placed by the program, not the user.
While it is possible for the user to reposition or resize the window after
it is created, window-positioning heuristics generally make
such positioning unnecessary.
Wily has no extension language, but is easy to connect to other
UNIX programs.
Program output is useful
The output (both stdout and stderr) of
any commands run from wily will appear in a wily window, where it may
be useful. For example, the author uses the shell functions sg
and def. sg (short for source grep) is
defined as fn sg {agrep -w -n $* *.[ch]}, def
as fn def {grep -n '^'^$1 *.c /dev/null}. To find the
definition of some C function, the author clicks with the left button
in the name of the function, and does a middle-left button combination
on the word def. The output from def
will appear in a wily window, and be something like
/usr/gary/src/dir/file.c:243 function(int arg, char* otherarg).
Clicking here with the right mouse button will then open the file if necessary,
and move to and highlight the correct line. The function sg
operates similarly, listing all occurrences of some identifier. Note that
it would be simple to modify these functions to operate with other languages
(HTML, Java, ...) and that they could be written in any language the
user chooses.
Filter programs
Commands beginning with
|, > or < operate on the most recent selection. They
either pipe it through a command, send it to a
command, or replace it with the output of a
command. For example, to reformat a paragraph, select
it (using the left button), then click anywhere in the text
|fmt. fmt will be executed,
with its input taken from the current selection, and its output
replacing the current selection.
Programs may also be used to filter text in wily windows. If a command
starts with the pipe symbol |, it uses the most recently
selected wily text as input and output. Indenting, formatting, html tagging
can all be done using standard Unix tools, or tools written by the user in
any language. Simply select some text, and click with the middle mouse
button in |cmd.
For example, here is the author's file lib/html/guide:
|title |h1 |h2 |h3 |h4
|italic |emph |strong |bold |code |href prog.html |name remote
|fmt >spell |blanks2P
Wily as a front-end
Longer-running processes may instead open
a socket to wily, which can be used to send requests or receive
events. One example of this is the program win,
which provides a simple terminal within Wily.
(For details refer to [Cap95a])
Python
and Perl bindings for this message interface are available.
Mail and news readers or code browsers should be fairly simple to
write using Wily as their front end. All of these programs would
operate in a familiar fashion (left mouse button selects, middle button
executes, right button does a "goto").
No confirmations
When you close a file that wily knows contains changes, it doesn't
bother you with a confirmation dialog, but does a backup of the file
and prints a warning message
in case you've made a mistake. This is quicker in the common case that
you do want to discard the changes, is simple to recover from
if you have made a mistake, and eliminates the mistake
of confirming a deletion that shouldn't have been confirmed.
Wily is a single-threaded event-driven server process. The events it
waits for are keyboard and mouse actions, and output arriving
on sockets shared with child processes. Text display is handled
by text widgets.
Child Processes
To execute a command that isn't built in, the wily server forks a child,
which modifies its execution environment, and execs the
required command.
The child sets its current directory to the directory the command was
invoked from. The child's file descriptors are set so that
stdin is redirected from /dev/null, and
stdout and stderr are redirected to a file
descriptor the server listens to for output.
The parent adds the file descriptors passed to the child to a list of
file descriptors that it monitors for output, and remembers which directory
that stream is associated with, so that output will appear in an appropriate window.
More sophisticated client processes can open a socket to
wily and send (and receive messages). The idea here is that wily
provides the "look and feel" of the user interface, with various
client programs providing different data (mail, news, debugger...),
Code bloat (not!)
Wily's source code (excluding some libraries from Bell Labs) takes
7600 lines of code, or 3100 counting only lines with semicolons.
The binary (ELF 32-bit MSB executable SPARC Version 1, dynamically linked, stripped) is 150k (c.f. 234k for vi, 2044k for xemacs).
Wily typically takes less memory to run than Xterm.
Strengths, Weaknesses and Further Work
The things the author misses most when using another editor are:
mouse chording for cut and paste (alternatives seem very awkward),
opening a file to a particular line with a single mouse click, and editing
in a proportional font.
Some of wily's strengths may also be seen as weaknesses: heavy
exploitation of bitmapped terminal and three button mouse mean wily is
unusable on glass and paper teletypes. The terse mouse command language is
opaque and even intimidating for new users.
The author is very interested in cooperating with any HCI researchers
interested in comparing the usability and/or ease of learning of this editor
with more traditional ones, or in comparing mouse-based and keyboard-based
editors.
Wily is not as robust or efficient as the author would like.
Wily source code and documentation (263k)
and some binaries are
available via FTP from sites in
Australia,
Israel,
the UK and
the US.
The author welcomes
comments and suggestions.
There is a mailing list for discussion
about wily and announcements of new releases. Mail
wilyfans-request@jli.com to
subscribe.
The list is archived.
Wily runs on BSDi, AIX, OSF, HP-UX, IRIX, Linux, Solaris,
SunOS4, (these are the OSs the author knows of to date). With any
luck, gunzip, tar, configure, make install should get you going.
Wily is a reimplementation of Acme [Pike95]
for the Unix/X environment. Acme itself was heavily inspired by the
Oberon [Wirt89] user interface. A port was not
possible because the Acme implementation relies on Alef
[Win95](a concurrent
programming language not widely available) and non-portable features
of Plan 9 [Pike95a].
The name "wily" derives from Wile E. Coyote, an avid user of
Acme products.
Acknowledgements
Many suggestions on wily and this paper,
and much of the code were received
from Bill Trost <trost@cloud.rain.com>. Libraries
used include libXg and libframe, part of the Sam distribution by Rob Pike and
Howard Trickey, and libtext by James Farrow.
This is an incomplete, alphabetical list of other people who have made significant contributions to wily:
Assar,
Davor Cubranic,
Kyle Dean,
Stephen Gallimore,
Mark H. Wilkinson,
Bjorn Helgaas,
Steve Kilbane,
Beirne Konarski,
Bob Krzaczek,
Alberto Nava,
Arnold Robbins,
Rich Salz,
Scott Schwartz,
Chris Siebenmann,
and Richard Wolff.
References
- [Cap95]
- Gary Capell:
Wily User's Guide
http://www.cs.su.oz.au/~gary/wily/user.html
- [Cap95a]
- Gary Capell:
Wily Programmer's Guide
http://www.cs.su.oz.au/~gary/wily/msg.html
- [Pike95]
- Rob Pike: Acme: A User Interface for Programmers,
Plan 9 Programmer's Manual, Volume Two, 2nd Ed.
http://plan9.bell-labs.com/plan9/doc/acme.html
- [Pike95a]
- Rob Pike et al.: Plan 9 from Bell Labs,
Plan 9 Programmer's Manual, Volume Two, 2nd Ed.
http://plan9.bell-labs.com/plan9/doc/9.html
- [Win95]
- Phil Winterbottom: Alef language Reference Manual,
Plan 9 Programmer's Manual, Volume Two, 2nd Ed.
http://plan9.bell-labs.com/plan9/doc/ref.html
- [vanRo95]
- Guido van Rossum: Python Tutorial,
CWI Technical Report CS-R9526,
1995
http://www.python.org/
- [Wirt89]
- N. Wirth and J. Gutknecht: The Oberon System,
Software - Practice and Experience,
Sep. 1989, Vol 19 #9, pp 857-894
place. For example, after opening a file at a particular
address, the cursor is warped to that position of that file.
The escape key selects any text typed since the last cursor movement,
making it easier to selectwily-0.13.42/Doc/sam/ 0000755 0236657 0000012 00000000000 10333201523 0013761 5 ustar 00oz staff 0000433 0000002 wily-0.13.42/Doc/sam/bitblt.3 0000644 0236657 0000012 00000015607 10333201523 0015336 0 ustar 00oz staff 0000433 0000002 .de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.TH BITBLT 3G
.SH NAME
bitblt, bitbltclip, copymasked, clipline, point, segment, polysegment, arc, circle, disc, ellipse, texture, border, string, strsize, strwidth, Fcode \- graphics functions
.SH SYNOPSIS
.nf
.B
#include
.B
#include
.PP
.ta \w'\fLPoint 'u
.B
void bitblt(Bitmap *db, Point dp, Bitmap *sb,
.B
Rectangle sr, Fcode f)
.PP
.B
int bitbltclip(void *)
.PP
.B
void copymasked(Bitmap *db, Point dp, Bitmap *sb, Bitmap *mb, Rectangle sr)
.PP
.B
int clipline(Rectangle r, Point *p0, Point *p1);
.PP
.B
void point(Bitmap *b, Point p, int v, Fcode f);
.PP
.B
void segment(Bitmap *b, Point p, Point q, int v, Fcode f)
.PP
.B
void polysegment(Bitmap *b, int n, Point *pp, int v, Fcode f)
.PP
.B
void circle(Bitmap *b, Point p, int r, int v, Fcode f);
.PP
.B
void arc(Bitmap *b, Point p0, Point p1, Point p2, int v, Fcode f);
.PP
.B
void disc(Bitmap *b, Point p, int r, int v, Fcode f);
.PP
.B
void ellipse(Bitmap *b, Point p, int a, int b, int v, Fcode f);
.PP
.B
void texture(Bitmap *b, Rectangle r, Bitmap *t, Fcode f)
.PP
.B
void border(Bitmap *b, Rectangle r, int w, Fcode f)
.PP
.B
Point string(Bitmap *b, Point p, Font *ft, char *s, Fcode f)
.PP
.B
Point strsize(Font *ft, char *s)
.PP
.B
long strwidth(Font *ft, char *s)
.PP
.ft L
.ta 8n +\w'xxxxxxxxxx'u +\w'xxxxxxxxxx'u +\w'xxxxxxxxxx'u +\w'xxxxxxxxxx'u
enum Fcode {
Zero, DnorS, DandnotS, notS,
notDandS, notD, DxorS, DnandS,
DandS, DxnorS, D, DornotS,
S, notDorS, DorS, F
} Fcode;
.ft P
.fi
.SH DESCRIPTION
.I Bitblt
(bit-block transfer)
takes bits from rectangle
.I sr
in the
.I source
Bitmap,
.IR sb,
and overlays them on a congruent rectangle with the
.B min
corner at point
.B dp
in the
.I destination
bitmap,
.IR db .
The
.I f
parameter says how to compute each destination pixel
as a function of the source and destination pixels.
The first sixteen codes in
.B Fcode
give all possible boolean operations
on the source,
.B S
and destination
.BR D .
The code values have been arranged so that they may be expressed as
boolean operations on the values
.B S
and
.BR D.
So, for example,
.B D|S
computes the result as the logical
.I or
of the destination pixel's old value and the overlaying source pixel's value.
If pixels are more than one bit deep, the operations are bitwise.
The
.B Zero
and
.B F
codes result in new pixel values that are all zeros or all ones, respectively.
.PP
If the source and destination bitmaps have different depths,
the source rectangle is first converted to have the same depth as the
destination, as follows:
conversion to a smaller number of bits per pixel is accomplished by
taking the desired number of high order bits;
conversion to a larger number of bits per pixel is accomplished by
putting the small value into the high order bits, and replicating it as many times
as necessary to fill the lower order bits.
.PP
.I Copymasked
copies rectangle
.I sr
in the source bitmap
.I sb
to the congruent rectangle with the
.B min
corner at point
.B dp
in the destination bitmap
.IR db ,
masked by
bitmap
.I mb .
This means that
.I mb
is overlayed on the destination rectangle, and only pixels corresponding to 1 bits
in the mask are changed.
.I Mb
must be a 1-bit-deep bitmap with origin (0,0) and congruent to
.IR sr .
Bitmaps
.I sb
and
.I db
must have the same depth.
.PP
All of the drawing graphics functions clip the rectangle against the
source and destination bitmaps, so that only
pixels within the destination bitmap are changed, and none are changed
that would have come from areas outside the source bitmap.
.I Bitbltclip
takes a pointer to the first argument of a
.I bitblt
argument list, and modifies
.I dp
and
.I sr
so that no more clipping is needed.
.PP
.I Point
changes the value of the destination point
.I p
in bitmap
.I b
according to function code
.IR f .
The source is a pixel with
value
.IR v .
It is useful to use
.B "~0"
when the maximum pixel value is desired for the source.
.PP
.IR Segment ,
.IR circle ,
.IR disc ,
and
.I ellipse
all draw in bitmap
.I b
with function code
.I f
and a source pixel with value
.IR v .
.I Arc
draws a circular arc centered on
.IR p0 ,
traveling clockwise from
.I p1
to
.I p2
or a point on the circle near
.IR p2 .
.I Segment
draws a line segment in bitmap
.I b
from point
.I p
to
.IR q .
The segment is half-open:
.I p
is the first point of the segment and
.I q
is the first point beyond the segment,
so adjacent segments sharing endpoints abut.
.PP
.I Polysegment
draws the
.IR n \-1
segments joining the
.I n
points in the array pointed to by
.I pp.
.I Clipline
clips the line segment from
.RI * p0
to
.RI * p1
.RI ( p0
is closed,
.I p1
is open)
to rectangle
.IR r ,
adjusting
.I p0
and
.I p1
so that the segment is within the rectangle and
.RI * p1
is closed.
It returns 0 if none of the segment is in the rectangle, 1 otherwise.
.PP
.I Circle
draws a circle with radius
.I r
and center at point
.IR p .
.I Disc
is the same except that it fills the circle.
.I Ellipse
draws an ellipse with horizontal semi-axis
.I a
and vertical semi-axis
.IR b.
.PP
.I Border
draws, with function
.I f
in bitmap
.IR b ,
the rectangular outline with lines of width
.IR w ,
fitting just inside rectangle
.IR r .
.PP
.I Texture
draws, with function
.I f
in bitmap
.IR b ,
a texture using the
bitmap specified by
.IR t .
The texture bitmap is aligned on
.IR b 's
coordinate system so that (0,0) in both coordinate systems coincide,
and then
.I t
is replicated to form a tiling of
.IR b .
The tiling is clipped to rectangle
.I r
in
.IR b ,
and then transferred to
.I b
using the specified function.
.PP
.I String
draws the text characters given by the null-terminated (UTF
encoded) string
.I s
into bitmap
.IR b ,
using font
.IR ft.
The upper left corner of the first character (i.e., a point
that is
.IB ft ->ascent
above the baseline) is placed at point
.IR p ,
and subsequent characters are placed on the same baseline, displaced to
the right by the previous character's
.BR width .
The individual characters are
.IR bitblt 'ed
into the destination, using drawing function
.IR f .
.I String
returns the point in the destination bitmap after the final character of
.I s
(or where the final character would be drawn, assuming no clipping;
the returned value might be outside the destination bitmap).
.PP
The bounding box for text to be drawn with
.I string
in font
.I ft
can be found with
.IR strsize ;
it returns the
.B max
point of the bounding box, assuming a
.B min
point of (0,0).
.I Strwidth
returns the
.IR x -component
of the
.B max
point.
.SH SEE ALSO
.IR graphics (3),
.IT utf (4).
wily-0.13.42/Doc/sam/bitmap.6 0000644 0236657 0000012 00000005227 10333201523 0015332 0 ustar 00oz staff 0000433 0000002 .de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.TH BITMAP 6
.SH NAME
bitmap \- external format for bitmaps
.SH SYNOPSIS
.B
#include
.B
#include
.SH DESCRIPTION
Bitmaps are described in
.IR graphics (3).
Fonts and bitmaps are stored in external files
in machine-independent formats.
.PP
Bitmap files are read and written using
.I rdbitmapfile
and
.I wrbitmapfile
(see
.IR balloc (3)).
A bitmap file starts with 5
decimal strings:
.BR ldepth ,
.BR r.min.x ,
.BR r.min.y ,
.BR r.max.x ,
and
.BR r.max.y .
Each number is right-justified and blank padded in 11 characters, followed by a blank.
The rest of the file contains the
.BR r.max.y \- r.min.y
rows of bitmap data.
A
.I row
consists of the byte containing pixel
.B r.min.x
and all the bytes up to and including the byte containing pixel
.B r.max.x\fR\(mi1.
A pixel with x-coordinate =
.I x
in a bitmap with
.B ldepth
=
.I l
will appear as
.if t \fIw\fP = 2\u\s8\fIl\fP\s10\d
.if n w = 2^l
contiguous bits in a byte, with the pixel's high order bit
starting at the byte's bit number
.if t \fIw\fP\(mu((\fIx\fP mod 8)/\fIw\fP),
.if n w*(x mod 8/w),
where bits within a byte are numbered 0 to 7 from the
high order to the low order bit.
If
.I w
is greater than 8, it is a multiple of 8, so
pixel values take up an integral number of bytes.
Rows contain integral number of bytes, so there may be some unused
pixels at either end of a row.
.PP
The
.I rdbitmap
and
.I wrbitmap
functions described in
.IR balloc (3)
also deal with rows in this format, stored in user memory.
.PP
Some small images, in particular 48\(mu48 face files
and 16\(mu16
cursors, are stored textually, suitable for inclusion in C source.
Each line of text represents one scan line as a
comma-separated sequence of hexadecimal
bytes, shorts, or words in C format.
For cursors, each line defines a pair of bytes.
(It takes two images to define a cursor; each must be stored separately.)
Face files of one bit per pixel are stored as a sequence of shorts,
those of larger pixel sizes as a sequence of longs.
Software that reads these files must deduce the image size from
the input; there is no header.
These formats reflect history rather than design.
.SH "SEE ALSO"
.IR graphics (3),
.IR bitblt (3),
.IR balloc (3),
.IR font (6)
wily-0.13.42/Doc/sam/add.3 0000644 0236657 0000012 00000007256 10333201523 0014607 0 ustar 00oz staff 0000433 0000002 .de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.TH ADD 3G
.SH NAME
add, sub, mul, divpt, raddp, rsubp, rmul, rdiv, rshift, inset, rcanon, eqpt, eqrect, ptinrect, rectinrect, rectXrect, rectclip, Dx, Dy, Pt, Rect, Rpt \- arithmetic on points and rectangles
.SH SYNOPSIS
.nf
.B
#include
.B
#include
.PP
.B
.ta 12n +12n +12n +12n +12n
Point add(Point p, Point q)
.PP
.B
Point sub(Point p, Point q)
.PP
.B
Point mul(Point p, int a)
.PP
.B
Point divpt(Point p, int a)
.PP
.B
Rectangle raddp(Rectangle r, Point p)
.PP
.B
Rectangle rsubp(Rectangle r, Point p)
.PP
.B
Rectangle rmul(Rectangle r, int a)
.PP
.B
Rectangle rdiv(Rectangle r, int a)
.PP
.B
Rectangle rshift(Rectangle r, int a)
.PP
.B
Rectangle inset(Rectangle r, int n)
.PP
.B
Rectangle rcanon(Rectangle r)
.PP
.B
int eqpt(Point p, Point q)
.PP
.B
int eqrect(Rectangle r, Rectangle s)
.PP
.B
int ptinrect(Point p, Rectangle r)
.PP
.B
int rectinrect(Rectangle r, Rectangle s)
.PP
.B
int rectXrect(Rectangle r, Rectangle s)
.PP
.B
int rectclip(Rectangle *rp, Rectangle b)
.PP
.B
int Dx(Rectangle r);
.PP
.B
int Dy(Rectangle r);
.PP
.B
Point Pt(int x, int y)
.PP
.B
Rectangle Rect(int x0, int y0, int x1, int y1)
.PP
.B
Rectangle Rpt(Point p, Point q)
.fi
.SH DESCRIPTION
The functions
.IR Pt ,
.I Rect
and
.I Rpt
construct geometrical data types from their components.
These are implemented as functions. (Under Plan 9
these are implemented as macros.)
.PP
.I Add
returns the Point
sum of its arguments:
.BI Pt( p .x+ q .x,
.IB p .y+ q .y).
.I Sub
returns the Point
difference of its arguments:
.BI Pt( p .x- q .x,
.IB p .y- q .y).
.I Mul
returns the Point
.BI Pt( p .x* a ,
.IB p .y* a ).
.I Divpt
returns the Point
.BI Pt( p .x/ a ,
.IB p .y/ a ).
.PP
.I Raddp
returns the Rectangle
.BI Rect(add( r .min,
.IB p ),
.BI add( r .max,
.IB p ))\fR;
.I rsubp
returns the Rectangle
.BI Rpt(sub( r .min,
.IB p ),
.BI sub( r .max,
.IB p ))\fR.
.I Rmul
returns the Rectangle
.BI Rpt(mul( r .min, a ),
.BI mul( r .max, a ))\fR;
.I Rdiv
returns the Rectangle
.BI Rpt(div( r .min, a ),
.BI div( r .max, a ))\fR.
.PP
.I Rshift
returns the rectangle
.I r
with all coordinates either left-shifted or right-shifted by
.IR a ,
depending on whether
.I a
is positive or negative, respectively.
.PP
.I Inset
returns the Rectangle
.BI Rect( r .min.x+ n ,
.IB r .min.y+ n ,
.IB r .max.x- n ,
.IB r .max.y- n ) .
.PP
.I Rcanon
returns a rectangle with the same extent as
.IR r ,
canonicalized so that
.B min.x
.if t \(<=
.if n <=
.BR max.x ,
and
.B min.y
.if t \(<=
.if n <=
.BR max.y .
.PP
.I Eqpt
compares its argument Points and returns
0 if unequal,
1 if equal.
.I Eqrect
does the same for its argument Rectangles.
.PP
.I Ptinrect
returns 1 if
.I p
is a point within
.IR r ,
and 0 otherwise.
.PP
.I Rectinrect
returns 1 if all the pixels in
.I r
are also in
.IR s ,
and 0 otherwise.
.PP
.I RectXrect
returns 1 if
.I r
and
.I s
share any point, and 0 otherwise.
.PP
.I Rectclip
clips in place
the Rectangle pointed to by
.I rp
so that it is completely contained within
.IR b .
The return value is 1 if any part of
.RI * rp
is within
.IR b .
Otherwise, the return value is 0 and
.RI * rp
is unchanged.
.PP
The functions
.I Dx
and
.I Dy
give the width (delta x) and height (delta y) of a Rectangle.
They are implemented as macros.
.SH SEE ALSO
.IR graphics (3).
wily-0.13.42/Doc/sam/sam.1 0000644 0236657 0000012 00000047302 10333201523 0014631 0 ustar 00oz staff 0000433 0000002 .de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.br
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.ds a \fR*\ \fP
.TH SAM 1
.CT 1 editor
.SH NAME
sam \- screen editor with structural regular expressions
.SH SYNOPSIS
.B sam
[
.I option .\|.\|.
] [
.I files
]
.PP
.B sam
.B \-r
.I machine
.PP
.B sam.save
.PP
.B B
[
.BI \-nnnn
]
.I file .\|.\|.
.SH DESCRIPTION
.I Sam
is a multi-file editor.
It modifies a local copy of an external file.
The copy is here called a
.IR file .
The files are listed in a menu available through mouse button 3
or the
.B n
command.
Each file has an associated name, usually the name of the
external file from which it was read, and a `modified' bit that indicates whether
the editor's file agrees with the external file.
The external file is not read into
the editor's file until it first becomes the current file\(emthat to
which editing commands apply\(emwhereupon its menu entry is printed.
The options are
.TF "\-r machine "
.TP
.B \-d
Do not download the terminal part of
.I sam.
Editing will be done with the command language only, as in
.IR ed (1).
.TP
.BI \-r " machine
Run the host part remotely
on the specified machine, the terminal part locally.
.TP
.BI \-s " file
Start the host part from the indicated file on the
remote host. Only meaningful with the
.BI \-r
option.
.TP
.BI \-t " path
Start the terminal part from the indicated file.
Useful for debugging.
.PP
The standard X11
.BI \-geom
toolkit option can be used
to select the desired window geometry.
.SS Regular expressions
Regular expressions are as in
.IR regexp (6)
with the addition of
.BR \en
to represent newlines.
A regular expression may never contain a literal newline character.
The elements of regular expressions are:
.TF "[^abc] "
.TP
.B .
Match any character except newline.
.TP
.B \en
Match newline.
.TP
.B \ex
For any character except
.B n
match the character (here
.BR x ).
.TP
.B [abc]
Match any character in the square brackets.
.B \en
may be mentioned.
.TP
.B [^abc]
Match any character not in the square brackets, but never a newline.
Both these forms accept a range of
.SM ASCII
characters indicated by
a dash, as in
.BR a\-z .
.TP
.B ^
Match the null string immediately after a newline.
.TP
.B $
Match the null string immediately before a newline.
.PP
Any other character except newline matches itself.
.PP
In the following,
.I r1
and
.I r2
are regular expressions.
.TF "r1|r2 "
.TP
.BI ( r1 )
Match what
.I r1
matches.
.TP
.IB r1 | r2
Match what
.I r1
or what
.IR r2
matches.
.TP
.IB r1 *
Match zero or more adjacent matches
of
.IR r1 .
.TP
.IB r1 +
Match one or more adjacent matches of
.IR r1 .
.TP
.IB r1 ?
Match zero or one matches of
.IR r1 .
.PP
The operators
.BR * ,
.B +
and
.B ?
are highest precedence, then catenation, then
.B |
is lowest.
The empty
regular expression stands for the last complete expression encountered.
A regular expression in
.I sam
matches the longest leftmost substring formally
matched by the expression.
Searching in the reverse direction is equivalent
to searching backwards with the catenation operations reversed in
the expression.
.SS Addresses
An address identifies a substring in a file.
In the following, `character
.IR n '
means the null string
after the
\%\fIn\fP-th
character in the file, with 1 the
first character in the file.
`Line
.IR n '
means the
.IR n -th
match,
starting at the beginning of the file, of the regular expression
.LR .*\en? .
(The peculiar properties of a last line without a newline are
temporarily undefined.)
All files always have a current substring, called dot,
that is the default address.
.SS Simple Addresses
.TF ?regexp?
.TP
.BI # n
The empty string after character
.IR n ;
.B #0
is the beginning of the file.
.TP
.I n
Line
.IR n .
.TP
.BI / regexp /
.PD0
.TP
.BI ? regexp ?
The substring that matches the regular expression,
found by looking toward the end
.RB ( / )
or beginning
.RB ( ? )
of the file,
and if necessary continuing the search from the other end to the
starting point of the search.
The matched substring may straddle
the starting point.
When entering a pattern containing a literal question mark
for a backward search, the question mark should be
specified as a member of a class.
.PD
.TP
.B 0
The string before the first full line.
This is not necessarily
the null string; see
.B +
and
.B \-
below.
.TP
.B $
The null string at the end of the file.
.TP
.B .
Dot.
.TP
.B \&'
The mark in the file (see the
.B k
command below).
.TP
\f(CW"\f2regexp\f(CW"\f1\f1
Preceding a simple address (default
.BR . ),
refers to the address evaluated in the unique file whose menu line
matches the regular expression.
.SS Compound Addresses
In the following,
.I a1
and
.I a2
are addresses.
.TF "a1+a2 "
.TP
.IB a1 + a2
The address
.I a2
evaluated starting at the end of
.IR a1 .
.TP
.IB a1 \- a2
The address
.I a2
evaluated looking in the reverse direction
starting at the beginning of
.IR a1 .
.TP
.IB a1 ,\^ a2
The substring from the beginning of
.I a1
to the end of
.IR a2 .
If
.I a1
is missing,
.B 0
is substituted.
If
.I a2
is missing,
.B $
is substituted.
.TP
.IB a1 ;\^ a2
Like
.IB a1 ,\^ a2,
but with
.I a2
evaluated at the end of, and dot set to,
.IR a1 .
.PP
The operators
.B +
and
.B \-
are high precedence, while
.B ,
and
.B ;
are low precedence.
.PP
In both
.B +
and
.B \-
forms, if
.I a2
is a line or character address with a missing
number, the number defaults to 1.
If
.I a1
is missing,
.L .
is substituted.
If both
.I a1
and
.I a2
are present and distinguishable,
.B +
may be elided.
.I a2
may be a regular
expression; if it is delimited by
.LR ? 's,
the effect of the
.B +
or
.B \-
is reversed.
.PP
It is an error for a compound address to represent a malformed substring.
Some useful idioms:
.IB a1 +\^\-
.RI ( a1 \&\f5\-\^+\fP )
selects the line containing
the end (beginning) of a1.
.BI 0/ regexp /
locates the first match of the expression in the file.
(The form
.B 0;\^//
sets dot unnecessarily.)
.BI .\^/ regexp ///
finds the second following occurrence of the expression,
and
.BI .\^,\^/ regexp /
extends dot.
.SS Commands
In the following, text demarcated by slashes represents text delimited
by any printable
.SM ASCII
character except alphanumerics.
Any number of
trailing delimiters may be elided, with multiple elisions then representing
null strings, but the first delimiter must always
be present.
In any delimited text,
newline may not appear literally;
.B \en
may be typed for newline; and
.B \e\^/
quotes the delimiter, here
.LR / .
Backslash is otherwise interpreted literally, except in
.B s
commands.
.PP
Most commands may be prefixed by an address to indicate their range
of operation.
Those that may not are marked with a
.L *
below.
If a command takes
an address and none is supplied, dot is used.
The sole exception is
the
.B w
command, which defaults to
.BR 0\^,\^$ .
In the description, `range' is used
to represent whatever address is supplied.
Many commands set the
value of dot as a side effect.
If so, it is always set to the `result'
of the change: the empty string for a deletion, the new text for an
insertion, etc. (but see the
.B s
and
.B e
commands).
.br
.ne 1.2i
.SS Text commands
.PD0
.TP
.BI a/ text /
.TP
or
.TP
.B a
.TP
.I lines of text
.TP
.B .
Insert the text into the file after the range.
Set dot.
.TP
.B c\fP
.br
.ns
.TP
.B i\fP
Same as
.BR a ,
but
.B c
replaces the text, while
.B i
inserts
.I before
the range.
.TP
.B d
Delete the text in the range.
Set dot.
.TP
.BI s/ regexp / text /
Substitute
.I text
for the first match to the regular expression in the range.
Set dot to the modified range.
In
.I text
the character
.B &
stands for the string
that matched the expression.
Backslash behaves as usual unless followed by
a digit:
.BI \e \^d
stands for the string that matched the
subexpression begun by the
.IR d -th
left parenthesis.
If
.I s
is followed immediately by a
number
.IR n ,
as in
.BR s2/x/y/ ,
the
.IR n -th
match in the range is substituted.
If the
command is followed by a
.BR g ,
as in
.BR s/x/y/g ,
all matches in the range
are substituted.
.TP
.BI m " a1
.br
.ns
.TP
.BI t " a1
Move the range to after
.I a1
.RB ( m ),
or copy it
.RB ( t ).
Set dot.
.SS Display commands
.TP
.B p
Print the text in the range.
Set dot.
.TP
.B =
Print the line address and character address of the range.
.TP
.B =#
Print just the character address of the range.
.SS File commands
.TP
.BI \*ab " file-list
Set the current file to the first file named in the list
that
.I sam
also has in its menu.
The list may be expressed
.BI < "shell command"
in which case the file names are taken as words (in the shell sense)
generated by the shell command.
.TP
.BI \*aB " file-list
Same as
.BR b ,
except that file names not in the menu are entered there,
and all file names in the list are examined.
.TP
.B \*an
Print a menu of files.
The format is:
.RS
.TF "XorXblankXX"
.TP
.BR ' " or blank"
indicating the file is modified or clean,
.TP
.BR \- " or \&" +
indicating the file is unread or has been read
(in the terminal,
.B *
means more than one window is open),
.TP
.BR . " or blank
indicating the current file,
.TP
a blank,
.TP
and the file name.
.RE
.TP 0
.BI \*aD " file-list
Delete the named files from the menu.
If no files are named, the current file is deleted.
It is an error to
.B D
a modified file, but a subsequent
.B D
will delete such a file.
.SS I/O Commands
.TP
.BI \*ae " filename
Replace the file by the contents of the named external file.
Set dot to the beginning of the file.
.TP
.BI r " filename
Replace the text in the range by the contents of the named external file.
Set dot.
.TP
.BI w " filename
Write the range (default
.BR 0\^,\^$ )
to the named external file.
.TP
.BI \*af " filename
Set the file name and print the resulting menu entry.
.PP
If the file name is absent from any of these, the current file name is used.
.B e
always sets the file name,
.B r
and
.B w
do so if the file has no name.
.TP
.BI < " shell-command
Replace the range by the standard output of the
shell command.
.TP
.BI > " shell-command
Sends the range to the standard input of the
shell command.
.TP
.BI | " shell-command
Send the range to the standard input, and replace it by
the standard output, of the
shell command.
.TP
.BI \*a! " shell-command
Run the
shell command.
.TP
.BI \*acd " directory
Change working directory.
If no directory is specified,
.B $HOME
is used.
.PP
In any of
.BR < ,
.BR > ,
.B |
or
.BR ! ,
if the
.I shell command
is omitted the last
.I shell command
(of any type) is substituted.
If
.I sam
is downloaded,
.B !
sets standard input to
.FR /dev/null ,
and otherwise
unassigned output
.RB ( stdout
for
.B !
and
.BR > ,
.B stderr
for all) is placed in
.F $HOME/sam.err
and the first few lines are printed.
.SS Loops and Conditionals
.TP
.BI x/ regexp / " command
For each match of the regular expression in the range, run the command
with dot set to the match.
Set dot to the last match.
If the regular
expression and its slashes are omitted,
.L /.*\en/
is assumed.
Null string matches potentially occur before every character
of the range and at the end of the range.
.TP
.BI y/ regexp / " command
Like
.B x,
but run the command for each substring that lies before, between,
or after
the matches that would be generated by
.BR x .
There is no default behavior.
Null substrings potentially occur before every character
in the range.
.TP
.BI \*aX/ regexp / " command
For each file whose menu entry matches the regular expression,
make that the current file and
run the command.
If the expression is omitted, the command is run
in every file.
.TP
.BI \*aY/ regexp / " command
Same as
.BR X ,
but for files that do not match the regular expression,
and the expression is required.
.TP
.BI g/ regexp / " command
.br
.ns
.TP
.BI v/ regexp / " command
If the range contains
.RB ( g )
or does not contain
.RB ( v )
a match for the expression,
set dot to the range and run the command.
.PP
These may be nested arbitrarily deeply, but only one instance of either
.B X
or
.B Y
may appear in a \%single command.
An empty command in an
.B x
or
.B y
defaults to
.BR p ;
an empty command in
.B X
or
.B Y
defaults to
.BR f .
.B g
and
.B v
do not have defaults.
.SS Miscellany
.TP
.B k
Set the current file's mark to the range. Does not set dot.
.TP
.B \*aq
Quit.
It is an error to quit with modified files, but a second
.B q
will succeed.
.TP
.BI \*au " n
Undo the last
.I n
(default 1)
top-level commands that changed the contents or name of the
current file, and any other file whose most recent change was simultaneous
with the current file's change.
Successive
.BR u 's
move further back in time.
The only commands for which u is ineffective are
.BR cd ,
.BR u ,
.BR q ,
.B w
and
.BR D .
.TP
(empty)
If the range is explicit, set dot to the range.
If
.I sam
is downloaded, the resulting dot is selected on the screen;
otherwise it is printed.
If no address is specified (the
command is a newline) dot is extended in either direction to
line boundaries and printed.
If dot is thereby unchanged, it is set to
.B .+1
and printed.
.PD
.SS Grouping and multiple changes
Commands may be grouped by enclosing them in braces
.BR {} .
Commands within the braces must appear on separate lines (no backslashes are
required between commands).
Semantically, an opening brace is like a command:
it takes an (optional) address and sets dot for each sub-command.
Commands within the braces are executed sequentially, but changes made
by one command are not visible to other commands (see the next paragraph).
Braces may be nested arbitrarily.
.PP
When a command makes a number of changes to a file, as in
.BR x/re/c/text/ ,
the addresses of all changes to the file are computed in the original file.
If the changes are in sequence,
they are applied to the file.
Successive insertions at the same address are catenated into a single
insertion composed of the several insertions in the order applied.
.SS The terminal
What follows refers to behavior of
.I sam
when downloaded, that is, when
operating as a display editor on a bitmap display.
This is the default
behavior; invoking
.I sam
with the
.B \-d
(no download) option provides access
to the command language only.
.PP
Each file may have zero or more windows open.
Each window is equivalent
and is updated simultaneously with changes in other windows on the same file.
Each window has an independent value of dot, indicated by a highlighted
substring on the display.
Dot may be in a region not within
the window.
There is usually a `current window',
marked with a dark border, to which typed text and editing
commands apply.
The escape key (ESC) selects (sets dot to) text typed
since the last mouse button hit.
.PP
The button 3 menu controls window operations.
The top of the menu
provides the following operators, each of which uses one or
more cursors to prompt for selection of a window or sweeping
of a rectangle.
.TF "reshape "
.TP
.B new
Create a new, empty file:
Depress button 3 where one corner of the new rectangle should
appear (box cursor), and move the mouse while holding down button 3 to the
diagonally opposite corner.
`Sweeping' a null rectangle gets a large window, disjoint
from the command window or the whole sam window, depending on
where the null rectangle is.
.TP
.B xerox
Create a copy of an existing window.
After selecting the window to copy with button 1,
sweep out the window for the copy.
.TP
.B reshape
Change the size and location of a window.
First click button 3 in the window to be changed
(gunsight cursor).
Then sweep out a window as for the
.B new
menu selection.
.TP
.B close
Delete the window.
In the last window of a file,
.B close
is equivalent to a
.B D
for the file.
.TP
.B write
Equivalent to a
.B w
for the file.
.PD
.PP
Below these operators is a list of available files, starting with
.BR ~~sam~~ ,
the command window.
Selecting a file from the list makes the most recently
used window on that file current, unless it is already current, in which
case selections cycle through the open windows.
If no windows are open
on the file, the user is prompted to open one.
Files other than
.B ~~sam~~
are marked with one of the characters
.B \-\^+*
according as zero, one, or more windows
are open on the file.
A further mark
.L .
appears on the file in the current window and
a single quote,
.BR ' ,
on a file modified since last write.
.PP
The command window, created automatically when
.B sam
starts, is an ordinary window except that text typed to it
is interpreted as commands for the editor rather than passive text,
and text printed by editor commands appears in it.
There is an `output point' that separates commands being typed from
previous output.
Commands typed in the command window apply to the
current open file\(emthe file in the most recently
current window.
.SS Manipulating text
Typed characters replace the current selection (dot) in the current
window.
Backspace deletes the previous character.
Escape selects (sets dot to) everything typed since the last mouse hit.
.PP
Button 1 changes selection.
Pointing to a non-current window with button 1 makes it current;
within the current window, button 1 selects text, thus setting dot.
Double-clicking selects text to the boundaries of words, lines,
quoted strings or bracketed strings, depending on the text at the click.
.PP
Button 2 provides a menu of editing commands:
.TF "/regexp"
.TP
.B cut
Delete dot and save the deleted text in the snarf buffer.
.TP
.B paste
Replace the text in dot by the contents of the snarf buffer.
.TP
.B snarf
Save the text in dot in the snarf buffer.
.TP
.B look
Search forward for the next occurrence of the literal text in dot.
If dot is the null string, the text in the snarf buffer is
used.
The snarf buffer is unaffected.
.TP
.B
Exchange the snarf buffer with the current selection in another X11 window.
The exchange of a large amount of selected text is truncated to the
size of Sam's internal snarf buffer (currently 4K) without warning.
.TP
.BI / regexp
Search forward for the next match of the last regular expression
typed in a command.
(Not in command window.)
.TP
.B send
Send the text in dot, or the snarf buffer if
dot is the null string, as if it were typed to the command window.
Saves the sent text in the snarf buffer.
(Command window only.)
.PD
.SS X11 resources
Various attributes of
.I sam
can be set by giving values to X11 resources for the class
.B Sam.
There are various ways to do this; one is to have a file
called
.B Sam
in your home directory, with entries in it like:
.PP
.CW
.nf
Sam*width: 500
Sam*height: 600
Sam*font: fixed
Sam*scrollForwardR: true
.fi
.PP
In addition to the usual X11 toolkit resources, the
.B scrollForwardR
resource says where the right button (button 3) scrolls
forward or backward in the file.
.SS Abnormal termination
If
.I sam
terminates other than by a
.B q
command (by hangup, deleting its window, etc.), modified
files are saved in an
executable file,
.FR $HOME/sam.save .
This program, when executed, asks whether to write
each file back to a external file.
The answer
.L y
causes writing; anything else skips the file.
If a machine crash prevents the creation of a
.F sam.save
file, all changes are lost.
If an editing session is difficult to replicate,
you should write your changed files often.
.PP
.I B
is a shell-level command that causes an instance of
.I sam
running on the same terminal to load the named
.I files.
The option allows a line number to be specified for
the initial position to display in the last named file.
.SH FILES
.F $HOME/sam.save
.br
.F $HOME/sam.err
.br
.B /samsave
the program called to unpack
.BR $home/sam.save .
.SH SEE ALSO
.IR ed (1),
.IR regexp (6)
.SH BUGS
.PP
When a sam window is resized, the command window may have the wrong size.
by the contents of the named external file.
Set dot.
.TP
.BI w " filename
Write the range (default
.BR 0\^,\^$ )
to the named external file.
.TP
.BI \*af " filename
Set the file name and print the resulting menu entry.
.PP
If the file name is absent from any of these, the current file name is used.
.B e
always sets twily-0.13.42/Doc/sam/utf.4 0000644 0236657 0000012 00000005243 10333201523 0014650 0 ustar 00oz staff 0000433 0000002 .de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.TH UTF 4
.SH NAME
UTF, Unicode, ASCII, rune \- character set and format
.SH DESCRIPTION
The Plan 9 character set and representation are
based on Unicode and on a proposed X-Open multibyte
.SM FSS-UCS-TF
(File System Safe Universal Character
Set Transformation Format) encoding.
Unicode represents its characters in 16
bits;
.SM FSS-UCS-TF,
or just
.SM UTF,
represent such
values in an 8-bit byte stream.
.PP
In Plan 9, a
.I rune
is a 16-bit quantity representing a Unicode character.
Internally, programs may store characters as runes.
However, any external manifestation of textual information,
in files or at the interface between programs, uses a
machine-independent, byte-stream encoding called
.SM UTF.
.PP
.SM UTF
is designed so the 7-bit
.SM ASCII
set (values hexadecimal 00 to 7F),
appear only as themselves
in the encoding.
Runes with values above 7F appear as sequences of two or more
bytes with values only from 80 to FF.
.PP
The
.SM UTF
encoding of Unicode is backward compatible with
.SM ASCII\c
:
programs presented only with
.SM ASCII
work on Plan 9
even if not written to deal with
.SM UTF,
as do
programs that deal with uninterpreted byte streams.
However, programs that perform semantic processing on
.SM ASCII
graphic
characters must convert from
.SM UTF
to runes
in order to work properly with non-\c
.SM ASCII
input.
See
.IR rune (2).
.PP
Letting numbers be binary,
a rune x is converted to a multibyte
.SM UTF
sequence
as follows:
.PP
01. x in [00000000.0bbbbbbb] \(-> 0bbbbbbb
.br
10. x in [00000bbb.bbbbbbbb] \(-> 110bbbbb, 10bbbbbb
.br
11. x in [bbbbbbbb.bbbbbbbb] \(-> 1110bbbb, 10bbbbbb, 10bbbbbb
.br
.PP
Conversion 01 provides a one-byte sequence that spans the
.SM ASCII
character set in a compatible way.
Conversions 10 and 11 represent higher-valued characters
as sequences of two or three bytes with the high bit set.
Plan 9 does not support the 4, 5, and 6 byte sequences proposed by X-Open.
When there are multiple ways to encode a value, for example rune 0,
the shortest encoding is used.
.PP
In the inverse mapping,
any sequence except those described above
is incorrect and is converted to rune 0080.
.SH "SEE ALSO"
.IR ascii (1),
.IR rune (3),
.IR keyboard (4),
.IR "The Unicode Standard" .
alled
.SM UTF.
.PP
.SM UTF
is designed so the 7-bit
.SM ASCII
set (values hexadecimal 00 to 7F),
appear only as themselves
in the encoding.
Runes with values above 7F appear as sequences of two or more
bytes with values only from 80 to FF.
.PP
The
.SM UTF
encoding of Unicode is backward compatible with
.SM ASCII\c
:
programs presented only with
.Swily-0.13.42/Doc/sam/README 0000644 0236657 0000012 00000036102 10333201523 0014643 0 ustar 00oz staff 0000433 0000002
* The authors of this software are Rob Pike and Howard Trickey.
* Copyright (c) 1992 by AT&T.
* Permission to use, copy, modify, and distribute this software for any
* purpose without fee is hereby granted, provided that this entire notice
* is included in all copies of any software which is or includes a copy
* or modification of this software and in all copies of the supporting
* documentation for such software.
* THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
* WARRANTY. IN PARTICULAR, NEITHER THE AUTHORS NOR AT&T MAKE ANY
* REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
* OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
This is an X11 version of Rob Pike's editor, sam. Documentation describing
its use and construction are provided in subdirectory doc. The file doc/sam.1
contains the manual page; doc/sam.tut.ms is a tutorial that can be
formatted with troff -ms. It substitutes Bold and Italics for the
fonts named CW and CS; if your system has these fonts, remove the
CW and CS macros at the beginning of the file. The files doc/sam.ps
and doc/se.ps are postscript versions of published papers describing
sam and structural regular expressions. These papers reflect sam's
capabilities at the time of publication several years ago; while the
general description remains accurate, some functions may have changed
or been removed. Other files in the doc directory contain manual pages
for the library packages used by sam.
Sam is composed of two programs: sam itself, which does the command processing
and file manipulation; and samterm, which controls the display and
interacts with the user. You can run sam on one machine and samterm on another
connected via remote execution.
This version of sam is based on the Plan 9 implementation. Its
design and expression reflect the functionality of the Plan 9 environment;
most notably, characters are represented internally by 16-bit values called
Runes. Header files include/u.h and include/libc.h and source files
libframe/misc.c, libXg/rune.c, sam/unix.c and samterm/unix.c contain
code that insinuates sam into the Unix world. Two other files,
sam/plan9.c and samterm/plan9.c, contain Plan 9-specific code; they
are not used in the Unix version of sam and are provided as examples
of the Plan 9 interface.
Sam requires an ANSI/POSIX-compatible C compiler and libraries. We have
found that some commercial compilers which claim to meet this standard are
deficient. For our sanity, we only port sam to the standard; it is up to
you to modify it for non-standard aspects of your local environment.
Hints for some non-standard systems are provided at the end of this file.
The handling of varargs is the source of many porting problems. We advise
you to inspect the functions dprint and fprint in the files sam/unix.c and
libframe/misc.c to ensure the accuracy of the implementation. We also
encourage you to look at function newtmp() in sam/unix.c which creates
a sam temporary file. We prefer to use the tempnam() function; it allows
us to select the directory where the temp file is placed, a useful
optimization for systems with small local disks. However, tempnam() is
not a POSIX function, so you may have to use tmpfile() or a similar
function to create the temporary file.
The typedefs for uchar, ushort, and ulong defined in include/u.h, may conflict
with exisiting definitions in include file on some systems.
If this occurs, remove the offending definitions from include/u.h.
The distribution consists of six directories:
sam - The source for sam. It loads against libXg to pick
up some utility routines.
samterm - The source for samterm. It loads against libframe,
libXg, and your local X11 libraries.
libframe - The source for the frame library. This library is used
by samterm so it must be made first.
libXg - The source code of the graphics library and some general
utility modules. Header file u.h provides much of the
interface between sam and the local environment. It is
included in every source file. Sam's graphics
operations are implemented by Plan 9 libg functions. This
library emulates those functions using X11 operations.
You might find libXg to be independently useful to tame the
horrors of X11 programming. You can put it anywhere; the
samterm makefiles assume it is in ../libXg. libXg must
be made first.
include - header files.
doc - The documentation for sam and the libraries.
Each source directory contains makefiles for several typical architectures.
The master makefile in the top directory builds the subdirectories in
proper order.
Most customization effort is confined to configuring the makefiles.
You can usually minimize your work by copying the makefile for
your architecture to Makefile and then editing a couple of lines.
For example, to install sam on a Sun, go to each source subdirectory,
copy Make.sun to Makefile, and customize each Makefile.
Most of the time only the makefiles need configuration. Occasionally, it may
be necessary to twiddle some of the macros and pre-processor magic in
include/u.h or include/libc.h. In unusual cases, you may have to massage
system-dependent code in files libXg/misc.c, sam/unix.c, or samterm/unix.c.
Of course, systems with non-standard compilers or libraries may require
minor modifications to any or all of the source files.
Variables in each makefile define most configuration-dependent parameters; each
is explained by a comment in the makefile. The RSAMNAME variable in
sam/Makefile contains the name of the sam executable; this is only used when
executing sam remotely. If sam is stored in the same path on every machine in
your network or you use symbolic links to make it look like it is, this variable
should specify the full path name of the executable. If sam resides in various
directories on different machines, you've got a problem. The best strategy is to
simply set the name of the file containing sam (usually, "sam") without a path
component and rely on the users to set the directory in their PATH on the remote
system. Unfortunately, this fails when the Berkeley rsh is used as the remote
execution agent because it neglects to evaluate the user's profile in some
situations.
If a sam session terminates abnormally, sam creates a shell script named
sam.save in the user's home directory. When this file is executed, it asks
the user about each file and restores those selected. The files are restored
with the names as they were known to sam; usually you will want to move
sam.save to the last directory you had changed to in sam and restore the files
from that point. The restoration script relies on a second script provided
in sam/samsave. The SAMSAVEDIR variable in the sam Makefile contains the name
of a directory to hold this script. The SAMSAVE variable contains the shell
command to unpack each file; the command works with both the Bourne shell or
Tom Duff's 'rc'.
After configuring the makefiles, change to the top-level directory and
type "make". Typing "make install" installs sam, samterm and samsave in
their permanent homes.
During testing, the path of samterm may be specified using the -t command line
option to sam. Similarly, the path of sam itself may be specified using the
-s command line option; this is handy for testing the remote execution feature.
You may want to install Sam.ad as "Sam" in the system application
defaults library (which will have some name like /usr/lib/X11/app-defaults)
or your own home directory, if you don't have permission to write in
app-defaults. Sam.ad can be edited to give default values for things
like the starting height and width, the font, and the foreground and
background colors. Currently, only the -geom X11 parameter can be
specified on the command line. New X11 parameters can be easily added
by including the first character of the parameter in the switch statement
in main() in file sam/sam.c. Valid parameter strings are passed to
samterm and then directly to X11 for interpretation.
The scripts 'B.sh' and and 'B.rc' for the Bourne Shell and 'rc', respectively,
send a 'B' command to a runninng instance of sam and optionally position the
file to a selected line. The scripts are located in the sam subdirectory;
install one or both in the appropriate directory depending on the conventions
of your site. There is no installation target for them in the makefiles.
These commands require a POSIX-compliant named pipe facility; if your
system lacks this capability, replace the code in exstart() in
samterm/unix.c with a 'return' statement and throw away B.sh and B.rc.
We have successfully made this distribution for IRIX 4.0.1, SunOs 4.1.1
and Mips 4.5.2 at our site. Additionally, Rich Salz, Dan McDonald,
Alain Kagi and Ed Kubaitis have contributed prototype makefiles for
other architectures. We are unable to test and verify them but
they provide a good starting point for customizing a makefile.
The original protocol between sam and samterm assumed that memory addresses
and longs were 32 bits. Dave Hanson removed this dependency from the
protocol allowing sam to run on 64-bit processors. However, other
dependencies on structure alignment remain. If you are installing sam
on a processor with 64-bit addresses, please read the comment immediately
preceding the declaration of the Block data structure in file sam/sam.h
(at approximately line 85), and fiddle with the declaration appropriately.
Rob Pike designed and implemented the original Unix version of sam and the
current version ported from Plan 9. Howard Trickey provided the X
version of the graphics library, libXg. Matty Farrow and his colleagues
at the University of Sydney extended libXg to support Runes. Boyd Roberts
supplied the external command interface and the shell scripts for
the 'B' command. Doug Gwyn contributed many useful ideas to the X
implementation of sam. James Clark provided the simulations of the V10
Unix Man macros at the beginning of each manual page.
Matty Farrow of the University of Sydney has implemented 9term, an X11
version of a Plan 9 window. It is available via anonymous FTP from
ftp.cs.su.oz.au in directory /matty/unicode. Chris Siebenmann of the University
of Toronto runs the sam-fans mailing list, a source of tips, bug patches,
controversy and gossip among sam users. Send your e-mail address to
sam-fans-request@hawkwind.utcs.toronto.edu to enroll in the list.
Andrew Hume has written tcs, a Unix utility which converts input
text in one user-specified character set to output text in another
user-specified character set. It is useful for converting text represented
in a variety of standard character set encodings to UTF, the standard
character set accepted by sam. The tcs source package is available
via ftp in file dist/tcs.shar.Z on research.att.com.
In general, we are uninterested in adding further capabilities to sam; we
provide the source to allow you to customize it if you wish to "improve" it.
Please send bug fixes and comments to:
Bob Flandrena, bobf@research.att.com
-----------------------------------------------------------------------------------
Following are modifications necessary to paper over compiler or
library deficiencies to complying with the ANSI/POSIX standard. Please
inform us of any other changes.
-----------------------------------------------------------------------------------
SUNOS Release 4.1.1
The implementation of realloc does not conform to ANSI semantics.
Sam assumes
realloc(0, n);
is equivalent to malloc(n). Replace each occurrence of
p = realloc(p, n);
with:
p = ((p == 0) ? malloc(n) : realloc(p, n));
or something equivalent. Several files that include the X11
Intrinsics header file must have the variable SYSV defined
before the inclusion. The shell script sun.ed attempts to
automatically apply these patches when run from the top directory.
Older versions of gcc lack the '-fno-builtin'. If this describes
your site, remove the flag from the CFLAGS variable in Make.sun.
Because the standard Sun compiler is not Ansi-compatible, frantic
Sun users have been forced to cobble together their own compiling
environment. Unfortunately, the resulting system configurations
have little in common and it is virtually impossible to provide a
universal build procedure. We suggest the use of gcc; other
than that, Sun users are, as always, in the dark and on their own.
-----------------------------------------------------------------------------------
MIPS OS Release 4.5.2
(and DEC ULTRIX Version 4.2A)
There are two major deficiencies with the Mips implementation: the use of the
old System V implementation of varargs and a compiler bug that botches the
parsing of certain typedeffed parameters in function prototypes.
The following changes are required:
In sam/unix.c, replace function dprint with the following code:
void
dprint(char *fmt, int va_alist)
va_dcl
{
va_list args;
char buf[BLOCKSIZE];
va_start(args);
vsprintf(buf, fmt, args);
termwrite(buf);
va_end(args);
}
In libframe/misc.c, replace function fprint with the following code:
void
fprint(int fd, char *fmt, int va_alist)
va_dcl
{
va_list args;
char buf[2048]; /* pick reasonable blocksize */
va_start(args);
vsprintf(buf, fmt, args);
write(fd, buf, strlen(buf));
va_end(args);
}
In samterm/flayer.h, replace the declaration of the member named
textfn (near line 20) in structure Flayer, currently declared as:
Rune *(*textfn)(Flayer*, long, ulong*);
with
Rune *(*textfn)(Flayer*, long, unsigned long*);
In sam/parse.h, replace the declaration of the member named fn
(near line 46) in structure cmdtab, currently declared as:
int (*fn)(File*, Cmd*); /* function to call with parse tree */
with
int (*fn)(File*, struct Cmd*); /* function to call with parse tree */
In sam/sam.h, replace the declaration of function dprint (near line 245) with:
void dprint();
In include/libc.h, replace the declaration of function fprint (near line 53) with:
void fprint();
Near line 71 of samterm/samterm.h, change the declaration of function gettext from:
Rune *gettext(Flayer*, long, ulong*);
to
Rune *gettext(Flayer*, long, unsigned long*);
The shell script mips.ed attempts to automatically apply these patches when
run from the top directory.
-----------------------------------------------------------------------------------
Convex ConvexOS 9.1
In libXg/latin1.c, the Convex compiler requires room for a NULL at the end
of the 2-byte character field in struct latin. This can be fixed by
changing the dimension of the character array named 'c' near line 6 to
3 from 2. This bug appears to be fixed in the compiler for Release 10.1.
-----------------------------------------------------------------------------------
Sequent PTX V2.0.3
The calls to _exits() in sam/io.c near lines 184 and 205 clash with the
prototype for a system function of the same name. Replace the statements
_exits("damn");
with
_exits('d');
-----------------------------------------------------------------------------------
IBM AIX V3.2.3
AIX xlc V1.2.1 generates bad code in the second call to border()
in samterm/flayer.c:flborder() causing a core dump. Fix is to
upgrade to later version of xlc (V1.2.1.4). Or, compile
samterm/flayer.c (at least) with '-O'.
d using the -t command line
option to sam. Similarly, the path of sam itself may be specified using the
-s command line option; this is handy for testing the remote execution feature.
You may want to install Sam.ad as "Sam" in the system application
defaults library (which will have some name like /usr/lib/X11/app-defaults)
or your own home directory, if you don't have permission to write in
app-defaults. Sam.ad can be edited to give defauwily-0.13.42/Doc/sam/rgbpix.3 0000644 0236657 0000012 00000005041 10333201523 0015340 0 ustar 00oz staff 0000433 0000002 .de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.TH RGBPIX 3G
.SH NAME
RGB, rgbpix, rdcolmap, wrcolmap
.SH SYNOPSIS
.nf
.PP
.B
#include
.B
#include
.PP
.ta \w'\fLunsigned long 'u
.B
unsigned long rgbpix(Bitmap *b, RGB rgb)
.PP
.B
void rdcolmap(Bitmap *b, RGB *map)
.PP
.B
void wrcolmap(Bitmap *b, RGB *map)
.fi
.SH DESCRIPTION
Colors are described by the red, green, and blue
light intensities, in an
.B RGB
datum:
.IP
.EX
.ta 6n
typedef
struct RGB {
unsigned long red;
unsigned long green;
unsigned long blue;
} RGB;
.EE
.PP
Zero intensity means there is no component of the given color;
hence, black is represented by zero in all three positions and
white has the maximum unsigned long value in all three positions.
.PP
Some of the graphics functions, such as
.I point
(see
.IR bitblt (3)),
take a
.I pixel value
argument, which is a single unsigned long.
For a given bitmap,
.I rgbpix
returns the pixel value with a color closest to
the color represented by the
.I rgb
argument.
.PP
There is a
.I colormap
associated with each Bitmap. A colormap is an array of
.BR RGB s,
of length
.if t 2\u\s82\u\s6\fIldepth\fP\d\d\s10,
.if n 2^(2^\fIldepth\fP),
giving the colors for pixels 0, 1, 2, etc.
.PP
.I Rdcolormap
reads the colormap for the given bitmap into the provided
.IR map ,
which must have enough space to hold it.
.I Wrcolormap
associates the given colormap with the given bitmap, if possible.
(The hardware might not allow this.)
.SH CAVEAT
The X implementation of libg uses whatever colourmap is
the default when it starts up.
A call to
.I rgbpix
will result in a call to
.I XAllocColor
and the allocation of a new colour in the application's colourmap
if there is room.
If no new colours can be allocated
.I rgbpix
will return the closest pixel value approximating the requested colour.
If an application calls
.I wrcolmap
the default colourmap is replaced with the new colourmap and from
then on
.I rgbpix
will deal with the new colourmap.
.SH BUGS
These functions only work for the screen bitmap.
This interface will have to be refined for screens with
ldepth > 3.
.SH "SEE ALSO"
.IR graphics (3),
.IR bitblt (3)
ap
.SH SYNOPSIS
.nf
.PP
.B
#include
.B
#include
.PP
.ta \w'\fLunsigned long 'u
.B
unsigned long rgbpix(Bitmap *b, RGB rgb)
.PP
.B
void rdcolmap(Bitmap *b, RGB *map)
.PP
.B
void wrcolmap(Bitmap *b, RGB *map)
.fi
.SH DESCRIPTION
Colors are described by the red, green, and blue
light intensities, in an
.B RGB
datum:
.IP
.EX
.ta 6n
typedef
struct RGB {
unsigned long red;
unsigned long green;
unsigned long blue;
} RGB;
.EE
.PP
Zero intensity means there is nowily-0.13.42/Doc/sam/cachechars.3 0000644 0236657 0000012 00000013114 10333201523 0016131 0 ustar 00oz staff 0000433 0000002 .de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.TH CACHECHARS 3G
.SH NAME
cachechars, Subfont, Cachesubf, Fontchar, Font \- font utilities
.SH SYNOPSIS
.nf
.B
#include
.B
#include
.PP
.ta \w'\fLCacheinfo 'u
.PP
.B
int cachechars(Font *f, char **s, XChar2b *c, int n, int *widp, ushort *fp)
.fi
.SH DESCRIPTION
A
.I Font
may contain too many characters to hold in memory
simultaneously.
The graphics library and X server
cooperate to solve this problem by maintaining a cache of recently used
character images.
The details of this cooperation need not be known by most programs:
.I xtbinit
and its associated
.I *p9font
X resource,
.I rdfontfile,
.I charwidth,
.I string,
and
.I ffree
are sufficient for most purposes.
The routines described below are used internally by the graphics library
to maintain the font cache.
.PP
A
.B Subfont
may be considered to be a set of images for a contiguous range of characters,
stored as a single bitmap
with the characters
placed side-by-side on a common baseline.
It is described by the following data structures.
.IP
.EX
.ta 6n +\w'Fontchar 'u +\w'bottom; 'u
typedef
struct Fontchar {
ushort cwidth; /* width of glyph */
uchar top; /* first non-zero scan-line */
uchar bottom; /* last non-zero scan-line */
char left; /* offset of baseline */
uchar width; /* advance to next char's origin */
} Fontchar;
typedef
struct Subfont {
short minrow; /* first character row in font (for X subfonts) */
short mincol; /* first character col in font (for X subfonts) */
short minchar; /* first char code in font (for X subfonts) */
short maxchar; /* last char code in font (for X subfonts) */
short width; /* number of chars in row (for X subfonts) */
short n; /* number of chars in subfont */
unsigned char height; /* height of bitmap */
char ascent; /* top of bitmap to baseline */
Fontchar *info; /* n+1 character descriptors */
int id; /* of font */
} Subfont;
.EE
.PP
The actual bitmap for each character is stored on the server
but the metrics associated with character
.I c
are cached locally in
.B
subfont->info[\fIc\fP]\fR.
When a character is displayed at
.B Point
.B p
in a bitmap,
the character rectangle is placed at
.BI (p.x+ i ->left,
.B p.y)
and the next character of the string is displayed at
.BI (p.x+ i ->width+( i +1)->left,
.BR p.y) .
The baseline of the characters is
.L ascent
rows down from the top of the subfont bitmap.
Each
.B Fontchar
has two widths associated with it:
.I width
is the width of the rectangular bitmap
to contain the character;
.I cwidth
is the true width of the character, that is,
the number of pixels between the leftmost and
rightmost pixels of the character glyph.
.PP
A
.B Font
consists of an overall height and ascent
and a collection of subfonts together with the ranges of runes (see
.IR utf (4))
they represent.
Fonts are described by the following structures.
.IP
.EX
.ta 6n +\w'Cachesubf 'u +\w'height; 'u
typedef
struct Cachesubf {
Rune min; /* rune value of 0th char in subfont */
Rune max; /* rune value+1 of last char in subfont */
char *name;
Subfont *f; /* attached subfont */
} Cachefont;
typedef
struct Font {
char *name;
uchar height; /* max height of bitmap, interline spacing */
char ascent; /* top of bitmap to baseline */
char width; /* widest so far; used in caching only */
char ldepth; /* of images */
short id; /* of font */
short nsubf; /* number of subfonts */
Cachesubf *subf; /* as read from file */
} Font;
.EE
.PP
The
.LR height ,
.LR ascent ,
and
.L ldepth
fields of Font are described in
.IR graphics (3).
.L Subf
contains
.L nsubf
pointers to
.BR Cachesubfs .
A
.B Cachesubf
connects runes
.L min
through
.LR max ,
inclusive, to the subfont
.LR name ;
it corresponds to a line of the file describing the font.
.PP
The image for rune
.I r
is found in position \fIr\fR\(mi\fLmin\fR\(pl\fLminchar\fR of the subfont.
.PP
For each font, the library, with support from the
graphics server,
maintains a list of
subfonts.
The
.L width
of a font is the maximum of the horizontal extents of the characters
in the cache. [
.L width
is unused in the X implementation of libg.]
.I String
draws a string by calling
.I cachechars
and emitting a sequence of
X font indices to draw.
.I Cachechars
calculates the subfont/index pairs for the characters pointed to by
.IR *s .
It calls
.I getsubfont
to fetch subfonts which are not yet in the subfont list of
.IR f .
.I Cachechars
translates the character string into a set of subfont/index pairs.
It loads the character indices into the array
.IR c ,
up to a maximum of
.I n
indices or the length of the string.
It also loads the corresponding element of
.I fp
with the subfont index for each character.
.I Cachechars
returns in
.I c
the number of subfont indices emitted,
updates
.I *s
to point to the next character to be processed, and sets
.I *widp
to the total width of the characters processed.
.I Cachechars
may return before the end of the string if it cannot
proceed.
It can return zero if it is unable to make progress because
a character code does not covered by any subfont range.
.SH SEE ALSO
.IR graphics (3),
.IR balloc (3),
.IR bitblt (3),
.IR font (4).
.SH DIAGNOSTICS
All of the functions use the graphics error function (see
.IR graphics (3)).
wily-0.13.42/Doc/sam/boilerplate 0000644 0236657 0000012 00000001310 10333201523 0016201 0 ustar 00oz staff 0000433 0000002
/*
* The authors of this software are Rob Pike and Howard Trickey.
* Copyright (c) 1992 by AT&T.
* Permission to use, copy, modify, and distribute this software for any
* purpose without fee is hereby granted, provided that this entire notice
* is included in all copies of any software which is or includes a copy
* or modification of this software and in all copies of the supporting
* documentation for such software.
* THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
* WARRANTY. IN PARTICULAR, NEITHER THE AUTHORS NOR AT&T MAKE ANY
* REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
* OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
*/
wily-0.13.42/Doc/sam/Sam.ad 0000644 0236657 0000012 00000000150 10333201523 0015003 0 ustar 00oz staff 0000433 0000002 *width: 500
*height: 600
*font: fixed
*scrollForwardR: true
*saveUnder: true
*backingStore: WhenMapped
wily-0.13.42/Doc/sam/event.3 0000644 0236657 0000012 00000013360 10333201523 0015171 0 ustar 00oz staff 0000433 0000002 .de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.TH EVENT 3G
.SH NAME
event, einit, estart, etimer, eread, emouse, ekbd, ecanread, ecanmouse, ecankbd, ereshaped, getrect, menuhit, Event, Mouse, Menu \- graphics events
.SH SYNOPSIS
.nf
.B
#include
.B
#include
.PP
.ta \w'\fLunsigned long 'u
.PP
.B
void einit(ulong keys)
.PP
.B
unsigned long event(Event *e)
.PP
.B
Mouse emouse(void)
.PP
.B
int ekbd(void)
.PP
.B
int ecanmouse(void)
.PP
.B
int ecankbd(void)
.PP
.B
unsigned long estart(ulong key, int fd, int n)
.PP
.B
unsigned long etimer(ulong key, int n)
.PP
.B
unsigned long eread(ulong keys, Event *e)
.PP
.B
int ecanread(ulong keys)
.PP
.B
void ereshaped(Rectangle r)
.PP
.B
Rectangle getrect(int but, Mouse *m)
.PP
.B
int menuhit(int but, Mouse *m, Menu *menu)
.PP
.ft L
enum{
Emouse = 1,
Ekeyboard = 2,
}
.ft P
.fi
.SH DESCRIPTION
These routines provide an interface to multiple sources of input.
To use them,
.I einit
must be called.
If the argument to
.I enit
has the
.B Emouse
and
.B Ekeyboard
bits set,
the mouse and keyboard events will be enabled;
in this case,
.IR xtbinit
(see
.IR graphics (3))
must have already been called.
The user must provide a function called
.IR ereshaped ,
which will be called whenever the window in which the process
is running has been reshaped; the argument will be the Rectangle
for the new window shape, including the border.
.PP
As characters are typed on the keyboard, they are read by the
event mechanism and put in a queue.
.I Ekbd
returns the next character from the queue, blocking until the
queue is non-empty.
The characters are read by the event mechanism from the keyboard
so they are available as soon as they are typed.
.PP
When the mouse moves or a mouse button is depressed or released,
a new mouse event is queued by the event mechanism.
.I Emouse
returns the next mouse event from the queue, blocking until the
queue is non-empty.
.I Emouse
returns a
.B Mouse
structure:
.IP
.EX
.ta 6n +\w'unsigned long 'u
struct Mouse
{
int buttons;
Point xy;
unsigned long msec;
};
.EE
.PP
.B Buttons
is a bit field;
.B buttons&1
is set when the left mouse button is depressed,
.B buttons&2
when the middle button is depressed,
and
.B buttons&4
when the right button is depressed.
The current mouse position is always returned in
.BR xy .
.BR Msec
is the time stamp of the mouse event in units of milliseconds.
.PP
.I Ecankbd
and
.I ecanmouse
return non-zero when there are keyboard or mouse events to available
to be read.
.PP
.I Estart
can be used to register additional file descriptors.
It takes as arguments the file descriptor to register,
the maximum length of an event message on that descriptor,
and a key to be used in accessing the event.
The key must be a power of 2 and must not confilict with any previous keys.
If a zero key is given, one which is not used will be chosen and returned.
.B
Ekeyboard
and
.B Emouse
are the mouse and keyboard event keys.
.PP
.I Etimer
starts a repeating timer with a period of n milliseconds (default 1 second).
Only one timer can be started.
Extra timer events are not queued and the timer channel has no associated data.
.PP
.I Eread
waits for the next event specified by the mask
.B keys
of event keys submitted to estart.
It fills in the appropriate field of the argument
.B Event
structure, which looks like:
.IP
.EX
struct Event
{
int kbdc;
Mouse mouse;
int n;
uchar data[EMAXMSG];
}
.EE
.PP
.B Data
is an array which is large enough to hold a plan 9 protocol message.
.I Eread
returns the key for the event which was chosen.
For example, if a mouse event was read,
.I Emouse
will be returned.
.PP
.I Event
waits for the next event of any kind.
The return is the same as for
.IR eread .
.PP
As described in
.IR graphics (3),
the graphics functions are buffered.
.IR Event ,
.IR eread ,
.IR emouse ,
and
.I ekbd
all cause a buffer flush unless there is an event of the
appropriate type ready to return.
.PP
.I Getrect
is used to prompt the user to sweep a rectangle.
It should be called with
.I m
holding the mouse event that triggered the
.I getrect
(or, if none, a
.B Mouse
with
.B buttons
set to 7).
It changes to the sweep cursor,
waits for the buttons to all go up,
and then waits for button number
.I but
to be depressed, marking the initial corner.
If another button is depressed instead,
.I getrect
returns a rectangle
with zero for both x-coordinates, after
waiting for all the buttons to be released.
Otherwise,
.I getrect
continually draws the swept rectangle
until the button is released again, and returns the swept rectangle.
The mouse structure pointed to by
.I m
will contain the final mouse event.
.PP
.I Menuhit
displays a menu and returns a seleced menu item number.
It should be called with
.I m
holding the mouse event that triggered the
.I menuhit .
A
.B Menu
is a structure:
.IP
.EX
struct Menu
{
char **item;
char *(*gen)(int);
int lasthit;
}
.EE
.PP
If
.B item
is nonzero, it should be a null-terminated array of the character strings
to be displayed as menu items.
Otherwise,
.B gen
should be a function that, given an item number, returns the character
string for that item, or zero if the number is past the end of the list.
Items are numbered starting at zero.
.I Menuhit
waits until
.I but
is released, and then returns the number of the selection,
or \(mi1 for no selection.
The
.I m
argument is filled in with the final mouse event.
.SH "SEE ALSO"
.IR graphics (3).
wily-0.13.42/Doc/sam/font.4 0000644 0236657 0000012 00000003630 10333201523 0015016 0 ustar 00oz staff 0000433 0000002 .de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.TH FONT 4
.SH NAME
font, subfont \- external format for fonts and subfonts
.SH SYNOPSIS
.nf
.B
#include
.B
#include
.fi
.SH DESCRIPTION
Fonts and subfonts are described in
.IR cachechars (3).
.PP
External fonts are described by a plain text file that can be read using
.I rdfontfile.
The format of the file is a header followed by any number of
subfont range specifications.
The header contains two numbers: the height and the ascent.
The height is the inter-line spacing and the ascent is the distance
from the top of the line to the baseline. These numbers are chosen
to display consistently all the subfonts of the font.
A subfont range specification contains two numbers and a font name.
The numbers are the inclusive range of characters covered by the subfont,
and name specifies the name of an X font suitable for
.IR getsubfont .
The minimum number of a covered range is mapped to the first defined
character of the corresponding subfont.
Each field must be followed by some white space.
Each numeric field may be C-format decimal, octal, or hexadecimal.
.PP
Subfonts may be loaded using
.IR getsubfont ,
see
.IR graphics (3).
.SH BUGS
Some X font names contain spaces which will terminate the field.
For some fonts this can be worked around by replacing the spaces
with
.L `*'
characters in an attempt to fool the X font name pattern matching mechanism.
.SH "SEE ALSO"
.IR graphics (3),
.IR bitblt (3),
.IR cachechars (3).
wily-0.13.42/Doc/sam/frame.3 0000644 0236657 0000012 00000014300 10333201523 0015135 0 ustar 00oz staff 0000433 0000002 .de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.TH FRINIT 3G
.SH NAME
frinit, frsetrects, frclear, frcharofpt, frptofchar, frinsert, frdelete, frselect, frselectp, frselectf, frgetmouse \- frames of text
.SH SYNOPSIS
.nf
.B
#include
.B
#include
.B
#include
.B
#include
.PP
.B
void frinit(Frame *f, Rectangle r, Font *ft, Bitmap *b);
.PP
.B
void frsetrects(Frame *f, Rectangle r, Bitmap *b);
.PP
.B
void frclear(Frame *f);
.PP
.B
ulong frcharofpt(Frame *f, Point pt);
.PP
.B
Point frptofchar(Frame *f, ulong p);
.PP
.B
void frinsert(Frame *f, Rune *r0, Rune *r1, ulong p);
.PP
.B
int frdelete(Frame *f, ulong p0, ulong p1);
.PP
.B
void frselect(Frame *f, Mouse *m);
.PP
.B
void frselectp(Frame *f, Fcode fc);
.PP
.B
void frselectf(Frame *f, Point p0, Point p1, Fcode c);
.PP
.B
extern void frgetmouse(void);
.fi
.SH DESCRIPTION
This library supports
.I frames
of editable text in a single font on bitmap displays, such as in
.IR sam (1),
.IR 8\(12 (1),
and
.IR 9term (1).
Frames may hold any character except NUL.
Long lines are folded and tabs are at fixed intervals.
.PP
The user-visible data structure, a
.BR Frame ,
is defined in
.BR :
.IP
.EX
.ta 6n +\w'Rectangle 'u +\w'lastlinefull; 'u
typedef struct Frame Frame;
struct Frame
{
Font *font; /* of chars in the frame */
Bitmap *b; /* on which frame appears */
Rectangle r; /* in which text appears */
Rectangle entire; /* of full frame */
Frbox *box;
ulong p0, p1; /* selection */
short left; /* left edge of text */
ushort nbox, nalloc;
ushort maxtab; /* max size of tab, in pixels */
ushort nchars; /* # runes in frame */
ushort nlines; /* # lines with text */
ushort maxlines; /* total # lines in frame */
ushort lastlinefull; /* last line fills frame */
ushort modified; /* changed since frselect() */
};
.EE
.PP
.B Frbox
is an internal type and is not used by the interface.
.B P0
and
.B p1
may be changed by the application provided the selection routines are called
afterwards to maintain a consistent display.
.I Maxtab
determines the size of tab stops.
.I Frinit
sets it to 8 times the width of a
.B 1
character in the font;
it may be changed before any text is added to the frame.
The other elements of the structure are maintained by the library and
should not be modified directly.
.PP
There are no routines in the library to allocate
.BR Frames ;
instead the interface assumes that
.B Frames
will be components of larger structures.
.I Frinit
prepares the
.B Frame
.I f
so characters drawn in it will appear
in the single
.B Font
.I ft.
It then calls
.B frsetrects
to initialize the geometry for the
.B Frame.
The
.B Bitmap
.I b
is where the
.B Frame
is to be drawn;
.B Rectangle
.I r
defines the limit of the portion of the
.B Bitmap
the text will occupy.
The
.B Bitmap
pointer
may be null, allowing the other routines to be called to maintain the
associated data structure in, for example, an obscured window.
.PP
.I Frclear
frees the internal structures associated with
.I f,
permitting another
.I frinit
or
.I frsetrects
on the
.BR Frame .
If
.I f
is to be deallocated, the associated
.B Font
and
.B Bitmap
must be freed separately.
.PP
To reshape a
.B Frame,
use
.I frclear
and
.I frinit
and then
.I frinsert
(q.v.) to recreate the display.
If a
.B Frame
is being moved but not reshaped, that is, if the shape of its containing
rectangle is unchanged, it is sufficient to
.IR bitblt (3)
the containing rectangle from the old to the new location and then call
.I frsetrects
to establish the new geometry.
No redrawing is necessary.
.PP
.B Frames
hold text as runes,
not as bytes.
.I Frptofchar
returns the location of the upper left corner of the
.I p'th
rune in the
.B Frame
.I f.
If
.I f
holds fewer than
.I p
runes,
.I frptofchar
returns the location of the upper right corner of the last character in
.I f.
.I Frcharofpt
is the inverse: it
returns the index of the closest rune whose image's upper left corner
is up and to the left of
.I pt.
.PP
.I Frinsert
inserts into
.B Frame
.I f
starting at rune index
.I p
the runes between
.I r0
and
.I r1.
.PP
.I Frdelete
deletes from the
.B Frame
the text between
.I p0
and
.I p1.
.PP
.I Frselect
tracks the mouse to select a contiguous string of text in the
.BR Frame .
When called, mouse button 1 should be depressed.
It will return when the button is released and will set
.IB f ->p0
and
.IB f ->p1
to the selected range of text.
.I Frselectf
and
.I Frselectp
modify the display of the selected text.
.I Frselectf
highlights the text between
.I p0
and
.I p1
(which must have been returned by
.IR frptofochar )
using
.B bitblt
in mode
.I c.
.I Frselectp
is similar but highlights the text from
.IB f ->p0
to
.IB f ->p1 .
Neither
.I frselectf
nor
.I frselectp
modifies
.IB f ->p0
or
.IB f ->p1 .
.PP
Upon return from
.I frinsert
or
.I frdelete,
the display will be consistent but
.IB f ->p0
and
.IB f ->p1
may not point to the desired selection.
It may be necessary to adjust the selection and use
.I frselectf
or
.I frselectp
to fix the display.
.PP
.I Frgetmouse
must be provided by the application;
.I frselect
calls it to get mouse updates.
Each call to
.I frgetmouse
should update
the
.B Mouse
structure pointed to by
.I frselect's
argument
.I m.
.I Frgetmouse
should block until the mouse status has changed.
.PP
The text within frames
is not directly addressable; instead frames are designed to work alongside
another structure that holds the text.
The typical application is to display a section of a longer document such
as a text file or terminal session.
Only the text that is visible is held by the
.BR Frame ;
the application must check
.BR maxlines ,
.BR nlines ,
and
.B lastlinefull
to determine, for example, whether new text needs to be appended
at the end of the
.B Frame
after calling
.BR frdelete .
.SH SEE ALSO
.IR graphics (3),
.IR bitblt (3),
.IR event (3),
.IR cachechar (3).
wily-0.13.42/Doc/sam/rune.3 0000644 0236657 0000012 00000005105 10333201523 0015017 0 ustar 00oz staff 0000433 0000002 .de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.TH RUNE 3
.SH NAME
runetochar, chartorune, runelen, fullrune, utflen, utfrune, utfrrune, utfutf \- rune/UTF conversion
.SH SYNOPSIS
.nf
.B
#include
.B
int runetochar(char *s, Rune *r)
.PP
.B
int chartorune(Rune *r, char *s)
.PP
.B
int runelen(long r)
.PP
.B
int fullrune(char *s, int n)
.PP
.B
int utflen(char *s)
.PP
.B
char* utfrune(char *s, long c)
.PP
.B
char* utfrrune(char *s, long c)
.PP
.B
char* utfutf(char *s1, char *s2)
.fi
.SH DESCRIPTION
These routines convert to and from a
.SM UTF
byte stream and runes.
.PP
.I Runetochar
copies one rune at
.I r
to at most
.B UTFmax
characters starting at
.I s
and returns the number of characters copied.
.BR UTFmax ,
defined as
.B 3
in
.BR ,
is the maximum number of bytes required to represent a rune.
.PP
.I Chartorune
copies at most
.B UTFmax
characters starting at
.I s
to one rune at
.I r
and returns the number of characters copied.
If the characters are not exactly in
.SM UTF
format,
.I chartorune
will convert to 0x80 and return 1.
.PP
.I Runelen
returns the number of characters
required to convert
.I r
into
.SM UTF.
.PP
.I Fullrune
returns 1 if the string
.I s
of length
.I n
is long enough to be decoded by
.I chartorune
and 0 otherwise.
This does not guarantee that the string
contains a legal
.SM UTF
encoding.
This routine is used by programs that
obtain input a character at
a time and need to know when a full rune
has arrived.
.PP
The following routines are analogous to the
corresponding string routines with
.B utf
substituted for
.B str
and
.B rune
substituted for
.BR chr .
.PP
.I Utflen
returns the number of runes that
are represented by the
.SM UTF
string
.IR s .
.PP
.I Utfrune
.RI ( utfrrune )
returns a pointer to the first (last)
occurrence of rune
.I c
in the
.SM UTF
string
.IR s ,
or 0 if
.I c
does not occur in the string.
The NUL character terminating a string is considered to
be part of the string
.IR s .
.PP
.I Utfutf
returns a pointer to the first occurrence of
the
.SM UTF
string
.I s2
as a
.SM UTF
substring of
.IR s1 ,
or 0 if there is none.
If
.I s2
is the null string,
.I utfutf
returns
.IR s1 .
.SH SEE ALSO
.IR utf (4)
wily-0.13.42/Doc/sam/version 0000644 0236657 0000012 00000000057 10333201523 0015373 0 ustar 00oz staff 0000433 0000002 Version 4.3 built Mon Mar 27 16:31:38 EST 1995
wily-0.13.42/Doc/sam/balloc.3 0000644 0236657 0000012 00000006775 10333201523 0015320 0 ustar 00oz staff 0000433 0000002 .de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.TH BALLOC 3G
.SH NAME
balloc, bfree, rdbitmap, wrbitmap, rdbitmapfile, wrbitmapfile \- allocating, freeing, reading, writing bitmaps
.SH SYNOPSIS
.nf
.PP
.B
#include
.B
#include
.PP
.ta \w'\fLBitmap 'u
.B
Bitmap *balloc(Rectangle r, int ldepth)
.PP
.B
void bfree(Bitmap *b)
.PP
.B
void rdbitmap(Bitmap *b, int miny, int maxy, uchar *data)
.PP
.B
void wrbitmap(Bitmap *b, int miny, int maxy, uchar *data)
.PP
.B
Bitmap *rdbitmapfile(int fd)
.PP
.B
void wrbitmapfile(int fd, Bitmap *b)
.SH DESCRIPTION
A new bitmap is allocated with
.BR balloc ;
it will have the extent and depth given by its arguments,
and will be filled with zeros. The
.I id
field contains the handle of the X
.B Pixmap
associated with the bitmap
and the
.I cache
field is zero.
.I Balloc
returns 0 if the server has run out of bitmap resources.
.B Bfree
frees the resources used by its argument bitmap.
.PP
The remaining functions deal with moving groups of pixel
values between bitmaps and user space or external files.
There is a fixed format for the bitmap data in user space or on
external files.
A pixel with x-coordinate =
.I x
in a bitmap with
.B ldepth
=
.I l
will appear as
.if t \fIw\fP = 2\u\s8\fIl\fP\s10\d
.if n w = 2^l
contiguous bits in a byte, with the pixel's high order bit
starting at the byte's bit number
.if t \fIw\fP\(mu(\fIx\fP mod 8/\fIw\fP),
.if n w*(x mod 8/w),
where bits within a byte are numbered 0 to 7 from the
high order to the low order bit.
If
.I w
is greater than 8, it is a multiple of 8, so
pixel values take up an integral number of bytes.
A
.I row
of bitmap
.I b
consists of the byte containing pixel
.IB b .r.min.x
and all the bytes up to and including the byte containing pixel
.IB b .r.max.x\fR\(mi1.
.PP
.I Rdbitmap
reads rows of pixels from bitmap
.I b
into
.IR data .
The rows read have
.IR y = ymin , ymin "+1, ... "
.IR ymax \(mi1.
Those rows must be within the range allowed by
.IB b .r.
.PP
.B Wrbitmap
replaces the specified rows of pixels in bitmap
.I b
with
.IR data .
.PP
.I Rdbitmapfile
creates a bitmap from data contained an external file;
.I fd
should be a file descriptor obtained by opening such a file for reading.
The external file should start with 5 ASCII integers:
.BR ldepth ,
.BR r.min.x ,
.BR r.min.y ,
.BR r.max.x ,
and
.BR r.max.y .
Each number is right-justified in 11 characters, followed by a blank.
The rows of bitmap data, formatted as described above,
follow the header.
The returned bitmap is allocated using
.I balloc .
.I Rdbitmapfile
returns 0 if the server has run out of bitmap resources.
.PP
.I Wrbitmapfile
writes bitmap
.I b
onto file descriptor
.IR fd ,
which should be open for writing.
The format is as just described for
.IR rdbitmapfile .
.PP
.I Rdbitmapfile
and
.I wrbitmapfile
don't close
.IR fd .
.PP
.SH DIAGNOSTICS
Some errors can occur when accessing the internal bitmaps,
when trying to malloc, or when trying to read or write the
argument file descriptors;
the graphics error function (see
.IR graphics (3))
is called when this happens.
.SH "SEE ALSO"
.IR bitmap (6),
.IR graphics (3),
.IR bitblt (3).
wily-0.13.42/Doc/sam/keyboard.4 0000644 0236657 0000012 00000007742 10333201523 0015660 0 ustar 00oz staff 0000433 0000002 .de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.TH KEYBOARD 4
.SH NAME
keyboard \- how to type characters
.SH DESCRIPTION
Keyboards are idiosyncratic.
It should be obvious how to type ordinary
.SM ASCII
characters,
backspace, tab, escape, and newline.
In general, the key labeled
.B Return
or
.B Enter
generates a newline
.RB ( 0x0A );
if there is a key labeled
.B Line
.BR Feed ,
it generates a carriage return
.RB ( 0x0D );
CRLFs are not used.
All control characters are typed in the usual way;
in particular, control-J is a line feed and control-M a carriage return.
.PP
The delete character
.RB ( 0x7F )
is usually generated by a key labeled
.BI Del ,
.BI Delete ,
or
.BI Int .
.PP
The view character
.RB ( 0x80 ),
.IR sam (1),
and
.IR 9term (1),
causes windows to scroll forward;
the back-view character
.RB ( 0x81 ),
causes windows to scroll backward.
The view character is generated by the
\(<- and \(da keys; the back-view character
is generated by the \(-> and \(ua keys.
.PP
Internally, characters are represented as runes (see
.IR utf (4)).
Any 16-bit rune can be typed as a multi-character sequence.
The compose key must be pressed while the first character
of the sequence is typed; on most terminals, the compose key
is labeled
.BI Alt .
While pressing the compose key, type a capital
.L X
and exactly four hexadecimal characters (digits and
.L a
to
.LR f )
to enter the rune with the value represented by
the typed number.
There are two-character shorthands for some characters. The
compose key must be pressed while typing the first character
of the pair. The following sequences
generate the desired rune:
.IP
.EX
.ta 10n +12n +10n +12n +10n +12n +10n +12n +10n
\(I! !! \(ct c$ \(po l$ \(gc g$
\($J y$ \(| || \(sc SS \(.. ""
\(co cO \(Fo sa \(d< << \(no no
[0xad] -- \(rg rO \(ma __ \(de de
\(+- +- \(s2 s2 \(s3 s3 \(aa ''
[0xb5] mi \(pp pg \(cp .. \(cd ,,
\(s1 s1 \(Mo s0 \(d> >> \(14 14
\(12 12 \(34 34 \(I? ?? \(`A `A
\('A 'A \(^A ^A \(~A ~A \("A "A
\(oA oA \(AE AE \(,C ,C \(`E `E
\('E 'E \(^E ^E \("E "E \(`I `I
\('I 'I \(^I ^I \("I "I \(D- D-
\(~N ~N \(`O `O \('O 'O \(^O ^O
\(~O ~O \("O "O \(mu mu \(O/ /O
\(`U `U \('U 'U \(^U ^U \("U "U
\('Y 'Y \(|P |P \(ss ss \(`a `a
\('a 'a \(^a ^a \(~a ~a \("a "a
\(oa oa \(ae ae \(,c ,c \(`e `e
\('e 'e \(^e ^e \("e "e \('i `i
\('i 'i \(^i ^i \("i "i \(d- d-
\(~n ~n \(`o `o \('o 'o \(^o ^o
\(~o ~o \("o "o \(di -: \(o/ /o
\(`u `u \('u 'u \(^u ^u \("u "u
\('y 'y \(|p |p \("y "y \(*a *a
\(*b *b \(*g *g \(*d *d \(*e *e
\(*z *z \(*y *y \(*h *h \(*i *i
\(*k *k \(*l *l \(*m *m \(*n *n
\(*c *c \(*o *o \(*p *p \(*r *r
\(ts ts \(*s *s \(*t *t \(*u *u
\(*f *f \(*x *x \(*q *q \(*w *w
\(*A *A \(*B *B \(*G *G \(*D *D
\(*E *E \(*Z *Z \(*Y *Y \(*H *H
\(*I *I \(*K *K \(*L *L \(*M *M
\(*N *N \(*C *C \(*O *O \(*P *P
\(*R *R \(*S *S \(*T *T \(*U *U
\(*F *F \(*X *X \(*Q *Q \(*W *W
\(<- <- \(ua ua \(-> -> \(da da
\(<> ab \(fa fa \(te te \(pd pd
\(es es [0x2206] De \(gr gr \(!m !m
[0x220d] st \(** ** \(bu bu \(sr sr
\(pt pt \(if if \(ag an \(an l&
\(lo l| \(ca ca \(cu cu \(is is
\(tf tf [0x2243] ~= \(~= cg [0x2248] ~~
\(!= != \(== == \(<= <= \(>= >=
\(sb sb \(sp sp \(!s !b \(ib ib
\(ip ip \(a+ O+ [0x2296] O- \(ax Ox
[0x22a2] tu [0x22a8] Tu [0x22c4] lz \(el el
.EE
.PP
Note the difference between \(ss (ss) and [0xb5] (micron) and
the Greek \(*b and \(*m.
As well, white and black chess pieces may be escaped using the sequence
color
.RB ( w
or
.BR b )
followed by piece
.RB ( k
for king,
.B q
for queen,
.B r
for rook,
.B n
for knight,
.B b
for bishop, or
.B p
for pawn).
.SH "SEE ALSO"
.IR ascii (5),
.IR sam (1),
.IR 9term (1),
.IR graphics (3),
.IR utf (4)
wily-0.13.42/Doc/sam/graphics.3 0000644 0236657 0000012 00000024624 10333201523 0015655 0 ustar 00oz staff 0000433 0000002 .de F
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de L
.B
.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.de FR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de LR
.BR "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
..
.de CW
.ft B
..
.\" This is gross but it avoids relying on internal implementation details
.\" of the -man macros.
.de TF
.IP "" \w'\fB\\$1\ \ \fP'u
.PD0
..
.de EX
.CW
.nf
..
.de EE
.fi
..
.\" delete above this point if your system has F, L, FR, LR, CW and TF macros
.TH GRAPHICS 3G
.SH NAME
Point, Rectangle, Bitmap, Cursor, xtbinit, bclose, berror, bscreenrect, bflush, clipr, cursorswitch, cursorset, rdfontfile, ffree, charwidth, getsubfont, mkfont, scrollfwdbut \- graphics
.SH SYNOPSIS
.nf
.PP
.B
#include
.B
#include
.PP
.ta \w'\fLRectangle 'u
.B
void xtbinit(void (*errfun)(char *), char *class, int *pargc,
.B
char **argv, char **fallbacks)
.PP
.B
void bclose(void)
.PP
.B
void berror(char *msg)
.PP
.B
Rectangle bscreenrect(Rectangle *clipr)
.PP
.B
void bflush(void)
.PP
.B
int clipr(Bitmap *b, Rectangle cr)
.PP
.B
void cursorswitch(Cursor *curs)
.PP
.B
void cursorset(Point p)
.PP
.B
Font* rdfontfile(char *name, int ldepth)
.PP
.B
void ffree(Font *f)
.PP
.B
int charwidth(Font *f, Rune r)
.PP
.B
Subfont *getsubfont(char *name)
.PP
.B
Font *mkfont(Subfont *subfont);
.PP
.B
int scrollfwdbut(void);
.PP
.B
extern Bitmap screen
.PP
.B
extern Font *font
.fi
.SH DESCRIPTION
A
.B Point
is a location in a bitmap
(see below),
such as the screen, and is defined as:
.IP
.EX
.ta 6n
typedef
struct Point {
int x;
int y;
} Point;
.EE
.PP
The coordinate system has
.I x
increasing to the right and
.I y
increasing down.
.PP
A
.B Rectangle
is a rectangular area in a bitmap.
.IP
.EX
.ta 6n
typedef
struct Rectangle {
Point min; /* upper left */
Point max; /* lower right */
} Rectangle;
.EE
.PP
By definition,
.B min.x <= max.x
and
.BR "min.y <= max.y" .
By convention, the right (maximum
.IR x )
and bottom (maximum
.IR y )
edges are
excluded from the represented rectangle, so abutting rectangles have no
points in common.
Thus,
.B max
contains the coordinates of the first point beyond the rectangle.
.PP
A
.B Bitmap
holds a rectangular image.
.IP
.EX
.ta 6n +\w'Rectangle 'u +\w'ldepth; 'u
typedef
struct Bitmap {
Rectangle r; /* rectangle in data area, local coords */
Rectangle clipr; /* clipping region */
int ldepth; /* log base 2 of number of bits per pixel */
int id; /* id as known in the X server */
Bitmap* cache; /* zero; distinguishes bitmap from layer */
int flag; /* flag used by X implementation of libg */
} Bitmap;
.EE
.PP
.B R.min
is the location in the bitmap
of the upper-leftmost point in the image.
There are
.if t .I 2\u\s8ldepth\s10\d
.if n 2^ldepth
contiguous bits for each pixel of the image;
the bits form a binary number giving the pixel value.
.L Clipr
is the clipping rectangle; typically it is the same as
.B r
except in a window, where it is inset by the width of
the border.
Graphical operations on the
.B Bitmap
will be confined to the clipping rectangle.
The subroutine
.I Clipr
sets the clipping rectangle of
.B b
to the intersection of
.B cr
and
.BR b->r .
If
.I cr
does not intersect
.BR b->r
it does nothing.
.I Clipr
returns 1 if the clipping region was set,
0 if it was not.
.PP
A
.B Font
is a set of character images, indexed by runes (see
.IR utf (4)).
The images are organized into
.BR Subfont s,
each containing the images for a small, contiguous set of runes.
.B Font
and
.B Subfont
structures contain two related fields:
.LR ascent ,
the distance from the top of the highest character
(actually the top of the bitmap holding all the characters)
to the baseline,
and
.LR height ,
the distance from the top of the highest character to the bottom of
the lowest character (and hence, the interline spacing).
The width of any particular character
.L r
in a font is returned by
.IR charwidth.
The width is defined as the amount to add to the horizontal position
after drawing the character.
.I Charwidth
calls the graphics error function if
.B r
is zero (NUL) because
.B string
(see
.IR bitblt (3))
cannot draw a NUL.
The other fields are used internally by the text-drawing functions.
See
.IR cachechars (3)
for a detailed description.
.PP
.I Rdfontfile
reads the font description in file
.I name
and returns a pointer that can by used by
.I string
(see
.IR bitblt (3))
to draw characters from the font.
The
.I ldepth
argument specifies how characters will be cached; it should usually
be the ldepth of the bitmap that will most often be the target of
.IR string .
[
.I ldepth
is unused in the X implementation of libg.]
.I Ffree
frees a font.
The convention for naming font files is:
.IP
.B \fIfontdir\fP/\fIname\fP.\fIrange\fP.\fIsize\fP.font
.PD
.PP
where
.I size
is approximately the height in pixels of the lower case letters
(without ascenders or descenders).
.I Range
gives some indication of which characters will be available: for example
.BR ascii ,
.BR latin1 ,
.BR euro ,
or
.BR unicode .
.B Euro
includes most European languages, punctuation marks, the International Phonetic
Alphabet, etc., but no Oriental languages.
.B Unicode
includes every character for which images exist on the system.
.PP
A font is selected by notifying the X server of the location
of the subfonts and then specifying the desired font file.
The directory containing the subfonts must be added to the
server's font search path using the
.B xset
command. For example,
.PP
.EX
xset +fp /usr/local/p9snf
.EE
.PP
adds the directory
.B /usr/local/p9snf
to the font search path.
The
.B p9font
resource contains the full path name
of the desired font file; it is usually specified in the
.B .Xdefaults
or
.B .xrdb
startup file. For example,
the entry:
.PP
.EX
*p9font: /n/pyxis/usr/local/p9fonts/pelm.unicode.9.font
.EE
.PP
selects the 9-point Pellucida Modern unicode font.
.PP
A
.I Cursor
is defined:
.IP
.EX
.ta 6n +\w'Point 'u
typedef struct
Cursor {
Point offset;
uchar clr[2*16];
uchar set[2*16];
} Cursor;
.EE
.PP
The arrays are arranged in rows, two bytes per row, left to
right in big-endian order to give 16 rows
of 16 bits each.
A cursor is displayed on the screen by adding
.B offset
to the current mouse position, using
.B clr
as a mask to zero the pixels where
.B clr
is 1, and then setting pixels to ones where
.B set
is one.
.PP
The function
.I xtbinit
should be called before using any graphics operations.
The
.I errfun
argument is a function that will be called with an error message
argument when the graphics functions detect an error;
such an error function should not return.
A zero for the
.I errfun
argument means use
.IR berror ,
which prints the message and exits.
The
.I class
argument is the name of the class of X application, or zero to
use the capitalized version of the program name.
The
.I pargc
and
.I argv
arguments should be a pointer to the main program's
.I argc
and
.IR argv ;
any standard toolkit options in the argument list will be used
to initialize the window's options, and after
.I xtbinit
returns, those options will have been removed from the argument list.
The
.I fallbacks
argument, when non-null, specifies a list of fallback resources
for the application.
.B Xtbinit
sets up the global
.I screen
to be a bitmap describing the area of the screen that the program
can use.
.I Xtbinit
also initializes the global default
.IR font .
By default,
.I xtbinit
does not install the standard Plan 9 colourmap, see
.IR rgbpix (3).
.PP
.I Bclose
releases the resources allocated by
.I xtbinit
and the other graphics functions.
It usually isn't necessary, since the resources will be released
on program exit. [
.I Bclose
is currently unimplemented.]
.PP
The
.IB screen .r
field is not guaranteed to be always accurate; the
.I bscreenrect
function returns the current size
(see
.IR event (3)
to see how to get reshape notification).
.PP
The mouse cursor is always displayed.
The initial cursor is an arrow.
.I Cursorswitch
causes the argument cursor to be displayed instead.
A zero argument causes a switch back to the arrow cursor.
.I Cursorset
moves the mouse cursor to position
.I p,
provided (if in a window) that the requesting program is
executing in the current window and the mouse is within
the window boundaries; otherwise
.I cursorset
is a no-op.
.PP
The graphics functions described in
.IR bitblt (3)
and
.IR balloc (3)
are implemented by writing commands to the X server;
the writes are buffered, so the functions may not take effect immediately.
.I Bflush
flushes the buffer, doing all pending graphics operations.
.I Xtbinit
arranges that
.I bflush
will be called on exit,
and the following graphics functions all cause a flush:
.IR balloc ,
.IR bfree ,
.IR bscreenrect ,
.IR cursorset ,
.IR cursorswitch ,
.IR ecankbd ,
.IR ecanmouse ,
.IR ekbd ,
.IR emouse ,
.IR event ,
.IR rdbitmap ,
and
.IR wrbitmap .
.PP
.I Getsubfont
attempts to load the font given by
.IR name ;
it returns a pointer to a
.B Subfont
struct if it succeeds, zero otherwise,
see
.IR font (4).
The subfont returned by
.I getsubfont
may be passed to
.I mkfont
to generate a
.B Font
suitable for use in
.IR string .
.PP
.I Scrollfwdbut
returns 3 or 1 depending on which buttons is to be used
as the forward scrolling button on the mouse.
The default is to return 3.
.SH "X DEFAULTS"
LibXg understands all of the core X Toolkit resource names and
classes as well as:
.TP 8
.B "p9font (\fPclass\fB P9font)"
Specifies the path name of a font file.
If the file does not exist or is not a properly formatted
font file, the default X11 font directory is searched for an
X11 font of the same name.
.TP 8
.B "composeMod (\fPclass\fB ComposeMod)"
Specifies the modifier key to be used in composing characters.
The integers 1 to 5 correspond to using modifier keys 1 to 5.
When this resource is non-zero it is only necessary to press the
compose modifier once before beginning a compose sequence, i.e.,
it need not be held down for any of the characters in the sequence.
A zero for
.B composeMod
means use modifier key 1 and this key must be held down in conjuction
with the first key of the sequence.
.TP 8
.B "scrollForwardR (\fPclass\fB ScrollForwardR)"
The value
.I true
for this resource
reverses the value returned by
.IR scrollfwdbut ,
i.e., it returns 3 instead of 1.
This reverses the scroll direction selected by clicks of the left or
right mouse buttons in the scrollbar.
.SH "SEE ALSO"
.IR add (3),
.IR balloc (3),
.IR cachechars (3),
.IR bitblt (3),
.IR event (3),
.IR frame (3),
.IR rgbpix (3),
.IR bitmap (4),
.IR font (4).
.SH DIAGNOSTICS
An error function may call
.IR errstr (2)
for further diagnostics.
wily-0.13.42/Doc/sam/sam.tut.ms 0000644 0236657 0000012 00000116472 10333201523 0015730 0 ustar 00oz staff 0000433 0000002 .de P1
.KS
.DS
.ft CW
.ta 5n 10n 15n 20n 25n 30n 35n 40n 45n 50n 55n 60n 65n 70n 75n 80n
..
.de P2
.ft 1
.DE
.KE
..
.de CW
.lg 0
\%\&\\$3\fB\\$1\fP\&\\$2
.lg
..
.de WC
.lg 0
\%\&\\$3\fI\\$1\fP\&\\$2
.lg
..
.TL
A tutorial for the
.CW sam
.B
command language
.AU
Rob Pike
.AI
.MH
.AB
.CW sam
is an interactive text editor with a command language that makes heavy use
of regular expressions.
Although the language is syntactically similar to
.CW ed (1),
the details are interestingly different.
This tutorial introduces the command language, but does not discuss
the screen and mouse interface.
With apologies to those unfamiliar with the Ninth Edition Blit software,
it is assumed that the similarity of
.CW sam
to
.CW mux (9)
at this level makes
.CW sam 's
mouse language easy to learn.
.PP
The
.CW sam
command language applies identically to two environments:
when running
.CW sam
on an ordinary terminal
(\f2via\f1\f1
.CW sam\ -d ),
and in the command window of a
.I downloaded
.CW sam ,
that is, one using the bitmap display and mouse.
.AE
.SH
Introduction
.PP
This tutorial describes the command language of
.CW sam ,
an interactive text editor that runs on Blits and
some computers with bitmap displays.
For most editing tasks, the mouse-based editing features
are sufficient, and they are easy to use and to learn.
.PP
The command language is often useful, however, particularly
when making global changes.
Unlike the commands in
.CW ed ,
which are necessary to make changes,
.CW sam
commands tend to be used
only for complicated or repetitive editing tasks.
It is in these more involved uses that
the differences between
.CW sam
and other text editors are most evident.
.PP
.CW sam 's
language makes it easy to do some things that other editors,
including programs like
.CW sed
and
.CW awk ,
do not handle gracefully, so this tutorial serves partly as a
lesson in
.CW sam 's
manner of manipulating text.
The examples below therefore concentrate entirely on the language,
assuming that facility with the use of the mouse in
.CW sam
is at worst easy to pick up.
In fact,
.CW sam
can be run without the mouse at all (not
.I downloaded ),
by specifying the
.CW -d
flag, and it is this domain that the tutorial
occupies; the command language in these modes
are identical.
.PP
A word to the Unix adept:
although
.CW sam
is syntactically very similar to
.CW ed ,
it is fundamentally and deliberately different in design and detailed semantics.
You might use knowledge of
.CW ed
to predict how the substitute command works,
but you'd only be right if you had used some understanding of
.CW sam 's
workings to influence your prediction.
Be particularly careful about idioms.
Idioms form in curious nooks of languages and depend on
undependable peculiarities.
.CW ed
idioms simply don't work in
.CW sam :
.CW 1,$s/a/b/
makes one substitution in the whole file, not one per line.
.CW sam
has its own idioms.
Much of the purpose of this tutorial is to publish them
and make fluency in
.CW sam
a matter of learning, not cunning.
.PP
The tutorial depends on familiarity with regular expressions, although
some experience with a more traditional Unix editor may be helpful.
To aid readers familiar with
.CW ed ,
I have pointed out in square brackets [] some of
the relevant differences between
.CW ed
and
.CW sam .
Read these comments only if you wish
to understand the differences; the lesson is about
.CW sam ,
not
.CW sam
.I vs.
.CW ed .
Another typographic convention is that output appears in
.CW "this font,
while typed input appears as
.WC "slanty text.
.PP
Nomenclature:
.CW sam
keeps a copy of the text it is editing.
This copy is called a
.I file .
To avoid confusion, I have called the permanent storage on disc a
.I
Unix file.
.R
.SH
Text
.PP
To get started, we need some text to play with.
Any text will do; try something from
James Gosling's Emacs manual:
.P1
$ \fIsam -d
a
This manual is organized in a rather haphazard manner. The first
several sections were written hastily in an attempt to provide a
general introduction to the commands in Emacs and to try to show
the method in the madness that is the Emacs command structure.
\&.
.ft
.P2
.WC "sam -d
starts
.CW sam
running.
The
.CW a
command adds text until a line containing just a period, and sets the
.I
current text
.R
(also called
.I dot )
to what was typed \(em everything between the
.CW a
and the period.
.CW ed "" [
would leave dot set to only the last line.]
The
.CW p
command prints the current text:
.P1
.WC p
This manual is organized in a rather haphazard manner. The first
several sections were written hastily in an attempt to provide a
general introduction to the commands in Emacs and to try to show
the method in the madness that is the Emacs command structure.
.P2
[Again,
.CW ed
would print only the last line.]
The
.CW a
command adds its text
.I after
dot; the
.CW i
command is like
.CW a,
but adds the text
.I before
dot.
.P1
.ft I
i
Introduction
\&.
p
.ft
Introduction
.P2
There is also a
.CW c
command that changes (replaces) the current text,
and
.CW d
that deletes it; these are illustrated below.
.PP
To see all the text, we can specify what text to print;
for the moment, suffice it to say that
.WC 0,$
specifies the entire file.
.CW ed "" [
users would probably type
.WC 1,$ ,
which in practice is the same thing, but see below.]
.P1
.WC 0,$p
Introduction
This manual is organized in a rather haphazard manner. The first
several sections were written hastily in an attempt to provide a
general introduction to the commands in Emacs and to try to show
the method in the madness that is the Emacs command structure.
.P2
Except for the
.CW w
command described below,
.I all
commands,
including
.CW p ,
set dot to the text they touch.
Thus,
.CW a
and
.CW i
set dot to the new text,
.CW p
to the text printed, and so on.
Similarly, all commands
(except
.CW w )
by default operate on the current
text [unlike
.CW ed ,
for which some commands (such as
.CW g )
default to the entire file].
.PP
Things are not going to get very interesting until we can
set dot arbitrarily.
This is done by
.I addresses ,
which specify a piece of the file.
The address
.CW 1 ,
for example, sets dot to the first line of the file.
.P1
.WC 1p
Introduction
.WC c
.WC Preamble
.WC .
.P2
The
.CW c
command didn't need to specify dot; the
.CW p
left it on line one.
It's therefore easy to delete the first line utterly;
the last command left dot set to line one:
.P1
.WC d
.WC 1p
This manual is organized in a rather haphazard manner. The first
.P2
(Line numbers change
to reflect changes to the file.)
.PP
The address \f(CW/\f2text\f(CW/\f1
sets dot to the first appearance of
.I text ,
after dot.
.CW ed "" [
matches the first line containing
.I text .]
If
.I text
is not found, the search restarts at the beginning of the file
and continues until dot.
.P1
.WC /Emacs/p
Emacs
.P2
It's difficult to indicate typographically, but in this example no newline appears
after
.CW Emacs :
the text to be printed is the string
.CW Emacs ', `
exactly.
(The final
.CW p
may be left off \(em it is the default command.
When downloaded, however, the default is instead to select the text,
to highlight it,
and to make it visible by moving the window on the file if necessary.
Thus,
.CW /Emacs/
indicates on the display the next occurrence of the text.)
.PP
Imagine we wanted to change the word
.CW haphazard
to
.CW thoughtless .
Obviously, what's needed is another
.CW c
command, but the method used so far to insert text includes a newline.
The syntax for including text without newlines is to surround the
text with slashes (which is the same as the syntax for
text searches, but what is going on should be clear from context).
The text must appear immediately after the
.CW c
(or
.CW a
or
.CW i ).
Given this, it is easy to make the required change:
.P1
.WC /haphazard/c/thoughtless/
1p
This manual is organized in a rather thoughtless manner. The first
.P2
[Changes can always be done with a
.CW c
command, even if the text is smaller than a line].
You'll find that this way of providing text to commands is much
more common than is the multiple-lines syntax.
If you want to include a slash
.CW /
in the text, just precede it with a backslash
.CW \e ,
and use a backslash to protect a backslash itself.
.P1
.WC /Emacs/c/Emacs\e\e360/
.WC 4p
general introduction to the commands in Emacs\e360 and to try to show
.P2
We could also make this particular change by
.P1
.WC /Emacs/a/\e\e360/
.P2
.PP
This is as good a place as any to introduce the
.CW u
command, which undoes the last command.
A second
.CW u
will undo the penultimate command, and so on.
.P1
.WC u
.WC 4p
general introduction to the commands in Emacs and to try to show
.WC u
.WC 3p
This manual is organized in a rather haphazard manner. The first
.P2
Undoing can only back up; there is no way to undo a previous
.CW u .
.SH
Addresses
.PP
We've seen the simplest forms of addresses, but there is more
to learn before we can get too much further.
An address selects a region in the file \(em a substring \(em
and therefore must define the beginning and the end of a region.
Thus, the address
.CW 13
selects from the beginning of line thirteen to the end of line thirteen, and
.CW /Emacs/
selects from the beginning of the word
.CW Emacs ' `
to the end.
.PP
Addresses may be combined with a comma:
.P1
13,15
.P2
selects lines thirteen through fifteen. The definition of the comma
operator is to select from the beginning of the left hand address (the
beginning of line 13) to the end of the right hand address (the
end of line 15).
.PP
A few special simple addresses come in handy:
.CW .
(a period) represents dot, the current text,
.CW 0
(line zero) selects the null string at the beginning of the file, and
.CW $
selects the null string at the end of the file
[not the last line of the file].
Therefore,
.P1
0,13
.P2
selects from the beginning of the file to the end of line thirteen,
.P1
\&.,$
.P2
selects from the beginning of the current text to the end of the file, and
.P1
0,$
.P2
selects the whole file [that is, a single string containing the whole file,
not a list of all the lines in the file].
.PP
These are all
.I absolute
addresses: they refer to specific places in the file.
.CW sam
also has relative addresses, which depend
on the value of dot,
and in fact we have already seen one form:
.CW /Emacs/
finds the first occurrence of
.CW Emacs
searching forwards from dot.
Which occurrence of
.CW Emacs
it finds depends on the value of dot.
What if you wanted the first occurrence
.CW before
dot? Just precede the pattern with a minus sign, which reverses the direction
of the search:
.P1
-/Emacs/
.P2
In fact, the complete syntax for forward searching is
.P1
+/Emacs/
.P2
but the plus sign is the default, and in practice is rarely used.
Here is an example that includes it for clarity:
.P1
0+/Emacs/
.P2
selects the first occurrence of
.CW Emacs
in the file; read it as ``go to line 0, then search forwards for
.CW Emacs .''
Since the
.CW +
is optional, this can be written
.CW 0/Emacs/ .
Similarly,
.P1
$-/Emacs/
.P2
finds the last occurrence in the file, so
.P1
0/Emacs/,$-/Emacs/
.P2
selects the text from the first to last
.CW Emacs ,
inclusive.
Slightly more interesting:
.P1
/Emacs/+/Emacs/
.P2
(there is an implicit
.CW .+
at the beginning) selects the second
.CW Emacs
following dot.
.PP
Line numbers may also be relative.
.P1
-2
.P2
selects the second previous line, and
.P1
+5
.P2
selects the fifth following line (here the plus sign is obligatory).
.PP
Since addresses may select (and dot may be) more than one line,
we need a definition of `previous' and `following:'
`previous' means
.I
before the beginning
.R
of dot, and `following'
means
.I
after the end
.R
of dot.
For example, if the file contains \fBA\fIAA\fBA\f1,
with dot set to the middle two
.CW A 's
(the slanting characters),
.CW -/A/
sets dot to the first
.CW A ,
and
.CW +/A/
sets dot to the last
.CW A .
Except under odd circumstances (such as when the only occurrence of the
text in the file is already the current text), the text selected by a
search will be disjoint from dot.
.PP
To select the
.CW "troff -ms
paragraph containing dot, however long it is, use
.P1
-/.PP/,/.PP/-1
.P2
which will include the
.CW .PP
that begins the paragraph, and exclude the one that ends it.
.PP
When typing relative line number addresses, the default number is
.CW 1 ,
so the above could be written slightly more simply:
.P1
-/.PP/,/.PP/-
.P2
.PP
What does the address
.CW +1-1
or the equivalent
.CW +-
mean? It looks like it does nothing, but recall that dot need not be a
complete line of text.
.CW +1
selects the line after the end of the current text, and
.CW -1
selects the line before the beginning. Therefore
.CW +1-1
selects the line before the line after the end of dot, that is,
the complete line containing the end of dot.
We can use this construction to expand a selection to include a complete line,
say the first line in the file containing
.CW Emacs :
.P1
.WC 0/Emacs/+-p
general introduction to the commands in Emacs and to try to show
.P2
The address
.CW +-
is an idiom.
.SH
Loops
.PP
Above, we changed one occurrence of
.CW Emacs
to
.CW Emacs\e360 ,
but if the name of the editor is really changing, it would be useful
to change
.I all
instances of the name in a single command.
.CW sam
provides a command,
.CW x
(extract), for just that job.
The syntax is
\f(CWx/\f2pattern\f(CW/\f2command\f1.
For each occurrence of the pattern in the selected text,
.CW x
sets dot to the occurrence and runs command.
For example, to change
.CW Emacs
to
.CW vi,
.P1
.WC 0,$x/Emacs/c/vi/
.WC 0,$p
This manual is organized in a rather haphazard manner. The first
several sections were written hastily in an attempt to provide a
general introduction to the commands in vi and to try to show
the method in the madness that is the vi command structure.
.P2
This
works by subdividing the current text
.CW 0,$ "" (
\(em the whole file) into appearances of its textual argument
.CW Emacs ), (
and then running the command that follows
.CW c/vi/ ) (
with dot set to the text.
We can read this example as, ``find all occurrences of
.CW Emacs
in the file, and for each one,
set the current text to the occurrence and run the command
.CW c/vi/ ,
which will replace the current text by
.CW vi. ''
[This command is somewhat similar to
.CW ed 's
.CW g
command. The differences will develop below, but note that the
default address, as always, is dot rather than the whole file.]
.PP
A single
.CW u
command is sufficient to undo an
.CW x
command, regardless of how many individual changes the
.CW x
makes.
.P1
.WC u
.WC 0,$p
This manual is organized in a rather haphazard manner. The first
several sections were written hastily in an attempt to provide a
general introduction to the commands in Emacs and to try to show
the method in the madness that is the Emacs command structure.
.P2
.PP
Of course,
.CW c
is not the only command
.CW x
can run. An
.CW a
command can be used to put proprietary markings on
.CW Emacs :
.P1
.WC 0,$x/Emacs/a/{TM}/
.WC /Emacs/+-p
general introduction to the commands in Emacs{TM} and to try to show
.P2
[There is no way to see the changes as they happen, as in
.CW ed 's
.CW g/Emacs/s//&{TM}/p ;
see the section on Multiple Changes, below.]
.PP
The
.CW p
command is also useful when driven by an
.CW x ,
but be careful that you say what you mean;
.P1
.WC 0,$x/Emacs/p
EmacsEmacs
.P2
since
.CW x
sets dot to the text in the slashes, printing only that text
is not going to be very
informative. But the command that
.CW x
runs can contain addresses. For example, if we want to print all
lines containing
.CW Emacs ,
just use
.CW +- :
.P1
.WC 0,$x/Emacs/+-p
general introduction to the commands in Emacs{TM} and to try to show
the method in the madness that is the Emacs{TM} command structure.
.P2
Finally, let's restore the state of the file with another
.CW x
command, and make use of a handy shorthand:
a comma in an address has its left side default to
.CW 0 ,
and its right side default to
.CW $ ,
so the easy-to-type address
.CW ,
refers to the whole file:
.P1
.WC ",x/Emacs/ /{TM}/d
.WC ,p
This manual is organized in a rather haphazard manner. The first
several sections were written hastily in an attempt to provide a
general introduction to the commands in Emacs and to try to show
the method in the madness that is the Emacs command structure.
.P2
Notice what this
.CW x
does: for each occurrence of Emacs,
find the
.CW {TM}
that follows, and delete it.
.PP
The `text'
.CW sam
accepts
for searches in addresses and in
.CW x
commands is not simple text, but rather
.I regular\ expressions.
Unix has several distinct interpretations of regular expressions.
The form used by
.CW sam
is that of
.CW regexp (6),
including parentheses
.CW ()
for grouping and an `or' operator
.CW |
for matching strings in parallel.
.CW sam
also matches the character sequence
.CW \en
with a newline character.
Replacement text, such as used in the
.CW a
and
.CW c
commands, is still plain text, but the sequence
.CW \en
represents newline in that context, too.
.PP
Here is an example. Say we wanted to double space the document, that is,
turn every newline into two newlines.
The following all do the job:
.P1
.WC ",x/\en/ a/\en/
.WC ",x/\en/ c/\en\en/
.WC ",x/$/ a/\en/
.WC ",x/^/ i/\en/
.P2
The last example is slightly different, because it puts a newline
.I before
each line; the other examples place it after.
The first two examples manipulate newlines directly
[something outside
.CW ed 's
ken]; the last two
use regular expressions:
.CW $
is the empty string at the end of a line, while
.CW ^
is the empty string at the beginning.
.PP
These solutions all have a possible drawback: if there is already a blank line
(that is, two consecutive newlines), they make it much larger (four
consecutive newlines).
A better method is to extend every group of newlines by one:
.P1
.WC ",x/\en+/ a/\en/
.P2
The regular expression operator
.CW +
means `one or more;'
.CW \en+
is identical to
.CW \en\en* .
Thus, this example
takes every sequence of newlines and adds another
to the end.
.PP
A more common example is indenting a block of text by a tab stop.
The following all work,
although the first is arguably the cleanest (the blank text in slashes is a tab):
.P1
.WC ",x/^/a/ /
.WC ",x/^/c/ /
.WC ",x/.*\en/i/ /
.P2
The last example uses the pattern (idiom, really)
.CW .*\en
to match lines:
.CW .*
matches the longest possible string of non-newline characters.
Taking initial tabs away is just as easy:
.P1
.WC ",x/^ /d
.P2
In these examples I have specified an address (the whole file), but
in practice commands like these are more likely to be run without
an address, using the value of dot set by selecting text with the mouse.
.SH
Conditionals
.PP
The
.CW x
command is a looping construct:
for each match of a regular expression,
it extracts (sets dot to) the match and runs a command.
.CW sam
also has a conditional,
.CW g :
\f(CWg/\f2pattern\f(CW/\f2command\f1
runs the command if dot contains a match of the pattern
.I
without changing the value of dot.
.R
The inverse,
.CW v ,
runs the command if dot does
.I not
contain a match of the pattern.
(The letters
.CW g
and
.CW v
are historical and have no mnemonic significance. You might
think of
.CW g
as `guard.')
.CW ed "" [
users should read the above definitions very carefully; the
.CW g
command in
.CW sam
is fundamentally different from that in
.CW ed .]
Here is an example of the difference between
.CW x
and
.CW g:
.P1
,x/Emacs/c/vi/
.P2
changes each occurrence of the word
.CW Emacs
in the file to the word
.CW vi ,
but
.P1
,g/Emacs/c/vi/
.P2
changes the
.I "whole file
to
.CW vi
if there is the word
.CW Emacs
anywhere in the file.
.PP
Neither of these commands is particularly interesting in isolation,
but they are valuable when combined with
.CW x
and with themselves.
.SH
Composition
.PP
One way to think about the
.CW x
command is that, given a selection (a value of dot)
it iterates through interesting subselections (values of dot within).
In other words, it takes a piece of text and cuts it into smaller pieces.
But the text that it cuts up may already be a piece cut by a previous
.CW x
command or selected by a
.CW g .
.CW sam 's
most interesting property is the ability to define a sequence of commands
to perform a particular task.\(dg
.FS
\(dg
The obvious analogy with shell pipelines is only partially valid,
because the individual
.CW sam
commands are all working on the same text; it is only how the text is
sliced up that is changing.
.FE
A simple example is to change all occurrences of
.CW Emacs
to
.CW emacs ;
certainly the command
.P1
.WC ",x/Emacs/ c/emacs/
.P2
will work, but we can use an
.CW x
command to save retyping most of the word
.CW Emacs :
.P1
.WC ",x/Emacs/ x/E/ c/e/
.P2
(Blanks can be used
to separate commands on a line to make them easier to read.)
What this command does is find all occurrences of
.CW Emacs
.CW ,x/Emacs/ ), (
and then
.I
with dot set to that text,
.R
find all occurrences of the letter
.CW E
.CW x/E/ ), (
and then
.I
with dot set to that text,
.R
run the command
.CW c/e/
to change the character to lower case.
Note that the address for the command \(em the whole file, specified by a comma
\(em is only given to the leftmost
piece of the command; the rest of the pieces have dot set for them by
the execution of the pieces to their left.
.PP
As another simple example, consider a problem
solved above: printing all lines in the file containing the word
.CW Emacs:
.P1
.WC ",x/.*\en/ g/Emacs/p
general introduction to the commands in Emacs and to try to show
the method in the madness that is the Emacs command structure.
.P2
This command says to break the file into lines
.CW ,x/.*\en/ ), (
and for each line that contains the string
.CW Emacs
.CW g/Emacs/ ), (
run the command
.CW p
with dot set to the line (not the match of
.CW Emacs ),
which prints the line.
To save typing, because
.CW .*\en
is a common pattern in
.CW x
commands,
if the
.CW x
is followed immediately by a space, the pattern
.CW .*\en
is assumed.
Therefore, the above could be written more succinctly:
.P1
.WC ",x g/Emacs/p
.P2
The solution we used before was
.P1
.WC ,x/Emacs/+-p
.P2
which runs the command
.CW +-p
with dot set to each match of
.CW Emacs
in the file (recall that the idiom
.CW +-p
prints the line containing the end of dot).
.PP
The two commands usually produce the same result
(the
.CW +-p
form will print a line twice if it contains
.CW Emacs
twice). Which is better?
.CW ,x/Emacs/+-p
is easier to type and will be much faster if the file is large and
there are few occurrences of the string, but it is really an odd special case.
.CW ",x/.*\en/ g/Emacs/p
is slower \(em it breaks each line out separately, then examines
it for a match \(em but is conceptually cleaner, and generalizes more easily.
For example, consider the following piece of the Emacs manual:
.P1
command name="append-to-file", key="[unbound]"
Takes the contents of the current buffer and appends it to the
named file. If the file doesn't exist, it will be created.
command name="apropos", key="ESC-?"
Prompts for a keyword and then prints a list of those commands
whose short description contains that keyword. For example,
if you forget which commands deal with windows, just type
"@b[ESC-?]@t[window]@b[ESC]".
\&\f2and so on\f(CW
.P2
This text consists of groups of non-empty lines, with a simple format
for the text within each group.
Imagine that we wanted to find the description of the `apropos'
command.
The problem is to break the file into individual descriptions,
and then to find the description of `apropos' and to print it.
The solution is straightforward:
.P1
.WC ,x/(.+\en)+/\ g/command\ name="apropos"/p
command name="apropos", key="ESC-?"
Prompts for a keyword and then prints a list of those commands
whose short description contains that keyword. For example,
if you forget which commands deal with windows, just type
"@b[ESC-?]@t[window]@b[ESC]".
.P2
The regular expression
.CW (.+\en)+
matches one or more lines with one or more characters each, that is,
the text between blank lines, so
.CW ,x/(.+\en)+/
extracts each description; then
.CW g/command\ name="apropos"/
selects the description for `apropos' and
.CW p
prints it.
.PP
Imagine that we had a C program containing the variable
.CW n ,
but we wanted to change it to
.CW num .
This command is a first cut:
.P1
.WC ",x/n/ c/num/
.P2
but is obviously flawed: it will change all
.CW n 's
in the file, not just the
.I identifier
.CW n .
A better solution is to use an
.CW x
command to extract the identifiers, and then use
.CW g
to find the
.CW n 's:
.P1
.WC ",x/[a-zA-Z_][a-zA-Z_0-9]*/ g/n/ v/../ c/num/
.P2
It looks awful, but it's fairly easy to understand when read
left to right.
A C identifier is an alphabetic or underscore followed by zero or more
alphanumerics or underscores, that is, matches of the regular expression
.CW [a-zA-Z_][a-zA-Z_0-9]* .
The
.CW g
command selects those identifiers containing
.CW n ,
and the
.CW v
is a trick: it rejects those identifiers containing more than one
character. Hence the
.CW c/num/
applies only to free-standing
.CW n 's.
.PP
There is still a problem here:
we don't want to change
.CW n 's
that are part of the character constant
.CW \en .
There is a command
.CW y ,
complementary to
.CW x ,
that is just what we need:
\f(CWy/\f2pattern\f(CW/\f2command\f1
runs the command on the pieces of text
.I between
matches of the pattern;
if
.CW x
selects,
.CW y
rejects.
Here is the final command:
.P1
.WC ",y/\e\en/ x/[a-zA-Z_][a-zA-Z_0-9]*/ g/n/ v/../ c/num/
.P2
The
.CW y/\e\en/
(with backslash doubled to make it a literal character)
removes the two-character sequence
.CW \en
from consideration, so the rest of the command will not touch it.
There is more we could do here; for example, another
.CW y
could be prefixed to protect comments in the code.
I won't elaborate the example any further, but you should have
an idea of the way in which the looping and conditional commands
in
.CW sam
may be composed to do interesting things.
.SH
Grouping
.PP
There is another way to arrange commands.
By enclosing them in brace brackets
.CW {} ,
commands may be applied in parallel.
This example uses the
.CW =
command, which reports the line and character numbers of dot,
together with
.CW p ,
to report on appearances of
.CW Emacs
in our original file:
.P1
.WC ,p
This manual is organized in a rather haphazard manner. The first
several sections were written hastily in an attempt to provide a
general introduction to the commands in Emacs and to try to show
the method in the madness that is the Emacs command structure.
.ft I
,x/Emacs/{
=
+-p
}
.ft
3; #171,#176
general introduction to the commands in Emacs and to try to show
4; #234,#239
the method in the madness that is the Emacs command structure.
.P2
(The number before the semicolon is the line number;
the numbers beginning with
.CW #
are character numbers.)
As a more interesting example, consider changing all occurrences of
.CW Emacs
to
.CW vi
and vice versa. We can type
.P1
.ft I
,x/Emacs|vi/{
g/Emacs/ c/vi/
g/vi/ c/Emacs/
}
.ft
.P2
or even
.P1
.ft I
,x/[a-zA-Z]+/{
g/Emacs/ v/....../ c/vi/
g/vi/ v/.../ c/Emacs/
}
.ft
.P2
to make sure we don't change strings embedded in words.
.SH
Multiple Changes
.PP
You might wonder why, once
.CW Emacs
has been changed to
.CW vi
in the above example,
the second command in the braces doesn't put it back again.
The reason is that the commands are run in parallel:
within any top-level
.CW sam
command, all changes to the file refer to the state of the file
before any of the changes in that command are made.
After all the changes have been determined, they are all applied
simultaneously.
.PP
This means, as mentioned, that commands within a compound
command see the state of the file before any of the changes apply.
This method of evaluation makes some things easier (such as the exchange of
.CW Emacs
and
.CW vi ),
and some things harder.
For instance, it is impossible to use a
.CW p
command to print the changes as they happen,
because they haven't happened when the
.CW p
is executed.
An indirect ramification is that changes must occur in forward
order through the file,
and must not overlap.
.SH
Unix
.PP
.CW sam
has a few commands to connect to Unix processes.
The simplest is
.CW ! ,
which runs the command with input and output connected to the terminal.
.P1
.WC !date
Wed May 28 23:25:21 EDT 1986
!
.P2
(When downloaded, the input is connected to
.CW /dev/null
and only the first few lines of output are printed;
any overflow is stored in
.CW $HOME/sam.err .)
The final
.CW !
is a prompt to indicate when the command completes.
.PP
Slightly more interesting is
.CW > ,
which provides the current text as standard input to the Unix command:
.P1
.WC "1,2 >wc
2 22 131
!
.P2
The complement of
.CW >
is, naturally,
.CW < :
it replaces the current text with the standard output of the Unix command:
.P1
.WC "1 :
the current text is provided as standard input to the Unix command,
and the Unix command's standard output is collected and used to
replace the original text.
For example,
.P1
.WC ",| sort
.P2
runs
.CW sort (1)
on the file, sorting the lines of the text lexicographically.
Note that
.CW < ,
.CW >
and
.CW |
are
.CW sam
commands, not Unix shell operators.
.PP
The next example converts all appearances of
.CW Emacs
to upper case using
.CW tr (1):
.P1
.WC ",x/Emacs/ | tr a-z A-Z
.P2
.CW tr
is run once for each occurrence of
.CW Emacs .
Of course, you could do this example more efficiently with a simple
.CW c
command, but here's a trickier one:
given a Unix mail box as input,
convert all the
.CW Subject
headers to distinct fortunes:
.P1
.WC ",x/^Subject:.*\en/ x/[^:]*\en/ < /usr/games/fortune
.P2
(The regular expression
.CW [^:]
refers to any character
.I except
.CW :
and newline; the negation operator
.CW ^
excludes newline from the list of characters.)
Again,
.CW /usr/games/fortune
is run once for each
.CW Subject
line, so each
.CW Subject
line is changed to a different fortune.
.SH
A few other text commands
.PP
For completeness, I should mention three other commands that
manipulate text. The
.CW m
command moves the current text to after the text specified by the
(obligatory) address after the command.
Thus
.P1
.WC "/Emacs/+- m 0
.P2
moves the next line containing
.CW Emacs
to the beginning of the file.
Similarly,
.CW t
(another historic character) copies the text:
.P1
.WC "/Emacs/+- t 0
.P2
would make, at the beginning of the file, a copy of the next line
containing
.CW Emacs .
.PP
The third command is more interesting: it makes substitutions.
Its syntax is
\f(CWs/\f2pattern\f(CW/\f2replacement\f(CW/\f1.
Within the current text, it finds the first occurrence of
the pattern and replaces it by the replacement text,
leaving dot set to the entire address of the substitution.
.P1
.WC 1p
This manual is organized in a rather haphazard manner. The first
.WC s/haphazard/thoughtless/
.WC p
This manual is organized in a rather thoughtless manner. The first
.P2
Occurrences of the character
.CW &
in the replacement text stand for the text matching the pattern.
.P1
.WC s/T/"&&&&"/
.WC p
"TTTT"his manual is organized in a rather thoughtless manner. The first
.P2
There are two variants. The first is that a number may be specified
after the
.CW s ,
to indicate which occurrence of the pattern to substitute; the default
is the first.
.P1
.WC s2/is/was/
.WC p
"TTTT"his manual was organized in a rather thoughtless manner. The first
.P2
The second is that suffixing a
.CW g
(global) causes replacement of all occurrences, not just the first.
.P1
.WC s/[a-zA-Z]/x/g
.WC p
"xxxx"xxx xxxxxx xxx xxxxxxxxx xx x xxxxxx xxxxxxxxxxx xxxxxxx xxx xxxxx
.P2
Notice that in all these examples
dot is left
set to the entire line.
.PP
[The substitute command is vital to
.CW ed,
because it is the only way to make changes within a line.
It is less valuable in
.CW sam ,
in which the concept of a line is much less important.
For example, many
.CW ed
substitution idioms are handled well by
.CW sam 's
basic commands. Consider the commands
.P1
s/good/bad/
s/good//
s/good/& bye/
.P2
which are equivalent in
.CW sam
to
.P1
/good/c/bad/
/good/d
/good/a/ bye/
.P2
and for which the context search is likely unnecessary because the desired
text is already dot.
Also, beware this
.CW ed
idiom:
.P1
1,$s/good/bad/
.P2
which changes the first
.CW good
on each line; the same command in
.CW sam
will only change the first one in the whole file.
The correct
.CW sam
version is
.P1
,x s/good/bad/
.P2
but what is more likely meant is
.P1
,x/good/ c/bad/
.P2
.CW sam
operates under different rules.]
.SH
Files
.PP
So far, we have only been working with a single file,
but
.CW sam
is a multi-file editor.
Only one file may be edited at a time, but
it is easy to change which file is the `current' file for editing.
To see how to do this, we need a
.CW sam
with a few files;
the easiest way to do this is to start it
with a list of Unix file names to edit.
.P1
$ \fIecho *.ms\f(CW
conquest.ms death.ms emacs.ms famine.ms slaughter.ms
$ \fIsam -d *.ms\f(CW
-. conquest.ms
.P2
(I'm sorry the Horsemen don't appear in liturgical order.)
The line printed by
.CW sam
is an indication that the Unix file
.CW conquest.ms
has been read, and is now the current file.
.CW sam
does not read the Unix file until
the associated
.CW sam
file becomes current.
.PP
The
.CW n
command prints the names of all the files:
.P1
.WC n
-. conquest.ms
- death.ms
- emacs.ms
- famine.ms
- slaughter.ms
.P2
This list is also available in the menu on mouse button 3.
The command
.CW f
tells the name of just the current file:
.P1
.WC f
-. conquest.ms
.P2
The characters to the left of the file name encode helpful information about
the file.
The minus sign becomes a plus sign if the file has a window open, and an
asterisk if more than one is open.
The period (another meaning of dot) identifies the current file.
The leading blank changes to an apostrophe if the file is different
from the contents of the associated Unix file, as far as
.CW sam
knows.
This becomes evident if we make a change.
.P1
.WC 1d
.WC f
\&'-. conquest.ms
.P2
If the file is restored by an undo command, the apostrophe disappears.
.P1
.WC u
.WC f
-. conquest.ms
.P2
The file name may be changed by providing a new name with the
.CW f
command:
.P1
.CW "f pestilence.ms
\&'-. pestilence.ms
.P2
.WC f
prints the new status of the file,
that is, it changes the name if one is provided, and prints the
name regardless.
A file name change may also be undone.
.P1
.WC u
.WC f
-. conquest.ms
.P2
.PP
When
.CW sam
is downloaded, the current file may be changed simply by selecting
the desired file from the menu (selecting the same file subsequently
cycles through the windows opened on the file).
Otherwise, the
.CW b
command can be used to choose the desired file:\(dg
.FS
\(dg A bug prevents the
.CW b
command from working when downloaded.
Because the menu is more convenient anyway, and
because the method
of choosing files from the command language is slated to change,
the bug hasn't been fixed.
.FE
.P1
.WC "b emacs.ms
-. emacs.ms
.P2
Again,
.CW sam
prints the name (actually, executes an implicit
.CW f
command) because the Unix file
.CW emacs.ms
is being read for the first time.
It is an error to ask for a file
.CW sam
doesn't know about, but the
.CW B
command will prime
.CW sam 's
menu with a new file, and make it current.
.P1
.WC "b flood.pic
?no such file `flood.pic'
.WC "B flood.pic
-. flood.pic
.WC n
- conquest.ms
- death.ms
- emacs.ms
- famine.ms
-. flood.pic
- slaughter.ms
.P2
Both
.CW b
and
.CW B
will accept a list of file names.
.CW b
simply takes the first file in the list, but
.CW B
loads them all.
The list may be typed on one line \(em
.P1
.WC "B devil.tex satan.tex 666.tex emacs.tex
.P2
\(em or generated by a Unix command \(em
.P1
.WC "B core dump
************ DOCO ***************
list of pointers to unicode software
make it easy to install/use fonts
add "what about a win 3.1/95/NT port" FAQ entry
************ PORTABILITY BUGS ***************
************ IMPORTANT FEATURES ***************
Use empty space when placing new windows (bill)
tab argument use -tab instead of -a
************ FEATURES ***************
persistence (Load/Store)
Check file mod. time, stop you from overwriting changed file
full Sam regexps
full Sam commands
argument to Font
wilyproxy
empty columns should still have a vertical line
tag should indicate if it isn't displaying everything
give tags different background colour
international characters entry
use X11R6 "input extensions"? (schwartz)
extra process monitors (and modifies) inputted text (Steve_Kilbane)
newline in tag on _directory_ could mean 'open that directory'
scrolling tag -- always show RIGHTmost stuff
experiment with DontList _regexp_ to restrict directory listings dir.c:#1227 (Elliott Hughes)
-title option
check out joe: claims:
Joe uses the Boyer-Moore algorithm adapted for segmented blocks. This more
than overcomes the simplicity you would get by having only a single gap.
************ EXPERIMENT ***************
running autosave?
"Get" builtin, like Look but for addresses, perhaps called ':'
wily-0.13.42/Doc/tute/ 0000755 0236657 0000012 00000000000 10333201523 0014162 5 ustar 00oz staff 0000433 0000002 wily-0.13.42/Doc/tute/start 0000644 0236657 0000012 00000022545 10333201523 0015252 0 ustar 00oz staff 0000433 0000002
START HERE
Hello, welcome to wily. Once you've finished this
tutorial you will know nearly all of wily's features, and
hopefully be addicted. Wily is quite different from
any editor you're already familiar with, but it isn't
difficult to learn the wily way.
TERMINOLOGY
B1, B2, B3 mean left, middle and right mouse buttons.
Each window is divided into a _tag_ (the single line of text
which has the filename in it and is at the top of the window)
and a _body_ (the big area below the tag where all the "meat"
of the file is).
SCROLLING UP AND DOWN
The Scroll-bar
The scrollbar is the vertical bar to the left. Clicking in it with
different mouse buttons scrolls the text window.
Move the cursor into the scrollbar next to this line, and click B3. The
line should have moved to the top of the window. Don't move the cursor,
and click with B1. The line should move back down so its next to the
cursor again. You can see that B1 and B3 in the scrollbar are good for
_relative_ movement. How far the text "jumps" depends on how far down
the scrollbar you click.
Use B2 in the scroll bar for _absolute_ positioning. For example, to
get to the top of this file, click with B2 in the scroll bar, at the
very top of the scroll bar. Try jumping quickly to the top and bottom
of the file using B2.
The "thumb" on the scrollbar (the bit which isn't "greyed out")
indicates where our visible region is in relation to the whole file, and
how big our visible region is in relation to the whole file.
If you hold a mouse button down in
the scroll bar, the window will keep scrolling.
Movement keys
The PageUp and PageDown keys move the text window up or
down by 1/2 a window. The Home and End keys move
the window to the top or bottom of the document.
The arrow keys move the "selection" by one character
or line.
Try these out now.
B3 MEANS "GOTO"
B3 (the rightmost mouse button) is also known as the "goto" button.
Selecting some
text (or clicking in some text) with the rightmost button
makes wily "goto" that text. What this means depends on
what the text is.
Before you start: clicking with B3 will create some new
windows. When you want to get rid of a window, look
for the word "Del" somewhere in that window, and click
on that word with B2. We'll learn later why this works.
Try clicking with the rightmost mouse button in some of
these examples: (NB wily will warp the cursor to the place
you "goto"--nine times out of ten this is what you want)
hello.c
hello.c:3
hello.c:/^main
hello.c:/p.*f
FNORD
Gnu
FNORD
$HOME
As you can see, you can "goto" a file, a directory, a
specific line of a file, a regular expression
within a file, an environment variable that represents any
of these, or the next occurrence of a piece of text. You
can use the "goto" mouse button on _any_ piece of text
_anywhere_ in wily.
B2 MEANS "exec"
This is also known as the "exec" button. Selecting some
text (or clicking in some text) with the middle mouse
button makes wily _execute_ that text. If the command
which is executed produces any output, it will be sent to
another wily window (which will be created if necessary).
Try clicking with the middle mouse button in some of these
examples:
who
pwd
id
date
./script
Builtin Functions
Wily provides some builtin functions which it searches for
first when asked to "exec" some text. By convention, these
all start with capital letters. You will see most of them
on the screen right now. For example, to exit wily, (don't
do this now!), you would click with the "exec" (middle)
mouse button somewhere in the word "Quit".
To delete a window, click with the "exec" (middle) mouse
button (but not right now) on the word "Del" somewhere in
that window.
B1 MEANS "select"
This is also known as the "select" button. This button is
used to select text, to be acted on later. Selected text is
highlighted (in reverse video). Text typed with
the keyboard replaces the current selection.
Double-clicking with the left mouse button selects a word,
a line, or the text delimited by quote marks, braces or
brackets, depending on where the double-click occurs.
The "exec" (middle) and "goto" (right) mouse buttons will
use an existing selection if they are clicked inside it.
Try this now: double-click just inside the quotation marks
in the paragraph below to _select_ the complex command,
then click with the "exec" (middle) mouse button in the
selection (reversed text) to execute the command. Here is
the command:
"grep -n main *"
Now modify the command above by double-clicking on "main"
to select it, typing "select", double-clicking just inside
the quote marks to select the whole command again, then
clicking inside the selection with the "exec" (middle)
button.
BUILTIN FUNCTIONS
These are pieces of text that wily recognises and treats
specially. By convention, they all start with capital
letters. When you deleted windows before by B2ing
(clicking with B2) the word "Del", you were executing
that builtin function.
They are often placed somewhere on the screen by
Wily, but their positions aren't magical: you could B2
the word 'Quit' _anywhere_ on the screen, to quit wily.
The builtin functions are:
Undo and Redo
Wily keeps an infinite undo history. Make a lot of changes to
this file (type stuff and delete stuff), and then B2 on Undo
repeatedly until the black square disappears from the little
box in the top left of this window. The black square indicates
that what you see on the screen is _not_ the same as what is on
disk.
Put and Get
Use these to write a file to disk, or fetch the old version
from disk, respectively. If the file cannot be written, a
diagnostic message will tell you about it. Putall writes all
dirty files to disk.
Newcol and Delcol
Used to create and delete columns.
Cut Paste Snarf
All of these act on the most recent selection.
Del
Delete a window. If the window represents a file
with some changes that haven't been written to
disk, a backup copy will be made, and a diagnostic
message printed.
Quit
Exits wily. Also backs up any modified files before
quitting.
New
Create a new file.
Kill
Kill a process which was started by wily. Must be
called with the name of the process (as seen at the top
left of the wily tag) as an argument.
USING UNIX TOOLS
As well as treating builtin functions specially, the "exec"
mouse button also treats specially text which starts with
any of the symbols | < or >
If the command you select with B2 starts with one of these, the command
is run using the most recent selection as its input or output or both.
For example, select the entire list below with the left button:
banana
apple
pear
carrot
then click with the middle (exec) button in the command
below:
|sort
You can use Undo to undo the change and do it again if you
like.
Similarly, select the paragraph below:
'Twas brillig and the slithy toves
did gyre and gimble in the wabe.
All mimsy were the borogroves
and "exec" this command:
>spell
Finally, select (with B1) _and_ exec (with B2) this text:
./send_to_gary
[ I finished the wily tutorial.
I thought it was too fast/too slow/just right.
I will definitely/maybe/never use wily again.
I think the interface is interesting/horrid/cool.
And furthermore ...]
For more information, B2 the line below:
netscape http://www.cs.su.oz.au/~gary/wily
To finish up, click in the word Quit with B2.
wily-0.13.42/Doc/tute/findword 0000644 0236657 0000012 00000000147 10333201523 0015723 0 ustar 00oz staff 0000433 0000002 #!/bin/sh
# list all places that $1 appears in all the files in the
# current directory.
grep -nw $1 *
wily-0.13.42/Doc/tute/hello.c 0000644 0236657 0000012 00000000061 10333201523 0015426 0 ustar 00oz staff 0000433 0000002 void
main(void)
{
printf("hello, world\n");
}
}
wily-0.13.42/Doc/tute/script 0000644 0236657 0000012 00000000715 10333201523 0015414 0 ustar 00oz staff 0000433 0000002 #!/bin/sh
echo Here is some output produced by a shell script called "script"
echo
echo 'Click with the "goto" (rightmost) mouse button'
echo on the word script to have a look at the program
echo
echo It uses grep to find all the places the word "mouse" appears in the
echo file "start".
echo Click with the "goto" button in any of the bits of text like
echo start:42 to go to one of the lines where the word "mouse" is used.
echo
grep -n mouse start /dev/null
wily-0.13.42/Doc/tute/send_to_gary 0000644 0236657 0000012 00000000113 10333201523 0016555 0 ustar 00oz staff 0000433 0000002 #!/bin/sh
cat | mail gary@cs.su.oz.au
echo message has been mailed to gary
wily-0.13.42/Doc/tute/typescript 0000644 0236657 0000012 00000000124 10333201523 0016310 0 ustar 00oz staff 0000433 0000002 Script started on Wed Apr 10 17:46:05 1996
script done on Wed Apr 10 17:46:05 1996
wily-0.13.42/Doc/hack.html 0000644 0236657 0000012 00000003520 10333201523 0014775 0 ustar 00oz staff 0000433 0000002 Hacking Wily
note
This document is pretty scrappy, and will likely remain so
for some time. You're best bet is to use the documentation
in the source files themselves.
Main data structures
Text
The text buffer data structure. All file and text manipulation happens
through a text buffer. Every text buffer has a pointer to a list of
Views which look after the screen. Texts
belonging to a window have a pointer to the corresponding
Data, with t->isbody indicating whether
the text is for the tag or body.
The text also maintains a small cache used in searching through
the buffer.
Files which #include "text.h":
- text.c
-
This (discounting text.h) is the only file that knows how
a text buffer is organised in memory (a simple buffer gap,
but keep that to yourself :-). It contains the basic routines
to read and write a text buffer to/from memory or a file.
- undo.c
-
Responsible for maintaining the undo log.
- sam.h, sambuf.c
-
Wrappers to make a Text behave like
a Sam file, so we can use the Sam regexp code. They provide
a small buffer and some macros for quickly traversing the
Runes of the buffer.
- click.c
-
Code to expand double-clicks etc. Uses the interface provided
by sambuf.c
- search.c
-
Various routines to search through a Text
- text2.c
-
Mostly convenience wrappers around the functionality of text.c,
plus routines for formatting directories.
Data
View
Tile
Main needs
Flicker-free scrolling, Tile heuristics, Sam commands
gary@cs.su.oz.au
wily-0.13.42/Doc/00README 0000644 0236657 0000012 00000000205 10333201523 0014216 0 ustar 00oz staff 0000433 0000002 index.html Start page for HTML documentation
tute/start Start page for "online tutorial"
(Just open this file with Wily and read)
wily-0.13.42/Doc/fonts 0000644 0236657 0000012 00000002541 10333201523 0014257 0 ustar 00oz staff 0000433 0000002 To read/write unicode text, you need three things:
your application defaults set correctly, a font file,
and appropriate X fonts installed.
1. application defaults (either with xrdb or $XAPPLRESDIR/Wily)
Your application defaults should point to a font file,
or you can start up wily with
wily -p9font fontfile
*p9font: /usr/pgrad/gary/lib/font/prop.9.font
*p9fixed: /usr/pgrad/gary/lib/font/fixed.9.font
2. Font file (e.g. ~gary/lib/font/prop.9.font)
The first line of this gives the line height and ascent,
the lines afterwards are unicode ranges and X font names.
e.g.
18 13
0x0000 0x0019 lucm.latin1.9
0x0000 0x007F -bigelow*-lucida-medium-r-*-*-16-*-*-*-p-*-*-*
0x0000 0x00ff lucm.latin1.9
0x0100 0x017E lucm.latineur.9
0x0180 0x01F0 matty.latinext.9
0x0250 0x02E9 lucm.ipa.9
0x0300 0x0308 matty.gendiacritics.9
0x0370 0x0372 matty.greekpunc.9
....
0x9800 0x99ff jis.jis9800.16
0x9a00 0x9bff jis.jis9a00.16
0x9c00 0x9dff jis.jis9c00.16
0x9e00 0x9fff jis.jis9e00.16
0xe000 0xe05f matty.tengwar.9
0xfee0 0xff5e lucm.latin1.9
0xfffd 0xfffd pelm.fffd.9
3. X fonts
The only source I'm aware of (please tell me if you know different)
for suitable X fonts is
ftp://ftp.cs.su.oz.au/matty/unicode/libXg.utf.fonts.tar.gz
which contains most of the maths and sci. symbols, and
a lot of CJK glyphs.
Adding these fonts to your font path is a bit system specific,
good luck :-)
wily-0.13.42/Doc/mouse 0000644 0236657 0000012 00000004307 10333201523 0014260 0 ustar 00oz staff 0000433 0000002 [Bruce Tognazzini, "Tog on Interface", Addison-Wesley pp
26-27]
We've done a cool $50 million of R&D on the Apple Human
Interface. We discovered, among other things, two pertinent
facts:
* Test subjects consistently report that keyboarding is faster than mousing.
* The stopwatch consistently proves mousing is faster than keyboarding.
This contradiction between user-experience and reality
apparently forms the basis for many user/developers' belief
that the keyboard is faster.
People new to the mouse find the process of reaching for
it every time they want to do anything other than type to
be incredibly time-wasting. And therein lies the very
advantage of the mouse: It is boring to find it because the
two-second search does not require high-level cognitive
engagement.
It takes two seconds to decide upon which special-function
key to press. Deciding among abstract symbols is a
high-level cognitive function. Not only is this decision
not boring, the user actually experiences amnesia! _Real_
amnesia! The time-slice spent making the decision simply
ceases to exist.
While the keyboard users in this case feel as though they
have gained two seconds over the mouse users, the oppositie
is really the case. Because while the keyboard users have
been engaged in a process so fascinating that they have
experienced amnesia, the mouse users have been so disengaged
that they have been able to continue thinking about the
task they are trying to accomplish. They have not had to
set their task aside to think about or remember abstract
symbols.
Hence, users achieve a singifcant productivity increase with
the mouse in spite of their subjective experience.
Not that any of the above True Facts will stop the religious
wars. And, in fact, I find myself on the opposite side in at
least one instance, namely editing. By using Command-X, -C
and -V, the user can select with one hand and act with the
other. Two-handed input. Two-handed input results in solid
productivity gains (Buxton, 1986)
[Buxton, William (1986). "There's More to Interaction than
Meets the Eye: Some Issues in Manual Input," in D. Norman
and F.W. Draper (Eds.), New Perspectives on Human-Computer
Interaction, Lawrene Erlbaum Associates, Hillsdale, N.J.]
wily-0.13.42/Doc/announce/ 0000755 0236657 0000012 00000000000 10333201523 0015007 5 ustar 00oz staff 0000433 0000002 wily-0.13.42/Doc/announce/1995.8 0000644 0236657 0000012 00000001631 10333201523 0015510 0 ustar 00oz staff 0000433 0000002 What is Wily?
Wily's basic functions are to edit and search for text and to run commands.
It requires UNIX, X and a three-button mouse. It is intended to eventually
be an integrated working environment for all tasks involving text.
It uses the mouse heavily. It emphasises speed for experienced
users, but is probably simple to learn as it has very few concepts.
What state is it in?
Not finished yet, but probably ready for most people to use. A few
people here (Basser) are using it pretty heavily already, but there's
still quite a lot of work remaining. Grab it if you want to have a
look/play, but expect (and please mail me) bugs. Please mail me
portability fixes (but not problems). It's being jointly written on a
Solaris and a FreeBSD machine.
Documentation?
Check out http://www.cs.su.oz.au/~gary/hobby/wily/auug.html
Where do you get it?
ftp://www.cs.su.oz.au/gary/wily.tgz (tar'ed, gzip'ed file)
wily-0.13.42/Doc/announce/1995.11 0000644 0236657 0000012 00000004317 10333201523 0015566 0 ustar 00oz staff 0000433 0000002 Announcing the first beta release of Wily.
What is Wily?
Wily's basic functions are to edit and search for text and to run
commands. It requires UNIX, X and a three-button mouse. It is
intended to eventually be an integrated working environment for all
tasks involving text. It uses the mouse heavily. It emphasises speed
for experienced users, but is probably simple to learn as it has very
few concepts.
What's different about it?
Wily is quite different from most other editors in a number of areas.
Nearly all operations are through mouse actions on text on the screen:
there are no menus, and almost no "key bindings" or "function keys".
Full support for Unicode and proportionally-spaced text is provided. A
bitmapped terminal and three-button mouse are assumed, and "chords"
(combinations of mouse buttons) are used extensively. Minimising the
number of keystrokes and mouse actions needed while working with wily
was a design aim. Wily itself is almost totally UNconfigurable, but it
is quite simple to connect wily to other programs, written in _any_
language, both for simple text-manipulation tasks, and to use wily as a
front-end for other programs such as mail or news readers, or
terminals. It is possible (and intended) to "live" in wily as with
other, more complicated editors. Wily itself is pretty simple, and
small (148k for the stripped dynamically linked binary on the author's
machine, c.f. 236k for vi, 2044k for xemacs).
What state is it in?
Development continues, but it is probably ready for most people to
use. About fifty people have been using it continuously for the last
few months.
More information?
Can be found at http://www.cs.usyd.edu.au/~gary/wily/
http://plan9.att.com/plan9/doc/acme.html describes the Plan 9 program
that wily was modelled after.
Where do you get it?
http://www.cs.usyd.edu.au/~gary/wily/wily.tgz or
ftp://ftp.cs.usyd.edu.au/gary/wily.tgz (tar'ed, gzip'ed file)
Will it work on my system?
I hope so. There's a 'configure' script which should work. It has
worked on SunOS, Solaris, Linux, AIX, HPUX, OSF, Ultrix, BSDI, Irix.
What conditions/license?
See the README, but basically do whatever you like so long as you don't
make money out of it and you leave my name around.
wily-0.13.42/Doc/announce/1996.11 0000644 0236657 0000012 00000004730 10333201523 0015566 0 ustar 00oz staff 0000433 0000002 Announcing the second beta release of Wily. (0.13.23)
What is Wily?
Wily edits and displays text and directories, and runs
commands. It requires UNIX, X and a three-button mouse.
It is intended to eventually be an integrated working
environment for all tasks involving text. It uses the mouse
heavily. It emphasises speed for experienced users, but is
probably simple to learn as it has very few concepts.
There are simple mouse-based editors for beginners, and
fast, powerful keyboard-based editors for experts. Wily is
a simple, fast, powerful mouse-based editor for experts. ;-)
It is based heavily on the Acme environment from Plan
9, which in turn was strongly influenced by the Oberon
environment.
What's different about it?
Wily is quite different from most other editors in a number
of areas. Nearly all operations are through mouse actions
on text on the screen: there are no menus, and almost no
"key bindings" or "function keys". Full support for Unicode
and proportionally-spaced text is provided. A bitmapped
terminal and three-button mouse are assumed, and "chords"
(combinations of mouse buttons) are used extensively.
Minimising the number of keystrokes and mouse actions needed
while working with wily was a design aim. Wily itself is
almost totally UNconfigurable, but it is quite simple to
connect wily to other programs, written in _any_ language,
both for simple text-manipulation tasks, and to use wily as
a front-end for other programs such as mail or news readers,
or terminals. It is possible (and intended) to "live"
in wily as with other, more complicated editors. Wily
itself is pretty simple, and small (148k for the stripped
dynamically linked binary on the author's machine, c.f. 236k
for vi, 2044k for xemacs).
What state is it in?
Development continues, but it is probably ready for most
people to use. About fifty people have been using it
continuously for more than a year.
More information?
Can be found at http://www.cs.usyd.edu.au/~gary/wily/
http://plan9.att.com/plan9/doc/acme.html describes the Plan
9 program that wily was modelled after.
Where do you get it?
ftp://ftp.cs.su.oz.au/gary/wily/
ftp://ftp.math.tau.ac.il/pub/laden/wily
ftp://ftp.cs.york.ac.uk:/pub/mhw/wily/
ftp://ftp.northsea.com:/pub/plan9_unix/wily/
Will it work on my system?
I hope so. There's a 'configure' script which should work.
It has worked on SunOS, Solaris, Linux, AIX, HPUX, OSF,
Ultrix, BSDI, Irix.
What conditions/license?
The Artistic License, similar to that of Perl.
wily-0.13.42/Doc/FAQ.txt 0000644 0236657 0000012 00000005415 10333201523 0014356 0 ustar 00oz staff 0000433 0000002 What is wily?
See the introduction.
What does "wilydiag: File exists: can't open fifo" mean?
Wily opens and listens on a fifo in /tmpin case some program
tries to communicate with it. If you're not doing anything
tricky like that, it won't get used at all. Ordinarily wily
cleans the fifo up when it exits, but if something dire happens
Wily may not get a chance to clean up. The fifo will be named
$WILYFIFO if that is defined, otherwise /tmp/wilyUSER$DISPLAY,
where USER is your login name. Just remove it and restart wily
to be able to use wily messages.
Why does my compiler/editor/whatever complain about illegal
characters? The line looks fine to me."
Chances are that you've managed to enter a control character
accidentally, and the font you're using doesn't display control
characters. The easiest way to check is to select the line (or other
text) that's causing the complaint, and click on "|cat -v" (or some
other program that can display control characters, such as vis or od). I
find ^A the most common offender.
Why does Wily have to do its own window management?
See a long explanation
Funky B3 expansion allows some letters, not others?
To quote rob (it was originally rob's comment, wasn't it?): "Hard to
get absolutely right." The problem is that you can have pretty much
everything in a filename apart from \0, but usually you want it to
pick sensible strings. It's not just filenames, after all, but also
identifiers in programs. After all, Acme is primarily a programmer's
tool, because there aren't any other kinds of Plan 9 user. :-) Plus,
most of them are shell metacharacters (in rc).
The set you want to match varies from instance to instance, so
it's pretty much an arbitrary choice. Sometimes you lose. Some
justification would be good for the docs, though. Anyone know
why "*" is considered a valid character? Hmmm. Ones not in the
above list are "#$^*_-:~,./". Of these, "~./" are parts of
common filenames (~steve/x.c), "#$-:,." are part of the syntax
for expressing an Acme address, and "_" is a common identifier
character. That just leaves "^*". I suspect these are allowed
because they're commonly used as part of a regexp search.
Steve Kilbane
Why does it take so long to load my [mumble]-meg file?
Blame steve.
What about a Win 3.1/95/NT port?
Gary's not likely to do it because he doesn't have
a development environment for Win (or know much
about the Win environment (or want to))
It may not be as useful under windows as under Unix
because you won't have the same command-line toolbox
(sed, grep, glimpse, ...)
There's a Win version of sam, which presumably means
there's a Win version of libg (libg.dll?). Starting from
that would probably make the port much easier.
he font you're using doesn't display control
characters. The easiest way to check is to select the line (or other
text) that's causing the complaint, and click on "|cat -v" (or some
other program that can display control characters, such aswily-0.13.42/Doc/README 0000644 0236657 0000012 00000000205 10333201523 0014056 0 ustar 00oz staff 0000433 0000002 index.html Start page for HTML documentation
tute/start Start page for "online tutorial"
(Just open this file with Wily and read)
wily-0.13.42/Doc/pythonpaper.html 0000644 0236657 0000012 00000051460 10333201523 0016446 0 ustar 00oz staff 0000433 0000002
Wily + Python > Emacs + Lisp?
DRAFT ONLY
This is a draft of a document which will be submitted to the 4th International
Python Conference to be held at June 4-6, 1996 at the Lawrence
Livermore labs in California.
This document describes aspects of Wily which are not yet released for beta
testing.
Wily + Python > Emacs + Lisp?
Gary Capell
<gary@cs.su.oz.au>
Basser Department of Computer Science,
University of Sydney, 2006
Australia
Wily is an editing environment which can be extended with Python
programs. Instead of using an embedded Python interpreter, Wily talks
a simple message protocol, and a module lets Python speak the same
protocol. This approach is general (one can use any language)
and clean (the editor is responsible for only a small set of functions).
The message interface promotes a clear separation of functions, with the
Wily editing environment providing a standard way of interacting with
client programs. The main disadvantage may be that the looser binding
between programming language and editor is less efficient, but this is
not expected to be a significant problem.
The editor itself is simple, clean, and efficient, with a few features
which combine consistently. It abandons backwards compatibility with
the virtual terminals of yesteryear, to take full advantage of a bitmapped
terminal and three button mouse.
Table of Contents
This documet describes:
An appendix defines the Python interface in
more detail.
This is necessarily very brief, and Wily and Acme are very different
from what most people are used to. Please read
Rob Pike's paper
for a better and more complete description of the interface.
Wily's main attractions are that it is very simple (the User Manual
describing the whole user interface is about seven pages), very quick to
use, and integrates well with other Unix tools.
History
Wily emulates in the Unix and X Windows environment the Acme editor
from Plan 9.
Acme couldn't easily be ported to Unix because it is written
in Alef
(a concurrent programming language not widely available) and uses
non-portable features of Plan 9 . Also, a port of Acme would not be
freely distributable.
The name ``Wily'' derives from Wile E. Coyote, an avid consumer of
Acme products.
Modern Aesthetics
The screen is divided into columns, which are divided into windows.
A window may represent a file, a directory, or the output from some
program. The screen, columns and windows each have a narrow horizontal
``tag'' at the top, which contains some useful text, and for windows
contains the name of the window and a "file is modified" indicator.
Text is displayed in a propotionally spaced font by default. There
is a built in function to toggle with a monospace font, but there are
very few occasions when this is necessary or desirable. In most cases
limiting a text editor to monospace fonts is blindly following the
hardware limitations of the 1960s.
Text is read and written as UTF8-encoded
Unicode,
providing some support for editing multi-lingual and scientific text,
but remaining backwardly compatible with plain 7-bit ASCII text.
Everything is text
All actions in Wily are through creating and interacting with text on
the screen, using the three-button mouse and the keyboard. B1 (mouse button
one) selects text, B2 executes text and B3 attempts to ``goto'' the text.
When executing text, there are some built in operations, such as
``Quit'', or ``Del'' which are executed by Wily itself. Otherwise, the
command is executed in a subprocess, with output redirected to a window
within Wily and input from /dev/null. It is also possible
to use the current selection (currently selected text) as input for
and/or output of some child program. For example |fmt
formats the current selection, >spell checks its
spelling and <date replaces it with the current time.
The goto operation used with B3 is polymorphic in that it
recognises three different patterns:
- name
- If name is a file or directory, open it, otherwise search
for the literal name
- :address
- Search for address in the current window. The
address may be a line number, a character number, a regular expression,
or two of these, separated by a comma.
- file:address
- Open file and search in it for address
Wily's power derives in part from its general treatment of text.
Whether text is found in a file, or directory listing, created by
Wily, output by some other program, or typed by the user, it can all
be treated the same way. A simple text file may be used as a menu of
commands or a simple form of hypertext. Previously typed commands or
``usage'' messages can be edited and executed. There is no need for
dialogs, menus, modes, buttons or accelerator keys, just operations on
text on the screen.
No wasted user actions
Wily minimizes the number of unnecessary mouse or keyboard
actions the user must make. For instance, placing newly created windows
is done without needing the user's help, although the user can easily
rearrange things if Wily's heuristics aren't acceptable. Wily also makes
cutting, pasting, executing and searching for text so easy to do with
the mouse that there is no need to retype text already on the screen.
Cutting and pasting text is made particularly convenient using
combinations of mouse buttons. To cut text, select it with B1,
and while still holding B1, also click B2: this is a B1-B2 chord.
To paste text use a B1-B3 chord. This style is unusual, but once it becomes
familiar other methods of cutting and pasting seem unbearably slow.
Another chord (B2-B1) is used to execute some text with
an argument.
To avoid having to position the mouse accurately, a mouse selection of
zero length (i.e. a mouse click) is expanded in a ``reasonable'' manner.
Clicking with B2 in a word expands to that word, which is then executed.
Clicking with B3 in an address (e.g. foo.c:45) expands to that
address. Double-clicking with B1 just inside paired braces, brackets or
quotes selects the region thus delimited.
Wily's general approach to text as commands and addresses
is compounded because these basic functions can be accessed so
conveniently. Most operations can be achieved with a single mouse click
or mouse combination.
Synergy
The consistent and general use of text for input and output
in Wily makes the combination of its features more than the
sum of its parts.
Stepping through an example session might best illustrate this:
Susan has fetched the file frob.tar.Z. She clicks with B1 in
the file name, and with B2 in the word untarz. The utility
untarz uncompresses and untars the file, verbosely printing
file names as it goes. She clicks with B3 on one of the file names,
INSTALL, which opens the file. The INSTALL file
suggests that she run configure then make. She clicks
B2 in each of these words to run the suggested programs, but there's a
problem. The make fails when gcc quits with the error message
keyboard.c:4: strings.h: No such file or directory.
She clicks with B3 in the first part of the error message, which
opens the file and selects the line. On Susan's system there is a
string.h but no strings.h. She removes the last
s with a B1-B2 chord. When she modifies the file, Wily sets
the ``file modified'' indicator, and adds the word ``Save'' to the tag
for this window. Susan clicks B2 on the word Save to write the
file, clicks B2 on make again, and she's done.
This whole process uses about ten mouse clicks and no typing.
Wily waits for a program to connect to it using a socket, and then sends
and receives messages. The messages can be RPC requests and replies,
or ``event'' messages generated by Wily when certain actions happen in
windows which a remote program has asked to monitor.
The interface is deliberately at a rather high level. The intent is that Wily
will take care of of the details of interaction, with other programs providing the
semantics of executing a command, opening a window or searching for an address.
This promotes a consistent set of tools and an efficient division of labour, but necessarily
at the loss of some generality.
The requests allow the remote program to
- list the windows currently open
- create a new window with a given name, which may or may not
correspond to an existing file or directory
- ask to be sent some subset of the events which happen in a
particular window
- change the name of a window
- read the text from some part of a window
- modify the text in a window
- act as if some string were selected with B2 or B3 in a window
(useful for searching for text, or accessing built in functions)
A program may ask to be notified when events happen in a particular
window. These events are generated when:
- text is selected with B2 or B3 (i.e. the user is trying to execute or ``goto''
some text)
- text has been modified
- the window is destroyed
When a program is being sent B2 or B3 events, Wily doesn't act on them,
merely sends them on. The program may opt to ``send back'' some events which
Wily will then act on. Events which modify text, on the
other hand, are always handled by Wily, which then may inform the
remote program what has happened. In other words, the remote program
cannot stop the user modifying any piece of text, although it can repair
the text later if it wishes.
Wilymodule.c
This is a very simple interface between Python
and the Wily message protocol. It establishes a connection,
provides remote procedure calls and queues events until they are requested.
A Connection is initialized with no arguments, and
represents the connection to Wily. All the other functions are methods of
a connection object.
The Connection has methods to return a list of windows
representing all the windows currently open in Wily, to create a new
window, and to return the next event from Wily.
Windows are represented as integers, which correspond to window
identifiers with Wily, and events are represented as tuples.
The Connection has a number of methods which provide
operations on Wily windows. These operations allow a program, once it
has an identifier for a window, to change its event mask, its name or
its ``tools'' (useful text in the window's tag), read or modify some of
its text, or simulate a B2 or B3 action.
Wilywin.py
This is a small Python module which provides a friendlier
interface to Wily's functionality.
Example Program Fragment
# Create a window called "hello",and fill it with
# the text "Hello, world"
import wily
con = wily.Connection()
win = con.win("hello")
con.replace(win, 0,0, "Hello, world\n")
These are small tools written as proof of concept, to test and refine
the message interface, and as templates for other applications.
News reader
This uses Python classes for threading, talking NNTP and reading and
writing .newsrc files, and Wily for displaying newsgroups and
articles. The program acts on B3 actions on article numbers, and B2
actions on some special function names (e.g. Catch-up, Follow-up) which
it also places in the correct tags.
Session save and restore
There are two programs to save and restore the ``state'' of an editing
session. The ``save'' program determines from Wily what windows are
open, what the current selection is for each, and the full text of
windows which don't represent a file or directory. The ``restore''
program connects to Wily and uses the saved information to create and
massage windows to hopefully return the session to the original state.
Terminal
There are some useful programs which require the traditional ``prompt
and read a line of input'' interface. Examples include gdb,
/bin/sh or /bin/mail. To use these programs, but from
within the Wily editing environment, a simple terminal program was
written, in C. It is called win.
Win provides standard input and output for its client program,
and creates and monitors a Wily window, maintaining an input
point. When win sees a carriage return entered after the input
point, it sends the text between the input point and the carriage return
to the client program. Output coming back from the client program is
inserted just before the input point.
Win does not attempt to provide a pseudo tty or work with any
programs which attempt to use curses-style screen addressing. However,
it works fine for programs such as those mentioned above, and was written with
only 230 lines of commented C.
Wily's approach to extending the editor is to communicate
with other processes using a socket or pipe. Here we examine
some alternative strategies, and why Wily doesn't use them.
Build an interpreter into the editor
This is by far the most common design for an extensible editor.
There are a few advantages to this approach.
Letting the extension language share the address space of the editor
is more efficient than using IPC. The language can also be tailored
to provide a close match to the editing requirements.
There are two reasons why this approach was rejected for Wily.
The first reason is that it restricts users to a single language,
and it often means designing a new (possibly half-baked) language.
The second reason is that embedding a language interpreter in the editing
environment seemed an unnecessary step towards monolithism
and code bloat.
For comparison, below are the sizes of three stripped, dynamically
linked executables on the author's sun4d Solaris system:
| 167264 | wily
|
| 234272 | vi
|
| 1873336 | xemacs
|
Link code dynamically
Another approach is to dynamically link extension code with the editor.
This is more general and more
efficient than the built in interpreter design.
CodeWright®
from Premia uses this approach in the Microsoft Windows environment.
One problem with this
approach is that dynamic linking is not standard on all UNIXes. Another
is that one errant code fragment dynamically linked
in might damage the integrity of the editor. The result might be lost
data, or even worse, data quietly modified in some subtle manner.
When this approach becomes ubiquitously available and more secure, it
will be re-examined.
ILU or CORBA
It would seem that
ILU
and
CORBA
both provide a ready-made solution to turn an editor into
a distributed object server. However, both seemed too
heavy-weight for this simple task.
There is a strong belief amongst Wily's users and developers that ``creeping
featurism'' is evil. Most of the ongoing work will be towards refining
existing features, and improving the clarity and correctness of the
code. Retaining the ``look and feel'' of Acme is also an important
consideration.
There is still room for innovation, though. The message interface
is still very young, and may change with the demands of application
writers. The author hopes that the Python community will be able to
make good use of an editor programmable in Python. Although there is no
need for cursor keys to navigate around Wily, they may be added
later, although they are a low priority.
Networking and security
Currently programs connect to Wily by writing to a UNIX named pipe.
Wily's security relies on this pipe being writable only by its owner.
This means Wily can't accept connections directly from remote machines,
which would be desirable for some applications. A design which avoids
this limitation securely and efficiently has not been decided upon.
Wily is freely available.
The prime source for information about Wily is the WWW page at
http://www.cs.su.oz.au/~gary/wily/
The wily
distribution contains wilymodule.c, and can be obtained at
ftp://ftp.cs.su.oz.au/gary/wily.tgz
The early design and source of Wily owe a lot to Bill Trost.
Wily and this paper have also been
improved by patches, suggestions and bug reports from
Assar,
Davor Cubranic,
Kyle Dean,
Stephen Gallimore,
Mark H. Wilkinson,
Bjorn Helgaas,
Steve Kilbane,
Beirne Konarski,
Bob Krzaczek,
Alberto Nava,
Arnold Robbins,
Rich Salz,
Scott Schwartz,
Chris Siebenmann,
and Richard Wolff.
Wily builds on the Sam distribution by Rob Pike and Howard
Trickey, and originally used libtext by James Farrow. James
Farrow also makes available a set of Unicode fonts for X at
ftp.cs.su.oz.au/matty/unicode/
con = wily.Con()
Connection
Connection objects have no attributes and suport the following methods:
- list()
- Returns a list of names and Win objects
representing the windows currently open.
- win(name)
- Return a new window called name
- event()
- Return the next Event. Note that this method
will block until an event is available.
- eventwouldblock()
- Indicates whether calling
Connection.event() would block.
- returnevent(event)
- Send event back to Wily, probably
because we have no use for it.
The following methods of a connection object act on a window.
- attach(id,mask)
- Request events for this window.
- detach(id)
- Cancel request for events for this window.
- setname(id,string)
- Set the name of this window.
- settools(id,string)
- Set the toolbar for this window.
- read(id,from,to)
- Read some range from this window, returns a UTF8 string.
- replace(id,from,to, string)
- Replace some range of window with some other text.
- run(id, command)
- Makes wily act as if command
had been selected with B2 in this window. This can be used to access
Wily's built in functions. For example, to delete w, call
con.run(w_id, "Del")
- goto(id,address)
- Makes wily act as if address had
been selected with B3 in this window. Returns a tuple identifying the
window and position which are the result of the search.
Events
Events are returned as tuples. Every event has at least two elements,
which are a window identifer, and an event type identifier (which is one of
wily.GOTO, wily.EXEC, wily.REPLACE
or wily.DEL). All of these event types except DEL
also have a from, to and string attribute.
e always handled by Wily, which then may inform the
remote program what has happened. In other words, the remote program
cannot stop the user modifying any piece of text, although it can repair
the twily-0.13.42/Doc/python.html 0000644 0236657 0000012 00000006416 10333201523 0015417 0 ustar 00oz staff 0000433 0000002
Wily Python Programmers Manual
Wily Python Programmers Manual
Summary
Create a Connection, use it to create and manipulate
Wily windows.
See pythonpaper.html for a discussion of the design.
(Unfortunately out of date).
Creating a Connection
import wily
con = wily.Connection()
methods of a Connection object
- list()
-
Returns the names and IDs of all open windows.
The values are returned in one big string, with names and IDs separated
by a tab, and each (name,id) pair on its own line.
listing = con.list()
lines = string.split(listing, '\n')
winid = {}
for line in lines[:-1]:
[name,id] = string.split(line, '\t')
winid[name] = string.atoi(id)
... will give you a dictionary mapping names to numeric ids.
- win(name:string, isBackedUp:integer)
-
Returns an integer window identifier, to be used for later operations on the window
- event()
-
returns an event tuple (w, t, r0, r1, s), whose fields are:
- w
-
window identifier
- t
-
event type
- r0, r1
-
affected range
- s
-
string
The meaning (if any) of the values of r0, r1 and s depend
on the event type 't'
- eventwouldblock()
-
If eventwouldblock() returns true, calling event() might have to wait.
If eventwouldblock() returns false, calling event() would return immediately
because an event is already queued up and waiting.
- bounce(tuple)
-
Called with an event tuple as returned by event(). Returns None. Used for returning an event we want Wily to handle instead of us.
- attach(w:integer, mask:integer)
-
'w' is a window identifier as obtained by new() or list().
'mask' is a bitmask of event types.
Sets the mask of events to be sent to us.
- setname(w:integer, s:string)
-
Set w's name to 's'
- settools(w:integer, s:string)
-
Set w's tools to 's'
- read(w:integer, from:integer, to:integer)
-
returns a (UTF) string
- replace(w:integer, from:integer, to:integer, s:string)
-
replace the text in 'w' from 'from' to 'to' with 's'
- run(w:integer, s:string)
-
has the same effect as sweeping 's' with B2 in window 'w'
- goto(w:integer, from:long, to:long, s:string, flag:integer)
-
has the same effect as sweeping 's' with B3 in window 'w',
and starting any search at range(from,to), except that we only
warp and select text if 'flag' is set.
Returns a tuple (w:integer, from:long, to:long),
which represents the window and selection that was
opened.
Constants
GOTO, EXEC, DESTROY
and REPLACE are event bitmask values, useful for comparing to
the event type returned by event(), and for setting the bitmask in
attach().
gary@cs.su.oz.au
wily-0.13.42/Doc/mailout 0000644 0236657 0000012 00000001055 10333201523 0014577 0 ustar 00oz staff 0000433 0000002 ~/.wilydirhide, .wilytools
> If wily checked to see if it needed to reload this file before generating a
> listing (a simple stat(2) -- a feature .wilytools needs as well), it would
> substitute for Dotfiles quite nicely.
That's a whole lot of stat-ing going on. Every time
a window opens for .wilytools, and every time
a directory opens for .wilydirhide.
A cheesy hack would be to look at those files when
we open or write them from inside wily, i.e. check the
label of the file we write/open to see if it is magic. strcmp
should be cheaper than stat
wily-0.13.42/Doc/one.html 0000644 0236657 0000012 00000007115 10333201523 0014654 0 ustar 00oz staff 0000433 0000002 Concise Wily User Manual
Notation
B1, B2 & B3 are left, middle, right mouse buttons, respectively. "B1B2"
means to select some text with B1 held down, then click and release
on B2 while still holding B1 down. This is the B1B2 chord. There are
others. "Sweep with B1" means to hold down B1, drag it across some text
to select it, and then release B1.
Screen layout/control.
The screen is divided into columns, each of which is divided into
windows. Each window has a scrollbar and a one-line "tag" containing a
file/directory name and some commands. There is also a tag at the top of
each column, and at the top of the whole screen. A "layout box" is at
the left of each tag: dragging this box with B1 moves the window around
the screen; windows re-layout automatically when you drag and release
windows with this box. Clicking on the with B1 "grows" the window
slightly; B2 makes it grow until all other windows in the column only
show their tags. B3 makes the window tag up the whole column, hiding
other windows completely.
Selecting and editing text
Type normally anywhere on the screen to enter text; move the pointer
into the tag/window you want to type into. Position the cursor within
text either with cursor keys, or clicking once with B1. Sweeping text
and then typing Cuts the selected text, and replaces it with the
typed text. Cut and Paste are chords B1B2 and B1B3: sweep text with
B1, and complete the B1B2 chord to delete. B1B3 Pastes text over the
selected text. Double-clicking with B1 selects text quickly, picking
a word, a line, or text delimited by quotes, brackets, braces, or
parentheses, depending on where you double-clicked. Undo and Redo give
edit history. Layout box is filled in when text is modified but not
saved.
Executing commands
Sweep text (anywhere!) with B2 to execute it as a command. A single B2
click automatically selects a sensible "word" as the command. Commands
can be built-in (Capital first letters, by convention) or passed to
the shell for invocation. To invoke commands with arguments, sweep the
argument with B1, then click on the command with B2B1. If a B2 command
begins with |, > or < characters, the B1-selected text is piped through,
fed into or replaced by the results of the command, respectively. Any
output generated by commands appears in a window named dir/+Errors,
where dir is the directory the command was invoked in.
File/directory management
Windows show file or directory contents. The full path of the
file/directory is given in the tag. Selecting a filename with B3 (sweep
or single-click) will attempt to open that name relative to the pathname
in the window's tag. The new file/directory appears in a new window. If
the file can't be found, the B3'd text is searched for in the current
window instead. If the B3'd text is of the form ":n", it is a line
number to go to. ":/pattern" is a regular expression pattern to search
for.
Builtin commands
Anchor prints current selection address in tag. Clear clears
window. Cut cuts selected text to buffer. Del deletes window. Delcol
deletes column and windows. Dotfiles toggles display of dot files in
directory windows. Font toggles fixed/proportional fonts. Get reloads
window. Indent toggles autoindent. Kill halts named B2'd program. Look
searches for text. New creates new window. Newcol creates new
column. Paste pastes buffer. Put writes file to disk. Putall writes
all files. Quit exits Wily. Redo undoes last Undo. Snarf copies text to
buffer. Split opens up another window on the same file. Undo undoes
last edit.
wily-0.13.42/Doc/example.gif 0000644 0236657 0000012 00000025403 10333201523 0015327 0 ustar 00oz staff 0000433 0000002 GIF87a , ڋH扦j L
ĢL*̦ J?jܮW| UFJn \xGGXhxH3888gc))Iɇ9h:ę*:䉳zǚx ek:;+ܘLXH-4 6[n~ ^=| >z _N:\>Y/ٽX!>%a|"6ۧ0ȑ$ѭ[ =>)R1K,9
f3Uz
iM [ #VV2֭YNJHUʰEe."*SؖmjhMMk6Rn;7-[N8b^+ K1 ם붲4oyZzwmნS g\!۾>G /.D5 gMQ_iO:aAavp4˛?[,V~t-CO]H f\NޱvS~CwS# oA
zNHnuWly_jf _ <}z=f8vWV cAơAaK NTj0vsQ^LShm@Dm=f9?g1ǑrD _m d\Bu)'`9&z`oėf fեui>rꨊj
QꫲΊފkz
l1 l&a.l> mNKm^mn[, ~ nKn枋nn oKoދo"p p p(̰4lmgTD,JHHxq&"ј hƄ˅3 9+n2|nϟFɄn
E4QΊ&qE
B/TUEX#[Mr]JGPrEQEMҞb{e "ݜN-tE.M3&> Ғ_n#܈K*ؐ鐼FhIy-~h4?gLz/ :nJnk5e6~L|օ
JPxCf<,a﹂%|琾v'}-Uy|MU%KZEhc`}?-@ C%Gl17(ɀ|% II V
]Ϸ-Cc5!́!{ݓKP 5D. Ax !2mMzC VɇcSbgO FrNIsgxvM ŭ:%9sGAEL7Ά\343!5dV ԑiGI]BYHZ S9<*2Ϝ&:3:zd
՜ {ے܇oT*ŪԜj\TE)
bDKKX`1K,kcձecKYcE eekfY14
-:MjVSL[i4mvBz
.p*wms Jwԭujڼ y{VXob&[m7J!V+~W]fg_v~_F +*6Fhn^ 6)eN{}
[1ۇ9wþu Y;t&!S:{ {7ҿH(# m*T SeLv0-l9d"bTǜc'79 y+M)64;;]5մ s"G)Tiň')HHط2z H7.$TpҷЛ P2Ƕ68On"n$5g"MXW9Y4g!Ie؞n^\i^3 숣iZ'k w'Or՜d+Ne_ 1Vf),C Ex-lJN,苴GvO!-UOva_yPj6KX 3|T$YϬ9oo&7 :H[uuQrT߽6A4qO]M{_o5^eo:oh.}YF9|ThuryzN{B=hvA(EJ4qDneܦ Th٠{+|gd4}tAAd_NT/vq} 5Iz=Nsehfl0w-$5cދ-߭v&=R4ܤ~mm8xgv~qz27 ]G ~*WqOrBk4UvWkF-Ewt'hKVGE~W'cUQCE,T
z4!wu/ׂqMgGUy
$=(im9SJ7c:g#sOT (AFrGvx:~,TW.8Hvs0:>HK7Y7\F1vnEMGsfwncVZ4
e"hy ]7>W}*5+BdLV-'8_$ xA38؊~ȋ^
hchh1Ȍ1(ܲ]٨ȍ(H.\ψȎE&(^8F!{1Nd&15x7/u8.eQ;]Vl&:7E2834W!Q7[R)b7#uW\@&e搘2(#^Yaqܣe=wR|ea"vqԓh`u6MSgg6puSVfWohxL0=tS5C)gX?Yx cn{Q} rQgXt9whkxDXGml&ʆ~дvy{O(ym(LJ3vi@I n9v|q"H{yrRޑ>eWkp);% SzjJF*ZBɈ]{1iO e˘h2gKl{:6Pi=BȴGȝ 2 . ڴN 9eW6G9J_G\9RJ
[L#pF6:B|ؑ]*pr7ۊ[wES=3xgVɻG(|`jsˣjg 7lXvaYކ?;UIUdq
>Qhz#j%7g,4hC6D& u(!l4Ŝxۗ"EۇVp&
?!xV%
*ꟕh(4 JP ů(<N>ڨ[$9 >YƧ+g|t)XF WCD
fYŗÀRy.|K1/: dHj
7,V[;
&9 ~Gyvf, DLZw?=gx],ڀ*Ɲ;W}%93ƪ')~jykL '۹x>ɑ h
QK:}Ž*%hjڢ)\\ |\w$̺_sRxwx8J:+Tn6,ȶwin
|Ü Лyl! 5"ЩòlMKaש܋CZ̦97벉 ){2{[n[
.
lf$} 1]+-؏:ӄз@ ,6MJ=Աҍ ڒU-黶X}1Pղ"Ԭx?[۸K֤˪#XYG-Yk(=} F`LEc3k zc-ثb3-מxzZpX+zp+6ל Mmviis* ƓW Mg[*(ZȾmt&8 ;!أY?keft&;_.ؒyYhI9
*Ƭ$'̪6 .;LS k4K)92< Zf#lgf?H E^xXWEY}kG]#ibK?GRݧaeݺUvMQ%T3&THŢh K@lF|7 S&$nV0O|%exb%#2raQGti?˽V&BJ0T HβA+[(ukαJr#VCo_%1X/`
+dT4aNs ]eWɎ1g<˛ksѠ l4 PO={hjiEun o껈+NDž3ws:zuga/戧ɱa={A? ~}փ+]
b|wO>Kn@ >T+?PB
0Pÿsm +h
Dى( OlB uO
S0
RHVsmTl8DH|-Iw .",2=t=9"jͦR5TCgqT.$+<;:S+-h2mlϦ̼P
w$oI)K1TM9OA
UQI-R T%.Y +{T)/XeIȘ;P(\TemgVi5C2QZ RIJrkYUϬJoR:c_-6_1]H S(^ʝq4%
&hy(XZU%Tu|.I.9t\D& NYXE
atk-3^px,rdӎ6Y+Rf?έӍj1pJC/=G}deO\5^}9(DN&8ٟ1F;Rx_T+ ZP]U,:"mEsNW5"oK5OBDTqe c?ôr|kERTPˌ7z J ةaqhz}%=#+@E6fљwau` W o[{^2=}πL +E@E(x\CҌ'( d Oe ObX&& HIMHP% V% ^ΈnK0:bjM\%WZOji JAHDv?JSr$s h^U"O ITZ3s)əS+EyShuj9ԔuukYVچ #Y xU _u;U*Tp[=^I;N}SX)&lW:+H/Jwڄvrm(_+ Zwe8iJfϙGb] lEc>2n
p*<%jv!>:,yԏ{a3ne:*nRSB/l9V2!BBE}y܌뀃l,ǓZ4f'}k܄ROeMoZWWs@, - bdMcoekaNT`8D{CW`ĺ9bI m
^Y]EN .1J\2$nc2 o1(Vo^_yV2@2HQe{]LVQD^َԻWr.k3z g Se0cSP$̍vF?GbV1A*' PQ˥>Kܒ rz~]Xp^a:PL j ;jsfaŜ bnֲ1_;0#EC$-[kj>ZL qOxſ=ԦYf@_Vm\gm[[Z
m~ }gT/s=2 o8Бn7%]1Dzљ u-]Ugԭu~Q]]ϐ7uFO: +>vw]eOi:kep"ݭM- ##s!+USnGIMXčn%G{ HO4&/:mA96^y<9N 0eL[9ϵ*YwLg b6\̠~lz }3~,c UBW&gO _gVQshw#(goJ ϲ GrVn)fI'fȻ .
"P,K>+;Zo&^uJ d,sU"-؇ y,zŬ.lUT6oJ gĉˤVN)Ljtt͜JH҆Ft:fIOX$/N 4l_z")pЁ~
Po`M,
Ph·fOrϯLp*jp<
3z"pઇ+(qg
j.1iKr-\O-ƫ \q"P,XlxQ 9+ْ1 KĭnIkQ{+/~ RQm0(y._hRG 1, ( ^ƞk9#2 nRr;0D
l=e'%RO%j#j#|"p̈f,$y~P%Ck&v d*D 1$!*(͒R<.Qj" ?|-bFFBp UR
q ]MmɴFA
rP'+Hsjv.)R3Q؊I&3iƱ.=)OoE3 Y9q%[d*lo!)8
=и
ʳz}5Yw)=ѓ?0sK21).gv3梒ΠQR TMpL49e@,d8cG<"߶<0V5qsMT2HABUsC#5':np4EN,yGHTXHC4IAo-@7ų#JtLFqFotdĔLElIJ#/qM0M41NZ1::M">APzD?`=˳rQ!mƴ:) ;u6J-tPP T-&OTg|Us]3'xR$J4#.4#0JVAm,> 1 5X L]O]1Xy^AZTV%2
/y hUr[u]
rI wG"q V_[4-{R<]iK'ͦ|tUeKT-u+]<Y 'bI=OU
na,uZŦ1S5ioVXi# } bgY5vhAh!,mI NdMNѦ8Qʒ[ԫԵ 6'V` TqlE ̶@rpb6nqWQInAWQ^G`_;Nk@ӵ\4qmS65pT.0TIWNnH% TewDSgo,\J5Gx/5yp @jGufqLOO=吏ܾw_4} {]6Uٷmv~Ke~}:>7JBDKԀw b5u˯ayܷ7
ytWU NAd5F΄ NV 5.MCix3S"awof?OSoWic9ؘ^5T Տ,lj9V'[rl+iԔO9!K?wy\ R*l/r 1%_AX6-0M
Ky89o`
9˖'+
|ϗ'xPő# fmdQQD)W3MFyXr#ק|v
g]/VuSX͡Vb#֜*SE@-ZNً;S[RÖx;q_ywAl|7LuR iT1x,mc1yN:Z{5[u~vkFٺIliHCWu3W
{b~ZOev0[u[9밓A;3YY㴟7XGQD#mPU/eq
;:oOx]lxTM=CzHȋKuxKWNt
k) &u_x ۳}P]ZI}ݝ=ޥ4]}}߅n==߽^ڡ=^
%^
k89( ;}{?41'N)؋g9< U-hL۸9 ~©ɻ ̝zHl~SDb-j_¬lO s.os ĔTI|ci=\gl}
K[̮ZJWp 87 -H`X{9a
l .~mf tKTo/hWqCuG خLwily-0.13.42/Doc/index.html 0000644 0236657 0000012 00000002461 10333201523 0015201 0 ustar 00oz staff 0000433 0000002 Wily Homepage
The primary location for these documents is
http://www.cs.su.oz.au/~gary/wily/
Wily Homepage
Please send comments or queries to gary@cs.su.oz.au
wily-0.13.42/Doc/Credits 0000644 0236657 0000012 00000002722 10333201523 0014524 0 ustar 00oz staff 0000433 0000002 N. Wirth, J. Gutknecht
Oberon
Rob Pike
Acme
Gary Capell
Wily first draft, current maintainer
Bill Trost
too many patches, bugfixes, ideas to list
fixed listen() race condition
stripnulls bug
expanded address stuff
better env.c
reduce excessive redraws
fix for next_width bug
much of the messaging design
"undo" bugfix
Dot builtin
tag_findtool
Steve Kilbane
integrated sam's regexp
Richard Wolff
sunos4 patches,
msg.c bugfix
use salloc, srealloc in sam regexp stuff
Arnold Robbins
cleanup wilyfifo
ignore SIGPIPE
Assar
autoconfig stuff
Scott Schwartz
prevent $TMPDIR replacing /tmp in tag
fix to wily/sam.c:/^error_c
path.c - nextstr pathfind searchincludedirs
Mark H. Wilkinson
fix ESC bug
use $WILYBAK as the backup directory
bug in delpane
snarf/paste use X clipboard
memory overrun in libmsg/util.c:/^stripnulls
pstrapp
Bjorn Helgaas
fix bug when scrolling one-line window
bug in event.c
Font builtin
better scrolling
Local builtin
nicer scroll_init
FILENAME_MAX -> MAXPATHLEN in libmsg/connect.c
Kyle
wily.xpm
bug: in win.c
Davor Cubranic
bugs: New window has no cursor, Look in empty window dumps core
Rich Salz,
Beirne Konarski,
Scott Schwartz
Daniel Neri
"Split" bug-report
Stephen Gallimore
pathfind patch
wily-0.13.42/Doc/onepage.html 0000644 0236657 0000012 00000007360 10333201523 0015513 0 ustar 00oz staff 0000433 0000002 Concise Wily User Manual
Wily
Notation
B1, B2 & B3 are left, middle, right mouse buttons, respectively. "B1B2"
means to select some text with B1 held down, then click and release
on B2 while still holding B1 down. This is the B1B2 chord. There are
others. "Sweep with B1" means to hold down B1, drag it across some text
to select it, and then release B1.
Screen layout/control.
The screen is divided into columns, each of which is divided into
windows. Each window has a scrollbar and a one-line "tag" containing a
file/directory name and some commands. There is also a tag at the top of
each column, and at the top of the whole screen. A "layout box" is at
the left of each tag: dragging this box with B1 moves the window around
the screen; windows re-layout automatically when you drag and release
windows with this box. Clicking on the with B1 "grows" the window
slightly; B2 makes it grow until all other windows in the column only
show their tags. B3 makes the window tag up the whole column, hiding
other windows completely.
Selecting and editing text
Type normally anywhere on the screen to enter text; move the pointer
into the tag/window you want to type into. Position the cursor within
text either with cursor keys, or clicking once with B1. Sweeping text
and then typing Cuts the selected text, and replaces it with the
typed text. Cut and Paste are chords B1B2 and B1B3: sweep text with
B1, and complete the B1B2 chord to delete. B1B3 Pastes text over the
selected text. Double-clicking with B1 selects text quickly, picking
a word, a line, or text delimited by quotes, brackets, braces, or
parentheses, depending on where you double-clicked. Undo and Redo give
edit history. Layout box is filled in when text is modified but not
saved.
Executing commands
Sweep text (anywhere!) with B2 to execute it as a command. A single B2
click automatically selects a sensible "word" as the command. Commands
can be built-in (Capital first letters, by convention) or passed to
the shell for invocation. To invoke commands with arguments, sweep the
argument with B1, then click on the command with B2B1. If a B2 command
begins with |, > or < characters, the B1-selected text is piped through,
fed into or replaced by the results of the command, respectively. Any
output generated by commands appears in a window named dir/+Errors,
where dir is the directory the command was invoked in.
File/directory management
Windows show file or directory contents. The full path of the
file/directory is given in the tag. Selecting a filename with B3 (sweep
or single-click) will attempt to open that name relative to the pathname
in the window's tag. The new file/directory appears in a new window. If
the file can't be found, the B3'd text is searched for in the current
window instead. If the B3'd text is of the form ":n", it is a line
number to go to. ":/pattern" is a regular expression pattern to search
for.
Builtin commands
Anchor prints current selection address in tag. Clear clears
window. Cut cuts selected text to buffer. Del deletes window. Delcol
deletes column and windows. Dotfiles toggles display of dot files in
directory windows. Font toggles fixed/proportional fonts. Get reloads
window. Indent toggles autoindent. Kill halts named B2'd program. Look
searches for text. New creates new window. Newcol creates new
column. Paste pastes buffer. Put writes file to disk. Putall writes
all files. Quit exits Wily. Redo undoes last Undo. Snarf copies text to
buffer. Split opens up another window on the same file. Undo undoes
last edit.
Steve_Kilbane@cegelecproj.co.uk
wily-0.13.42/Doc/winmanager.html 0000644 0236657 0000012 00000002700 10333201523 0016216 0 ustar 00oz staff 0000433 0000002 The Wily Window Manager?
Window management is probably the biggest open problem with Wily,
probably because there's no real solution, only heuristics.
The first iteration of Wily creatied a bunch of separate X windows
and let the window manager handle arranging them. This seems a more
modular, tool-based approach. However, bitter experience showed that
most existing window managers just don't cut it when you're quickly
creating and deleting lots of windows. Acme's window management,was
much better.
The logical solution then would be to write an X window manager that
works like the window management in Acme. However:
- Writing a window manager requires knowing a _lot_ more about X than
I ever want to know
- Either the wily windows would need to be separate processes,
communicating probably via some sort of X IPC (more arcane X'ery), or
libXg would need to be modified to allow multiple windows (O who will
save me from this plague of X?)
- This sort of window manager would probably _not_ be appropriate
for managing the other windows normally on the desktop.
So Wily is designed to be run in one big window, and it does its own
window management within that. It's a bit of a hack, but probably the
best solution for the moment.
Still, I hope it shouldn't be too hard to remove the "Wily is managing
all the windows" assumption from the code if some brave soul solves the
problems mentioned above.
wily-0.13.42/Doc/download.html 0000644 0236657 0000012 00000001304 10333201523 0015674 0 ustar 00oz staff 0000433 0000002
Fetching Wily
Wily
Fetching Wily
Wily source code and documentation
and some binaries are
available via FTP from sites in
The Australian site is the primary, the others are mirrors.
If anyone else sets up a mirror for this stuff, please tell me?
gary@cs.su.oz.au
wily-0.13.42/Doc/idioms.html 0000644 0236657 0000012 00000012514 10333201523 0015356 0 ustar 00oz staff 0000433 0000002 Wily Idioms
Wily
Wily Idioms
This is a collection of useful scripts, guide files and ways
of working with Wily.
Guide files
Collect useful script names, file names, regular expressions
into a simple text file, which can act as a tool box/menu.
e.g.
my $h/lib/html/guide
|title |h1 |h2 |h3
|href http://
|mailto gary@cs.su.oz.au
|i |b |tt
|tag blockquote
|indent
and my $h/guide
remote rm guide |par |indent |undent :., :, W sam sg wdef 9term
Mace/in src/jcrab
news; overp comp.risks
$wilysrc $wilybin
I edit my $h/guide to have the names of files and directories
I'm frequently working with.
Start-up Script
Start Wily from a shell script which sets up the environment,
and initial files
#!/plan9/bin/rc
EDITOR=W # makes wily the editor for mail, etc.
path=(. $path) # add '.' to the path
exec wily $h/guide # use an initial 'guide file'
Short-cut Environment Variables
Set environment variables to make window labels
shorter and easier to type, e.g.
h = $HOME
wilysrc = $h/src/wily/wily
wilybin = $h/obj/$cputype/wily/wily
"buttons"
These are commands designed to operate on the window in which
they are clicked.
- Write a script which operates on $WILYLABEL, e.g.
createreplymessage $WILYLABEL
- Add a .wilytools entry so the name of the
script appears automatically in the tags of appropriate windows,
e.g.
Mace.*\$ subject
Mace reply
would ensure that all the subdirectories of Mace have a "subject"
button, and all the normal files in the Mace file tree have a "reply"
button.
wily tag
Use the wily tag (the tag above the columns) to store very
frequently used commands and addresses. This is particularly
useful because the wily tag is never obscured.
I normally copy the top line of my $h/guide file
to the wilytag as soon as I start Wily.
B3 to change "last selection"
B3 in the label of a window to make its body the last selection
without having to sweep the selection out again.
Plan to double-click
Put quotes or brackets around long commands you might want to
re-select later. It's just a bit easier than sweeping the
command out again.
double-click to check syntax
Double-click just inside a bracket or brace to find where
the other half of the matching pair is, e.g. to check if
you've got enough closing brackets.
double-click to select SGML elements
Double-clicking will select between >< pairs,
so given this text: "<H1>the heading</H1>",
double-clicking just before "the" will select "the heading".
address expressions in the wily tag
B3-ing in a tag with no body (i.e. the wily tag or a column tag)
searches for the address in the last selected window. This lets
you put common address searches (e.g. :, (select the whole window))
in the wily tag and apply them to a window by selecting the window,
then B3-ing in the address.
use history file(s)
Set $history and use it as a memory for obscure
commands you perform infrequently, and as a short-cut for
for commands you've performed recently.
I set $history based on the date. This gives me one file
with recent commands, and a directory full of files with older
commands. I use two history-printing commands, one called 'h'
which searches through the current history file, the other called
'hg' searches through all my history files, using
glimpse.
h
#!/plan9/bin/rc
if ( % $#* 0 ) {
tail $history
} else {
agrep $1 $history | tail
}
hg
#!/plan9/bin/rc
glimpse -H $h/lib/history -h -y -L 15 $*
remote interface to netscape
I call this script 'remote'
#!/plan9/bin/rc
for(i) {
netscape -noraise -remote 'openURL('^$i^',new-window)'
}
To use it, select one or more URLs, and B2B1 on 'remote'.
Netscape will then open a window on each of the URLs.
Look
- Use B2B1 on "Look" to search in one window for a symbol you have
selected in a different window
- Use "Look" to search for a symbol you can't search for with B3 because
its also the name of a file in "this" directory or the include path.
Backups
Edit and execute the "backup warning"
messages.
A typical one might be
backup 48 /n/staff/u13/pgrad/gary/guide
Replace the word backup with 'diff' and execute
the line to find out what changes were discarded.
Replace the word 'backup' with 'cp' to easily recover
the modified version of the file.
Poor man's hypertext
You can put the name of a related file in a comment, to
let you more easily jump between files. E.g. I have the
documentation for msg.h in C.html, so
each file has a comment referring to the other, e.g.
in msg.h,
/* see ../Doc/C.html for more extensive documentation */
and in C.html
<!-- documentation for msg.h -->
This makes it more likely that when I change one
file I'll just B3 in the name of the related file to jump to it.
gary@cs.su.oz.au
wily-0.13.42/Doc/Tcl.html 0000644 0236657 0000012 00000004344 10333201523 0014616 0 ustar 00oz staff 0000433 0000002 Tcl Programmers Manual
Wily Tcl Programmers Manual
this is a package of tools for communicating with wily using the Tcl
library. the file wily.c defines a thin veneer round wily's libmsg.
this compiles with wily-0.13.1[89] with tclversion 7.4.
the files wtcl.c and wtk.c compile against wily.c to give a tclsh alike
with wily support called wtcl, and a wish alike with wily support called
wtk.
the only addition to standard tcl/tk is the ``wily'' command. this has
several subcommands
- wily init
-
connects to wily. should be called before any other wily command
- wily isconnected
-
checks that we can still talk to wily. returns boolean.
- wily list
-
returns a list of window ids (integers).
- wily name <id>
-
returns the name of the window with given id.
- wily new <filename>
-
opens a new window with given filename.
- wily attach <id>
-
offer to collect events for window with given id.
we collect _all_ events.
- wily setname <id> <name>
-
set the name of window with given id to the given new name.
- wily settools <id> <tools>
-
appends the given tools to the tools for window with given id.
- wily read <id> <begin> <end>
-
returns the text between points <begin> and <end> in window <id>.
- wily replace <id> <begin> <end> <text>
-
replaces the text between points <begin> and <end> in window
id with .
- wily exec <id> <command>
-
just as if <command> had been b2'd in window <id>.
- wily goto <id> <string> <bool>
-
as if string had been b3'd in windows <id>. if <bool>
is true then we jump to and select the result.
- wily length <id>
-
the length of the text in window <id>
- wily wouldblock
-
return boolean. true if there is no event in queue.
false if there is.
- wily event
-
returns a string describing the event.
- wily bounce
-
return the last event received back to wily.
"stephen" sp106@york.ac.uk wily-0.13.42/Doc/demo.utf 0000644 0236657 0000012 00000000515 10333201523 0014646 0 ustar 00oz staff 0000433 0000002 ∙ Why use :-) when you can use ☺?
∙ Gøëring, Garçon
∙ Γαρη Ξαπελλ
∙ ∀x ∃y : ½y ≧ x²
∙ ♘♙♚♜♝♞♟♠♡♢♣♤♥♦♧♩♪♭♮♯
∙ ЙКЛ МОП РСУФХЦЧШЩЪЫЬЭЯабвг
∙ ひびぴふぶぷへべ ぺみむめもゃやゅゆょよるゎゐァイキ
∙ ∴ Use Wily
wily-0.13.42/Doc/Tcl.txt 0000644 0236657 0000012 00000003330 10333201523 0014463 0 ustar 00oz staff 0000433 0000002 this is a package of tools for communicating with wily using the Tcl
library. the file wily.c defines a thin veneer round wily's libmsg.
this compiles with wily-0.13.1[89] with tclversion 7.4.
the files wtcl.c and wtk.c compile against wily.c to give a tclsh alike
with wily support called wtcl, and a wish alike with wily support called
wtk.
the only addition to standard tcl/tk is the ``wily'' command. this has
several subcommands
wily init
connects to wily. should be called before any other wily command
wily isconnected
checks that we can still talk to wily. returns boolean.
wily list
returns a list of window ids (integers).
wily name
returns the name of the window with given id.
wily new
opens a new window with given filename.
wily attach
offer to collect events for window with given id.
we collect _all_ events.
wily setname
set the name of window with given id to the given new name.
wily settools
appends the given tools to the tools for window with given id.
wily read
returns the text between points and in window .
wily replace
replaces the text between points and in window
id with .
wily exec
just as if had been b2'd in window .
wily goto
as if string had been b3'd in windows . if
is true then we jump to and select the result.
wily length
the length of the text in window
wily wouldblock
return boolean. true if there is no event in queue.
false if there is.
wily event
returns a string describing the event.
wily bounce
return the last event received back to wily.
wily-0.13.42/Doc/auug.html 0000644 0236657 0000012 00000002461 10333201523 0015033 0 ustar 00oz staff 0000433 0000002 Wily Homepage
The primary location for these documents is
http://www.cs.su.oz.au/~gary/wily/
Wily Homepage
Please send comments or queries to gary@cs.su.oz.au
wily-0.13.42/Doc/AcmeVsWily.html 0000644 0236657 0000012 00000005465 10333201523 0016124 0 ustar 00oz staff 0000433 0000002 Acme Vs. Wily
Acme Vs. Wily
The following is a side-by-side comparison of Acme under Plan 9 vs. Wily
under Unix.
See http://www.cs.su.oz.au/~gary/wily/
for more docs.
Wily extensions and differences include:
- sam-like command redirections: <, >, | - operate on the current selection
- you can export rc functions and variables to wily
- no confirmations - automatic backup of dirty files
- no warnings when using New to create a new file
- black (dirty) resize box is more visible in wily
- long-running processes can open a socket to wily
- HISTORY mechanism
- Indent, Dotfiles, Clear and Anchor builtins
- Exit in acme is called Quit in wily
- Zerox in acme is called Split in wily
- acme executes a B2B1 command in the context of the command whereas
wily does it in the context of the argument
- acme selects B2 output
- window tags scroll horizontally
- contracting labels using environment variables. For example, if a window
represents /u13/pgrad/gary/src/, on the screen it will show up as $h/src/
if you set h=/usr/pgrad/gary
- if you hit Return immediately after selecting some tag text with the
Escape key, it acts as if you'd clicked it with button 2, so typing
'echo fish', Escape, Return executes that command.
- each line in $WILYTOOLS or $HOME/.wilytools can contain either a comment
(starts with whitespace or '#') or a regexp, then a tab, then some tools
(i.e. some text) which will be appended into the tag of any window whose
label matches the regexp. The first regexp match wins.
- editing the label of a window does "the right thing" if you then B2 on Get
- you can set the wily file, directory, column and main tags, via $WFILETAG,
$WDIRTAG, $WCOLTAG and $WMAINTAG
Wily does not have the following Acme capabilities:
- the Font builtin should be able to take an argument - this can be fixed
- Dump/Load not implemented yet (could be done by an external program)
- acme makes the right column skinnier - good for guide files
- there is no equivalent to /mnt/acme
- ID, Incl, Local, Send, Sort not implemented
A striking similarity :-)
- the View will scroll (with lots of ugly flicker) while selecting,
to allow you to select an area larger than the View.
Thanks to <Gerry.Tomlinson@newcastle.ac.uk>
and
<gary@cs.su.oz.au> for their comments.
Steve Kotsopoulos <steve@border.com> - Nov 11, 1996
wily-0.13.42/Doc/intro.html 0000644 0236657 0000012 00000010004 10333201523 0015215 0 ustar 00oz staff 0000433 0000002 Introduction to Wily
Introduction to Wily
What is it?
Wily is a mouse-oriented, text-based working environment for
programmers. It lets you interact with your files, directories and
other programs through mouse and keyboard operations on plain text.
./configure; make
should compile the program with no problems on most
Unixes with X Windows.
What does it look like?
Wily divides the screen into columns, and the columns
into windows. Each window has a one-line tag
which holds the name of the window, and some useful
bits of text. Text can be displayed in either proportional
or fixed-width fonts. Unicode fonts are supported.
Text is read and written in UTF8 format, which is backwards
compatible with 7-bit ASCII. The screen shot demonstrates
some of these features. Directories are tabulated.
What's good about it?
Wily's most attractive qualities are simplicity,
power and speed.
Simplicity
The interface is simple to learn.
A one page user manual
gives a reasonably complete description of how to use Wily.
The implementation is also reasonably simple:
wc -l *.[ch] gives a total of 8832 lines.
Power
Wily's simplicity derives from having few features.
However, these features are quite general, have few
complicating exceptions and combine well together.
Every piece of text on screen can be interacted
with in exactly the same way.
Part of Wily's power emerges from being able to combine
a few simple primitives in arbitrary combinations
(like chess or go).
Wily also encourages the use of other tools from the Unix
toolchest. It is easy to build a set of (for example) HTML
processing tools that work well with Wily.
Speed
With some practice, a decent mouse and mousepad,
a Wily user can be very quick. The author is moved
almost to tears of frustration using many other editors.
You need never retype anything while using Wily.
Interesting Features
Backups
Whenever a window containing changes not refleted on disk is deleted,
Wily first makes a backup of the file, instead of initiating an "are you sure?"
dialog. This seems not only quicker but safer than forcing a dialog, as
occasionally the user might give the wrong answer to a dialog, whereas
with this system a backup is always there.
Proportional text by default
This is much easier to read. On the rare occasions you need
to drop back to monospace, it can be done with a mouse-click.
Mouse "chords"
i.e. using a combination of mouse buttons for Cut and Paste.
This is way cool.
Unicode text
This is becoming more expected than unusual.
Drawbacks and problems
Wily is certainly not for everyone.
The main complaints against Wily, with some responses,
follow:
- You have to use the mouse too much
- The mouse is currently the best way to quickly select
an arbitrary piece of text on screen. Mostly you're
either using the mouse exclusively or the keyboard exclusively.
It is quite rare to "thrash" between the two.
- There aren't enough control keys/function keys
- go away
- There's no syntax highlighting
- Wily is for editing plain text
- I have to use an external program to do global replace?
- this is pretty simple and reasonably efficient
- Wily may someday include this functionality
- A builtin extension language would be more efficient than
using external programs
- Probably. The current system is much simpler and is
efficient enough so far.
- It doesn't seem very intuitive
- In other words, it doesn't seem very familiar, at first.
Of course. This is a necessary price of being very different.
On the other hand, Wily is so simple it takes very little time
to become familiar with it.
gary@cs.su.oz.au
wily-0.13.42/Doc/credits.html 0000644 0236657 0000012 00000005203 10333201523 0015524 0 ustar 00oz staff 0000433 0000002 People and history behind Wily
People and history behind Wily
Wilyfans
Mail wilyfans@jli.com with comments
and queries about Wily. The wilyfans list is the place for discussing and announcing
changes to Wily.
Mail wilyfans-request@jli.com
to (un)subscribe.
The list is archived at http://wwwtios.cs.utwente.nl/archive/wilyfans/threads.html
People
Regrettably, this list is very incomplete and out-of-date.
- N. Wirth, J. Gutknecht
- Oberon
- Rob Pike <rob@plan9.bell-labs.com>
- Acme
- Gary Capell <gary@cs.su.oz.au>
- Wily first draft, current maintainer
- Bill Trost <trost@cloud.rain.com>
- too many patches, bugfixes, ideas to list
fixed listen() race condition
stripnulls bug
expanded address stuff
better env.c
reduce excessive redraws
fix for next_width bug
much of the messaging design
"undo" bugfix
Dot builtin
tag_findtool
- Steve Kilbane
- integrated sam's regexp
- Richard Wolff
- sunos4 patches,
msg.c bugfix
use salloc, srealloc in sam regexp stuff
- Arnold Robbins
- cleanup wilyfifo
ignore SIGPIPE
- Assar <assar@pdc.kth.se>
- autoconfig stuff
- Scott Schwartz
- prevent $TMPDIR replacing /tmp in tag
fix to wily/sam.c:/^error_c
path.c - nextstr pathfind searchincludedirs
- Mark H. Wilkinson <mhw@minster.york.ac.uk>
- fix ESC bug
use $WILYBAK as the backup directory
bug in delpane
snarf/paste use X clipboard
memory overrun in libmsg/util.c:/^stripnulls
pstrapp
- Bjorn Helgaas <helgaas@convex.hp.com>
- fix bug when scrolling one-line window
bug in event.c
Font builtin
better scrolling
Local builtin
nicer scroll_init
FILENAME_MAX -> MAXPATHLEN in libmsg/connect.c
- Kyle <kaschei@staff.cs.su.oz.au>
- wily.xpm
bug: in win.c
- Davor Cubranic <cubranic@hermes.si>
- bugs: New window has no cursor, Look in empty window dumps core
- Rich Salz,
- Beirne Konarski,
- Scott Schwartz
- Daniel Neri <d92-dne@nada.kth.se>
- "Split" bug-report
- Stephen Gallimore <stephen@psyc.leeds.ac.uk>
- pathfind patch
History
Oberon
Help
Acme
Wily
Differences between Wily and Acme
Are detailed in another file
wily-0.13.42/Doc/FAQ.html 0000644 0236657 0000012 00000007427 10333201523 0014510 0 ustar 00oz staff 0000433 0000002 Wily FAQ
- What is wily?
-
See the introduction.
- What does "wilydiag: File exists: can't open fifo" mean?
-
Wily opens and listens on a fifo in /tmpin case some program tries
to communicate with it. If you're not doing anything tricky like that,
it won't get used at all. Ordinarily wily cleans the fifo up when it
exits, but if something dire happens Wily may not get a chance to clean
up. The fifo will be named $WILYFIFO if that is defined, otherwise
/tmp/wilyUSER$DISPLAY, where USER is your login name. Just remove it
and restart wily to be able to use wily messages.
- "Why does my compiler/editor/whatever complain about illegal
characters? The line looks fine to me."
-
Chances are that you've managed to enter a control character
accidentally, and the font you're using doesn't display control
characters. The easiest way to check is to select the line (or other
text) that's causing the complaint, and click on "|cat -v" (or some
other program that can display control characters, such as vis or od). I
find ^A the most common offender.
The Wily Window Manager?
Window management is probably the biggest open problem with Wily,
probably because there's no real solution, only heuristics.
The first iteration of Wily creatied a bunch of separate X windows
and let the window manager handle arranging them. This seems a more
modular, tool-based approach. However, bitter experience showed that
most existing window managers just don't cut it when you're quickly
creating and deleting lots of windows. Acme's window management,was
much better.
The logical solution then would be to write an X window manager that
works like the window management in Acme. However:
- Writing a window manager requires knowing a _lot_ more about X than
I ever want to know
- Either the wily windows would need to be separate processes,
communicating probably via some sort of X IPC (more arcane X'ery), or
libXg would need to be modified to allow multiple windows (O who will
save me from this plague of X?)
- This sort of window manager would probably _not_ be appropriate
for managing the other windows normally on the desktop.
So Wily is designed to be run in one big window, and it does its own
window management within that. It's a bit of a hack, but probably the
best solution for the moment.
Still, I hope it shouldn't be too hard to remove the "Wily is managing
all the windows" assumption from the code if some brave soul solves the
problems mentioned above.
Funky B3 expansion allows some letters, not others?
To quote rob (it was originally rob's comment, wasn't it?): "Hard to
get absolutely right." The problem is that you can have pretty much
everything in a filename apart from \0, but usually you want it to
pick sensible strings. It's not just filenames, after all, but also
identifiers in programs. After all, Acme is primarily a programmer's
tool, because there aren't any other kinds of Plan 9 user. :-) Plus,
most of them are shell metacharacters (in rc).
The set you want to match varies from instance to instance, so it's
pretty much an arbitrary choice. Sometimes you lose. Some justification
would be good for the docs, though. Anyone know why "*" is considered
a valid character? Hmmm. Ones not in the above list are "#$^*_-:~,./".
Of these, "~./" are parts of common filenames (~steve/x.c), "#$-:,."
are part of the syntax for expressing an Acme address, and "_" is a
common identifier character. That just leaves "^*". I suspect these
are allowed because they're commonly used as part of a regexp search.
Steve Kilbane
Why does it take so long to load my [mumble]-meg file?
Blame steve.
wily-0.13.42/Doc/user.html 0000644 0236657 0000012 00000057560 10333201523 0015062 0 ustar 00oz staff 0000433 0000002 Wily User Manual
Wily User Manual
Command-line Arguments
wily [-p9fn font] [-fn font] [-p9fixed fixedfont] [-a tabsize] [-c columns] [file name...]
- -p9fn font
- (or X resource
p9font) set the default
proportional font. This must be the name
of a Plan 9 font file.
- -fn font
- (or X resource
font) set the default
proportional font. This must be the name
of a X font. The default is "variable"
- -p9fixed fixedfont
- (or X resource
p9fixed) set the monospace font.
This must be the name
of a Plan 9 font file.
The default monospace font is "fixed"
- -a tabsize
- set the maximum width of tabs (as multiple of the
width of the character '0') for the proportional font.
Defaults to 4.
- -c columns
- set the initial number of columns.
Defaults to 2.
- -e command
- Run 'command' on startup.
- file name...
- Start wily with the named files and directories
open.
Environment variables
- SHELL
-
External commands are sent to the shell for evaluation.
Defaults to /bin/sh
- HISTORY
-
If $HISTORY or $history are set,
commands are written to this file before execution.
- WILYBAK
-
Wily uses $WILYBAK or $HOME/.wilybak
as the directory for backups.
- WMAINTAG, WCOLTAG, WFILETAG, WDIRTAG
-
If any of these are set, their value is appended to the default
text to be added to the tag of the main window, a column,
a file window or a directory window, respectively.
- WILYTOOLS
-
If $WILYTOOLS or $HOME/.wilytools
exist, they are read and used as a tools patterns file.
(See later section).
- INCLUDES
-
If set, this is used as a search path for include files.
- WILYLABEL, w
-
For external processes, Wily sets $WILYLABEL and
$w to the label of the window in whose context a
command is executing.
- PATH
-
Wily itself ignores $PATH, but when it calls the
shell to run external programs the value of $PATH
is important.
- WILYFIFO, DISPLAY, TMPDIR
-
Wily communicates with some other programs using a fifo at
a well-known location.
The name of the fifo will be $WILYFIFO
if this variable is set, otherwise it will be
/tmp/wilyUSER$DISPLAY, where USER
is calculated from the password file. If $TMPDIR
is defined, it is used instead of /tmp.
Wily also sets $WILYFIFO so any children
it creates will know how to talk to it.
Appearance
Column, window, tag, body, resize box
Wily appears as one or more vertical columns, divided into windows
of scrolling text. Each column or window is headed by a one-line
tag. The leftmost text of the tag (up until the first whitespace)
is the name of the window. Usually this is the name of some file or
directory. Wily also places other bits of text in the tag, which might be
useful later as commands. There is a one-line tag above all the columns,
which is called the wily tag.
The text in the body of the window may represent a directory,
a file, the interface to some program like a news reader, or the output
from a program.
The small square-ish box to the left of the tag is called the
resize box. The resize box is used for moving and reshaping
windows and columns.
If the resize box is filled in, this indicates that the window is
dirty. A dirty window contains text which has been modified
since it was last read from or written to disk.
Proportionally spaced, Unicode text
Text is displayed in a propotionally spaced font by default. There
is a built in function to toggle with a monospace font when required.
Text is read and written as
UTF8-encoded Unicode,
providing some support for editing multi-lingual and scientific text,
but remaining backwardly compatible with plain 7-bit ASCII text. See
9term for
an example of another program with Unicode support, with some screen
shots.
Notation
B1, B2 & B3 are left, middle, right mouse
buttons, respectively. Used as a verb, they mean "click with that
button". E.g. "B2 in the command word" means "click with the middle
mouse button in the command word".
B1B2
means to select some text with B1 held down, then click and release
on B2 while still holding B1 down.
Sweep with B1 means to hold down B1, drag it across some text
to select it, and then release B1.
The last selected text is the text which was most
recently selected, usually by being swept with B1.
The last selected window is the window containing
the last selected text. This is indicated by
that window having a slightly thicker border. If the last
selected text was in a column tag or the wily tag, there is no
last selected window.
Context
All text in wily has a context. The context is the name of a
directory associated with that text. This context is used when
executing commands and opening files.
If the text is in a window, its context is the name of that window,
up to and including the last /. So if three windows have the
names /usr/gary/+Errors, /usr/gary/guide and
/usr/gary/, the context for all the text in all of these
windows is the same: /usr/gary/. Note that the context need
not be a directory which actually exists.
If the text is in a tag which isn't part of a window
(i.e. a column tag or the wily tag), the context is the
name of the directory where wily was started.
Scrollbars and scrolling
Scrollbars are proportional, i.e. the size and position of the
scrollbar's thumb indicates the size and position of the visible
portion of the text.
Each of the three mouse buttons does something different when
clicked in the scrollbar.
B1 and B3 are used for relative movements. B3 moves the text
next to the mouse pointer up to the top of the window. B1 moves the
text at the top of the window down so it is next to the pointer. Both
of these rules have the effect that clicking near the top of the
scrollbar causes small movements, (either up or down) and clicking near
the bottom causes large movements.
B2 is used for absolute positioning.
B2 moves the visible part of the text to a point in the
text proportional to how far down the scrollbar the pointer is.
That is, clicking at the bottom of the scrollbar with B2 jumps
to the end of the text, clicking at the top of the scrollbar with B2
jumps to the beginning of the text.
All of these movements repeat if the mouse button is held down
in the scroll bar.
The PageUp and PageDown keys scroll up or down
by about half a page. The Home and End keys
scroll to the top or bottom of the file.
Selecting and editing text (B1)
Type normally anywhere on the screen to enter text. The keyboard focus
follows the pointer in a "point to type" fashion. That is, the
characters you type will appear in the tag or body which currently
contains the pointer. Position the cursor within text either with
cursor keys, or clicking once with B1. Select text by sweeping it with
B1. Sweeping text and then typing replaces the selected text with the
typed text.
Control Keys
- ctrl-u
-
delete line
- ctrl-w
-
delete word
- Escape
-
if the selection is null, select all the most recently typed text,
otherwise delete the selection
Double-click
Double-clicking with B1 can select a word, a line, or the text
delimited by quotation marks, braces, brackets or parentheses,
depending on where you double-click.
Executing commands (B2)
Selecting the command
Sweep text with B2 to execute it as a command.
If you start sweeping some text with B2, then decide you
don't want to execute it, click B3 before you release B2
(i.e. a B3B2 chord) to abort.
The command window is the window containing the
text which was swept with B2. The context of the command is
the context of the text swept with B2.
If the text starts with the name of one of the builtin commands,
that builtin is executed.
Otherwise, the command is executed by forking a subprocess, establishing
an environment and execing $SHELL -c command.
Environment for external commands
- The current directory is set to the context of the command.
- $WILYLABEL and $w are set to the name of the command window
and added to the environment.
- Standard input is set to /dev/null
- Standard output and standard error are set such that output
to them ends up being sent to a window in Wily called
context/+Errors
- The first word of the command will be added to the wily tag to
indicate which programs are currently running.
- $WILYFIFO will be set to the name of the fifo this
instance of Wily is listening to for messages. See the main wily page for programmers manuals on how to
use this messaging interface.
One exception is that if the name of the command starts with
"|", "<" or ">", standard input and
output of the command are set up such that the last selection is piped
through the command, fed into the command or replaced by the output of
the command, respectively.
For example if a paragraph is currently the last selection,
executing "|fmt" will format the paragraph, executing
">lp" will print it, and executing "<cat file"
will replace it with "file"
Builtin Functions
By convention all of the builtin functions start with a capital letter.
Some of them operate differently
if called with an argument.
- Put, Get, Putall
-
Put and Get write the window to disk, or fetch from disk, respectively.
If called with an argument, they will use the argument as the
filename, instead of the name of the window.
Putall writes all dirty files to disk.
- New, Del
-
Create a new window, or delete a window, respectively. If New
is called with an argument, it will use the argument as the
name of a file to create, otherwise the new window is called
context/New, where the context is taken from the last
selection.
- Look
-
Searches in the command window for literal text.
The text it searches for is either the argument to Look, or the
current selection in the body of the command window.
- Undo, Redo
-
Move backward or forwards through the (infinite) Undo log.
If called with an argument, these commands repeat until they
reach an end of the log, or the text is in the same state as it was
the last time the file was read from or written to disk.
- Newcol, Delcol
-
Create or delete a column
- Cut, Paste, Snarf
-
Cut the currently selected text to the X selection buffer,
replace the currently selected text with the X selection buffer,
or copy the currently selected text to the X selection buffer, respectively.
- Quit
-
Exit wily.
- Kill
-
Kill some process which was started from wily. If called with an
argument, Kill that process. Without an argument, Kill writes a
list of possible Kill commands to window $wilydir/+Errors
- Font
-
Toggle between fixed and proportional fonts. Depending
on where Font is clicked, changes the font for a window, a column,
or for all the windows on the screen.
- Dotfiles
-
Toggles whether or not dot files are displayed in directories. Directories
will not be re-read automatically, though.
- Anchor
-
Adds an address to the tag of the last selected window.
If called with an argument, the address is a line address,
otherwise the address is a character address. The address is
of the form ":currentaddress,."
To select large chunks of text, B1 click at the beginning
position, execute Anchor, B1 click at the end position, then
click with B3 in the address in the tag. The anchor may also
be used as a bookmark, or just to find the character or line
position in a window.
- Split
-
Split the most recently selected window into two. Editing actions in
one window will be visible in the other.
- Indent
-
Toggles autoindent for a window or all windows, depending on the command window.
- Clear
-
Deletes all the text in the command window.
The system tries to ensure that the names of some builtin
commands are added to or removed from window tags as appropriate.
For instance, when a window becomes "dirty", the word "Put" is
added to its tag, and removed again when the file becomes clean.
Similarly, the words "Undo" and "Redo" should appear in the tag of
a window when and only when they can be executed.
Open/Search (B3)
Sweep text with B3 to make Wily try to goto (open or search for)
the swept text.
The text may be interpreted as:
- filename:address
-
Open filename and search in it for address
- :address
-
Search for address in the window containing the swept text,
or in the last selected window, if the swept text was not in a window.
- filename
-
Open file or directory filename if it exists.
- includefilename
-
Open includefilename if it can be "massaged" (see
below) into the name of an include file (e.g. stdio.h)
- literal
-
If the swept text is contained in a window, do a literal search in
the body of the window for literal.
When trying to open a file or directory, the swept file name will be interpreted
relative to its context. For example, the text foo.c:14 in
a window with context /usr/gary/src/ will be
interpreted to mean the address /usr/gary/src/foo.c:14
Addresses
Wily uses the address and regular expression code from
Sam.
Please refer to the Sam manual
for a better explanation.
- #n
-
The empty string after character n; #0 is the beginning of the file.
- n
-
Line n; 1 is the beginning of the file.
- /regexp/ ?regexp?
-
The substring that matches the regular expression, found by
looking toward the end (/) or beginning (?) of the file, and
if necessary continuing the search from the other end to the
starting point of the search. The matched substring may straddle
the starting point. When entering a pattern containing a literal
question mark for a backward search, the question mark should be
specified as a member of a class.
Regexps are as defined in
regexp(6)
in the Plan 9 manual.
- $
-
The null string at the end of the file.
- .
-
Dot. The current selection in a window.
- address1,address2
-
The range from the start of address1 (defaulting to the start of
the file) to the end of address2 (defaulting to the end of the file).
E.g. :., selects from the current selection to the end of file.
Include Files
When searching for a filename, if the filename doesn't exist in the
context of the search text, Wily also tries to expand the file name
using a few simple heuristics.
If we are searching for name
and name appears between double-quotes or
angle brackets, Wily also
searches for name in the directories in the search path
$INCLUDES (or
/usr/include, if $INCLUDES isn't set).
For example, sweeping stdio.h between angle brackets will
open /usr/include/stdio.h on the author's system.
Mouse short cuts
Cut (B1B2), Paste (B1B3)
To cut some text into the clipboard, select the text with B1,
and while holding it down, click B2.
The selected text will be cut from the window and copied to the
clipboard.
Similarly, select some text with B1, and while
holding it down also click B2, and the selected text will
be replaced by the contents of the clipboard. The clipboard will be
unaltered.
Note that so long as you hold down B1, you can alternately
Cut and Paste the selected text with B2 and B3.
A Cut immediately followed by a Paste in this way leaves the
file unmodified, and has the effect of copying the current
selection to the clipboard.
Execute with argument (B2B1)
A command can be called with an argument using another mouse chord.
Sweep the command with B2, and while holding it down,
click B1. The last selection will be appended to the command.
The context of the command and the command window
will be set to the context of the last selection (unless the command
is a builtin).
For example, say I have a script called "sg" (short for
source grep) that greps through all the source files
in the current directory for a symbol given as an argument. I can
then sweep with B1 to select "printf" in a source file, then B2B1
on the word sg (anywhere). The command "sg printf"
will then run in the same directory as the source file.
Selection expansion
A null selection (single click) with B2 or B3 will be expanded to some of the surrounding
text.
A click inside an existing selection will be expanded to that selection.
This means you can select (with B1)
some complicated command once,
and B2 inside
this selection many times to execute the command repeatedly.
This rule is also helpful when searching through multiple occurrences
of a piece of text, as clicking with B3 in the most recently found
instance searches for the next instance.
A click that is not inside an existing selection will be expanded depending
on which mouse button was used.
A single B2 click
automatically selects a sensible "word" as the command. Commands can be
built-in (Capital first letters, by convention) or passed to the shell
for invocation.
Clicks with B2
are expanded to select commands, i.e. strings of alphanumeric characters,
|, > or <.
Clicks with B3
are expanded to select addresses, i.e. strings of alphanumeric characters,
:, ",".
Miscellaneous
Window management
Wily windows are placed automatically using heuristics. Hopefully most
of the time the window will be placed somewhere useful. However,
windows and columns can be moved and reshaped. The resize box (the
little box on the far left of the tag) of a pane or a column may be
manipulated to move or reshape a window.
Dragging the resize box (with any mouse button) moves the column or
window to the desired location.
Clicking in a pane's button with different mouse buttons has these
different effects:
- B1
-
the window grows a bit, first taking up any blank space
in the column
- B2
-
Every window except the desired one is shrunk so that only their tags
are visible, leaving more space for the desired window.
- B3
-
The window expands to take up the whole column, obscuring all
the other windows in that column. Clicking with any mouse
button in the window's resize box will undo this effect.
Cursor Warping
After a successful search, the text that was found is highlighted, and
the cursor is warped there, so that to search for the next instance of
the search text, no cursor movement is required, it is only necessary
to click the rightmost mouse button again.
Window re-arranging operations warp the cursor to the resize box of the
window that moved, so the move can be easily refined.
Back-up files
Whenever a dirty window is to be deleted, a backup is made.
This is an alternative to the familiar (and
often-annoying) "are you sure you want to close this
window?" dialog. A warning message is printed when this happens.
Backup files are kept in directory $WILYBAK if it
exists, or $HOME/.wilybak. In this directory the file
TOC is a table of contents showing what real file each backup
file maps to.
.wilytools
Wily attempts to read either $WILYTOOLS or $HOME/.wilytools. Each line in this file should be either empty, a comment
(starts with '#') or a pattern, a tab, and some arbitrary text.
The pattern is a regular expression. Every time Wily creates a new
window, if the window's name matches one of the patterns, the text after
the tab on that line will be appended to the tag for that window.
Wily stops searching after the first match.
Below is the author's .wilytools :
Mace.*Errors$ Clear mace subject
Errors$ Clear
Mace/in/$ mace subject
Mace/in reply wrm wmov
Mace.*/$ subject
Mace/out deliver
Mace reply wrm
/src/.*/$ def sg
News followup
Makefile make
print/$ gv bpr
\.py$ ptest
bin/rc/ 775
The mace, reply, deliver and subject scripts and Mace
directory are to do with reading mail. def and sg
are useful scripts for searching through source files, so they are
added to the tag of any directory with src in its pathname.
make is a logical command to execute when viewing a
Makefile.
Fonts
Wily uses two fonts: a variable-width default font, and
an alternative fixed-width font. These may be set with
command-line arguments or X resources.
Wily first tries to open a Plan 9 font file, given as either
a -p9fn command-line option or *p9font X resource.
Failing that, it uses the -fn command-line option or *font X resource.
Failing that, it uses the font "variable".
Plan 9 font files are useful for
supporting the full Unicode range without requiring
massive fonts. The font file sets up a font by joining together
different subfonts. See the 9term page
for information about obtaining Unicode fonts and utilities to convert
other character sets to Unicode.
The format of of a font file is described below:
(Taken from font(4) from the Plan 9 Manual)
External fonts are described by a plain text file that can be read
using rdfontfile. The format of the file is a header followed by
any number of subfont range specifications. The header contains two
numbers: the height and the ascent. The height is the inter-line
spacing and the ascent is the distance from the top of the line to the
baseline. These numbers are chosen to display consistently all the
subfonts of the font. A subfont range specification contains two
numbers and a font name. The numbers are the inclusive range of
characters covered by the subfont, and name specifies the name of an X
font suitable for getsubfont. The minimum number of a covered
range is mapped to the first defined character of the corresponding
subfont. Each field must be followed by some white space. Each
numeric field may be C-format decimal, octal, or hexadecimal.
Here is the start of the font file the author uses for a monospace font:
17 14
0x0000 0x00FF lucm.latin1.9
0x0100 0x017E lucm.latineur.9
0x0180 0x01F0 matty.latinext.9
0x0250 0x02E9 lucm.ipa.9
0x0300 0x0308 matty.gendiacritics.9
0x0370 0x0372 matty.greekpunc.9
0x0386 0x03F5 lucm.greek.9
0x0400 0x0475 misc.cyrillic.9
Entering non-ASCII characters
Refer to the Plan 9 keyboard(6) manual page, which is mostly how
it works in wily.
References
UTF8-encoded
Unicode,
gary@cs.su.oz.au
the text foo.c:14 in
a window with context /usr/gary/src/ will be
interpreted to mean the address /usr/gary/src/foo.c:14;[ThztSiY :dED#F}Φw[/2hlul&3jPH飉fƥ)!cvk$n\X mScreate('/win/name');
%wins = $wily->list();
$id = $win->id();
if ($win->isattached()) { ... }
$win->setname('/mumble');
$win->settools('foo bar baz');
$win->attach($mask);
$win = $wily->open($name, $id);
$text = $win->read($p0, $p1);
$win->replace($p0, $p1, $newtext);
$win->exec($cmd);
$win->goto($q0, $q1, $addr, $setdot);
$length = $win->length();
if ($win->wouldblock()) { ... }
$msg = $wily->event();
$msg = $win->event();
$win->bounce($msg);
$wily->bounce($msg);
($type, $msgid, $winid, $p0, $p1, $flag, $string) = unwrapmsg($msg);
$msg = wrapmsg($type, $msgid, $winid, $p0, $p1, $flag, $string);
$fd = $wily->fileno();
$errmsg = $wily->errstr();
DESCRIPTION
CONNECTING TO WILY
$wily = new Wily;
This connects to Wily. It doesn't do anything else, so you're
not going to receive any events, or see any new windows appear.
$wily is an object that you can use to communicate with wily,
however.
There is no disconnect operation: this happens automatically
when the Perl process dies.
CREATING NEW WINDOWS
$win = $wily->create($winname);
This returns a new object that you can use for performing
operations on the window. The window should appear on Wily's
screen immediately. You can use $win for sending messages to
Wily immediately - see below. Right now, you can't specify
whether the window refers to a real or virtual file.
This method used to be called newwin(), but was renamed to
open() as of 0.03. newwin() will still work, but you'll get a
non-suppressable warning.
LISTING EXISTING WINDOWS
%list = $wily->list();
or
%list = $win->list();
The returned hash is the paths of each window currently open in
Wily, indexed by their window ids. Note that it doesn't matter
whether you use the connection object or a window object to get
the list.
OPENING EXITING WINDOWS
$win = $wily->open($name);
$win = $wily->open($id);
$win = $wily->open($name, $id);
This method returns a window object that is connected to the
named window, but not attached to it; you won't receive any
events from it yet. You can use the window's name, id or both to
specify the window to be opened.
This method was briefly called oldwin(), which was pretty daft.
It's also the reason why newwin() was renamed to create().
WINDOW IDENTIFIERS
$id = $win->id();
This just returns the id of the current window. You only really
need this for finding out the window's pathname, with the list()
method above. Window objects will return their identifiers, but
the connection object will return a fake ID (because it's not
really a window). This ID has the value $MainCon, which you can
reference if you include it in the "use" statement, or if you
explicitly give the package name: $Wily::MainCon.
CHANGING TAG LINES
$win->setname($newname);
$win->settools($newtools);
These methods allow you to change the pathname or tool list for
a window. They return true if successful. Note that the tool
listing is a single string. It should probably be a list, but it
isn't, at the moment.
READING WINDOW TEXT
$text = $win->read($p0, $p1);
This method returns a single UTF string, containing the text
between character offsets $p0 and $p1 ($p1 is the offset of the
first character AFTER the returned range). If the read fails -
such as because the range is invalid - the method returns undef.
WRITING WINDOW TEXT
$win->replace($p0, $p1, $newtext);
This method is used for updating window contents. The text
specified by the range $p0-$p1 is removed, and $newtext is
inserted in its place. If $p0==$p1, this is just a simple
insertion. If $newtext is the empty string, then this is just a
deletion. Returns false if it fails.
SEARCHING AND ADDRESSES
$win->goto($q0, $q1, $addr, $setdot);
A slightly more complex method, this. It's used for two things:
resolving a textual address into a character offset range, and
for setting dot. $q0 and $q1 specify the starting range for the
search. $addr is the text to search for. It can be any Wily
address:
If Wily manages to find what you're searching for, it sets
the values of $q0 and $q1 to its address. If $setdot is also
true, it also moves the window's current selection to be
where the matched text is.
Returns true if the pattern is found, and false otherwise.
There are a couple of bugs in this method. The first is that
you should be able to specify that dot will be used, and
that $q0 and $q1 are ignored. The second is that if the
address happens to reference a different window, it should
return the window id of the new window.
WINDOW CONTENTS LENGTH
$len = $win->length();
This method is just a wrapper around goto(), but it seems to
be quite handy.
SENDING COMMANDS TO WILY
$win->exec($cmd);
Runs $cmd in the context of the window. $cmd can be a shell
command, or it can be a Wily builtin. Returns false if
something doesn't work.
HANDLING EVENTS
Attaching
Initially, window objects aren't attached to the window
they're associated with. This means that Wily handles all
events itself. To start receiving events for a window you've
created, use:
$win->attach($mask);
Mask specifies which events you're interested in. The events
are:
Just add the events that you're interested in together,
as in:
$win->attach($WEexec + $WEgoto);
Again, name the events in the "use" statement, or use
$Wily::WEexec, etc.
Attach returns true for success, and false for failure.
To attach to an existing window, use:
$win = $wily->open($id);
$win->attach($mask);
where $id is the ID (or the name) of the window you want
to attach to. The resulting object is an attached window
object (or undef, if something goes wrong).
Version 0.02 used a method called attachid(), which
turned out to just a fairly limited improvement over
version 0.01 - you could attach to windows just created
with newwin(), but not to existing windows. attachid()
has been replaced by a combination of open() and
attach(); attachid() will still work, but you'll get a
non-suppressable warning message.
Wily will send goto and exec events directly to your
client, without any processing. In contrast, replace
events will already have been processed when you receive
them; Wily is merely informing you of their occurrence.
I'm not sure when wily sends destroy events; so far,
I've never seen one. :-)
Wily patch
The wily.patch file contains a patch to
../wily/external.c - it fixes two problems. The first is
that Wily 0.12.11 didn't expect any clients to bounce
WEreplace events (after all, Wily's already processed
them), so it didn't check for them. The result was that
it reports them as unknown events. This patch just makes
Wily ignore them. The other problem is that Wily echoes
WEreplace events back to the client that sent them in
the first place, if that client is attached to the
window. This is a little silly, and means that clients
have to be extremely careful about event handling. This
patch stops Wily doing this, so you know that if you
*cause* the event, you're not going to be notified about
it too.
Detaching
$status = $win->isattached();
This method is to determine whether you're attached to
the window. The Wily.pm module is supposed to notice the
destroy events coming in from Wily, and mark the window
object as detached, but since Wily doesn't seem to send
these events, this doesn't work at the moment. As for
explicitly detaching, there ISN'T a method for doing
that. Nor, apparently, can you change the set of events
you want to receive.
Accepting events
You receive events with:
$msg = $win->event();
The returned value is an anonymous hash containing the
components of the message. The keys are:
't' - the message type.
=item 'm' - message ID.
=item 'w' - window ID.
=item 'p0' and 'p1' - the range.
=item 'f' - the flag.
=item 's' - the string.
so you can do:
if ($msg->{'t'} == $WEexec && $msg->{'s'} eq 'Del') {
...
}
The event() method blocks until it receives an event, so
you can use:
$win->wouldblock()
which returns true if event() would block.
For both event() and wouldblock(), if you call them from
a window object, they'll only consider events for that
window. If you call them from the connection object,
they'll return events for any windows. WARNING: This is
untested functionality - I *think* it'll queue events
for other windows properly, but I haven't had a chance
to check it yet. Also, bear in mind that if you have
several windows accepting events, you should make sure
that you read events for other windows eventually, to
drain the queues.
In the returned hash, 't' is a numeric value, equal to
one of the four event types given previously. 'm' is the
identifier of the message. I don't think it's actually
useful, but Wily might pay attention to it in bounces -
I'm not sure.
'w' is the window identifier of the window this event
occurred in. This is necessary if you've got more than
one window attached at once, and you're reading with the
connection object, instead of the window object.
'p0' and 'p1' are range involved:
In both exec and goto events, the range will have
been expanded by Wily to something sensible, if it
was a single-click event.
Offhand, I can't remember what 'f', the flag
signifies, in events.
's' is the inserted text, for replace events, the
command to be executed in exec events, or the
pattern to be searched for, in goto events.
If you don't like using the returned hash, you can
break it up into a list, using the function
"unwrapmsg":
($type, $msgid, $winid, $p0, $p1, $flag, $string) = unwrapmsg($msg);
Note that this isn't a method, which means that you
have to name it in the "use" statement, or precede
it with "Wily::".
Bouncing events
It's quite common that you're only interested in
specific instances of a kind of event. For example,
with exec events, you probably only care about the
commands your client supports. The bounce() method
allows you to send an event back to wily, if you're
not interesting in handling it:
$win->bounce($msg);
$wily->bounce($msg);
It doesn't matter whether you use the connection
object or a window object - the information needed
is all in the message anyway.
If you to construct the message yourself, you can
use the function "wrapmsg":
$msg = wrapmsg($type, $msgid, $winid, $p0, $p1, $flag, $string);
Again, this is a function, not a method, so you'll
have to import it.
WAITING ON MULTIPLE INPUT SOURCES
If you need to select() on Wily's connection,
because you've got other input sources to worry
about, then you can use:
$fd = $wily->fileno();
This will return a file descriptor that you can use
with vec() and select() in the normal Perl way. Note
that this relies on a small modification to
libmsg/rpc.c, so you have to apply the patch in the
file msg/rpc.patch before it'll work (or, in fact,
compile).
ERROR MESSAGES
The errstr() method is supposed to return any error
messages generated by libmsg, but it doesn't appear
to be too reliable. Is that ironic, or what?
print "Everything's broken: " $wily->errstr(), "\n";
DEBUGGING
If you set $Wily::Debugging = 1, then you'll get
buckets of diagnostics from the Perl module. If you
define -DWILYPERLDEBUG in the Makefile.PLs, and
rebuild *everything*, you'll get a little more from
the underlying C code, but nothing startling.
TESTING
The test script, test.pl, attempts to exercise some
of the module's functionality in a controlled way.
It doesn't try out everything, because I can't think
of a way of testing some of the methods where I can
confirm their results reliably.
You should have an instance of Wily running when you
do "make test", and the Wily version must be the
same as the one you originally linked the Wily
module with, otherwise they probably won't talk to
each other.
Also check at the beginning of the script, for where
it sets the value of $WILYFIFO:
# $
Steve_Kilbane@cegelecproj.co.uk
rch. $addr is the text to search for. It can be any Wily
address:
If Wily manages to find what you're searching for, it sets
the values of $q0 and $q1 to its address. If $setdot is also
true, it also moves the window's current selection to be
where the matched text is.
Returns true if the pattern is found, and false otherwise.
There are a couple of bugs in this method. The first is that
you should be able to specwily-0.13.42/Doc/C.html 0000644 0236657 0000012 00000027265 10333201523 0014265 0 ustar 00oz staff 0000433 0000002 Wily C Programmers Manual
Wily C Programmers Manual
Introduction
Although a lot can be done with simple scripts and Wily,
some applications will need finer control. Wily can act as a
"user interface server". Clients can create and manipulate
windows, and/or monitor events which happen in windows,
by sending and receiving messages.
There are two "levels" to the interface: an "RPC" level,
where the library looks after low-level details of queueing, packing
and unpacking messages, and a lower-level interface dealing more
directly with message packets.
Warning this API hasn't been used very much.
There could well be bugs lurking in unused sections of code,
and the API could well change.
Establishing a Connection
Call client_connect(), which returns a file descriptor
open for reading and writing to Wily, or a negative number if
there's been some error. client_connect() uses $WILYFIFO
if it is set.
RPC-style Interface
Opening, Closing and Checking the RPC interface
Handle* rpc_init (int fd);
Create a new RPC handle to use file descriptor fd, which
was probably returned from client_connect
rpc_init cannot fail.
Bool rpc_isconnected(Handle*h);
Return whether or not h is still connected. If the RPC
library starts receiving gibberish messages, it will cut the
connection.
void rpc_freehandle(Handle*h);
Release any resources used by h, and free h
itself.
Requests
If there's any sort of failure, all of these functions return a
pointer to an error message, which is stored in a static buffer and
only guaranteed to remain valid until the next rpc_*
function is called. After a failure, it's possible that the connection
to wily has been lost. This should be checked using
rpc_isconnected
If successful, these functions return (char*)0.
List existing windows
char* rpc_list (Handle*, char **bufptr);
If successful, allocates a string,
and stores a pointer to it in bufptr. It is the programmer's
responsibility to free(*bufptr).
The string contains one line for each window currently open in Wily.
Each line contains the name of the window, some whitespace, and a
unique number which identifies the window. The window identifiers
are not reused within an invocation of Wily.
Below is some example output from rpc_list:
/n/staff/u13/pgrad/gary/src/wily/Doc/C.html 45
/n/staff/u13/pgrad/gary/src/wily/Doc/index.html 41
/n/staff/u13/pgrad/gary/src/wily/Doc/ 40
/n/staff/u13/pgrad/gary/guide 0
Open or create a window
char* rpc_new (Handle*, char *s, Id*id, ushort backup);
Create or open window with name s. If
Wily already has a window named 's', it uses that window,
otherwise it creates a new window.
The identifier for the opened/created window will be stored in
id.
If this request creates (not just opens) the window,
Wily will make sure backups are kept for the window (and indicate
when the window is dirty) if and only if backup is set.
Request events from a window
char* rpc_attach (Handle*, Id w, ushort mask);
Asks Wily to send us events which happen in window w
and match event bitmask mask.
Each window can be sending events to at most one remote process.
The window sends only events which match its event bitmask.
An event bitmask is formed by ORing some combination of (WEexec, WEgoto, WEdestroy, WEreplace) (explained further below).
rpc_attach will
fail if w doesn't exist, or is already sending its
events somewhere else.
To stop receiving events from a window,
use an rpc_attach with a mask of 0.
Change a window's name
char* rpc_setname (Handle*, Id w, char *s);
Set the name of window w to s.
Change a window's "tools"
char* rpc_settools (Handle*, Id w, char *s);
Set the tools section of w to s
Read data from a window
char* rpc_read (Handle*, Id w, Range r, char*buf);
Read range r from w into buf,
which must have enough space (UTFmax * RLEN(r)).
The range r means the Rune offsets in w
>= r.p0 and < r.p1. Don't forget
that each Rune will be potentially encoded in UTFmax
bytes.
rpc_read fails if
r is not fully contained in window w.
rpc_goto may be useful to obtain legal ranges.
Insert, delete or replace text
char* rpc_replace (Handle*, Id w, Range r, char*s);
Replace range r in w with UTF string s
Note that insertion and deletion are special
cases of replacement.
Ask Wily to execute a command
char* rpc_exec (Handle*, Id w , char *s);
Cause Wily to act as though s were selected in
w with button 2.
Note that builtin functions (e.g. Del) can
also be executed with rpc_exec.
Ask Wily to "goto" a file or location
char* rpc_goto (Handle*, Id *w , Range* r, char*s, ushort flag);
Cause Wily to act as though s were selected in
w with button 3.
If this makes Wily do a search within '*w', the start position
for the search is usually taken from '*r'.
The search can instead start from the current selection of the
file if r->p0 > r->p1. If there are multiple
views of the same file, one is chosen arbitrarily.
If the search is successful, '*w' and '*r' are set to the window
and range found by the search. The range found will be selected
and highlighted if and only if 'flag' is set.
Hint: rpc_goto can be used to find useful
ranges for rpc_read and rpc_replace. Don't forget that the search string
can be any address that Wily understands, e.g. :4 or :, or :.,
Events
int rpc_event (Handle*h, Msg *m);
Block until an event is received by h and fill
in m. Returns 0 for success, -1 for failure.
After a successful call to rpc_event,
you will need to free(m->s).
char *rpc_bounce(Handle *h, Msg *m)
Returns m to Wily.
Useful for events which we receive but we'd rather Wily
took the default action on.
Bool rpc_event_iswaiting(Handle*h);
Returns true if rpc_event could be called
without needing to block. Only useful if your program
is reading from other input sources as well. (e.g. see win.c)
Message-Passing Interface
struct Msg {
Mtype t; /* message type */
Id m; /* message */
Id w; /* window */
Range r;
uchar flag;
char *s;
};
All the fields except the message
type are optional. The string s is always null-terminated,
is in UTF format, must be a complete UTF sequence,
and is of zero length if not being used.
These are the message types declared in msg.h, with brief
descriptions, and important parameters:
Request/Reply/Error
WRerror(s)
Message type returned by wily if there's an error with
some request. s contains an error message. On the other
hand, if the request completes successfully wily returns a message with
message type one greater than the message type of the request.
WMlist
Asks wily to send a list of windows currently displayed.
WRlist(s)
Wily's reply to WMlist. Includes a string containing
one line per active window. Each line contains a name and an id (as a
textual number) separated by whitespace.
WMnew(s,flag)
Asks wily to create a window with
a given label (which may be an existing file).
If and only if flag is set, backups will be
kept for the new window.
WRnew(w)
The id of the newly created window.
WMattach(w,flag)
Asks wily to send to the client
events associated with this window, and matching
the event mask set in flag
WRattach()
WMdetach(w)
Asks wily to stop sending to the client
events associated with this window.
WRdetach()
WMsetname(w,s)
Change the name of this window.
WRsetname()
WMsettools(w,s)
Change the tools for this window.
Tools are simply words appearing in the
tag of a window, after the window name and
before the 'pipe' symbol. They are (will be)
automatically maintained, i.e. they will be replaced
if accidentally deleted.
WRsettools()
WMread(w,r)
Read the text from w in range r.
WRread(s)
The requested text, as a UTF string.
WMreplace(w,r,s)
Replace the text from w in range r with UTF string
s
WRreplace()
WMexec(w,s)
Act as if s had been clicked with b2
in w
WRexec()
WMgoto(w,r,flag,s)
Act as if s had been clicked with B3 in w at
r. If flag is set then "dot" is set by wily,
otherwise we return the window and range that would have been jumped
to, but don't actually change "dot".
WRgoto(w,r)
The window and range we went to.
WMfencepost()
Not used for any message. Messages with Mtype less than
WMfencepost are to do with our requests. Messages with Mtype
greater than WMfencepost are events.
Events
These are the messages sent by Wily to clients who request
to be notified of events in a particular window using WMattach
The event types are used to form a mask to be given as a
parameter to the WMattach request. For example, to
request only exec and goto events, set
m.f = WEexec|WEgoto before sending message m
WEexec(w,s)
s was selected with the middle (execute)
button somewhere in w
WEgoto(w,r,s)
s was selected with the right (goto)
button at r in w
WEdestroy(w)
w has been destroyed.
WEreplace(w,r,s)
The text at r in w was
replaced by s.
Packing and Unpacking Messages
int msg_size (Msg *m);
Returns the size of buffer that will be needed to "flatten"
m
void msg_flatten (Msg*m, char*buf);
"Flatten" m into buf, which must have enough storage
space allocated.
ulong msg_bufsize (char*buf);
Returns the total size of the flattened message starting at
buf. Assumes that at least HSIZE bytes are stored in
buf. A useful macro is #define FULLMSG(ptr,n) ( (n) >=
HSIZE && (n) >= msg_bufsize(ptr) )
int msg_init (Msg*m, char*buf);
The reverse of msg_flatten. Fills in the fields of 'm' using
the flat representation starting at buf Msg_init
assumes that buf holds the complete message. m->s
will point to an area within buf, but buf itself is
not modified.
void msg_print (Msg *m);
Print a human-readable form of m to stderr
Egoto, WEdestroy, WEreplace
) (explained further below).
rpc_attach will
fail if w doesn't exist, or is already sending its
events somewhere else.
To stop receiving events from a window,
use an rpc_attach with a mask of 0.
Preview of new Wily homepage