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

       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  /font/lucsans/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 appropriate font.

       The -m option instructs acme to use FUSE	(see to	mount itself at	 mtpt.

       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 or	the output  of
       a  program,  as in an window.  The tag contains a number	of blank-sepa-
       rated words, followed by	a vertical bar	character,  followed  by  any-
       thing.  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; exam-
       ples 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 or except that scrolling occurs when the  button  is
       pressed,	 rather	than released, and continues as	long as	the mouse but-
       ton 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

       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	except that the	 char-
       acters  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 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, and when a	window is  Put,	 acme  removes
       all  trailing end-of-line white space before writing the	file.  The op-
       tion -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	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 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 command is the body
	      of  the  window  in which	the Edit command is executed.  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

       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

       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 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 in  /home/rob/sam,  producing
       output  in  a window labeled /home/rob/sam/+Errors.  The	environment 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

       The environment variable	$acmeshell determines which shell is  used  to
       execute such commands; the 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	within the body	of the window containing the  text.   The  ad-
       dress 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.  is executed this	way, the  extra	 argu-
       ment  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.

   Simulated buttons
       For  systems  without  a	three-button mouse, the	keyboard modifier keys
       can be used to modify the effect	of the main  mouse  button.   On  Unix
       systems,	 the  Control key changes the main button to button 2, and the
       Alt key changes it to button 3.	On Mac systems,	the Option key changes
       the  main  button to button 2, and the Command key changes it to	button
       3.  Pressing the	key after the button is	held down adds the  button  to
       form  a	chord,	so  that  for  example on Macs selecting text with the
       trackpad	button and then	typing Option without letting go of the	button
       will  cause  a  1-2  chord, cutting the selection.  On Mac systems, the
       usual keyboard shortcuts	Command-C, -V, -X, and -Z invoke copy,	paste,
       cut,  and undo, and Command-Shift-Z invokes redo, as in other programs.
       Especially on Mac laptops, these	keyboard shortcuts are typically  much
       less awkward than the equivalent	chords.

   Support programs
       Win  creates  a	new acme window	and runs a command (default $SHELL) in
       it, turning the window into something analogous to an window.   Execut-
       ing  text  in a win window with button 2	is similar to using Send.  Win
       windows follow the same scrolling heuristic as in 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