Column, window, tag, body, resize boxWily 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.
NotationB1, 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.
ContextAll 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 scrollingScrollbars 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.
Double-clickDouble-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
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 FunctionsBy convention all of the builtin functions start with a capital letter. Some of them operate differently if called with an argument.
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:
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
AddressesWily uses the address and regular expression code from Sam. Please refer to the Sam manual for a better explanation.
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.
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, :, ",".
Window managementWily 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:
Cursor WarpingAfter 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.
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.
.wilytoolsWily 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/ 775The 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.
FontsWily 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 charactersRefer to the Plan 9 keyboard(6) manual page, which is mostly how it works in wily.