3 acme, win, awd \- interactive text windows
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
47 these are discussed in
59 option, the state of the entire system is loaded
62 which should have been created by a
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.
76 option sets the main font, usually variable-pitch (alternate, usually fixed-pitch);
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
82 numeral zeros in the appropriate font.
96 windows are in two parts: a one-line
100 The body typically contains an image of a file, as in
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
116 If a window holds a directory, the name (first word of the tag) will end with
119 Each window has a scroll bar to the left of the body.
120 The scroll bar behaves much as in
124 except that scrolling occurs when the button is pressed, rather than released,
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
132 reverses the scrolling behavior of buttons 1 and 3, to behave
137 windows are arranged in columns. By default, it creates two columns when starting;
138 this can be overridden with the
141 Placement is automatic but may be adjusted
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.
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.
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':
158 believes it is modified from its original
161 Tags exist at the top of each column and across the whole display.
163 pre-loads them with useful commands.
164 Also, the tag across the top maintains a list of executing long-running commands.
166 The behavior of typed text is similar to that in
168 except that the characters are delivered to the tag or body under the mouse; there is no
170 (The experimental option
172 causes typing to go to the most recently clicked-at or made window.)
173 The usual backspacing conventions apply.
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
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
192 When a window is in autoindent mode
195 command below) and a newline character is typed,
197 copies leading white space on the current line to the new line,
201 removes all trailing end-of-line white space before writing the file.
204 causes each window to start in
207 When a window is in spacesindent mode
210 command below) and a tab character is typed,
211 acme indents the line with spaces equal to the current
212 tabstop for the window. The option
214 causes each window to start in spacesindent
216 .SS "Directory context
217 Each window's tag names a directory: explicitly if the window
218 holds a directory; implicitly if it holds a regular file
223 This directory provides a
225 for interpreting file names in that window.
226 For example, the string
232 will be interpreted as the file name
234 The directory is defined purely textually, so it can be a non-existent
235 directory or a real directory associated with a non-existent file
237 .BR /adm/not-a-file ).
238 File names beginning with a slash
239 are assumed to be absolute file names.
241 Windows whose names begin with
245 conventionally hold diagnostics and other data
246 not directly associated with files.
249 receives all diagnostics produced by
252 Diagnostics from commands run by
254 appear in a window named
255 .IB directory /+Errors
258 is identified by the context of the command.
259 These error windows are created when needed.
261 Mouse button 1 selects text just as in
265 including the usual double-clicking conventions.
268 action similar to selecting text with button 1,
269 button 2 indicates text to execute as a command.
270 If the indicated text has multiple white-space-separated words,
271 the first is the command name and the second and subsequent
273 If button 2 is `clicked'\(emindicates a null string\(em\c
276 the indicated text to find a command to run:
277 if the click is within button-1-selected text,
279 takes that selection as the command;
280 otherwise it takes the largest string of valid file name characters containing the click.
281 Valid file name characters are alphanumerics and
287 This behavior is similar to double-clicking with button 1 but,
288 because a null command is meaningless, only a single click is required.
290 Some commands, all by convention starting with a capital letter, are
292 that are executed directly by
296 Delete most recently selected text and place in snarf buffer.
299 Delete window. If window is dirty, instead print a warning; a second
304 Delete column and all its windows, after checking that windows are not dirty.
307 Delete window without checking for dirtiness.
312 to the file name, if specified, or
317 Treat the argument as a text editing command in the style of
321 language is implemented except for the commands
329 command is slightly different: it includes the file name and
330 gives only the line address unless the command is explicitly
332 The `current window' for the command is the body of the window in which the
337 command would be typed in a tag; longer commands may be prepared in a
338 scratch window and executed, with
340 itself in the current window, using the 2-1 chord described below.
345 after checking that windows are not dirty.
348 With no arguments, change the font of the associated window from fixed-spaced to
349 proportional-spaced or
352 Given a file name argument, change the font of the window to that stored in the named file.
353 If the file name argument is prefixed by
356 also set the default proportional-spaced (fixed-spaced) font for future use to that font.
357 Other existing windows are unaffected.
360 Load file into window, replacing previous contents (after checking for dirtiness as in
362 With no argument, use the existing file name of the window.
363 Given an argument, use that file but do not change the window's file name.
366 Print window ID number
370 When opening `include' files
375 searches in directories
380 adds its arguments to a supplementary list of include directories, analogous to
383 option to the compilers.
384 This list is per-window and is inherited when windows are created by actions in that window, so
386 is most usefully applied to a directory containing relevant source.
389 prints the supplementary list.
390 This command is largely superseded by plumbing
395 Set the autoindent mode according to the argument:
399 set the mode for the current window;
403 set the mode for all existing and future windows.
410 commands named as arguments.
416 .BR $HOME/acme.dump )
424 this prefix causes a command to be run in
426 file name space and environment variable group.
427 On Unix this is impossible.
429 is recognized as a prefix, but has no effect on the command being executed.
432 .\" When prefixed to a command
434 .\" command in the same file name space and environment variable group as
436 .\" The environment of the command
437 .\" is restricted but is sufficient to run
444 .\" and to set environment variables such as
448 Search in body for occurrence of literal text indicated by the argument or,
449 if none is given, by the selected text in the body.
452 Make new window. With arguments, load the named files into windows.
458 Replace most recently selected text with contents of snarf buffer.
461 Write window to the named file.
462 With no argument, write to the file named in the tag of the window.
465 Write all dirty windows whose names indicate existing regular files.
472 Append selected text or snarf buffer to end of body; used mainly with
476 Place selected text in snarf buffer.
479 Arrange the windows in the column from top to bottom in lexicographical
480 order based on their names.
483 Set the spacesindent mode according to the argument:
487 set the mode for the current window;
491 set the mode for all existing and future windows.
494 Set the width of tab stops for this window to the value of the argument, in units of widths of the zero
496 With no arguments, it prints the current value.
499 Undo last textual change or set of changes.
502 Create a copy of the window containing most recently selected text.
505 If a regular shell command is preceded by a
510 character, the selected text in the body of the window is affected by the
511 I/O from the command.
514 character causes the selection to be replaced by the standard output
517 causes the selection to be sent as standard input to the command; and
519 does both at once, `piping' the selection through the command and
520 replacing it with the output.
522 A common place to store text for commands is in the tag; in fact
524 maintains a set of commands appropriate to the state of the window
525 to the left of the bar in the tag.
527 If the text indicated with button 2 is not a recognized built-in, it is executed as
528 a shell command. For example, indicating
533 and error outputs of commands are sent to the error window associated with
534 the directory from which the command was run, which will be created if
536 For example, in a window
540 will produce the output
542 in a (possibly newly-created) window labeled
544 in a window containing
545 .B /home/rob/sam/sam.c
552 producing output in a window labeled
553 .BR /home/rob/sam/+Errors .
554 The environment of such commands contains the variable
558 with value set to the filename of the window in which the command is run,
561 set to the window's id number
565 The environment variable
567 determines which shell is used to execute such commands; the
569 shell is used by default.
571 Pointing at text with button 3 instructs
573 to locate or acquire the file, string, etc. described by the indicated text and
575 This description follows the actions taken when
576 button 3 is released after sweeping out some text.
579 refers to the text of the original sweep or, if it was null, the result of
580 applying the same expansion rules that apply to button 2 actions.
582 If the text names an existing window,
584 moves the mouse cursor to the selected text in the body of that window.
585 If the text names an existing file with no associated window,
587 loads the file into a new window and moves the mouse there.
588 If the text is a file name contained in angle brackets,
590 loads the indicated include file from the directory appropriate to the
591 suffix of the file name of the window holding the text.
594 command adds directories to the standard list.)
596 If the text begins with a colon, it is taken to be an address, in
599 within the body of the window containing the text.
600 The address is evaluated, the resulting text highlighted, and the mouse moved to it.
611 (There is an easier way to locate literal text; see below.)
613 If the text is a file name followed by a colon and an address,
615 loads the file and evaluates the address. For example, clicking button 3 anywhere
621 27, and put the mouse at the beginning of the line. The rules about Error
622 files, directories, and so on all combine to make this an efficient way to
623 investigate errors from compilers, etc.
625 If the text is not an address or file, it is taken to
626 be literal text, which is then searched for in the body of the window
627 in which button 3 was clicked. If a match is found, it is selected and the mouse is
628 moved there. Thus, to search for occurrences of a word in a file,
629 just click button 3 on the word. Because of the rule of using the
630 selection as the button 3 action, subsequent clicks will find subsequent
631 occurrences without moving the mouse.
633 In all these actions, the mouse motion is not done if the text is a null string
634 within a non-null selected string in the tag, so that (for example) complex regular expressions
635 may be selected and applied repeatedly to the
636 body by just clicking button 3 over them.
637 .SS "Chords of mouse buttons
638 Several operations are bound to multiple-button actions.
639 After selecting text, with button 1 still down, pressing button 2
642 and button 3 executes
644 After clicking one button, the other undoes
645 the first; thus (while holding down button 1) 2 followed by 3 is a
647 that leaves the file undirtied;
648 3 followed by 2 is a no-op.
649 These actions also apply to text selected by double-clicking because
650 the double-click expansion is made when the second
651 click starts, not when it ends.
653 Commands may be given extra arguments by a mouse chord with buttons 2 and 1.
654 While holding down button 2 on text to be executed as a command, clicking button 1
655 appends the text last pointed to by button 1 as a distinct final argument.
656 For example, to search for literal
660 with button 2 or instead point at
662 with button 1 in any window, release button 1,
665 clicking button 1 while 2 is held down.
667 When an external command (e.g.
669 is executed this way, the extra argument is passed as expected and an
672 is created that holds, in the form interpreted by button 3,
673 the fully-qualified address of the extra argument.
674 .SS "Simulated buttons
675 For systems without a three-button mouse, the keyboard modifier
676 keys can be used to modify the effect of the main mouse button.
677 On Unix systems, the Control key changes the main button to button 2,
678 and the Alt key changes it to button 3.
679 On Mac systems, the Option key changes the main button to button 2,
680 and the Command key changes it to button 3.
681 Pressing the key after the button is held down adds the button to form
682 a chord, so that for example on Macs selecting text with the trackpad
683 button and then typing Option without letting go of the button will
684 cause a 1-2 chord, cutting the selection.
685 On Mac systems, the usual keyboard shortcuts
686 Command-C, -V, -X, and -Z invoke
687 copy, paste, cut, and undo,
688 and Command-Shift-Z invokes redo,
689 as in other programs.
690 Especially on Mac laptops, these keyboard shortcuts are
691 typically much less awkward than the equivalent chords.
692 .SS "Support programs
700 in it, turning the window into something analogous to an
706 2 is similar to using
709 windows follow the same scrolling heuristic as in
711 the window scrolls on output only if the window is displaying the end of the buffer.
714 loads the tag line of its window with the directory in which it's running, suffixed
719 intended to be executed by a
723 windows. An example definition is
725 fn cd { builtin cd $1 && awd $sysname }
727 .SS "Applications and guide files
730 live several subdirectories, each corresponding to a program or
731 set of related programs that employ
734 Each subdirectory includes source, binaries, and a
736 file for further information.
739 a text file holding sample commands to invoke the programs.
740 The idea is to find an example in the guide that best matches
741 the job at hand, edit it to suit, and execute it.
743 Whenever a command is executed by
745 the default search path includes the directory of the window containing
746 the command and its subdirectory
748 The program directories in
750 contain appropriately labeled subdirectories of binaries,
752 in the guide files will be found automatically when run.
755 binds the directories
758 .B /acme/bin/$cputype
761 when it starts; this is where
776 also where state is written if
778 dies or is killed unexpectedly, e.g. by deleting its window.
781 template files for applications
784 informal documentation for applications
787 source for applications
790 MIPS-specific binaries for applications
794 .B \*9/src/cmd/9term/win.c
802 Acme: A User Interface for Programmers.
809 the recreation of windows under control of external programs
812 is just to rerun the command; information may be lost.
