ACME(1) ACME(1)
NAME
acme, win - interactive text windows
SYNOPSIS
acme [ -f varfont ] [ -F fixfont ] [ -c ncol ] [ -b ] [ -l
file | file ... ]
win [ command ]
DESCRIPTION
Acme manages windows of text that may be edited interac-
tively or by external programs. The interactive interface
uses the keyboard and mouse; external programs use a set of
files served by acme; these are discussed in acme(4).
Any named files are read into acme windows before acme
accepts input. With the -l option, the state of the entire
system is loaded from file, which should have been created
by a Dump command (q.v.), and subsequent file names are
ignored. Plain files display as text; directories display
as columnated lists of the names of their components with
the names of subdirectories having a slash appended.
The -f (-F) option sets the default variable-pitch (fixed-
pitch) font; the default is /fonts/lucidasans/euro.8.font
(.../lucm/unicode.9.font). Tab intervals are set to the
width of 4 numeral zeros in the variable-pitch font.
Windows
Acme windows are in two parts: a one-line tag above a
multi-line body. The body typically contains an image of a
file or the output of a program. The tag contains a number
of blank-separated words, followed by a vertical bar charac-
ter, 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. Changes to the text left of the bar will be
ignored, unless the result is to change the name of the win-
dow.
If a window holds a directory, the name (first word of the
tag) will end with a slash.
Scrolling
Each window has a scroll bar to the left of the body.
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
Page 1 Plan 9 (printed 11/18/24)
ACME(1) ACME(1)
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. Scrolling backwards is performed sim-
ilarly using button 1. Button 2 allows absolute movement
within the text; clicking it at different heights within the
scroll bar changes the focused text without intermediate
scrolling.
Layout
Acme windows are arranged in columns. By default, it cre-
ates two columns when starting; this can be overridden with
the -c option. Placement is automatic but may be adjusted
using the 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 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': Acme believes it is modi-
fied from its original contents.
Tags exist at the top of each column and across the whole
display. Acme pre-loads them with useful commands. Also,
the tag across the top maintains a list of executing long-
running commands.
Typing
The behaviour of typed text is as one would expect except
that the characters are delivered to the tag or body under
the mouse; there is no `click to type'. (The experimental
option -b causes typing to go to the most recently clicked-
at or made window.) The usual backspacing conventions
apply. 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 Cut command (q.v.).
Most text, including the names of windows, may be edited
uniformly. The only exception is that the command names to
the left of the bar in a tag are maintained automatically;
changes to them are repaired by acme.
Directory context
Each window's tag names a directory: explicitly if the win-
dow holds a directory; implicitly if it holds a regular file
(e.g. the directory /module if the window holds
/module/sys.m). This directory provides a context for
interpreting file names in that window. For example, the
Page 2 Plan 9 (printed 11/18/24)
ACME(1) ACME(1)
string sys.m in a window labelled /module/ or /module/draw.m
will be interpreted as the file name /module/sys.m. 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. /module/not-a-file). File names
beginning with a slash are assumed to be absolute file
names.
Errors
Windows whose names begin with - or + conventionally hold
diagnostics and other data not directly associated with
files. A window labelled +Errors receives all diagnostics
produced by acme itself. Diagnostics from commands run by
acme appear in a window named directory/+Errors where
directory is identified by the context of the command.
These error windows are created when needed.
Mouse button 1
Mouse button 1 selects text and double-clicking highlights
the text for replacement text to be typed in.
Button 1 is also useful for matching symbols. For example to
match curly brackets in some limbo source, double click but-
ton 1 immediately after the open curly bracket. The whole
of the text up to any matching end curly bracket will be
highlighted. A similar match is made if the double click is
performed immediately before the end bracket. In all, acme
will match the pairs { and }, [ and ], ( and ), < and >, «
and », ' and ', " and ", ` and `. Also whole lines of text
may be highlighted by double clicking at the beginning or
end of the line.
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 argu-
ments. If button 2 is `clicked'-indicates a null string-
acme expands the indicated text to find a command to run: if
the click is within button-1-selected text, acme 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 _ . - + /.
This behaviour is similar to double-clicking with button 1
but, because a null command is meaningless, only a single
click is required.
Some commands, all by convention starting with a capital
letter, are built-ins that are executed directly by acme:
Cut Delete most recently selected text and place in
Page 3 Plan 9 (printed 11/18/24)
ACME(1) ACME(1)
snarf buffer.
Del Delete window. If window is dirty, instead print
a warning; a second Del will succeed.
Delcol Delete column and all its windows, after checking
that windows are not dirty.
Delete Delete window without checking for dirtiness.
Dump Write the state of acme to the file name, if spec-
ified, or $home/acme.dump by default.
Edit Treat the argument as a text editing command in
the style of Plan9's sam. The full Sam language is
implemented except for the commands k, n, q, and
!. The = command is slightly different: it
includes the file name and gives only the line
address unless the command is explicitly =#. The
`current window' for the command is the body of
the window in which the Edit command is executed.
Usually the Edit command would be typed in a tag;
longer commands may be prepared in a scratch win-
dow and executed, with Edit itself in the current
window, using the 2-1 chord described below.
Exit Exit acme after checking that windows are not
dirty.
Font With no arguments, change the font of the associ-
ated window from fixed-spaced to proportional-
spaced or vice versa. Given a file name argument,
change the font of the window to that stored in
the named file. If the file name argument is pre-
fixed by var (fix), also set the default
proportional-spaced (fixed-spaced) font for future
use to that font. Other existing windows are
unaffected.
Get Load file into window, replacing previous contents
(after checking for dirtiness as in Del). With no
argument, use the existing file name of the win-
dow. Given an argument, use that file but do not
change the window's file name.
ID Print window ID number (q.v.).
Incl When opening `include' files with button 3, acme
searches in the directories /module and /include .
Incl adds its arguments to a supplementary list of
include directories, analogous to the -I option to
the compilers. This list is per-window and is
Page 4 Plan 9 (printed 11/18/24)
ACME(1) ACME(1)
inherited when windows are created by actions in
that window, so Incl is most usefully applied to a
directory containing relevant source. With no
arguments, Incl prints the supplementary list.
Kill Send a kill note to acme-initiated commands named
as arguments.
Lineno Give the line number(s) of the currently selected
text.
Load Restore the state of acme from a file (default
$home/acme.dump) created by the Dump command.
Local When prefixed to a command run the command in the
same file name space and environment variable
group as acme. The environment of the command is
restricted but is sufficient to run bind(1),
mount, etc., and to set environment variables.
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.
New Make new window. With arguments, load the named
files into windows.
Newcol Make new column.
Paste Replace most recently selected text with contents
of snarf buffer.
Put Write window to the named file. With no argument,
write to the file named in the tag of the window.
Putall Write all dirty windows whose names indicate
existing regular files.
Redo Complement of Undo.
Send Append selected text or snarf buffer to end of
body; used mainly with win.
Snarf Place selected text in snarf buffer.
Sort Arrange the windows in the column from top to bot-
tom in lexicographical order based on their names.
Undo Undo last textual change or set of changes.
Zerox Create a copy of the window containing most
recently selected text.
Page 5 Plan 9 (printed 11/18/24)
ACME(1) ACME(1)
A common place to store text for commands is in the tag; in
fact acme maintains a set of commands appropriate to the
state of the window to the left of the bar in the tag.
If the text indicated with button 2 is not a recognized
built-in, it is executed as a shell command. For example,
indicating date with button 2 runs date(1). The standard and
error outputs of commands are sent to the error window asso-
ciated with the directory from which the command was run,
which will be created if necessary. For example, in a win-
dow /module/sys.m executing pwd will produce the output
/module in a (possibly newly-created) window labelled
/adm/+Errors; in a window containing /appl/cmd/date.b exe-
cuting limbo date.b will run limbo(1) in /appl/cmd, produc-
ing output in a window labelled /appl/cmd/+Errors.
Mouse button 3
Pointing at text with button 3 instructs acme 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, text refers to the text of the
original sweep or, if it was null, the result of applying
the same expansion rules that apply to button 2 actions.
If the text names an existing window, acme 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,
acme loads the file into a new window and moves the mouse
there. If the text is a file name contained in double
quotes, acme loads the indicated include file from the
directory appropriate to the suffix of the file name of the
window holding the text. (The Incl command adds directories
to the standard list.)
If the text begins with a colon, it is taken to be an
address 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 acme, one must type
:/regexp or :127 not just /regexp or 127. (There is an eas-
ier way to locate literal text; see below.)
If the text is a file name followed by a colon and an
address, acme loads the file and evaluates the address. For
example, clicking button 3 anywhere in the text file.c:27
will open file.c, select line 27, and put the mouse at the
beginning of the line. The rules about Error files, direc-
tories, and so on all combine to make this an efficient way
to investigate errors from compilers, etc.
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
Page 6 Plan 9 (printed 11/18/24)
ACME(1) ACME(1)
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 but-
ton 3 on the word. Because of the rule of using the selec-
tion as the button 3 action, subsequent clicks will find
subsequent occurrences without moving the mouse.
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.
Chords of mouse buttons
Several operations are bound to multiple-button actions.
After selecting text, with button 1 still down, pressing
button 2 executes Cut and button 3 executes Paste. After
clicking one button, the other undoes the first; thus (while
holding down button 1) 2 followed by 3 is a 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.
Thus to copy a word a number of times, double click on the
word with button 1 to highlight it leaving button 1 down,
press and release button 2 to cut it and save it in the
snarf buffer, press and release button 3 to paste it back
and then release button 1. Now move the cursor to any
selected place in the text, press button 1 down, then button
3 and the word is copied in.
Similarly lines may be deleted by double clicking at the
beginning or end of the line and then pressing button 2 with
button 1 still down.
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 text one may execute Look
text with button 2 or instead point at text with button 1 in
any window, release button 1, then execute Look, clicking
button 1 while 2 is held down.
When an external command (e.g. echo(1)) is executed this
way, the extra argument is passed as expected and an envi-
ronment variable $acmeaddr is created that holds, in the
form interpreted by button 3, the fully-qualified address of
the extra argument.
Support programs
Page 7 Plan 9 (printed 11/18/24)
ACME(1) ACME(1)
win creates a new acme window and runs a command (default
/dis/sh.dis) in it, turning the window into a shell window
in which commands may be executed. Executing text in a win
window with button 2 is similar to using Send.
Similarly winm creates a new window but runs the shell
/dis/mash.dis by default. adiff behaves as diff in finding
the difference between two files but the listing uses
filename:linenumber format to allow the user to simply click
on this to be sent to that line in the file. agrep does for
grep what adiff does for diff above. cd changes directory
but when used in a win window for example, sends information
to the window to display a new heading reflecting the new
directory.
Mail
In the directory /acme/mail there are two mail programs that
may be used under acme. These Mail and Mailpop3 can be run
to display the user's current mail, read the mail, reply to
mail, save or delete mail, send mail and write the user's
mail box.
The former expects the user's mail box to be in the direc-
tory and file specified as its first argument, the latter
uses the POP3 protocol to connect to a server for the user's
mail and will prompt for a password when first run. Other-
wise their behaviour is the same.
Applications and guide files
In the directory /acme live several subdirectories, each
corresponding to a program or set of related programs that
employ acme's user interface. Each subdirectory includes
dis files and a readme file for further information. It
also includes a guide, a text file holding sample commands
to invoke the programs. The idea is to find an example in
the guide that best matches the job at hand, edit it to
suit, and execute it.
Whenever a command is executed by acme, the default search
path includes the directory of the window containing the
command. Also, acme binds the directory /acme/dis in front
of /dis when it starts; this is where acme-specific programs
such as win reside.
FILES
$home/acme.dump default file for Dump and Load; also
where state is written if acme dies
unexpectedly.
/acme/*/guide template files for applications
/acme/*/readme informal documentation for applica-
tions
/appl/acme/acme/*/src source for applications
Page 8 Plan 9 (printed 11/18/24)
ACME(1) ACME(1)
/acme/dis dis files for applications
SOURCE
/appl/acme
/appl/acme/acme/bin/src/win.b
SEE ALSO
acme(4)
Rob Pike, Acme: A User Interface for Programmers, Volume 2
.}f
BUGS
With the -l option or Load command, the recreation of win-
dows under control of external programs such as win is just
to rerun the command; information may be lost.
Page 9 Plan 9 (printed 11/18/24)