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