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