1 058b0118 2005-01-03 devnull .TH ACME 4
3 058b0118 2005-01-03 devnull acme \- control files for text windows
4 058b0118 2005-01-03 devnull .SH SYNOPSIS
8 058b0118 2005-01-03 devnull .I varfont
11 058b0118 2005-01-03 devnull .I fixfont
16 058b0118 2005-01-03 devnull .SH DESCRIPTION
17 058b0118 2005-01-03 devnull The text window system
19 058b0118 2005-01-03 devnull serves a variety of files for reading, writing, and controlling
21 058b0118 2005-01-03 devnull Some of them are virtual versions of system files for dealing
22 058b0118 2005-01-03 devnull with the virtual console; others control operations
26 058b0118 2005-01-03 devnull When a command is run under
27 058b0118 2005-01-03 devnull .IR acme ,
28 c8b6342d 2005-01-13 devnull a directory holding these files is posted as the 9P service
31 d32deab1 2020-08-16 rsc .MR 9pserve (4) ).
33 058b0118 2005-01-03 devnull Some of these files supply virtual versions of services available from the underlying
34 058b0118 2005-01-03 devnull environment, in particular the character terminal files in Plan 9's
35 977b25a7 2020-08-14 rsc .IR cons (3).
36 977b25a7 2020-08-14 rsc (Unlike in Plan 9's
38 058b0118 2005-01-03 devnull each command under
40 058b0118 2005-01-03 devnull sees the same set of files; there is not a distinct
41 058b0118 2005-01-03 devnull .B /dev/cons
42 058b0118 2005-01-03 devnull for each window.)
43 058b0118 2005-01-03 devnull Other files are unique to
44 058b0118 2005-01-03 devnull .IR acme .
47 058b0118 2005-01-03 devnull is a subdirectory used by
50 d32deab1 2020-08-16 rsc .MR acme (1) )
51 058b0118 2005-01-03 devnull as a mount point for the
53 058b0118 2005-01-03 devnull files associated with the window in which
55 058b0118 2005-01-03 devnull is running.
56 058b0118 2005-01-03 devnull It has no specific function under
61 058b0118 2005-01-03 devnull is the standard and diagnostic output file for all commands
62 058b0118 2005-01-03 devnull run under
63 058b0118 2005-01-03 devnull .IR acme .
64 058b0118 2005-01-03 devnull (Input for commands is redirected to
65 058b0118 2005-01-03 devnull .BR /dev/null .)
66 058b0118 2005-01-03 devnull Text written to
68 058b0118 2005-01-03 devnull appears in a window labeled
69 058b0118 2005-01-03 devnull .IB dir /+Errors\f1,
72 058b0118 2005-01-03 devnull is the directory in which the command
74 058b0118 2005-01-03 devnull The window is created if necessary, but not until text is actually written.
76 058b0118 2005-01-03 devnull .B consctl
77 4a3fb872 2014-04-30 rsc is an empty unwritable file present only for compatibility; there is no way
78 058b0118 2005-01-03 devnull to turn off `echo', for example, under
79 058b0118 2005-01-03 devnull .IR acme .
82 058b0118 2005-01-03 devnull holds a sequence of lines of text, one per window. Each line has 5 decimal numbers,
83 058b0118 2005-01-03 devnull each formatted in 11 characters plus a blank\(emthe window ID;
84 058b0118 2005-01-03 devnull number of characters (runes) in the tag;
85 058b0118 2005-01-03 devnull number of characters in the body;
86 058b0118 2005-01-03 devnull a 1 if the window is a directory, 0 otherwise;
87 058b0118 2005-01-03 devnull and a 1 if the window is modified, 0
88 058b0118 2005-01-03 devnull otherwise\(emfollowed by the tag up to a newline if present.
89 058b0118 2005-01-03 devnull Thus at character position 5×12 starts the name of the window.
90 058b0118 2005-01-03 devnull If a file has multiple zeroxed windows open,
91 058b0118 2005-01-03 devnull only the most recently used will appear in the
96 058b0118 2005-01-03 devnull is an empty file, writable without effect, present only for compatibility with
97 058b0118 2005-01-03 devnull .BR rio .
100 4a3fb872 2014-04-30 rsc reports a log of window operations since the opening of the
103 4a3fb872 2014-04-30 rsc Each line describes a single operation using three fields separated by single spaces:
104 4a3fb872 2014-04-30 rsc the decimal window ID, the operation, and the window name.
105 4a3fb872 2014-04-30 rsc Reading from
107 4a3fb872 2014-04-30 rsc blocks until there is an operation to report, so reading the file
108 4a3fb872 2014-04-30 rsc can be used to monitor editor activity and react to changes.
109 4a3fb872 2014-04-30 rsc The reported operations are
111 4a3fb872 2014-04-30 rsc (window creation),
113 4a3fb872 2014-04-30 rsc (window creation via zerox),
118 4a3fb872 2014-04-30 rsc (window deletion).
119 4a3fb872 2014-04-30 rsc The window name can be the empty string; in particular it is empty in
121 4a3fb872 2014-04-30 rsc log entries corresponding to windows created by external programs.
124 4a3fb872 2014-04-30 rsc is a directory analogous to the numbered directories
125 058b0118 2005-01-03 devnull .RI ( q.v. ).
126 058b0118 2005-01-03 devnull Accessing any
129 058b0118 2005-01-03 devnull creates a new window. Thus to cause text to appear in a new window,
130 058b0118 2005-01-03 devnull write it to
131 058b0118 2005-01-03 devnull .BR /dev/new/body .
132 058b0118 2005-01-03 devnull For more control, open
133 058b0118 2005-01-03 devnull .BR /dev/new/ctl
134 058b0118 2005-01-03 devnull and use the interface described below.
139 058b0118 2005-01-03 devnull window has associated a directory numbered by its ID.
140 058b0118 2005-01-03 devnull Window IDs are chosen sequentially and may be discovered by the
142 058b0118 2005-01-03 devnull command, by
143 058b0118 2005-01-03 devnull reading the
145 058b0118 2005-01-03 devnull file, or
146 058b0118 2005-01-03 devnull indirectly through the
147 058b0118 2005-01-03 devnull .B index
148 058b0118 2005-01-03 devnull file. The files in the numbered directories are as follows.
151 058b0118 2005-01-03 devnull may be written with any textual address (line number, regular expression, etc.),
152 058b0118 2005-01-03 devnull in the format understood by button 3 but without the initial colon, including compound addresses,
153 058b0118 2005-01-03 devnull to set the address for text accessed through the
156 058b0118 2005-01-03 devnull When read, it returns the value of the address that would next be read
157 058b0118 2005-01-03 devnull or written through the
159 058b0118 2005-01-03 devnull file, in the format
160 058b0118 2005-01-03 devnull .BI # m ,# n
165 058b0118 2005-01-03 devnull are character (not byte) offsets. If
169 058b0118 2005-01-03 devnull are identical, the format is just
170 058b0118 2005-01-03 devnull .BI # m\f1.
171 058b0118 2005-01-03 devnull Thus a regular expression may be evaluated by writing it to
173 058b0118 2005-01-03 devnull and reading it back.
176 058b0118 2005-01-03 devnull address has no effect on the user's selection of text.
179 058b0118 2005-01-03 devnull holds contents of the window body. It may be read at any byte offset.
180 058b0118 2005-01-03 devnull Text written to
182 058b0118 2005-01-03 devnull is always appended; the file offset is ignored.
185 058b0118 2005-01-03 devnull may be read to recover the five numbers as held in the
186 058b0118 2005-01-03 devnull .B index
187 d0d44086 2021-10-19 noreply file, described above, plus five more fields: the width of the
188 d0d44086 2021-10-19 noreply window in pixels; the name of the font used in the window;
189 d0d44086 2021-10-19 noreply the width of a tab character in pixels; a 1 if there is undo history, 0 otherwise;
190 d0d44086 2021-10-19 noreply a 1 if there is redo history, 0 otherwise.
191 058b0118 2005-01-03 devnull Text messages may be written to
193 058b0118 2005-01-03 devnull to affect the window.
194 058b0118 2005-01-03 devnull Each message is terminated by a newline and multiple
195 058b0118 2005-01-03 devnull messages may be sent in a single write.
197 058b0118 2005-01-03 devnull .TF limit=addr
199 058b0118 2005-01-03 devnull .B addr=dot
202 058b0118 2005-01-03 devnull address to that of the user's selected text in the window.
204 058b0118 2005-01-03 devnull .B clean
205 058b0118 2005-01-03 devnull Mark the window clean as though it has just been written.
207 058b0118 2005-01-03 devnull .B dirty
208 058b0118 2005-01-03 devnull Mark the window dirty, the opposite of clean.
210 058b0118 2005-01-03 devnull .B cleartag
211 058b0118 2005-01-03 devnull Remove all text in the tag after the vertical bar.
214 058b0118 2005-01-03 devnull Equivalent to the
216 058b0118 2005-01-03 devnull interactive command.
218 058b0118 2005-01-03 devnull .B delete
219 058b0118 2005-01-03 devnull Equivalent to the
220 058b0118 2005-01-03 devnull .B Delete
221 058b0118 2005-01-03 devnull interactive command.
223 058b0118 2005-01-03 devnull .B dot=addr
224 058b0118 2005-01-03 devnull Set the user's selected text in the window to the text addressed by the
226 058b0118 2005-01-03 devnull address.
228 058b0118 2005-01-03 devnull .BI dump " command
229 058b0118 2005-01-03 devnull Set the command string to recreate the window from a dump file.
231 058b0118 2005-01-03 devnull .BI dumpdir " directory
232 058b0118 2005-01-03 devnull Set the directory in which to run the command to recreate the window from a dump file.
235 058b0118 2005-01-03 devnull Equivalent to the
237 058b0118 2005-01-03 devnull interactive command with no arguments; accepts no arguments.
239 057d8a76 2020-07-19 rsc .BI font " path
240 057d8a76 2020-07-19 rsc Equivalent to the
242 057d8a76 2020-07-19 rsc interactive command with a single (required) argument.
244 058b0118 2005-01-03 devnull .B limit=addr
245 058b0118 2005-01-03 devnull When the
247 058b0118 2005-01-03 devnull file is first opened, regular expression context searches in
249 058b0118 2005-01-03 devnull addresses examine the whole file; this message restricts subsequent
250 058b0118 2005-01-03 devnull searches to the current
252 058b0118 2005-01-03 devnull address.
256 058b0118 2005-01-03 devnull .BR nomark ,
257 058b0118 2005-01-03 devnull returning the window to the usual state wherein each modification to the
258 058b0118 2005-01-03 devnull body must be undone individually.
260 058b0118 2005-01-03 devnull .BI name " name
261 058b0118 2005-01-03 devnull Set the name of the window to
262 058b0118 2005-01-03 devnull .IR name .
264 058b0118 2005-01-03 devnull .B nomark
265 058b0118 2005-01-03 devnull Turn off automatic `marking' of changes, so a set of related changes
266 058b0118 2005-01-03 devnull may be undone in a single
268 058b0118 2005-01-03 devnull interactive command.
271 058b0118 2005-01-03 devnull Equivalent to the
273 058b0118 2005-01-03 devnull interactive command with no arguments; accepts no arguments.
276 058b0118 2005-01-03 devnull Guarantee at least some of the selected text is visible on the display.
281 058b0118 2005-01-03 devnull is used in conjunction with
283 058b0118 2005-01-03 devnull for random access to the contents of the body.
284 058b0118 2005-01-03 devnull The file offset is ignored when writing the
286 058b0118 2005-01-03 devnull file; instead the location of the data to be read or written is determined by the state of the
289 058b0118 2005-01-03 devnull Text, which must contain only whole characters (no `partial runes'),
290 058b0118 2005-01-03 devnull written to
292 058b0118 2005-01-03 devnull replaces the characters addressed by the
294 058b0118 2005-01-03 devnull file and sets the address to the null string at the end of the written text.
295 058b0118 2005-01-03 devnull A read from
297 058b0118 2005-01-03 devnull returns as many whole characters as the read count will permit starting
298 058b0118 2005-01-03 devnull at the beginning of the
300 058b0118 2005-01-03 devnull address (the end of the address has no effect)
301 058b0118 2005-01-03 devnull and sets the address to the null string at the end of the returned
302 058b0118 2005-01-03 devnull characters.
304 9d01e221 2005-01-30 devnull .B errors
305 9d01e221 2005-01-30 devnull Writing to the
306 9d01e221 2005-01-30 devnull .B errors
307 9d01e221 2005-01-30 devnull file appends to the body of the
308 9d01e221 2005-01-30 devnull .IB dir /+Errors
309 9d01e221 2005-01-30 devnull window, where
311 9d01e221 2005-01-30 devnull is the directory currently named in the tag.
312 9d01e221 2005-01-30 devnull The window is created if necessary,
313 9d01e221 2005-01-30 devnull but not until text is actually written.
315 058b0118 2005-01-03 devnull .B event
316 058b0118 2005-01-03 devnull When a window's
317 058b0118 2005-01-03 devnull .B event
318 058b0118 2005-01-03 devnull file is open, changes to the window occur as always but the
319 058b0118 2005-01-03 devnull actions are also reported as
320 058b0118 2005-01-03 devnull messages to the reader of the file. Also, user actions with buttons 2 and 3
321 058b0118 2005-01-03 devnull (other than chorded
324 058b0118 2005-01-03 devnull .BR Paste ,
325 058b0118 2005-01-03 devnull which behave normally) have no immediate effect on the window;
326 058b0118 2005-01-03 devnull it is expected that the program reading the
327 058b0118 2005-01-03 devnull .B event
328 058b0118 2005-01-03 devnull file will interpret them.
329 058b0118 2005-01-03 devnull The messages have a fixed format:
330 058b0118 2005-01-03 devnull a character indicating the origin or cause of the action,
331 058b0118 2005-01-03 devnull a character indicating the type of the action,
332 058b0118 2005-01-03 devnull four free-format blank-terminated decimal numbers,
333 058b0118 2005-01-03 devnull optional text, and a newline.
334 058b0118 2005-01-03 devnull The first and second numbers are the character addresses of the action,
335 058b0118 2005-01-03 devnull the third is a flag,
336 058b0118 2005-01-03 devnull and the final is a count of the characters in the optional text, which
337 058b0118 2005-01-03 devnull may itself contain newlines.
338 058b0118 2005-01-03 devnull The origin characters are
340 058b0118 2005-01-03 devnull for writes to the
346 058b0118 2005-01-03 devnull for actions through the window's other files,
348 058b0118 2005-01-03 devnull for the keyboard, and
350 058b0118 2005-01-03 devnull for the mouse.
351 058b0118 2005-01-03 devnull The type characters are
353 058b0118 2005-01-03 devnull for text deleted from the body,
355 058b0118 2005-01-03 devnull for text deleted from the tag,
357 058b0118 2005-01-03 devnull for text inserted to the body,
359 058b0118 2005-01-03 devnull for text inserted to the tag,
361 058b0118 2005-01-03 devnull for a button 3 action in the body,
363 058b0118 2005-01-03 devnull for a button 3 action in the tag,
365 058b0118 2005-01-03 devnull for a button 2 action in the body, and
367 058b0118 2005-01-03 devnull for a button 2 action in the tag.
369 058b0118 2005-01-03 devnull If the relevant text has less than 256 characters, it is included in the message;
370 058b0118 2005-01-03 devnull otherwise it is elided, the fourth number is 0, and the program must read
371 058b0118 2005-01-03 devnull it from the
373 058b0118 2005-01-03 devnull file if needed. No text is sent on a
377 058b0118 2005-01-03 devnull message.
385 058b0118 2005-01-03 devnull the flag is always zero.
390 058b0118 2005-01-03 devnull the flag is a bitwise OR (reported decimally) of the following:
391 058b0118 2005-01-03 devnull 1 if the text indicated is recognized as an
393 058b0118 2005-01-03 devnull built-in command;
394 058b0118 2005-01-03 devnull 2 if the text indicated is a null string that has a non-null expansion;
395 058b0118 2005-01-03 devnull if so, another complete message will follow describing the expansion
396 058b0118 2005-01-03 devnull exactly as if it had been indicated explicitly (its flag will always be 0);
397 058b0118 2005-01-03 devnull 8 if the command has an extra (chorded) argument; if so,
398 058b0118 2005-01-03 devnull two more complete messages will follow reporting the argument (with
399 058b0118 2005-01-03 devnull all numbers 0 except the character count) and where it originated, in the form of
400 058b0118 2005-01-03 devnull a fully-qualified button 3 style address.
406 058b0118 2005-01-03 devnull the flag is the bitwise OR of the following:
409 058b0118 2005-01-03 devnull can interpret the action without loading a new file;
410 058b0118 2005-01-03 devnull 2 if a second (post-expansion) message follows, analogous to that with
412 058b0118 2005-01-03 devnull messages;
413 058b0118 2005-01-03 devnull 4 if the text is a file or window name (perhaps with address) rather than
414 058b0118 2005-01-03 devnull plain literal text.
416 058b0118 2005-01-03 devnull For messages with the 1 bit on in the flag,
417 058b0118 2005-01-03 devnull writing the message back to the
418 058b0118 2005-01-03 devnull .B event
419 058b0118 2005-01-03 devnull file, but with the flag, count, and text omitted,
420 058b0118 2005-01-03 devnull will cause the action to be applied to the file exactly as it would
421 058b0118 2005-01-03 devnull have been if the
422 058b0118 2005-01-03 devnull .B event
423 058b0118 2005-01-03 devnull file had not been open.
426 058b0118 2005-01-03 devnull holds contents of the window tag. It may be read at any byte offset.
427 058b0118 2005-01-03 devnull Text written to
429 058b0118 2005-01-03 devnull is always appended; the file offset is ignored.
431 9d01e221 2005-01-30 devnull .B xdata
433 9d01e221 2005-01-30 devnull .B xdata
434 9d01e221 2005-01-30 devnull file like
436 9d01e221 2005-01-30 devnull except that reads stop at the end address.
437 058b0118 2005-01-03 devnull .SH SOURCE
438 c3674de4 2005-01-11 devnull .B \*9/src/cmd/acme
439 058b0118 2005-01-03 devnull .SH SEE ALSO
440 d32deab1 2020-08-16 rsc .MR rio (1) ,
441 d32deab1 2020-08-16 rsc .MR acme (1)
