Return to acme CVS log

Up to [Plan 9 NeXT] / lucent / sys / man / 1

Annotation of lucent/sys/man/1/acme, revision 1.1

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

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.