Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ACME(1)			    General Commands Manual		       ACME(1)

       acme, win, awd -	interactive text windows

       acme  [	-abr ] [ -f varfont ] [	-F fixfont ] [ -c ncol ] [ -m mtpt ] [
       -l file | file ... ]

       win [ command ]

       awd [ label ]

       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 file,
       which should have been created by a Dump	command	(q.v.),	and subsequent
       file names are ignored.	Plain files display as text; directories  dis-
       play  as	columnated lists of the	names of their components, as in ls -p
       directory|mc except that	the names of subdirectories have a  slash  ap-

       The  -f	(-F) option sets the main font,	usually	variable-pitch (alter-
       nate, usually fixed-pitch); the default	is  /usr/local/plan9/font/luc-
       sans/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.

       The  -m	option instructs acme to use FUSE (see 9pfuse(4)) to mount it-
       self at mtpt.  (Experimental.)

       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.

       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.  (The	experimental option -r reverses	the scrolling behavior
       of buttons 1 and	3, to behave more like xterm(1).)

       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.

       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

       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.

       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

       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

       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(7)).

       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  In  the  Plan  9 acme, this prefix causes	a command to be	run in
	      acme'sown	file name space	and environment	 variable  group.   On
	      Unix  this  is impossible.  Local	is recognized as a prefix, but
	      has no effect on the command being executed.

       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-

       Newcol Make new column.

       Paste  Replace most recently selected text with contents	of snarf  buf-

       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

       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

       <|>    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
       /etc/passwd  executing  pwd will	produce	the output /etc	in a (possibly
       newly-created) window labeled  /etc/+Errors;  in	 a  window  containing
       /home/rob/sam/sam.c  executing mk will run mk(1)	in /home/rob/sam, pro-
       ducing output in	a window labeled /home/rob/sam/+Errors.	 The  environ-
       ment  of	such commands contains the variable $% and $samfile 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)).

       The  environment	 variable $acmeshell determines	which shell is used to
       execute such commands; the rc(1)	shell is used by default.

   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

       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

       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 $SHELL) in
       it, turning the window into something analogous to an 9term(1)  window.
       Executing  text in a win	window with button 2 is	similar	to using Send.
       Win windows follow the same scrolling heuristic	as  in	9term(1):  the
       window  scrolls	on  output only	if the window is displaying the	end of
       the buffer.

       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 end of /bin when it
       starts; this is where acme-specific programs such as win	 and  awd  re-

	      default  file  for Dump and Load;	also where state is written if
	      acme dies	or is killed unexpectedly, e.g.	by deleting  its  win-

	      template files for applications

	      informal documentation for applications

	      source for applications

	      MIPS-specific binaries for applications


       Rob Pike, Acme: A User Interface	for Programmers.

       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.



Want to link to this manual page? Use this URL:

home | help