3 acme, win, awd \- interactive text windows
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
43 these are discussed in
55 option, the state of the entire system is loaded
58 which should have been created by a
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.
72 option sets the main font, usually variable-pitch (alternate, usually fixed-pitch);
74 .B \*9/font/lucidasans/euro.8.font
75 .RB ( \&.../lucm/unicode.9.font ).
76 Tab intervals are set to the width of 4 (or the value of
78 numeral zeros in the appropriate font.
82 windows are in two parts: a one-line
86 The body typically contains an image of a file, as in
92 The tag contains a number of
93 blank-separated words, followed by a vertical bar character, followed by anything.
94 The first word is the name of the window, typically the name of the associated
95 file or directory, and the other words are commands available in that window.
96 Any text may be added after the bar; examples are strings to search for or
97 commands to execute in that window.
98 Changes to the text left of the bar will be ignored,
99 unless the result is to change the name of the
102 If a window holds a directory, the name (first word of the tag) will end with
105 Each window has a scroll bar to the left of the body.
106 The scroll bar behaves much as in
110 except that scrolling occurs when the button is pressed, rather than released,
112 as long as the mouse button is held down in the scroll bar.
113 For example, to scroll slowly through a file,
114 hold button 3 down near the top of the scroll bar. Moving the mouse
115 down the scroll bar speeds up the rate of scrolling.
116 (The experimental option
118 reverses the scrolling behavior of buttons 1 and 3, to behave
123 windows are arranged in columns. By default, it creates two columns when starting;
124 this can be overridden with the
127 Placement is automatic but may be adjusted
130 in the upper left corner of each window and column.
131 Pressing and holding any mouse button in the box drags
132 the associated window or column.
134 clicking in the layout box grows the window in place: button 1
135 grows it a little, button 2 grows it as much as it can, still leaving all other
136 tags in that column visible, and button 3 takes over the column completely,
137 temporarily hiding other windows in the column.
140 if any of them needs attention.)
141 The layout box in a window is normally white; when it is black in the center,
142 it records that the file is `dirty':
144 believes it is modified from its original
147 Tags exist at the top of each column and across the whole display.
149 pre-loads them with useful commands.
150 Also, the tag across the top maintains a list of executing long-running commands.
152 The behavior of typed text is similar to that in
154 except that the characters are delivered to the tag or body under the mouse; there is no
156 (The experimental option
158 causes typing to go to the most recently clicked-at or made window.)
159 The usual backspacing conventions apply.
164 the ESC key selects the text typed since the last mouse action,
165 a feature particularly useful when executing commands.
166 A side effect is that typing ESC with text already selected is identical
172 Most text, including the names of windows, may be edited uniformly.
173 The only exception is that the command names to the
174 left of the bar in a tag are maintained automatically; changes to them are repaired
178 When a window is in autoindent mode
181 command below) and a newline character is typed,
182 acme copies leading white space on the current line to the new line.
185 causes each window to start in
187 .SS "Directory context
188 Each window's tag names a directory: explicitly if the window
189 holds a directory; implicitly if it holds a regular file
194 This directory provides a
196 for interpreting file names in that window.
197 For example, the string
203 will be interpreted as the file name
205 The directory is defined purely textually, so it can be a non-existent
206 directory or a real directory associated with a non-existent file
208 .BR /adm/not-a-file ).
209 File names beginning with a slash
210 are assumed to be absolute file names.
212 Windows whose names begin with
216 conventionally hold diagnostics and other data
217 not directly associated with files.
220 receives all diagnostics produced by
223 Diagnostics from commands run by
225 appear in a window named
226 .IB directory /+Errors
229 is identified by the context of the command.
230 These error windows are created when needed.
232 Mouse button 1 selects text just as in
236 including the usual double-clicking conventions.
239 action similar to selecting text with button 1,
240 button 2 indicates text to execute as a command.
241 If the indicated text has multiple white-space-separated words,
242 the first is the command name and the second and subsequent
244 If button 2 is `clicked'\(emindicates a null string\(em\c
247 the indicated text to find a command to run:
248 if the click is within button-1-selected text,
250 takes that selection as the command;
251 otherwise it takes the largest string of valid file name characters containing the click.
252 Valid file name characters are alphanumerics and
258 This behavior is similar to double-clicking with button 1 but,
259 because a null command is meaningless, only a single click is required.
261 Some commands, all by convention starting with a capital letter, are
263 that are executed directly by
267 Delete most recently selected text and place in snarf buffer.
270 Delete window. If window is dirty, instead print a warning; a second
275 Delete column and all its windows, after checking that windows are not dirty.
278 Delete window without checking for dirtiness.
283 to the file name, if specified, or
288 Treat the argument as a text editing command in the style of
292 language is implemented except for the commands
300 command is slightly different: it includes the file name and
301 gives only the line address unless the command is explicitly
303 The `current window' for the command is the body of the window in which the
308 command would be typed in a tag; longer commands may be prepared in a
309 scratch window and executed, with
311 itself in the current window, using the 2-1 chord described below.
316 after checking that windows are not dirty.
319 With no arguments, change the font of the associated window from fixed-spaced to
320 proportional-spaced or
323 Given a file name argument, change the font of the window to that stored in the named file.
324 If the file name argument is prefixed by
327 also set the default proportional-spaced (fixed-spaced) font for future use to that font.
328 Other existing windows are unaffected.
331 Load file into window, replacing previous contents (after checking for dirtiness as in
333 With no argument, use the existing file name of the window.
334 Given an argument, use that file but do not change the window's file name.
337 Print window ID number
341 When opening `include' files
346 searches in directories
351 adds its arguments to a supplementary list of include directories, analogous to
354 option to the compilers.
355 This list is per-window and is inherited when windows are created by actions in that window, so
357 is most usefully applied to a directory containing relevant source.
360 prints the supplementary list.
361 This command is largely superseded by plumbing
366 Set the autoindent mode according to the argument:
370 set the mode for the current window;
374 set the mode for the current window and all future windows.
381 commands named as arguments.
387 .BR $home/acme.dump )
395 this prefix causes a command to be run in
397 file name space and environment variable group.
398 On Unix this is impossible.
400 is recognized as a prefix, but has no effect on the command being executed.
403 .\" When prefixed to a command
405 .\" command in the same file name space and environment variable group as
407 .\" The environment of the command
408 .\" is restricted but is sufficient to run
415 .\" and to set environment variables such as
419 Search in body for occurrence of literal text indicated by the argument or,
420 if none is given, by the selected text in the body.
423 Make new window. With arguments, load the named files into windows.
429 Replace most recently selected text with contents of snarf buffer.
432 Write window to the named file.
433 With no argument, write to the file named in the tag of the window.
436 Write all dirty windows whose names indicate existing regular files.
443 Append selected text or snarf buffer to end of body; used mainly with
447 Place selected text in snarf buffer.
450 Arrange the windows in the column from top to bottom in lexicographical
451 order based on their names.
454 Set the width of tab stops for this window to the value of the argument, in units of widths of the zero
456 With no arguments, it prints the current value.
459 Undo last textual change or set of changes.
462 Create a copy of the window containing most recently selected text.
464 A common place to store text for commands is in the tag; in fact
466 maintains a set of commands appropriate to the state of the window
467 to the left of the bar in the tag.
469 If the text indicated with button 2 is not a recognized built-in, it is executed as
470 a shell command. For example, indicating
475 and error outputs of commands are sent to the error window associated with
476 the directory from which the command was run, which will be created if
478 For example, in a window
482 will produce the output
484 in a (possibly newly-created) window labeled
486 in a window containing
487 .B /home/rob/sam/sam.c
494 producing output in a window labeled
495 .BR /home/rob/sam/+Errors .
496 The environment of such commands contains the variable
498 with value set to the filename of the window in which the command is run,
501 set to the window's id number
505 Pointing at text with button 3 instructs
507 to locate or acquire the file, string, etc. described by the indicated text and
509 This description follows the actions taken when
510 button 3 is released after sweeping out some text.
513 refers to the text of the original sweep or, if it was null, the result of
514 applying the same expansion rules that apply to button 2 actions.
516 If the text names an existing window,
518 moves the mouse cursor to the selected text in the body of that window.
519 If the text names an existing file with no associated window,
521 loads the file into a new window and moves the mouse there.
522 If the text is a file name contained in angle brackets,
524 loads the indicated include file from the directory appropriate to the
525 suffix of the file name of the window holding the text.
528 command adds directories to the standard list.)
530 If the text begins with a colon, it is taken to be an address, in
533 within the body of the window containing the text.
534 The address is evaluated, the resulting text highlighted, and the mouse moved to it.
545 (There is an easier way to locate literal text; see below.)
547 If the text is a file name followed by a colon and an address,
549 loads the file and evaluates the address. For example, clicking button 3 anywhere
555 27, and put the mouse at the beginning of the line. The rules about Error
556 files, directories, and so on all combine to make this an efficient way to
557 investigate errors from compilers, etc.
559 If the text is not an address or file, it is taken to
560 be literal text, which is then searched for in the body of the window
561 in which button 3 was clicked. If a match is found, it is selected and the mouse is
562 moved there. Thus, to search for occurrences of a word in a file,
563 just click button 3 on the word. Because of the rule of using the
564 selection as the button 3 action, subsequent clicks will find subsequent
565 occurrences without moving the mouse.
567 In all these actions, the mouse motion is not done if the text is a null string
568 within a non-null selected string in the tag, so that (for example) complex regular expressions
569 may be selected and applied repeatedly to the
570 body by just clicking button 3 over them.
571 .SS "Chords of mouse buttons
572 Several operations are bound to multiple-button actions.
573 After selecting text, with button 1 still down, pressing button 2
576 and button 3 executes
578 After clicking one button, the other undoes
579 the first; thus (while holding down button 1) 2 followed by 3 is a
581 that leaves the file undirtied;
582 3 followed by 2 is a no-op.
583 These actions also apply to text selected by double-clicking because
584 the double-click expansion is made when the second
585 click starts, not when it ends.
587 Commands may be given extra arguments by a mouse chord with buttons 2 and 1.
588 While holding down button 2 on text to be executed as a command, clicking button 1
589 appends the text last pointed to by button 1 as a distinct final argument.
590 For example, to search for literal
594 with button 2 or instead point at
596 with button 1 in any window, release button 1,
599 clicking button 1 while 2 is held down.
601 When an external command (e.g.
603 is executed this way, the extra argument is passed as expected and an
606 is created that holds, in the form interpreted by button 3,
607 the fully-qualified address of the extra argument.
608 .SS "Support programs
616 in it, turning the window into something analogous to an
622 2 is similar to using
626 loads the tag line of its window with the directory in which it's running, suffixed
631 intended to be executed by a
635 windows. An example definition is
637 fn cd { builtin cd $1 && awd $sysname }
639 .SS "Applications and guide files
642 live several subdirectories, each corresponding to a program or
643 set of related programs that employ
646 Each subdirectory includes source, binaries, and a
648 file for further information.
651 a text file holding sample commands to invoke the programs.
652 The idea is to find an example in the guide that best matches
653 the job at hand, edit it to suit, and execute it.
655 Whenever a command is executed by
657 the default search path includes the directory of the window containing
658 the command and its subdirectory
660 The program directories in
662 contain appropriately labeled subdirectories of binaries,
664 in the guide files will be found automatically when run.
667 binds the directories
670 .B /acme/bin/$cputype
673 when it starts; this is where
688 also where state is written if
690 dies or is killed unexpectedly, e.g. by deleting its window.
693 template files for applications
696 informal documentation for applications
699 source for applications
702 MIPS-specific binaries for applications
706 .B \*9/src/cmd/9term/win.c
714 Acme: A User Interface for Programmers.
721 the recreation of windows under control of external programs
724 is just to rerun the command; information may be lost.
