3 acme, win \- interactive text windows
34 manages windows of text that may be edited interactively or by external programs.
35 The interactive interface uses the keyboard and mouse; external programs
36 use a set of files served by
38 these are discussed in
50 option, the state of the entire system is loaded
53 which should have been created by a
59 Plain files display as text; directories display as columnated lists of the
60 names of their components, as in
61 .B "ls -p directory|mc
62 except that the names of subdirectories have a slash appended.
67 option sets the main font, usually variable-pitch (alternate, usually fixed-pitch);
69 .B /lib/font/bit/lucidasans/euro.8.font
70 .RB ( \&.../lucm/unicode.9.font ).
71 Tab intervals are set to the width of 4 (or the value of
73 numeral zeros in the appropriate font.
77 windows are in two parts: a one-line
81 The body typically contains an image of a file, as in
87 The tag contains a number of
88 blank-separated words, followed by a vertical bar character, followed by anything.
89 The first word is the name of the window, typically the name of the associated
90 file or directory, and the other words are commands available in that window.
91 Any text may be added after the bar; examples are strings to search for or
92 commands to execute in that window.
93 Changes to the text left of the bar will be ignored,
94 unless the result is to change the name of the
97 If a window holds a directory, the name (first word of the tag) will end with
100 Each window has a scroll bar to the left of the body.
101 The scroll bar behaves much as in
105 except that scrolling occurs when the button is pressed, rather than released,
107 as long as the mouse button is held down in the scroll bar.
108 For example, to scroll slowly through a file,
109 hold button 3 down near the top of the scroll bar. Moving the mouse
110 down the scroll bar speeds up the rate of scrolling.
113 windows are arranged in columns. By default, it creates two columns when starting;
114 this can be overridden with the
117 Placement is automatic but may be adjusted
120 in the upper left corner of each window and column.
121 Pressing and holding any mouse button in the box drags
122 the associated window or column.
124 clicking in the layout box grows the window in place: button 1
125 grows it a little, button 2 grows it as much as it can, still leaving all other
126 tags in that column visible, and button 3 takes over the column completely,
127 temporarily hiding other windows in the column.
130 if any of them needs attention.)
131 The layout box in a window is normally white; when it is black in the center,
132 it records that the file is `dirty':
134 believes it is modified from its original
137 Tags exist at the top of each column and across the whole display.
139 pre-loads them with useful commands.
140 Also, the tag across the top maintains a list of executing long-running commands.
142 The behavior of typed text is similar to that in
144 except that the characters are delivered to the tag or body under the mouse; there is no
146 (The experimental option
148 causes typing to go to the most recently clicked-at or made window.)
149 The usual backspacing conventions apply.
154 the ESC key selects the text typed since the last mouse action,
155 a feature particularly useful when executing commands.
156 A side effect is that typing ESC with text already selected is identical
162 Most text, including the names of windows, may be edited uniformly.
163 The only exception is that the command names to the
164 left of the bar in a tag are maintained automatically; changes to them are repaired
168 When a window is in autoindent mode
171 command below) and a newline character is typed,
172 acme copies leading white space on the current line to the new line.
175 causes each window to start in
177 .SS "Directory context
178 Each window's tag names a directory: explicitly if the window
179 holds a directory; implicitly if it holds a regular file
184 This directory provides a
186 for interpreting file names in that window.
187 For example, the string
193 will be interpreted as the file name
195 The directory is defined purely textually, so it can be a non-existent
196 directory or a real directory associated with a non-existent file
198 .BR /adm/not-a-file ).
199 File names beginning with a slash
200 are assumed to be absolute file names.
202 Windows whose names begin with
206 conventionally hold diagnostics and other data
207 not directly associated with files.
210 receives all diagnostics produced by
213 Diagnostics from commands run by
215 appear in a window named
216 .IB directory /+Errors
219 is identified by the context of the command.
220 These error windows are created when needed.
222 Mouse button 1 selects text just as in
226 including the usual double-clicking conventions.
229 action similar to selecting text with button 1,
230 button 2 indicates text to execute as a command.
231 If the indicated text has multiple white-space-separated words,
232 the first is the command name and the second and subsequent
234 If button 2 is `clicked'\(emindicates a null string\(em\c
237 the indicated text to find a command to run:
238 if the click is within button-1-selected text,
240 takes that selection as the command;
241 otherwise it takes the largest string of valid file name characters containing the click.
242 Valid file name characters are alphanumerics and
248 This behavior is similar to double-clicking with button 1 but,
249 because a null command is meaningless, only a single click is required.
251 Some commands, all by convention starting with a capital letter, are
253 that are executed directly by
257 Delete most recently selected text and place in snarf buffer.
260 Delete window. If window is dirty, instead print a warning; a second
265 Delete column and all its windows, after checking that windows are not dirty.
268 Delete window without checking for dirtiness.
273 to the file name, if specified, or
278 Treat the argument as a text editing command in the style of
282 language is implemented except for the commands
290 command is slightly different: it includes the file name and
291 gives only the line address unless the command is explicitly
293 The `current window' for the command is the body of the window in which the
298 command would be typed in a tag; longer commands may be prepared in a
299 scratch window and executed, with
301 itself in the current window, using the 2-1 chord described below.
306 after checking that windows are not dirty.
309 With no arguments, change the font of the associated window from fixed-spaced to
310 proportional-spaced or
313 Given a file name argument, change the font of the window to that stored in the named file.
314 If the file name argument is prefixed by
317 also set the default proportional-spaced (fixed-spaced) font for future use to that font.
318 Other existing windows are unaffected.
321 Load file into window, replacing previous contents (after checking for dirtiness as in
323 With no argument, use the existing file name of the window.
324 Given an argument, use that file but do not change the window's file name.
327 Print window ID number
331 When opening `include' files
336 searches in directories
341 adds its arguments to a supplementary list of include directories, analogous to
344 option to the compilers.
345 This list is per-window and is inherited when windows are created by actions in that window, so
347 is most usefully applied to a directory containing relevant source.
350 prints the supplementary list.
351 This command is largely superseded by plumbing
356 Set the autoindent mode according to the argument:
360 set the mode for the current window;
364 set the mode for all existing and future windows.
371 commands named as arguments.
377 .BR $home/acme.dump )
383 When prefixed to a command
385 command in the same file name space and environment variable group as
387 The environment of the command
388 is restricted but is sufficient to run
395 and to set environment variables such as
399 Search in body for occurrence of literal text indicated by the argument or,
400 if none is given, by the selected text in the body.
403 Make new window. With arguments, load the named files into windows.
409 Replace most recently selected text with contents of snarf buffer.
412 Write window to the named file.
413 With no argument, write to the file named in the tag of the window.
416 Write all dirty windows whose names indicate existing regular files.
423 Append selected text or snarf buffer to end of body; used mainly with
427 Place selected text in snarf buffer.
430 Arrange the windows in the column from top to bottom in lexicographical
431 order based on their names.
434 Set the width of tab stops for this window to the value of the argument, in units of widths of the zero
436 With no arguments, it prints the current value.
439 Undo last textual change or set of changes.
442 Create a copy of the window containing most recently selected text.
445 If a regular shell command is preceded by a
450 character, the selected text in the body of the window is affected by the
451 I/O from the command.
454 character causes the selection to be replaced by the standard output
457 causes the selection to be sent as standard input to the command; and
459 does both at once, `piping' the selection through the command and
460 replacing it with the output.
462 A common place to store text for commands is in the tag; in fact
464 maintains a set of commands appropriate to the state of the window
465 to the left of the bar in the tag.
467 If the text indicated with button 2 is not a recognized built-in, it is executed as
468 a shell command. For example, indicating
473 and error outputs of commands are sent to the error window associated with
474 the directory from which the command was run, which will be created if
476 For example, in a window
480 will produce the output
482 in a (possibly newly-created) window labeled
484 in a window containing
485 .B /sys/src/cmd/sam/sam.c
491 .BR /sys/src/cmd/sam ,
492 producing output in a window labeled
493 .BR /sys/src/cmd/sam/+Errors .
494 The environment of such commands contains the variable
496 with value set to the filename of the window in which the command is run,
499 set to the window's id number
503 Pointing at text with button 3 instructs
505 to locate or acquire the file, string, etc. described by the indicated text and
507 This description follows the actions taken when
508 button 3 is released after sweeping out some text.
511 refers to the text of the original sweep or, if it was null, the result of
512 applying the same expansion rules that apply to button 2 actions.
514 If the text names an existing window,
516 moves the mouse cursor to the selected text in the body of that window.
517 If the text names an existing file with no associated window,
519 loads the file into a new window and moves the mouse there.
520 If the text is a file name contained in angle brackets,
522 loads the indicated include file from the directory appropriate to the
523 suffix of the file name of the window holding the text.
526 command adds directories to the standard list.)
528 If the text begins with a colon, it is taken to be an address, in
531 within the body of the window containing the text.
532 The address is evaluated, the resulting text highlighted, and the mouse moved to it.
543 (There is an easier way to locate literal text; see below.)
545 If the text is a file name followed by a colon and an address,
547 loads the file and evaluates the address. For example, clicking button 3 anywhere
553 27, and put the mouse at the beginning of the line. The rules about Error
554 files, directories, and so on all combine to make this an efficient way to
555 investigate errors from compilers, etc.
557 If the text is not an address or file, it is taken to
558 be literal text, which is then searched for in the body of the window
559 in which button 3 was clicked. If a match is found, it is selected and the mouse is
560 moved there. Thus, to search for occurrences of a word in a file,
561 just click button 3 on the word. Because of the rule of using the
562 selection as the button 3 action, subsequent clicks will find subsequent
563 occurrences without moving the mouse.
565 In all these actions, the mouse motion is not done if the text is a null string
566 within a non-null selected string in the tag, so that (for example) complex regular expressions
567 may be selected and applied repeatedly to the
568 body by just clicking button 3 over them.
569 .SS "Chords of mouse buttons
570 Several operations are bound to multiple-button actions.
571 After selecting text, with button 1 still down, pressing button 2
574 and button 3 executes
576 After clicking one button, the other undoes
577 the first; thus (while holding down button 1) 2 followed by 3 is a
579 that leaves the file undirtied;
580 3 followed by 2 is a no-op.
581 These actions also apply to text selected by double-clicking because
582 the double-click expansion is made when the second
583 click starts, not when it ends.
585 Commands may be given extra arguments by a mouse chord with buttons 2 and 1.
586 While holding down button 2 on text to be executed as a command, clicking button 1
587 appends the text last pointed to by button 1 as a distinct final argument.
588 For example, to search for literal
592 with button 2 or instead point at
594 with button 1 in any window, release button 1,
597 clicking button 1 while 2 is held down.
599 When an external command (e.g.
601 is executed this way, the extra argument is passed as expected and an
604 is created that holds, in the form interpreted by button 3,
605 the fully-qualified address of the extra argument.
606 .SS "Support programs
614 in it, turning the window into something analogous to an
620 2 is similar to using
622 .SS "Applications and guide files
625 live several subdirectories, each corresponding to a program or
626 set of related programs that employ
629 Each subdirectory includes source, binaries, and a
631 file for further information.
634 a text file holding sample commands to invoke the programs.
635 The idea is to find an example in the guide that best matches
636 the job at hand, edit it to suit, and execute it.
638 Whenever a command is executed by
640 the default search path includes the directory of the window containing
641 the command and its subdirectory
643 The program directories in
645 contain appropriately labeled subdirectories of binaries,
647 in the guide files will be found automatically when run.
650 binds the directories
653 .B /acme/bin/$cputype
656 when it starts; this is where
669 also where state is written if
671 dies or is killed unexpectedly, e.g. by deleting its window.
674 template files for applications
677 informal documentation for applications
680 source for applications
683 MIPS-specific binaries for applications
687 .B /acme/bin/source/win
693 Acme: A User Interface for Programmers.
700 the recreation of windows under control of external programs
703 is just to rerun the command; information may be lost.
projects / plan9front.git / blob