<HTML><HEAD><TITLE>Wily User Manual</TITLE></HEAD>
<BODY><H1><A HREF="index.html">Wily</A> User Manual</H1>
<P><CODE>wily [-p9fn font] [-fn font] [-p9fixed fixedfont] [-a tabsize] [-c columns] [file name...]</CODE>
<DD>(or X resource <CODE>p9font</CODE>) set the default
proportional font. This must be the name
of a Plan 9 font file.
<DD>(or X resource <CODE>font</CODE>) set the default
proportional font. This must be the name
of a X font. The default is "<TT>variable</TT>"
<DD>(or X resource <CODE>p9fixed</CODE>) set the monospace font.
This must be the name
of a Plan 9 font file.
The default monospace font is "<TT>fixed</TT>"
<DD>set the maximum width of tabs (as multiple of the
width of the character '0') for the proportional font.
Defaults to 4.
<DD>set the initial number of columns.
Defaults to 2.
<DD>Run '<TT>command</TT>' on startup.
<DD>Start wily with the named files and directories
External commands are sent to the shell for evaluation.
Defaults to <TT>/bin/sh</TT>
If <TT>$HISTORY</TT> or <tt>$history</tt> are set,
commands are written to this file before execution.
Wily uses <tt>$WILYBAK</TT> or <tt>$HOME/.wilybak</tt>
as the directory for backups.
<DT>WMAINTAG, WCOLTAG, WFILETAG, WDIRTAG<DD>
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.
If <tt>$WILYTOOLS</TT> or <tt>$HOME/.wilytools</tt>
exist, they are read and used as a tools patterns file.
(See later section).
If set, this is used as a search path for include files.
For external processes, Wily sets <TT>$WILYLABEL</TT> and
<TT>$w</TT> to the label of the window in whose context a
command is executing.
Wily itself ignores <TT>$PATH</TT>, but when it calls the
shell to run external programs the value of <TT>$PATH</TT>
<DT>WILYFIFO, DISPLAY, TMPDIR<DD>
Wily communicates with some other programs using a fifo at
a well-known location.
<P>The name of the fifo will be <tt>$WILYFIFO</TT>
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</TT>
is defined, it is used instead of <tt>/tmp</tt>.
<P>Wily also sets <tt>$WILYFIFO</TT> so any children
it creates will know how to talk to it.
<H3>Column, window, tag, body, resize box</H3>
<IMG SRC="thumb.gif" WIDTH=174 HEIGHT=96 ALT="screen shot" ALIGN=left></A>
Wily appears as one or more vertical columns, divided into <I>windows</I>
of scrolling text. Each column or window is headed by a one-line
<I>tag</I>. 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 <I>wily tag</I>.
<P>The text in the <I>body</I> of the window may represent a directory,
a file, the interface to some program like a news reader, or the output
from a program.
<P>The small square-ish box to the left of the tag is called the
<I>resize box</I>. The resize box is used for moving and reshaping
windows and columns.
<P>If the resize box is filled in, this indicates that the window is
<I>dirty</I>. A dirty window contains text which has been modified
since it was last read from or written to disk.
<H3>Proportionally spaced, Unicode text</H3>
<P>Text is displayed in a propotionally spaced font by default. There
is a built in function to toggle with a monospace font when required.
<P>Text is read and written as <A
providing some support for editing multi-lingual and scientific text,
but remaining backwardly compatible with plain 7-bit ASCII text. See
<A HREF="http://www.cs.su.oz.au/~matty/9term/index.html">9term</A> for
an example of another program with Unicode support, with some screen
<I>B1</I>, <I>B2</I> & <I>B3</I> 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".
means to select some text with B1 held down, then click and release
on B2 while still holding B1 down.
<P><I>Sweep with B1</I> means to hold down B1, drag it across some text
to select it, and then release B1.
<P>The <I>last selected text</I> is the text which was most
recently selected, usually by being swept with B1.
<P>The <I>last selected window</I> 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.
All text in wily has a <I>context</I>. The context is the name of a
directory associated with that text. This context is used when
executing commands and opening files.
<P>If the text is in a window, its context is the name of that 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>, the context for all the text in all of these
windows is the same: <TT>/usr/gary/</TT>. Note that the context need
not be a directory which actually exists.
<P>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.
<H2>Scrollbars and scrolling</H2>
Scrollbars are proportional, i.e. the size and position of the
scrollbar's <I>thumb</I> indicates the size and position of the visible
portion of the text.
<P>Each of the three mouse buttons does something different when
clicked in the scrollbar.
<P>B1 and B3 are used for <I>relative movements</I>. 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.
<P>B2 is used for <I>absolute positioning</I>.
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.
<P>All of these movements repeat if the mouse button is held down
in the scroll bar.
<P>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.
<H2>Selecting and editing text (B1)</H2>
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
if the selection is null, select all the most recently typed text,
otherwise delete the selection
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.
<H2>Executing commands (B2)</H2>
<H3>Selecting the command</H3>
<P>Sweep text with B2 to execute it as a command.
<P>If you start sweeping some text with B2, then decide you
<I>don't</I> want to execute it, click B3 <B>before you release B2</B>
(i.e. a B3B2 chord) to abort.
<P>The <I>command window</I> 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.
<P>If the text starts with the name of one of the builtin commands,
that builtin is executed.
<P>Otherwise, the command is executed by forking a subprocess, establishing
an environment and <TT>exec</TT>ing <TT>$SHELL -c command</TT>.
<H3>Environment for external commands</H3>
<LI>The current directory is set to the context of the command.
<LI><TT>$WILYLABEL</TT> and <TT>$w</TT> are set to the name of the command window
and added to the environment.
<LI>Standard input is set to <TT>/dev/null</TT>
<LI>Standard output and standard error are set such that output
to them ends up being sent to a window in Wily called
<LI>The first word of the command will be added to the wily tag to
indicate which programs are currently running.
<LI><TT>$WILYFIFO</TT> will be set to the name of the fifo this
instance of Wily is listening to for messages. See the <A
HREF="index.html">main wily page</A> for programmers manuals on how to
use this messaging interface.
<P>One exception is that if the name of the command starts with
"<TT>|</TT>", "<TT><</TT>" or "<TT>></TT>", 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.
<P>For example if a paragraph is currently the last selection,
executing "<TT>|fmt</TT>" will format the paragraph, executing
"<TT>>lp</TT>" will print it, and executing "<TT><cat file</TT>"
will replace it with "<TT>file</TT>"
By convention all of the builtin functions start with a capital letter.
Some of them operate differently
if called with an argument.
<DT>Put, Get, Putall<DD>
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.
<P>Putall writes all dirty files to disk.
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
<TT>context/New</TT>, where the context is taken from the last
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.
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.
Create or delete a column
<DT>Cut, Paste, Snarf<DD>
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.
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 <TT>$wilydir/+Errors</TT>
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.
Toggles whether or not dot files are displayed in directories. Directories
will not be re-read automatically, though.
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 "<TT>:currentaddress,.</TT>"
<P>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 the most recently selected window into two. Editing actions in
one window will be visible in the other.
Toggles autoindent for a window or all windows, depending on the command window.
Deletes all the text in the command window.
<P>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.
Sweep text with B3 to make Wily try to <I>goto</I> (open or search for)
the swept text.
<P>The text may be interpreted as:
Open filename and search in it for address
Search for <TT>address</TT> in the window containing the swept text,
or in the last selected window, if the swept text was not in a window.
Open file or directory <TT>filename</TT> if it exists.
Open <TT>includefilename</TT> if it can be "massaged" (see
below) into the name of an include file (e.g. <TT>stdio.h</TT>)
If the swept text is contained in a window, do a literal search in
the body of the window for <TT>literal</TT>.
<P>When trying to open a file or directory, the swept file name 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/</tt> will be
interpreted to mean the address <tt>/usr/gary/src/foo.c:14</tt>
Wily uses the address and regular expression code from
Please refer to the <A HREF="http://plan9.bell-labs.com/magic/man2html/1/sam">Sam manual</A>
for a better explanation.
The empty string after character n; #0 is the beginning of the file.
Line n; 1 is the beginning of the file.
<DT>/regexp/ ?regexp? <DD>
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.
<P>Regexps are as defined in
in the Plan 9 manual.
The null string at the end of the file.
Dot. The current selection in a window.
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. <TT>:.,</TT> selects from the current selection to the end of file.
<P>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.
<P>If we are searching for <TT>name</TT>
and <TT>name</TT> appears between double-quotes or
angle brackets, Wily also
searches for <TT>name</TT> in the directories in the search path
/usr/include, if $INCLUDES isn't set).
<P>For example, sweeping <TT>stdio.h</TT> between angle brackets will
open<TT> /usr/include/stdio.h</TT> on the author's system.
<H2>Mouse short cuts</H2>
<H3>Cut (B1B2), Paste (B1B3)</H3>
To cut some text into the clipboard, select the text with B1,
and <em>while holding it down</em>, click B2.
The selected text will be cut from the window and copied to the
<P>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
<P>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.
<H3>Execute with argument (B2B1)</H3>
<P>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).
<P>For example, say I have a script called "<TT>sg</TT>" (short for
source grep) that <TT>grep</TT>s through all the source files
in the current directory for a symbol given as an argument. I can
then sweep with B1 to select "<TT>printf</TT>" in a source file, then B2B1
on the word <TT>sg</TT> (anywhere). The command "<TT>sg printf</TT>"
will then run in the same directory as the source file.
<P>A null selection (single click) with B2 or B3 will be expanded to some of the surrounding
<P>A click inside an existing selection will be expanded to that selection.
<P>This means you can select (with B1)
some complicated command once,
and B2 inside
this selection many times to execute the command repeatedly.
<P>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.
<P>A click that is not inside an existing selection will be expanded depending
on which mouse button was used.
<P>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
<P>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,
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.
<P>Dragging the resize box (with any mouse button) moves the column or
window to the desired location.
<P>Clicking in a pane's button with different mouse buttons has these
the window grows a bit, first taking up any blank space
in the column
Every window except the desired one is shrunk so that only their tags
are visible, leaving more space for the desired window.
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.
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.
<P>Whenever a dirty window is to be deleted, a backup is made.
This is an alternative to the familiar (and
often-annoying) "are you <I>sure</I> you want to close this
window?" dialog. A warning message is printed when this happens.
<P>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.
Wily attempts to read either <TT>$WILYTOOLS</TT> or <TT>$HOME/.wilytools</TT>. Each line in this file should be either empty, a comment
(starts with '<TT>#</TT>') 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.
<P>Below is the author's <TT>.wilytools</TT> :
Mace.*Errors$ Clear mace subject
Mace/in/$ mace subject
Mace/in reply wrm wmov
Mace reply wrm
/src/.*/$ def sg
print/$ gv bpr
The <TT>mace, reply, deliver and subject</TT> scripts and <TT>Mace</TT>
directory are to do with reading mail. <TT>def</TT> and <TT>sg</TT>
are useful scripts for searching through source files, so they are
added to the tag of any directory with <TT>src</TT> in its pathname.
<TT>make</TT> is a logical command to execute when viewing a
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.
<P>Wily first tries to open a Plan 9 font file, given as either
a -<TT>p9fn</TT> command-line option or <TT>*p9font</TT> X resource.
Failing that, it uses the <TT>-fn</TT> command-line option or <TT>*font</TT> X resource.
Failing that, it uses the font "<TT>variable</TT>".
<P>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 <A HREF="http://www.cs.su.oz.au/~matty/9term/">9term</A> page
for information about obtaining Unicode fonts and utilities to convert
other character sets to Unicode.
<P>The format of of a font file is described below:
(Taken from <TT>font(4)</TT> from the Plan 9 Manual)
External fonts are described by a plain text file that can be read
using <I>rdfontfile</I>. 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 <I>getsubfont</I>. 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.
<P>Here is the start of the font file the author uses for a monospace font:
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
<H3>Entering non-ASCII characters</H3>
Refer to the Plan 9 <A HREF="http://plan9.bell-labs.com/magic/man2html/6/keyboard">keyboard(6)</A> manual page, which is mostly how
it works in wily.