acme.1 (20663B)
1 .TH ACME 1 2 .SH NAME 3 acme, win, awd \- interactive text windows 4 .SH SYNOPSIS 5 .B acme 6 [ 7 .B -abr 8 ] 9 [ 10 .B -f 11 .I varfont 12 ] 13 [ 14 .B -F 15 .I fixfont 16 ] 17 [ 18 .B -c 19 .I ncol 20 ] 21 [ 22 .B -m 23 .I mtpt 24 ] 25 [ 26 .B -l 27 .I file 28 | 29 .I file 30 \&... ] 31 .LP 32 .B win 33 [ 34 .I command 35 ] 36 .LP 37 .B awd 38 [ 39 .I label 40 ] 41 .SH DESCRIPTION 42 .I Acme 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 46 .IR acme ; 47 these are discussed in 48 .MR acme (4) . 49 .PP 50 Any named 51 .I files 52 are read into 53 .I acme 54 windows before 55 .I acme 56 accepts input. 57 With the 58 .B -l 59 option, the state of the entire system is loaded 60 from 61 .IR file , 62 which should have been created by a 63 .B Dump 64 command (q.v.), 65 and subsequent 66 .I file 67 names are ignored. 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. 72 .PP 73 The 74 .B -f 75 .RB ( -F ) 76 option sets the main font, usually variable-pitch (alternate, usually fixed-pitch); 77 the default is 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 81 .BR $tabstop ) 82 numeral zeros in the appropriate font. 83 .PP 84 The 85 .B -m 86 option instructs 87 .I acme 88 to use FUSE (see 89 .MR 9pfuse (4) ) 90 to mount itself at 91 .IR mtpt . 92 (Experimental.) 93 .PP 94 .SS Windows 95 .I Acme 96 windows are in two parts: a one-line 97 .I tag 98 above a multi-line 99 .IR body . 100 The body typically contains an image of a file, as in 101 .MR sam (1) , 102 or the output of a 103 program, as in an 104 .MR rio (1) 105 window. 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 114 window. 115 .PP 116 If a window holds a directory, the name (first word of the tag) will end with 117 a slash. 118 .SS Scrolling 119 Each window has a scroll bar to the left of the body. 120 The scroll bar behaves much as in 121 .MR sam (1) 122 or 123 .MR rio (1) 124 except that scrolling occurs when the button is pressed, rather than released, 125 and continues 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 131 .B -r 132 reverses the scrolling behavior of buttons 1 and 3, to behave 133 more like 134 .MR xterm (1) .) 135 .SS Layout 136 .I Acme 137 windows are arranged in columns. By default, it creates two columns when starting; 138 this can be overridden with the 139 .B -c 140 option. 141 Placement is automatic but may be adjusted 142 using the 143 .I layout box 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. 147 For windows, just 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. 152 (They will return 153 .I en masse 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': 157 .I acme 158 believes it is modified from its original 159 contents. 160 .PP 161 Tags exist at the top of each column and across the whole display. 162 .I Acme 163 pre-loads them with useful commands. 164 Also, the tag across the top maintains a list of executing long-running commands. 165 .SS Typing 166 The behavior of typed text is similar to that in 167 .MR rio (1) 168 except that the characters are delivered to the tag or body under the mouse; there is no 169 `click to type'. 170 (The experimental option 171 .B -b 172 causes typing to go to the most recently clicked-at or made window.) 173 The usual backspacing conventions apply. 174 As in 175 .MR sam (1) 176 but not 177 .IR rio , 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 181 to a 182 .B Cut 183 command 184 .RI ( q.v. ). 185 .PP 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 189 by 190 .IR acme . 191 .PP 192 When a window is in autoindent mode 193 (see the 194 .B Indent 195 command below) and a newline character is typed, 196 .I acme 197 copies leading white space on the current line to the new line, 198 and when a window is 199 .BR Put , 200 .I acme 201 removes all trailing end-of-line white space before writing the file. 202 The option 203 .B -a 204 causes each window to start in 205 autoindent mode. 206 .SS "Directory context 207 Each window's tag names a directory: explicitly if the window 208 holds a directory; implicitly if it holds a regular file 209 (e.g. the directory 210 .B /adm 211 if the window holds 212 .BR /adm/users ). 213 This directory provides a 214 .I context 215 for interpreting file names in that window. 216 For example, the string 217 .B users 218 in a window labeled 219 .B /adm/ 220 or 221 .B /adm/keys 222 will be interpreted as the file name 223 .BR /adm/users . 224 The directory is defined purely textually, so it can be a non-existent 225 directory or a real directory associated with a non-existent file 226 (e.g. 227 .BR /adm/not-a-file ). 228 File names beginning with a slash 229 are assumed to be absolute file names. 230 .SS Errors 231 Windows whose names begin with 232 .B - 233 or 234 .B + 235 conventionally hold diagnostics and other data 236 not directly associated with files. 237 A window labeled 238 .B +Errors 239 receives all diagnostics produced by 240 .I acme 241 itself. 242 Diagnostics from commands run by 243 .I acme 244 appear in a window named 245 .IB directory /+Errors 246 where 247 .I directory 248 is identified by the context of the command. 249 These error windows are created when needed. 250 .SS "Mouse button 1 251 Mouse button 1 selects text just as in 252 .MR sam (1) 253 or 254 .IR rio (1) , 255 including the usual double-clicking conventions. 256 .SS "Mouse button 2 257 By an 258 action similar to selecting text with button 1, 259 button 2 indicates text to execute as a command. 260 If the indicated text has multiple white-space-separated words, 261 the first is the command name and the second and subsequent 262 are its arguments. 263 If button 2 is `clicked'\(emindicates a null string\(em\c 264 .I acme 265 .I expands 266 the indicated text to find a command to run: 267 if the click is within button-1-selected text, 268 .I acme 269 takes that selection as the command; 270 otherwise it takes the largest string of valid file name characters containing the click. 271 Valid file name characters are alphanumerics and 272 .B _ 273 .B . 274 .B - 275 .B + 276 .BR / . 277 This behavior is similar to double-clicking with button 1 but, 278 because a null command is meaningless, only a single click is required. 279 .PP 280 Some commands, all by convention starting with a capital letter, are 281 .I built-ins 282 that are executed directly by 283 .IR acme : 284 .TP 285 .B Cut 286 Delete most recently selected text and place in snarf buffer. 287 .TP 288 .B Del 289 Delete window. If window is dirty, instead print a warning; a second 290 .B Del 291 will succeed. 292 .TP 293 .B Delcol 294 Delete column and all its windows, after checking that windows are not dirty. 295 .TP 296 .B Delete 297 Delete window without checking for dirtiness. 298 .TP 299 .B Dump 300 Write the state of 301 .I acme 302 to the file name, if specified, or 303 .B $HOME/acme.dump 304 by default. 305 .TP 306 .B Edit 307 Treat the argument as a text editing command in the style of 308 .MR sam (1) . 309 The full 310 .B Sam 311 language is implemented except for the commands 312 .BR k , 313 .BR n , 314 .BR q , 315 and 316 .BR ! . 317 The 318 .B = 319 command is slightly different: it includes the file name and 320 gives only the line address unless the command is explicitly 321 .BR =# . 322 The `current window' for the command is the body of the window in which the 323 .B Edit 324 command is executed. 325 Usually the 326 .B Edit 327 command would be typed in a tag; longer commands may be prepared in a 328 scratch window and executed, with 329 .B Edit 330 itself in the current window, using the 2-1 chord described below. 331 .TP 332 .B Exit 333 Exit 334 .I acme 335 after checking that windows are not dirty. 336 .TP 337 .B Font 338 With no arguments, change the font of the associated window from fixed-spaced to 339 proportional-spaced or 340 .I vice 341 .IR versa . 342 Given a file name argument, change the font of the window to that stored in the named file. 343 If the file name argument is prefixed by 344 .B var 345 .RB ( fix ), 346 also set the default proportional-spaced (fixed-spaced) font for future use to that font. 347 Other existing windows are unaffected. 348 .TP 349 .B Get 350 Load file into window, replacing previous contents (after checking for dirtiness as in 351 .BR Del ). 352 With no argument, use the existing file name of the window. 353 Given an argument, use that file but do not change the window's file name. 354 .TP 355 .B ID 356 Print window ID number 357 .RI ( q.v. ). 358 .TP 359 .B Incl 360 When opening `include' files 361 (those enclosed in 362 .BR <> ) 363 with button 3, 364 .I acme 365 searches in directories 366 .B /$objtype/include 367 and 368 .BR /sys/include . 369 .B Incl 370 adds its arguments to a supplementary list of include directories, analogous to 371 the 372 .B -I 373 option to the compilers. 374 This list is per-window and is inherited when windows are created by actions in that window, so 375 .I Incl 376 is most usefully applied to a directory containing relevant source. 377 With no arguments, 378 .I Incl 379 prints the supplementary list. 380 This command is largely superseded by plumbing 381 (see 382 .MR plumb (7) ). 383 .TP 384 .B Indent 385 Set the autoindent mode according to the argument: 386 .B on 387 and 388 .B off 389 set the mode for the current window; 390 .B ON 391 and 392 .B OFF 393 set the mode for all existing and future windows. 394 .TP 395 .B Kill 396 Send a 397 .B kill 398 note to 399 .IR acme -initiated 400 commands named as arguments. 401 .TP 402 .B Load 403 Restore the state of 404 .I acme 405 from a file (default 406 .BR $HOME/acme.dump ) 407 created by the 408 .B Dump 409 command. 410 .TP 411 .B Local 412 In the Plan 9 413 .IR acme , 414 this prefix causes a command to be run in 415 .IR acme 's own 416 file name space and environment variable group. 417 On Unix this is impossible. 418 .B Local 419 is recognized as a prefix, but has no effect on the command being executed. 420 .\" .TP 421 .\" .B Local 422 .\" When prefixed to a command 423 .\" run the 424 .\" command in the same file name space and environment variable group as 425 .\" .IR acme . 426 .\" The environment of the command 427 .\" is restricted but is sufficient to run 428 .\" .IR bind (1), 429 .\" .IR 9fs 430 .\" (see 431 .\" .IR srv (4)), 432 .\" .IR import (4), 433 .\" etc., 434 .\" and to set environment variables such as 435 .\" .BR $objtype . 436 .TP 437 .B Look 438 Search in body for occurrence of literal text indicated by the argument or, 439 if none is given, by the selected text in the body. 440 .TP 441 .B New 442 Make new window. With arguments, load the named files into windows. 443 .TP 444 .B Newcol 445 Make new column. 446 .TP 447 .B Paste 448 Replace most recently selected text with contents of snarf buffer. 449 .TP 450 .B Put 451 Write window to the named file. 452 With no argument, write to the file named in the tag of the window. 453 .TP 454 .B Putall 455 Write all dirty windows whose names indicate existing regular files. 456 .TP 457 .B Redo 458 Complement of 459 .BR Undo . 460 .TP 461 .B Send 462 Append selected text or snarf buffer to end of body; used mainly with 463 .IR win . 464 .TP 465 .B Snarf 466 Place selected text in snarf buffer. 467 .TP 468 .B Sort 469 Arrange the windows in the column from top to bottom in lexicographical 470 order based on their names. 471 .TP 472 .B Tab 473 Set the width of tab stops for this window to the value of the argument, in units of widths of the zero 474 character. 475 With no arguments, it prints the current value. 476 .TP 477 .B Undo 478 Undo last textual change or set of changes. 479 .TP 480 .B Zerox 481 Create a copy of the window containing most recently selected text. 482 .TP 483 .B <|> 484 If a regular shell command is preceded by a 485 .BR < , 486 .BR | , 487 or 488 .B > 489 character, the selected text in the body of the window is affected by the 490 I/O from the command. 491 The 492 .B < 493 character causes the selection to be replaced by the standard output 494 of the command; 495 .B > 496 causes the selection to be sent as standard input to the command; and 497 .B | 498 does both at once, `piping' the selection through the command and 499 replacing it with the output. 500 .PP 501 A common place to store text for commands is in the tag; in fact 502 .I acme 503 maintains a set of commands appropriate to the state of the window 504 to the left of the bar in the tag. 505 .PP 506 If the text indicated with button 2 is not a recognized built-in, it is executed as 507 a shell command. For example, indicating 508 .B date 509 with button 2 runs 510 .MR date (1) . 511 The standard 512 and error outputs of commands are sent to the error window associated with 513 the directory from which the command was run, which will be created if 514 necessary. 515 For example, in a window 516 .B /etc/passwd 517 executing 518 .B pwd 519 will produce the output 520 .B /etc 521 in a (possibly newly-created) window labeled 522 .BR /etc/+Errors ; 523 in a window containing 524 .B /home/rob/sam/sam.c 525 executing 526 .B mk 527 will run 528 .MR mk (1) 529 in 530 .BR /home/rob/sam , 531 producing output in a window labeled 532 .BR /home/rob/sam/+Errors . 533 The environment of such commands contains the variable 534 .B $% 535 and 536 .B $samfile 537 with value set to the filename of the window in which the command is run, 538 and 539 .B $winid 540 set to the window's id number 541 (see 542 .MR acme (4) ). 543 .PP 544 The environment variable 545 .B $acmeshell 546 determines which shell is used to execute such commands; the 547 .MR rc (1) 548 shell is used by default. 549 .SS "Mouse button 3 550 Pointing at text with button 3 instructs 551 .I acme 552 to locate or acquire the file, string, etc. described by the indicated text and 553 its context. 554 This description follows the actions taken when 555 button 3 is released after sweeping out some text. 556 In the description, 557 .I text 558 refers to the text of the original sweep or, if it was null, the result of 559 applying the same expansion rules that apply to button 2 actions. 560 .PP 561 If the text names an existing window, 562 .I acme 563 moves the mouse cursor to the selected text in the body of that window. 564 If the text names an existing file with no associated window, 565 .I acme 566 loads the file into a new window and moves the mouse there. 567 If the text is a file name contained in angle brackets, 568 .I acme 569 loads the indicated include file from the directory appropriate to the 570 suffix of the file name of the window holding the text. 571 (The 572 .B Incl 573 command adds directories to the standard list.) 574 .PP 575 If the text begins with a colon, it is taken to be an address, in 576 the style of 577 .MR sam (1) , 578 within the body of the window containing the text. 579 The address is evaluated, the resulting text highlighted, and the mouse moved to it. 580 Thus, in 581 .IR acme , 582 one must type 583 .B :/regexp 584 or 585 .B :127 586 not just 587 .B /regexp 588 or 589 .BR 127 . 590 (There is an easier way to locate literal text; see below.) 591 If shift is held down during the selection or click, 592 any leading regular expression search defaults to 593 searching backward in the text instead of forward. 594 .PP 595 If the text is a file name followed by a colon and an address, 596 .I acme 597 loads the file and evaluates the address. For example, clicking button 3 anywhere 598 in the text 599 .B file.c:27 600 will open 601 .BR file.c , 602 select line 603 27, and put the mouse at the beginning of the line. The rules about Error 604 files, directories, and so on all combine to make this an efficient way to 605 investigate errors from compilers, etc. 606 .PP 607 If the text is not an address or file, it is taken to 608 be literal text, which is then searched for in the body of the window 609 in which button 3 was clicked. If a match is found, it is selected and the mouse is 610 moved there. Thus, to search for occurrences of a word in a file, 611 just click button 3 on the word. Because of the rule of using the 612 selection as the button 3 action, subsequent clicks will find subsequent 613 occurrences without moving the mouse. 614 If shift is held down during the selection or click, 615 the search looks backward in the file. 616 .PP 617 In all these actions, the mouse motion is not done if the text is a null string 618 within a non-null selected string in the tag, so that (for example) complex regular expressions 619 may be selected and applied repeatedly to the 620 body by just clicking button 3 over them. 621 .SS "Chords of mouse buttons 622 Several operations are bound to multiple-button actions. 623 After selecting text, with button 1 still down, pressing button 2 624 executes 625 .B Cut 626 and button 3 executes 627 .BR Paste . 628 After clicking one button, the other undoes 629 the first; thus (while holding down button 1) 2 followed by 3 is a 630 .B Snarf 631 that leaves the file undirtied; 632 3 followed by 2 is a no-op. 633 These actions also apply to text selected by double-clicking because 634 the double-click expansion is made when the second 635 click starts, not when it ends. 636 .PP 637 Commands may be given extra arguments by a mouse chord with buttons 2 and 1. 638 While holding down button 2 on text to be executed as a command, clicking button 1 639 appends the text last pointed to by button 1 as a distinct final argument. 640 For example, to search for literal 641 .B text 642 one may execute 643 .B Look text 644 with button 2 or instead point at 645 .B text 646 with button 1 in any window, release button 1, 647 then execute 648 .BR Look , 649 clicking button 1 while 2 is held down. 650 .PP 651 When an external command (e.g. 652 .MR echo (1) ) 653 is executed this way, the extra argument is passed as expected and an 654 environment variable 655 .B $acmeaddr 656 is created that holds, in the form interpreted by button 3, 657 the fully-qualified address of the extra argument. 658 .SS "Simulated buttons 659 For systems without a three-button mouse, the keyboard modifier 660 keys can be used to modify the effect of the main mouse button. 661 On Unix systems, the Control key changes the main button to button 2, 662 and the Alt key changes it to button 3. 663 On Mac systems, the Option key changes the main button to button 2, 664 and the Command key changes it to button 3. 665 Pressing the key after the button is held down adds the button to form 666 a chord, so that for example on Macs selecting text with the trackpad 667 button and then typing Option without letting go of the button will 668 cause a 1-2 chord, cutting the selection. 669 On Mac systems, the usual keyboard shortcuts 670 Command-C, -V, -X, and -Z invoke 671 copy, paste, cut, and undo, 672 and Command-Shift-Z invokes redo, 673 as in other programs. 674 Especially on Mac laptops, these keyboard shortcuts are 675 typically much less awkward than the equivalent chords. 676 .SS "Support programs 677 .I Win 678 creates a new 679 .I acme 680 window and runs a 681 .I command 682 (default 683 .BR $SHELL ) 684 in it, turning the window into something analogous to an 685 .MR 9term (1) 686 window. 687 Executing text in a 688 .I win 689 window with button 690 2 is similar to using 691 .BR Send . 692 .I Win 693 windows follow the same scrolling heuristic as in 694 .MR 9term (1) : 695 the window scrolls on output only if the window is displaying the end of the buffer. 696 .PP 697 .I Awd 698 loads the tag line of its window with the directory in which it's running, suffixed 699 .BI - label 700 (default 701 .BR rc ); 702 it is 703 intended to be executed by a 704 .B cd 705 function for use in 706 .I win 707 windows. An example definition is 708 .EX 709 fn cd { builtin cd $1 && awd $sysname } 710 .EE 711 .SS "Applications and guide files 712 In the directory 713 .B /acme 714 live several subdirectories, each corresponding to a program or 715 set of related programs that employ 716 .I acme's 717 user interface. 718 Each subdirectory includes source, binaries, and a 719 .B readme 720 file for further information. 721 It also includes a 722 .BR guide , 723 a text file holding sample commands to invoke the programs. 724 The idea is to find an example in the guide that best matches 725 the job at hand, edit it to suit, and execute it. 726 .PP 727 Whenever a command is executed by 728 .IR acme , 729 the default search path includes the directory of the window containing 730 the command and its subdirectory 731 .BR $cputype . 732 The program directories in 733 .B /acme 734 contain appropriately labeled subdirectories of binaries, 735 so commands named 736 in the guide files will be found automatically when run. 737 Also, 738 .I acme 739 binds the directories 740 .B /acme/bin 741 and 742 .B /acme/bin/$cputype 743 to the end of 744 .B /bin 745 when it starts; this is where 746 .IR acme -specific 747 programs such as 748 .I win 749 and 750 .I awd 751 reside. 752 .SH FILES 753 .TF $HOME/acme.dump 754 .TP 755 .B $HOME/acme.dump 756 default file for 757 .B Dump 758 and 759 .BR Load ; 760 also where state is written if 761 .I acme 762 dies or is killed unexpectedly, e.g. by deleting its window. 763 .TP 764 .B /acme/*/guide 765 template files for applications 766 .TP 767 .B /acme/*/readme 768 informal documentation for applications 769 .TP 770 .B /acme/*/src 771 source for applications 772 .TP 773 .B /acme/*/mips 774 MIPS-specific binaries for applications 775 .SH SOURCE 776 .B \*9/src/cmd/acme 777 .br 778 .B \*9/src/cmd/9term/win.c 779 .br 780 .B \*9/bin/awd 781 .SH SEE ALSO 782 .MR acme (4) 783 .br 784 Rob Pike, 785 .I 786 Acme: A User Interface for Programmers. 787 .SH BUGS 788 With the 789 .B -l 790 option or 791 .B Load 792 command, 793 the recreation of windows under control of external programs 794 such as 795 .I win 796 is just to rerun the command; information may be lost.