acme 18 KB

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