glenda.party
term% ls -F
term% pwd
$home/manuals/9front/1/acme
term% cat index.txt
ACME(1)                     General Commands Manual                    ACME(1)



NAME
       acme, win, awd - interactive text windows

SYNOPSIS
       acme  [ -ab ] [ -c ncol ] [ -f varfont ] [ -F fixfont ] [ -l loadfile |
       file ... ]

       win [ command ]

       awd [ label ]

DESCRIPTION
       Acme manages windows of text that may be edited interactively or by ex‐
       ternal  programs.   The  interactive  interface  uses  the keyboard and
       mouse; external programs use a set of files served by acme;  these  are
       discussed in acme(4).

       Any  named  files are read into acme windows before acme accepts input.
       With the -l option, the state of the entire system is loaded from load‐
       file, which should have been created by a Dump command (q.v.), and sub‐
       sequent file names are ignored.  Plain files display as text;  directo‐
       ries  display  as columnated lists of the names of their components, as
       in ls -p directory|mc except that the names of  subdirectories  have  a
       slash appended.

       The  -f  (-F) option sets the main font, usually variable-pitch (alter‐
       nate,  usually  fixed-pitch);  the   default   is   /lib/font/bit/luci‐
       dasans/euro.8.font (.../lucm/unicode.9.font).  Tab intervals are set to
       the width of 4 (or the value of $tabstop) numeral zeros in  the  appro‐
       priate font.

   Windows
       Acme  windows are in two parts: a one-line tag above a multi-line body.
       The body typically contains an image of a file, as in  sam(1),  or  the
       output of a program, as in an rio(1) window.  The tag contains a number
       of blank-separated words, followed by a vertical  bar  character,  fol‐
       lowed 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.

       If a window holds a directory, the name (first word of  the  tag)  will
       end with a slash.

   Scrolling
       Each  window  has a scroll bar to the left of the body.  The scroll bar
       behaves much as in sam(1) or 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.

   Layout
       Acme  windows are arranged in columns.  By default, it creates two col‐
       umns when starting; this can be overridden with the -c option.   Place‐
       ment is automatic but may be adjusted using the 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 col‐
       umn  completely, temporarily hiding other windows in the column.  (They
       will return 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': acme believes it is modified from its
       original contents.

       Tags  exist  at  the  top  of each column and across the whole display.
       Acme pre-loads them with useful commands.  Also, the tag across the top
       maintains a list of executing long-running commands.

   Typing
       The behavior of typed text is similar to that in 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 causes typing to go to
       the most recently clicked-at or made window.)   The  usual  backspacing
       conventions  apply.   As in sam(1) but not 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 Cut command (q.v.).

       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
       acme.

       When  a window is in autoindent mode (see the Indent command below) and
       a newline character is typed, acme copies leading white  space  on  the
       current  line  to  the  new  line.  The option -a causes each window to
       start in autoindent mode.

   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
       /adm if the window holds /adm/users).  This directory provides  a  con‐
       text  for  interpreting  file  names  in that window.  For example, the
       string users in a window labeled /adm/ or /adm/keys will be interpreted
       as  the  file  name /adm/users.  The directory is defined purely textu‐
       ally, so it can be a non-existent directory or a real directory associ‐
       ated  with a non-existent file (e.g.  /adm/not-a-file).  File names be‐
       ginning with a slash are assumed to be absolute file names.

   Errors
       Windows whose names begin with - or + conventionally  hold  diagnostics
       and  other  data  not directly associated with files.  A window labeled
       +Errors receives all diagnostics produced by acme itself.   Diagnostics
       from  commands  run  by acme appear in a window named directory/+Errors
       where directory is identified by the context of the command.  These er‐
       ror windows are created when needed.

   Mouse button 1
       Mouse  button 1 selects text just as in sam(1) or rio(1), including the
       usual double-clicking conventions.

   Mouse button 2
       By an action similar to selecting text with button 1,  button  2  indi‐
       cates text to execute as a command.  If the indicated text has multiple
       white-space-separated words, the first is the command name and the sec‐
       ond  and  subsequent are its arguments.  If button 2 is `clicked'—indi‐
       cates a null string—acme expands the indicated text to find  a  command
       to  run: if the click is within button-1-selected text, acme takes that
       selection as the command; otherwise it  takes  the  largest  string  of
       valid file name characters containing the click.  Valid file name char‐
       acters are alphanumerics and _ .  - + /.  This behavior is  similar  to
       double-clicking  with  button 1 but, because a null command is meaning‐
       less, only a single click is required.

       Some commands, all by convention starting with a  capital  letter,  are
       built-ins that are executed directly by acme:

       Cut    Delete most recently selected text and place in snarf buffer.

       Del    Delete  window.   If window is dirty, instead print a warning; a
              second Del will succeed.

       Delcol Delete column and all its windows, after checking  that  windows
              are not dirty.

       Delete Delete window without checking for dirtiness.

       Dump   Write  the  state  of  acme  to  the file name, if specified, or
              $home/acme.dump by default.

       Edit   Treat the argument as a text editing command  in  the  style  of
              sam(1).   The  full  Sam  language is implemented except for the
              commands k, n, q, and !.  The = command is  slightly  different:
              it includes the file name and gives only the line address unless
              the command is explicitly =#.  The `current window' for the com‐
              mand is the body of the window in which the Edit command is exe‐
              cuted.  Usually the Edit command would be typed in a tag; longer
              commands  may be prepared in a scratch window and executed, with
              Edit itself in the current window, using the 2-1 chord described
              below.

       Exit   Exit acme after checking that windows are not dirty.

       Font   With no arguments, change the font of the associated window from
              fixed-spaced to proportional-spaced or vice 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  var
              (fix),  also  set the default proportional-spaced (fixed-spaced)
              font for future use to that font.  Other  existing  windows  are
              unaffected.

       Get    Load file into window, replacing previous contents (after check‐
              ing for dirtiness as in Del).  With no argument, use the  exist‐
              ing  file  name of the window.  Given an argument, use that file
              but do not change the window's file name.

       ID     Print window ID number (q.v.).

       Incl   When opening `include' files (those enclosed in <>) with  button
              3,  acme  searches in directories /$objtype/include and /sys/in‐
              clude.  Incl adds its arguments to a supplementary list  of  in‐
              clude  directories, analogous to the -I option to the compilers.
              This list is per-window and is inherited when windows  are  cre‐
              ated by actions in that window, so Incl is most usefully applied
              to a directory containing relevant source.  With  no  arguments,
              Incl prints the supplementary list.  This command is largely su‐
              perseded by plumbing (see plumb(6)).

       Indent Set the autoindent mode according to the argument:  on  and  off
              set the mode for the current window; ON and OFF set the mode for
              all existing and future windows.

       Kill   Send a kill note to acme-initiated commands named as arguments.

       Load   Restore the state of acme from a file (default  $home/acme.dump)
              created by the Dump command.

       Local  When prefixed to a command run the command in the same file name
              space and environment variable group as acme.   The  environment
              of  the  command is restricted but is sufficient to run bind(1),
              9fs (see srv(4)), import(4), etc., and to set environment  vari‐
              ables such as $objtype.

       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.

       New    Make new window.  With arguments, load the named files into win‐
              dows.

       Newcol Make new column.

       Paste  Replace  most recently selected text with contents of snarf buf‐
              fer.

       Put    Write window to the named file.  With no argument, write to  the
              file named in the tag of the window.

       Putall Write  all  dirty  windows whose names indicate existing regular
              files.

       Redo   Complement of Undo.

       Send   Append selected text or snarf buffer to end of body; used mainly
              with win.

       Snarf  Place selected text in snarf buffer.

       Sort   Arrange  the windows in the column from top to bottom in lexico‐
              graphical order based on their names.

       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 ar‐
              guments, it prints the current value.

       Undo   Undo last textual change or set of changes.

       Zerox  Create a copy of the window containing  most  recently  selected
              text.

       <|>    If  a  regular shell command is preceded by a <, |, or > charac‐
              ter, the selected text in the body of the window is affected  by
              the  I/O from the command.  The < character causes the selection
              to be replaced by the standard output of the command;  >  causes
              the selection to be sent as standard input to the command; and |
              does both at once, `piping' the selection  through  the  command
              and replacing it with the output.

       A  common  place to store text for commands is in the tag; in fact acme
       maintains a set of commands appropriate to the state of the  window  to
       the left of the bar in the tag.

       If the text indicated with button 2 is not a recognized built-in, it is
       executed as a shell command.  For example, indicating date with  button
       2 runs 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
       /adm/users executing pwd will produce the output /adm  in  a  (possibly
       newly-created)  window  labeled  /adm/+Errors;  in  a window containing
       /sys/src/cmd/sam/sam.c executing mk will run mk(1) in /sys/src/cmd/sam,
       producing output in a window labeled /sys/src/cmd/sam/+Errors.  The en‐
       vironment of such commands contains the variable $% with value  set  to
       the  filename of the window in which the command is run, and $winid set
       to the window's id number (see acme(4)).

   Mouse button 3
       Pointing at text with button 3 instructs 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, 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.

       If  the  text  names an existing window, acme moves the mouse cursor to
       the selected text in the body of that window.  If the text names an ex‐
       isting  file  with no associated window, acme loads the file into a new
       window and moves the mouse there.  If the text is a file name contained
       in  angle  brackets, acme loads the indicated include file from the di‐
       rectory appropriate to the suffix of the file name of the window  hold‐
       ing  the  text.   (The  Incl  command  adds directories to the standard
       list.)

       If the text begins with a colon, it is taken to be an address,  in  the
       style  of  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 acme, one must type :/regexp or :127 not just
       /regexp or 127.  (There is an easier way to locate  literal  text;  see
       below.)

       If  the  text  is  a file name followed by a colon and an address, acme
       loads the file and evaluates the address.  For example, clicking button
       3  anywhere in the text file.c:27 will open 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.

       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 occur‐
       rences without moving the mouse.

       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  re‐
       peatedly to the body by just clicking button 3 over them.

   Chords of mouse buttons
       Several operations are bound to multiple-button actions.  After select‐
       ing text, with button 1 still down, pressing button 2 executes Cut  and
       button  3  executes Paste.  After clicking one button, the other undoes
       the first; thus (while holding down button 1) 2  followed  by  3  is  a
       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.

       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 com‐
       mand, clicking button 1 appends the text last pointed to by button 1 as
       a distinct final argument.  For example, to search for literal text one
       may execute Look text with button 2 or instead point at text with  but‐
       ton 1 in any window, release button 1, then execute Look, clicking but‐
       ton 1 while 2 is held down.

       When an external command (e.g.  echo(1)) is executed this way, the  ex‐
       tra  argument  is  passed  as  expected  and  an  environment  variable
       $acmeaddr is created that holds, in the form interpreted by  button  3,
       the fully-qualified address of the extra argument.

   Support programs
       Win  creates  a new acme window and runs a command (default /bin/rc) in
       it, turning the window into something analogous to  an  rio(1)  window.
       Executing text in a win window with button 2 is similar to using Send.

       Awd  loads  the tag line of its window with the directory in which it's
       running, suffixed -label (default rc); it is intended to be executed by
       a cd function for use in win windows.  An example definition is
            fn cd { builtin cd $1 && awd $sysname }

   Applications and guide files
       In  the directory /acme live several subdirectories, each corresponding
       to a program or set of related programs that employ acme's user  inter‐
       face.   Each  subdirectory includes source, binaries, and a readme file
       for further information.  It also includes a 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.

       Whenever  a  command  is  executed by acme, the default search path in‐
       cludes the directory of the window containing the command and its  sub‐
       directory $cputype.  The program directories in /acme contain appropri‐
       ately labeled subdirectories of binaries,  so  commands  named  in  the
       guide files will be found automatically when run.  Also, acme binds the
       directories /acme/bin and /acme/bin/$cputype to the beginning  of  /bin
       when  it  starts;  this is where acme-specific programs such as win and
       awd reside.

FILES
       $home/acme.dump
              default file for Dump and Load; also where state is  written  if
              acme  dies  or is killed unexpectedly, e.g. by deleting its win‐
              dow.

       /acme/*/guide
              template files for applications

       /acme/*/readme
              informal documentation for applications

       /acme/*/src
              source for applications

       /acme/*/mips
              MIPS-specific binaries for applications

SOURCE
       /sys/src/cmd/acme
       /acme/bin/source/win
       /sys/src/cmd/awd.c

SEE ALSO
       acme(4)
       Rob Pike, Acme: A User Interface for Programmers.

BUGS
       With the -l option or Load command, the  recreation  of  windows  under
       control  of external programs such as win is just to rerun the command;
       information may be lost.



                                                                       ACME(1)