diff options
Diffstat (limited to 'man/man1/acme.1')
| -rw-r--r-- | man/man1/acme.1 | 683 |
1 files changed, 683 insertions, 0 deletions
diff --git a/man/man1/acme.1 b/man/man1/acme.1 new file mode 100644 index 00000000..5cae0036 --- /dev/null +++ b/man/man1/acme.1 @@ -0,0 +1,683 @@ +.TH ACME 1 +.SH NAME +acme, win, awd \- interactive text windows +.SH SYNOPSIS +.B acme +[ +.B -f +.I varfont +] +[ +.B -F +.I fixfont +] +[ +.B -c +.I ncol +] +[ +.B -b +] +[ +.B -l +.I file +| +.I file +\&... ] +.LP +.B win +[ +.I command +] +.LP +.B awd +[ +.I label +] +.SH DESCRIPTION +.I Acme +manages windows of text that may be edited interactively or by external programs. +The interactive interface uses the keyboard and mouse; external programs +use a set of files served by +.IR acme ; +these are discussed in +.IR acme (4). +.PP +Any named +.I files +are read into +.I acme +windows before +.I acme +accepts input. +With the +.B -l +option, the state of the entire system is loaded +from +.IR file , +which should have been created by a +.B Dump +command (q.v.), +and subsequent +.I file +names are ignored. +Plain files display as text; directories display as columnated lists of the +names of their components, as in +.B "ls -p directory|mc +except that the names of subdirectories have a slash appended. +.PP +The +.B -f +.RB ( -F ) +option sets the main font, usually variable-pitch (alternate, usually fixed-pitch); +the default is +.B /lib/font/bit/lucidasans/euro.8.font +.RB ( \&.../lucm/unicode.9.font ). +Tab intervals are set to the width of 4 (or the value of +.BR $tabstop ) +numeral zeros in the appropriate font. +.PP +.SS Windows +.I Acme +windows are in two parts: a one-line +.I tag +above a multi-line +.IR body . +The body typically contains an image of a file, as in +.IR sam (1), +or the output of a +program, as in an +.IR rio (1) +window. +The tag contains a number of +blank-separated words, followed by a vertical bar character, followed by anything. +The first word is the name of the window, typically the name of the associated +file or directory, and the other words are commands available in that window. +Any text may be added after the bar; examples are strings to search for or +commands to execute in that window. +Changes to the text left of the bar will be ignored, +unless the result is to change the name of the +window. +.PP +If a window holds a directory, the name (first word of the tag) will end with +a slash. +.SS Scrolling +Each window has a scroll bar to the left of the body. +The scroll bar behaves much as in +.IR sam (1) +or +.IR rio (1) +except that scrolling occurs when the button is pressed, rather than released, +and continues +as long as the mouse button is held down in the scroll bar. +For example, to scroll slowly through a file, +hold button 3 down near the top of the scroll bar. Moving the mouse +down the scroll bar speeds up the rate of scrolling. +.SS Layout +.I Acme +windows are arranged in columns. By default, it creates two columns when starting; +this can be overridden with the +.B -c +option. +Placement is automatic but may be adjusted +using the +.I layout box +in the upper left corner of each window and column. +Pressing and holding any mouse button in the box drags +the associated window or column. +For windows, just +clicking in the layout box grows the window in place: button 1 +grows it a little, button 2 grows it as much as it can, still leaving all other +tags in that column visible, and button 3 takes over the column completely, +temporarily hiding other windows in the column. +(They will return +.I en masse +if any of them needs attention.) +The layout box in a window is normally white; when it is black in the center, +it records that the file is `dirty': +.I Acme +believes it is modified from its original +contents. +.PP +Tags exist at the top of each column and across the whole display. +.I Acme +pre-loads them with useful commands. +Also, the tag across the top maintains a list of executing long-running commands. +.SS Typing +The behavior of typed text is similar to that in +.IR rio (1) +except that the characters are delivered to the tag or body under the mouse; there is no +`click to type'. +(The experimental option +.B -b +causes typing to go to the most recently clicked-at or made window.) +The usual backspacing conventions apply. +As in +.IR sam (1) +but not +.IR rio , +the ESC key selects the text typed since the last mouse action, +a feature particularly useful when executing commands. +A side effect is that typing ESC with text already selected is identical +to a +.B Cut +command +.RI ( q.v. ). +.PP +Most text, including the names of windows, may be edited uniformly. +The only exception is that the command names to the +left of the bar in a tag are maintained automatically; changes to them are repaired +by +.IR acme . +.SS "Directory context +Each window's tag names a directory: explicitly if the window +holds a directory; implicitly if it holds a regular file +(e.g. the directory +.B /adm +if the window holds +.BR /adm/users ). +This directory provides a +.I context +for interpreting file names in that window. +For example, the string +.B users +in a window labeled +.B /adm/ +or +.B /adm/keys +will be interpreted as the file name +.BR /adm/users . +The directory is defined purely textually, so it can be a non-existent +directory or a real directory associated with a non-existent file +(e.g. +.BR /adm/not-a-file ). +File names beginning with a slash +are assumed to be absolute file names. +.SS Errors +Windows whose names begin with +.B - +or +.B + +conventionally hold diagnostics and other data +not directly associated with files. +A window labeled +.B +Errors +receives all diagnostics produced by +.I acme +itself. +Diagnostics from commands run by +.I acme +appear in a window named +.IB directory /+Errors +where +.I directory +is identified by the context of the command. +These error windows are created when needed. +.SS "Mouse button 1 +Mouse button 1 selects text just as in +.IR sam (1) +or +.IR rio (1) , +including the usual double-clicking conventions. +.SS "Mouse button 2 +By an +action similar to selecting text with button 1, +button 2 indicates text to execute as a command. +If the indicated text has multiple white-space-separated words, +the first is the command name and the second and subsequent +are its arguments. +If button 2 is `clicked'\(emindicates a null string\(em\c +.I acme +.I expands +the indicated text to find a command to run: +if the click is within button-1-selected text, +.I acme +takes that selection as the command; +otherwise it takes the largest string of valid file name characters containing the click. +Valid file name characters are alphanumerics and +.B _ +.B . +.B - +.B + +.BR / . +This behavior is similar to double-clicking with button 1 but, +because a null command is meaningless, only a single click is required. +.PP +Some commands, all by convention starting with a capital letter, are +.I built-ins +that are executed directly by +.IR acme : +.TP +.B Cut +Delete most recently selected text and place in snarf buffer. +.TP +.B Del +Delete window. If window is dirty, instead print a warning; a second +.B Del +will succeed. +.TP +.B Delcol +Delete column and all its windows, after checking that windows are not dirty. +.TP +.B Delete +Delete window without checking for dirtiness. +.TP +.B Dump +Write the state of +.I acme +to the file name, if specified, or +.B $home/acme.dump +by default. +.TP +.B Edit +Treat the argument as a text editing command in the style of +.IR sam (1). +The full +.B Sam +language is implemented except for the commands +.BR k , +.BR n , +.BR q , +and +.BR ! . +The +.B = +command is slightly different: it includes the file name and +gives only the line address unless the command is explicitly +.BR =# . +The `current window' for the command is the body of the window in which the +.B Edit +command is executed. +Usually the +.B Edit +command would be typed in a tag; longer commands may be prepared in a +scratch window and executed, with +.B Edit +itself in the current window, using the 2-1 chord described below. +.TP +.B Exit +Exit +.I acme +after checking that windows are not dirty. +.TP +.B Font +With no arguments, change the font of the associated window from fixed-spaced to +proportional-spaced or +.I vice +.IR versa . +Given a file name argument, change the font of the window to that stored in the named file. +If the file name argument is prefixed by +.B var +.RB ( fix ), +also set the default proportional-spaced (fixed-spaced) font for future use to that font. +Other existing windows are unaffected. +.TP +.B Get +Load file into window, replacing previous contents (after checking for dirtiness as in +.BR Del ). +With no argument, use the existing file name of the window. +Given an argument, use that file but do not change the window's file name. +.TP +.B ID +Print window ID number +.RI ( q.v. ). +.TP +.B Incl +When opening `include' files +(those enclosed in +.BR <> ) +with button 3, +.I acme +searches in directories +.B /$objtype/include +and +.BR /sys/include . +.B Incl +adds its arguments to a supplementary list of include directories, analogous to +the +.B -I +option to the compilers. +This list is per-window and is inherited when windows are created by actions in that window, so +.I Incl +is most usefully applied to a directory containing relevant source. +With no arguments, +.I Incl +prints the supplementary list. +This command is largely superseded by plumbing +(see +.IR plumb (6)). +.TP +.B Kill +Send a +.B kill +note to +.IR acme -initiated +commands named as arguments. +.TP +.B Local +When prefixed to a command +run the +command in the same file name space and environment variable group as +.IR acme . +The environment of the command +is restricted but is sufficient to run +.IR bind (1), +.IR 9fs +(see +.IR srv (4)), +.IR import (4), +etc., +and to set environment variables such as +.BR $objtype . +.TP +.B Load +Restore the state of +.I acme +from a file (default +.BR $home/acme.dump ) +created by the +.B Dump +command. +.TP +.B Look +Search in body for occurrence of literal text indicated by the argument or, +if none is given, by the selected text in the body. +.TP +.B New +Make new window. With arguments, load the named files into windows. +.TP +.B Newcol +Make new column. +.TP +.B Paste +Replace most recently selected text with contents of snarf buffer. +.TP +.B Put +Write window to the named file. +With no argument, write to the file named in the tag of the window. +.TP +.B Putall +Write all dirty windows whose names indicate existing regular files. +.TP +.B Redo +Complement of +.BR Undo . +.TP +.B Send +Append selected text or snarf buffer to end of body; used mainly with +.IR win . +.TP +.B Snarf +Place selected text in snarf buffer. +.TP +.B Sort +Arrange the windows in the column from top to bottom in lexicographical +order based on their names. +.TP +.B Tab +Set the width of tab stops for this window to the value of the argument, in units of widths of the zero +character. +With no arguments, it prints the current value. +.TP +.B Undo +Undo last textual change or set of changes. +.TP +.B Zerox +Create a copy of the window containing most recently selected text. +.PP +A common place to store text for commands is in the tag; in fact +.I acme +maintains a set of commands appropriate to the state of the window +to the left of the bar in the tag. +.PP +If the text indicated with button 2 is not a recognized built-in, it is executed as +a shell command. For example, indicating +.B date +with button 2 runs +.IR date (1). +The standard +and error outputs of commands are sent to the error window associated with +the directory from which the command was run, which will be created if +necessary. +For example, in a window +.B /adm/users +executing +.B pwd +will produce the output +.B /adm +in a (possibly newly-created) window labeled +.BR /adm/+Errors ; +in a window containing +.B /sys/src/cmd/sam/sam.c +executing +.B mk +will run +.IR mk (1) +in +.BR /sys/src/cmd/sam , +producing output in a window labeled +.BR /sys/src/cmd/sam/+Errors . +The environment of such commands contains the variable +.B $% +with value set to the filename of the window in which the command is run. +.SS "Mouse button 3 +Pointing at text with button 3 instructs +.I acme +to locate or acquire the file, string, etc. described by the indicated text and +its context. +This description follows the actions taken when +button 3 is released after sweeping out some text. +In the description, +.I text +refers to the text of the original sweep or, if it was null, the result of +applying the same expansion rules that apply to button 2 actions. +.PP +If the text names an existing window, +.I acme +moves the mouse cursor to the selected text in the body of that window. +If the text names an existing file with no associated window, +.I acme +loads the file into a new window and moves the mouse there. +If the text is a file name contained in angle brackets, +.I acme +loads the indicated include file from the directory appropriate to the +suffix of the file name of the window holding the text. +(The +.B Incl +command adds directories to the standard list.) +.PP +If the text begins with a colon, it is taken to be an address, in +the style of +.IR sam (1), +within the body of the window containing the text. +The address is evaluated, the resulting text highlighted, and the mouse moved to it. +Thus, in +.IR acme , +one must type +.B :/regexp +or +.B :127 +not just +.B /regexp +or +.BR 127 . +(There is an easier way to locate literal text; see below.) +.PP +If the text is a file name followed by a colon and an address, +.I acme +loads the file and evaluates the address. For example, clicking button 3 anywhere +in the text +.B file.c:27 +will open +.BR file.c , +select line +27, and put the mouse at the beginning of the line. The rules about Error +files, directories, and so on all combine to make this an efficient way to +investigate errors from compilers, etc. +.PP +If the text is not an address or file, it is taken to +be literal text, which is then searched for in the body of the window +in which button 3 was clicked. If a match is found, it is selected and the mouse is +moved there. Thus, to search for occurrences of a word in a file, +just click button 3 on the word. Because of the rule of using the +selection as the button 3 action, subsequent clicks will find subsequent +occurrences without moving the mouse. +.PP +In all these actions, the mouse motion is not done if the text is a null string +within a non-null selected string in the tag, so that (for example) complex regular expressions +may be selected and applied repeatedly to the +body by just clicking button 3 over them. +.SS "Chords of mouse buttons +Several operations are bound to multiple-button actions. +After selecting text, with button 1 still down, pressing button 2 +executes +.B Cut +and button 3 executes +.BR Paste . +After clicking one button, the other undoes +the first; thus (while holding down button 1) 2 followed by 3 is a +.B Snarf +that leaves the file undirtied; +3 followed by 2 is a no-op. +These actions also apply to text selected by double-clicking because +the double-click expansion is made when the second +click starts, not when it ends. +.PP +Commands may be given extra arguments by a mouse chord with buttons 2 and 1. +While holding down button 2 on text to be executed as a command, clicking button 1 +appends the text last pointed to by button 1 as a distinct final argument. +For example, to search for literal +.B text +one may execute +.B Look text +with button 2 or instead point at +.B text +with button 1 in any window, release button 1, +then execute +.BR Look , +clicking button 1 while 2 is held down. +.PP +When an external command (e.g. +.IR echo (1)) +is executed this way, the extra argument is passed as expected and an +environment variable +.B $acmeaddr +is created that holds, in the form interpreted by button 3, +the fully-qualified address of the extra argument. +.SS "Support programs +.I Win +creates a new +.I acme +window and runs a +.I command +(default +.BR /bin/rc ) +in it, turning the window into something analogous to an +.IR rio (1) +window. +Executing text in a +.I win +window with button +2 is similar to using +.BR Send . +.PP +.I Awd +loads the tag line of its window with the directory in which it's running, suffixed +.BI - label +(default +.BR rc ); +it is +intended to be executed by a +.B cd +function for use in +.I win +windows. An example definition is +.EX + fn cd { builtin cd $1 && awd $sysname } +.EE +.SS "Applications and guide files +In the directory +.B /acme +live several subdirectories, each corresponding to a program or +set of related programs that employ +.I acme's +user interface. +Each subdirectory includes source, binaries, and a +.B readme +file for further information. +It also includes a +.BR guide , +a text file holding sample commands to invoke the programs. +The idea is to find an example in the guide that best matches +the job at hand, edit it to suit, and execute it. +.PP +Whenever a command is executed by +.IR acme , +the default search path includes the directory of the window containing +the command and its subdirectory +.BR $cputype . +The program directories in +.B /acme +contain appropriately labeled subdirectories of binaries, +so commands named +in the guide files will be found automatically when run. +Also, +.I acme +binds the directories +.B /acme/bin +and +.B /acme/bin/$cputype +to the end of +.B /bin +when it starts; this is where +.IR acme -specific +programs such as +.I win +and +.I awd +reside. +.SH FILES +.TF $home/acme.dump +.TP +.B $home/acme.dump +default file for +.B Dump +and +.BR Load ; +also where state is written if +.I acme +dies or is killed unexpectedly, e.g. by deleting its window. +.TP +.B /acme/*/guide +template files for applications +.TP +.B /acme/*/readme +informal documentation for applications +.TP +.B /acme/*/src +source for applications +.TP +.B /acme/*/mips +MIPS-specific binaries for applications +.SH SOURCE +.B /sys/src/cmd/acme +.br +.B /acme/bin/source/win +.br +.B /sys/src/cmd/awd.c +.SH SEE ALSO +.IR acme (4) +.br +Rob Pike, +.I +Acme: A User Interface for Programmers. +.SH BUGS +With the +.B -l +option or +.B Load +command, +the recreation of windows under control of external programs +such as +.I win +is just to rerun the command; information may be lost. |