aboutsummaryrefslogtreecommitdiff
path: root/man/man1/acme.1
blob: f21566f913a17fa06476fd9195ba4eefd5446510 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
.TH ACME 1
.SH NAME
acme, win, awd \- interactive text windows
.SH SYNOPSIS
.B acme
[
.B -abr
]
[
.B -f
.I varfont
]
[
.B -F
.I fixfont
]
[
.B -c
.I ncol
]
[
.B -m
.I mtpt
]
[
.B -l
.I file
|
.I file
\&... ]
.LP
.B win
[
.I command
]
.LP
.B awd
[
.I label
]
.SH DESCRIPTION
.I Acme
manages windows of text that may be edited interactively or by external programs.
The interactive interface uses the keyboard and mouse; external programs
use a set of files served by
.IR acme ;
these are discussed in
.IR acme (4).
.PP
Any named
.I files
are read into
.I acme
windows before
.I acme
accepts input.
With the
.B -l
option, the state of the entire system is loaded
from
.IR file ,
which should have been created by a
.B Dump
command (q.v.),
and subsequent
.I file
names are ignored.
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 main font, usually variable-pitch (alternate, usually fixed-pitch);
the default is
.B \*9/font/lucsans/euro.8.font
.RB ( \&.../lucm/unicode.9.font ).
Tab intervals are set to the width of 4 (or the value of
.BR $tabstop )
numeral zeros in the appropriate font.
.PP
The
.B -m
option instructs
.I acme
to use FUSE (see
.IR 9pfuse (4))
to mount itself at
.IR mtpt .
(Experimental.)
.PP
.SS Windows
.I Acme
windows are in two parts: a one-line
.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 rio (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.
Changes to the text left of the bar will be ignored,
unless the result is to change the name of the
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 rio (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.
(The experimental option
.B -r
reverses the scrolling behavior of buttons 1 and 3, to behave
more like
.IR xterm (1).)
.SS Layout
.I Acme
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 acme
believes it is modified from its original
contents.
.PP
Tags exist at the top of each column and across the whole display.
.I Acme
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 rio (1)
except that the characters are delivered to the tag or body under the mouse; there is no
`click to type'.
(The experimental option
.B -b
causes typing to go to the most recently clicked-at or made window.)
The usual backspacing conventions apply.
As in
.IR sam (1)
but not
.IR rio ,
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
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
.IR acme .
.PP
When a window is in autoindent mode
(see the
.B Indent
command below) and a newline character is typed,
.I acme
copies leading white space on the current line to the new line,
and when a window is
.BR Put ,
.I acme
removes all trailing end-of-line white space before writing the file.
The option
.B -a
causes each window to start in
autoindent mode.
.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 acme
itself.
Diagnostics from commands run by
.I acme
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 rio (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 acme
.I expands
the indicated text to find a command to run:
if the click is within button-1-selected text,
.I 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
.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 acme :
.TP
.B Cut
Delete most recently selected text and place in snarf buffer.
.TP
.B Del
Delete window.  If window is dirty, instead print a warning; a second
.B Del
will succeed.
.TP
.B Delcol
Delete column and all its windows, after checking that windows are not dirty.
.TP
.B Delete
Delete window without checking for dirtiness.
.TP
.B Dump
Write the state of
.I acme
to the file name, if specified, or
.B $HOME/acme.dump
by default.
.TP
.B Edit
Treat the argument as a text editing command in the style of
.IR sam (1).
The full
.B Sam
language is implemented except for the commands
.BR k ,
.BR n ,
.BR q ,
and
.BR ! .
The
.B =
command is slightly different: it includes the file name and
gives only the line address unless the command is explicitly
.BR =# .
The `current window' for the command is the body of the window in which the
.B Edit
command is executed.
Usually the
.B Edit
command would be typed in a tag; longer commands may be prepared in a
scratch window and executed, with
.B Edit
itself in the current window, using the 2-1 chord described below.
.TP
.B Exit
Exit
.I acme
after checking that windows are not dirty.
.TP
.B Font
With no arguments, change the font of the associated window from fixed-spaced to
proportional-spaced or
.I vice
.IR 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 prefixed by
.B var
.RB ( fix ),
also set the default proportional-spaced (fixed-spaced) font for future use to that 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 ID
Print window ID number
.RI ( q.v. ).
.TP
.B Incl
When opening `include' files
(those enclosed in
.BR <> )
with button 3,
.I acme
searches in directories
.B /$objtype/include
and
.BR /sys/include .
.B Incl
adds its arguments to a supplementary list of include directories, analogous to
the
.B -I
option to the compilers.
This list is per-window and is inherited when windows are created by actions in that window, so
.I Incl
is most usefully applied to a directory containing relevant source.
With no arguments,
.I Incl
prints the supplementary list.
This command is largely superseded by plumbing
(see
.IR plumb (7)).
.TP
.B Indent
Set the autoindent mode according to the argument:
.B on
and
.B off
set the mode for the current window;
.B ON
and
.B OFF
set the mode for all existing and future windows.
.TP
.B Kill
Send a
.B kill
note to
.IR acme -initiated
commands named as arguments.
.TP
.B Load
Restore the state of
.I acme
from a file (default
.BR $HOME/acme.dump )
created by the
.B Dump
command.
.TP
.B Local
In the Plan 9
.IR acme ,
this prefix causes a command to be run in
.IR acme 's own
file name space and environment variable group.
On Unix this is impossible.
.B Local
is recognized as a prefix, but has no effect on the command being executed.
.\" .TP
.\" .B Local
.\" When prefixed to a command
.\" run the
.\" command in the same file name space and environment variable group as
.\" .IR acme .
.\" The environment of the command
.\" is restricted but is sufficient to run
.\" .IR bind (1),
.\" .IR 9fs
.\" (see
.\" .IR srv (4)),
.\" .IR import (4),
.\" etc.,
.\" and to set environment variables such as
.\" .BR $objtype .
.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 Tab
Set the width of tab stops for this window to the value of the argument, in units of widths of the zero
character.
With no arguments, it prints the current value.
.TP
.B Undo
Undo last textual change or set of changes.
.TP
.B Zerox
Create a copy of the window containing most recently selected text.
.TP
.B <|>
If a regular shell command is preceded by a
.BR < ,
.BR | ,
or
.B >
character, the selected text in the body of the window is affected by the
I/O from the command.
The
.B <
character causes the selection to be replaced by the standard output
of the command;
.B >
causes the selection to be sent as standard input to the command; and
.B |
does both at once, `piping' the selection through the command and
replacing it with the output.
.PP
A common place to store text for commands is in the tag; in fact
.I acme
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 /etc/passwd
executing
.B pwd
will produce the output
.B /etc
in a (possibly newly-created) window labeled
.BR /etc/+Errors ;
in a window containing
.B /home/rob/sam/sam.c
executing
.B mk
will run
.IR mk (1)
in
.BR /home/rob/sam ,
producing output in a window labeled
.BR /home/rob/sam/+Errors .
The environment of such commands contains the variable
.B $%
and
.B $samfile
with value set to the filename of the window in which the command is run,
and
.B $winid
set to the window's id number
(see
.IR acme (4)).
.PP
The environment variable
.B $acmeshell
determines which shell is used to execute such commands; the
.IR rc (1)
shell is used by default.
.SS "Mouse button 3
Pointing at text with button 3 instructs
.I 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,
.I 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.
.PP
If the text names an existing window,
.I 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,
.I acme
loads the file into a new window and moves the mouse there.
If the text is a file name contained in angle brackets,
.I acme
loads the indicated include file from the directory appropriate to the
suffix of the file name of the window holding the text.
(The
.B Incl
command adds directories to the standard list.)
.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 acme ,
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 acme
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 $acmeaddr
is created that holds, in the form interpreted by button 3,
the fully-qualified address of the extra argument.
.SS "Simulated buttons
For systems without a three-button mouse, the keyboard modifier
keys can be used to modify the effect of the main mouse button.
On Unix systems, the Control key changes the main button to button 2,
and the Alt key changes it to button 3.
On Mac systems, the Option key changes the main button to button 2,
and the Command key changes it to button 3.
Pressing the key after the button is held down adds the button to form
a chord, so that for example on Macs selecting text with the trackpad
button and then typing Option without letting go of the button will
cause a 1-2 chord, cutting the selection.
On Mac systems, the usual keyboard shortcuts
Command-C, -V, -X, and -Z invoke
copy, paste, cut, and undo,
and Command-Shift-Z invokes redo,
as in other programs.
Especially on Mac laptops, these keyboard shortcuts are
typically much less awkward than the equivalent chords.
.SS "Support programs
.I Win
creates a new
.I acme
window and runs a
.I command
(default
.BR $SHELL )
in it, turning the window into something analogous to an
.IR 9term (1)
window.
Executing text in a
.I win
window with button
2 is similar to using
.BR Send .
.I Win
windows follow the same scrolling heuristic as in
.IR 9term (1):
the window scrolls on output only if the window is displaying the end of the buffer.
.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
.SS "Applications and guide files
In the directory
.B /acme
live several subdirectories, each corresponding to a program or
set of related programs that employ
.I acme's
user interface.
Each subdirectory includes source, binaries, and a
.B readme
file for further information.
It also includes a
.BR 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.
.PP
Whenever a command is executed by
.IR acme ,
the default search path includes the directory of the window containing
the command and its subdirectory
.BR $cputype .
The program directories in
.B /acme
contain appropriately labeled subdirectories of binaries,
so commands named
in the guide files will be found automatically when run.
Also,
.I acme
binds the directories
.B /acme/bin
and
.B /acme/bin/$cputype
to the end of
.B /bin
when it starts; this is where
.IR acme -specific
programs such as
.I win
and
.I awd
reside.
.SH FILES
.TF $HOME/acme.dump
.TP
.B $HOME/acme.dump
default file for
.B Dump
and
.BR Load ;
also where state is written if
.I acme
dies or is killed unexpectedly, e.g. by deleting its window.
.TP
.B /acme/*/guide
template files for applications
.TP
.B /acme/*/readme
informal documentation for applications
.TP
.B /acme/*/src
source for applications
.TP
.B /acme/*/mips
MIPS-specific binaries for applications
.SH SOURCE
.B \*9/src/cmd/acme
.br
.B \*9/src/cmd/9term/win.c
.br
.B \*9/bin/awd
.SH SEE ALSO
.IR acme (4)
.br
Rob Pike,
.I
Acme: A User Interface for Programmers.
.SH BUGS
With the
.B -l
option or
.B Load
command,
the recreation of windows under control of external programs
such as
.I win
is just to rerun the command; information may be lost.