From 058b0118a52061ad57694c01fc8763b22b789c4d Mon Sep 17 00:00:00 2001
From: rsc <devnull@localhost>
Date: Mon, 3 Jan 2005 06:40:20 +0000
Subject: Some man pages.

---
 man/man4/acme.4 | 406 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 406 insertions(+)
 create mode 100644 man/man4/acme.4

(limited to 'man/man4/acme.4')

diff --git a/man/man4/acme.4 b/man/man4/acme.4
new file mode 100644
index 00000000..f6a48538
--- /dev/null
+++ b/man/man4/acme.4
@@ -0,0 +1,406 @@
+.TH ACME 4
+.SH NAME
+acme \- control files for text windows
+.SH SYNOPSIS
+.B acme
+[
+.B -f
+.I varfont
+] [
+.B -F
+.I fixfont
+]
+[
+.I file
+\&... ]
+.SH DESCRIPTION
+The text window system
+.IR acme (1)
+serves a variety of files for reading, writing, and controlling
+windows.
+Some of them are virtual versions of system files for dealing
+with the virtual console; others control operations
+of 
+.I acme
+itself.
+When a command is run under
+.IR acme ,
+a directory holding these files is mounted on
+.B /mnt/acme
+(also bound to
+.BR /mnt/wsys )
+and also
+.BR /dev ;
+the files mentioned here
+appear in both those directories.
+.PP
+Some of these files supply virtual versions of services available from the underlying
+environment, in particular the character terminal files in Plan 9's
+\fIcons\fR(3).
+(Unlike in Plan 9's \fIrio\fR(1),
+each command under
+.I acme
+sees the same set of files; there is not a distinct
+.B /dev/cons
+for each window.)
+Other files are unique to
+.IR acme .
+.TP
+.B acme
+is a subdirectory used by
+.B win
+(see
+.IR acme (1))
+as a mount point for the
+.I acme
+files associated with the window in which
+.B win
+is running.
+It has no specific function under
+.I acme
+itself.
+.TP
+.B cons
+is the standard and diagnostic output file for all commands
+run under
+.IR acme .
+(Input for commands is redirected to
+.BR /dev/null .)
+Text written to
+.B cons
+appears in a window labeled
+.IB dir /+Errors\f1,
+where
+.I dir
+is the directory in which the command
+was run.
+The window is created if necessary, but not until text is actually written.
+.TP
+.B consctl
+Is an empty unwritable file present only for compatibility; there is no way
+to turn off `echo', for example, under
+.IR acme .
+.TP
+.B index
+holds a sequence of lines of text, one per window.  Each line has 5 decimal numbers,
+each formatted in 11 characters plus a blank\(emthe window ID;
+number of characters (runes) in the tag;
+number of characters in the body;
+a 1 if the window is a directory, 0 otherwise;
+and a 1 if the window is modified, 0
+otherwise\(emfollowed by the tag up to a newline if present.
+Thus at character position 5×12 starts the name of the window.
+If a file has multiple zeroxed windows open,
+only the most recently used will appear in the
+.B index
+file.
+.TP
+.B label
+is an empty file, writable without effect, present only for compatibility with
+.BR rio .
+.TP
+.B new
+A directory analogous to the numbered directories
+.RI ( q.v. ).
+Accessing any
+file in
+.B new
+creates a new window.  Thus to cause text to appear in a new window,
+write it to
+.BR /dev/new/body .
+For more control, open
+.BR /dev/new/ctl
+and use the interface described below.
+.LP
+.PP
+Each
+.I acme
+window has associated a directory numbered by its ID.
+Window IDs are chosen sequentially and may be discovered by the
+.B ID
+command, by
+reading the
+.B ctl
+file, or
+indirectly through the
+.B index
+file.  The files in the numbered directories are as follows.
+.TP
+.B addr
+may be written with any textual address (line number, regular expression, etc.),
+in the format understood by button 3 but without the initial colon, including compound addresses,
+to set the address for text accessed through the
+.B data
+file.
+When read, it returns the value of the address that would next be read
+or written through the
+.B data
+file, in the format
+.BI # m ,# n
+where
+.I m
+and
+.I n
+are character (not byte) offsets.  If
+.I m
+and
+.I n
+are identical, the format is just
+.BI # m\f1.
+Thus a regular expression may be evaluated by writing it to
+.B addr
+and reading it back.
+The
+.B addr
+address has no effect on the user's selection of text.
+.TP
+.B body
+holds contents of the window body.  It may be read at any byte offset.
+Text written to
+.B body
+is always appended; the file offset is ignored.
+.TP
+.B ctl
+may be read to recover the five numbers as held in the
+.B index
+file, described above, plus two more fields: the width of the
+window in pixels and the name of the font used in the window.
+Text messages may be written to
+.B ctl
+to affect the window.
+Each message is terminated by a newline and multiple
+messages may be sent in a single write.
+.RS .5i
+.TF limit=addr
+.TP
+.B addr=dot
+Set the
+.B addr
+address to that of the user's selected text in the window.
+.TP
+.B clean
+Mark the window clean as though it has just been written.
+.TP
+.B dirty
+Mark the window dirty, the opposite of clean.
+.TP
+.B cleartag
+Remove all text in the tag after the vertical bar.
+.TP
+.B del
+Equivalent to the
+.B Del
+interactive command.
+.TP
+.B delete
+Equivalent to the
+.B Delete
+interactive command.
+.TP
+.B dot=addr
+Set the user's selected text in the window to the text addressed by the
+.B addr
+address.
+.TP
+.BI dump " command
+Set the command string to recreate the window from a dump file.
+.TP
+.BI dumpdir " directory
+Set the directory in which to run the command to recreate the window from a dump file.
+.TP
+.B get
+Equivalent to the
+.B Get
+interactive command with no arguments; accepts no arguments.
+.TP
+.B limit=addr
+When the
+.B ctl
+file is first opened, regular expression context searches in
+.B addr
+addresses examine the whole file; this message restricts subsequent
+searches to the current
+.B addr
+address.
+.TP
+.B mark
+Cancel
+.BR nomark ,
+returning the window to the usual state wherein each modification to the
+body must be undone individually.
+.TP
+.BI name " name
+Set the name of the window to
+.IR name .
+.TP
+.B nomark
+Turn off automatic `marking' of changes, so a set of related changes
+may be undone in a single
+.B Undo
+interactive command.
+.TP
+.B noscroll
+Turn off automatic `scrolling' of the window to show text written to the body.
+.TP
+.B put
+Equivalent to the
+.B Put
+interactive command with no arguments; accepts no arguments.
+.TP
+.B scroll
+Cancel a
+.B noscroll
+message, returning the window to the default state wherein each write
+to the
+.B body
+file causes the window to `scroll' to display the new text.
+.TP
+.B show
+Guarantee at least some of the selected text is visible on the display.
+.RE
+.PD
+.TP
+.B data
+is used in conjunction with
+.B addr
+for random access to the contents of the body.
+The file offset is ignored when writing the
+.B data
+file; instead the location of the data to be read or written is determined by the state of the
+.B addr
+file.
+Text, which must contain only whole characters (no `partial runes'),
+written to
+.B data
+replaces the characters addressed by the
+.B addr
+file and sets the address to the null string at the end of the written text.
+A read from
+.B data
+returns as many whole characters as the read count will permit starting
+at the beginning of the
+.B addr
+address (the end of the address has no effect)
+and sets the address to the null string at the end of the returned
+characters.
+.TP
+.B event
+When a window's
+.B event
+file is open, changes to the window occur as always but the
+actions are also reported as
+messages to the reader of the file.  Also, user actions with buttons 2 and 3
+(other than chorded
+.B Cut
+and
+.BR Paste ,
+which behave normally) have no immediate effect on the window;
+it is expected that the program reading the
+.B event
+file will interpret them.
+The messages have a fixed format:
+a character indicating the origin or cause of the action,
+a character indicating the type of the action,
+four free-format blank-terminated decimal numbers,
+optional text, and a newline.
+The first and second numbers are the character addresses of the action,
+the third is a flag,
+and the final is a count of the characters in the optional text, which
+may itself contain newlines.
+The origin characters are
+.B E
+for writes to the
+.B body
+or
+.B tag
+file,
+.B F
+for actions through the window's other files,
+.B K
+for the keyboard, and
+.B M
+for the mouse.
+The type characters are
+.B D
+for text deleted from the body,
+.B d
+for text deleted from the tag,
+.B I
+for text inserted to the body,
+.B i
+for text inserted to the tag,
+.B L
+for a button 3 action in the body,
+.B l
+for a button 3 action in the tag,
+.B X
+for a button 2 action in the body, and
+.B x
+for a button 2 action in the tag.
+.IP
+If the relevant text has less than 256 characters, it is included in the message;
+otherwise it is elided, the fourth number is 0, and the program must read
+it from the
+.B data
+file if needed.  No text is sent on a
+.B D
+or
+.B d
+message.
+.IP
+For
+.BR D ,
+.BR d ,
+.BR I ,
+and
+.BR i
+the flag is always zero.
+For
+.BR X
+and
+.BR x ,
+the flag is a bitwise OR (reported decimally) of the following:
+1 if the text indicated is recognized as an
+.I acme
+built-in command;
+2 if the text indicated is a null string that has a non-null expansion;
+if so, another complete message will follow describing the expansion
+exactly as if it had been indicated explicitly (its flag will always be 0);
+8 if the command has an extra (chorded) argument; if so,
+two more complete messages will follow reporting the argument (with
+all numbers 0 except the character count) and where it originated, in the form of
+a fully-qualified button 3 style address.
+.IP
+For
+.B L
+and
+.BR l ,
+the flag is the bitwise OR of the following:
+1 if
+.I acme
+can interpret the action without loading a new file;
+2 if a second (post-expansion) message follows, analogous to that with
+.B X
+messages;
+4 if the text is a file or window name (perhaps with address) rather than
+plain literal text.
+.IP
+For messages with the 1 bit on in the flag,
+writing the message back to the
+.B event
+file, but with the flag, count, and text omitted,
+will cause the action to be applied to the file exactly as it would
+have been if the
+.B event
+file had not been open.
+.TP
+.B tag
+holds contents of the window tag.  It may be read at any byte offset.
+Text written to
+.B tag
+is always appended; the file offset is ignored.
+.SH SOURCE
+.B /usr/local/plan9/src/cmd/acme
+.SH SEE ALSO
+.IR rio (1),
+.IR acme (1)
-- 
cgit v1.2.3