.TH NILE 1
.SH NAME
nile, label, window, wloc \- window system
.SH SYNOPSIS
.B nile
[
.BI "-i '"cmd '
]
[
.BI "-k '"kbdcmd '
]
[
.B -sm
]
[
.B -f
.I font
]
.PP
.B label
.I name
.PP
.B window
[
.B -m
] [
.B -r
.I minx miny maxx maxy
] [
.B -dx
.I n
] [
.B -dy
.I n
] [
.B -minx
.I n
] [
.B -miny
.I n
] [
.B -maxx
.I n
] [
.B -maxy
.I n
] [
.B -cd
.I dir
] [
.B -hide
] [
.B -scroll
] [
.B -noscroll
] [
.I cmd
.I arg ...
]
.PP
.B wloc
.SH DESCRIPTION
.I Nile
manages asynchronous layers of text, or windows, on a raster display.
It also serves a variety of files for communicating with
and controlling windows; these are discussed in section
.IR rio (4).
.PP
.I Nile
is derived from
.IR rio (1);
the most notable changes are simplified menus on the mouse buttons,
creating new windows by sweeping with button 3 starting anywhere on
the background, and the option of a menuless mode of operation.
.SS Commands
The
.I nile
command starts a new instance of the window system.
Its
.B -i
option names a startup script, which typically contains several
.I window
commands generated by
.IR wloc .
The
.B -k
option causes
.I nile
to run the command
.I kbdcmd
at startup and allow it to provide characters as keyboard input; the
.B keyboard
program described in
.IR bitsyload (1)
is the usual choice.
.PP
The
.B -s
option initializes windows so that text will not scroll;
the default is to scroll.
The
.B -m
option enables a (nearly) menuless mode, described below.
The
.I font
argument names a font used to display text, both in
.IR nile 's
menus
and as a default for any programs running in its windows; it also
establishes the
environment variable
.BR $font .
If
.B -f
is not given,
.I nile
uses the imported value of
.BR $font
if set; otherwise it imports the default font from the underlying graphics
server, usually the terminal's operating system.
.PP
The
.I label
command changes a window's identifying name.
.PP
The
.I window
command creates a window.
By default, it creates a shell window and sizes and places it automatically.
The geometry arguments control the size
.IB ( dx ,
.BR dy )
and placement
.RB ( minx ,
.BR miny ,
.BR maxx ,
.BR maxy );
the units are pixels with the
upper left corner of the screen at (0, 0).
The
.B hide
option causes the window to be created off-screen.
The
.B scroll
and
.B noscroll
options set the scroll mode.
The
.B cd
option sets the working directory.
The optional command and arguments 
define which program to run in the window.
.PP
By default,
.I window
uses
.B /dev/wctl
(see
.IR rio (4))
to create the window and run the command.  Therefore, the window and command
will be created by
.I nile
and run in a new file name space, just as if the window had been created using the mouse.
However, the
.B -m
option uses the file server properties of
.I nile
to
.B mount
(see
.IR bind (1))
the new window's name space within the name space of the program calling
.IR window .
This means, for example, that running
.B window
in a CPU window will create another window whose command runs on the terminal, where
.I nile
is running; while
.B window
.B -m
will create another window whose command runs on the CPU server.
.PP
The
.I wloc
command prints the coordinates and label of each window in its instance of
.I nile
and is used to construct arguments for
.IR window .
.SS Window control
Each window behaves as a separate terminal with at least one process
associated with it.
When a window is created, a new process (usually a shell; see
.IR rc (1))
is established and bound to the window as a new process group.
Initially, each window acts as a simple terminal that displays character text;
the standard input and output of its processes
are attached to
.BR /dev/cons .
Other special files, accessible to the processes running in a window,
may be used to make the window a more general display.
Some of these are mentioned here; the complete set is
discussed in
.IR rio (4).
.PP
One window is
.IR current ,
and is indicated with a dark border and higher-contrast text;
characters typed on the keyboard are available in the
.B /dev/cons
file of the process in the current window.
Characters written on
.B /dev/cons
appear asynchronously in the associated window whether or not the window
is current.
.PP
Windows are created, deleted and rearranged using the mouse.
Clicking (pressing and releasing) mouse button 1 in a non-current
window makes that window current and brings it in front of
any windows that happen to be overlapping it.
When the mouse cursor points to the background area, pressing
mouse button 3 begins the process of sweeping out a new window.
Press button 3 where one corner of the new rectangle should
appear, and move the mouse, while holding down button 3, to the
diagonally opposite corner. The cursor will change to a cross
during this process.
Releasing button 3 creates the window, and makes it current.
Very small windows may not be created.
When the mouse cursor is in a window that has not claimed the
mouse for its own use, pressing mouse button 3 activates a
menu of window operations provided by
.IR nile .
Releasing button 3 then selects an operation.
.TF Delete
.TP
.B Delete
Delete a window. The cursor will change to a gunsight; click with
button 3 in the window to be deleted, or on the background to
dismiss the action without deleting a window.
Deleting a window causes a
.L hangup
note to be sent to all processes in the window's process group
(see
.IR notify (2)).
.TP
.B Hide
Hide a window.  The cursor will change to a gunsight; click with
button 3 in a window to move it off-screen, or on the background to
dismiss the action without hiding a window.
Each hidden window is given a menu entry in the button 1 menu
(described below) according to the value of the file
.BR /dev/label ,
which
.I nile
maintains
(see
.IR rio (4)).
.TP
.B Exit
Immediately exit
.IR nile ;
no confirmation is asked for.
.PD
.PP
Windows may be rearranged by dragging their borders.
Pressing button 1 or 2 over a window's border allows one to
move the corresponding edge or corner, while button 3
moves the whole window.
.PP
.I Nile
maintains a list of hidden windows. Commands in these windows
execute normally, but they are not visible on the screen. Pressing
and holding button 1 on the background will display the current list
of hidden windows; release button 1 on an item to make it visible.
.SS Text windows
Characters typed on the keyboard or written to
.B /dev/cons
collect in the window to form
a long, continuous document.
.PP
There is always some
.I selected
.IR text ,
a contiguous string marked on the screen by reversing its color.
If the selected text is a null string, it is indicated by a hairline cursor
between two characters.
The selected text
may be edited by mousing and typing.
Text is selected by pointing and clicking button 1
to make a null-string selection, or by pointing,
then sweeping with button 1 pressed.
Text may also be selected by double-clicking:
just inside a matched delimiter-pair
with one of
.B {[(<«`'"
on the left and
.B }])>»`'"
on the right, it selects all text within
the pair; at the beginning
or end of a line, it selects the line; within or at the edge of an alphanumeric word,
it selects the word.
.PP
Characters typed on the keyboard replace the selected text;
if this text is not empty, it is placed in a
.I snarf buffer
common to all windows but distinct from that of
.IR sam (1).
.PP
Programs access the text in the window at a single point
maintained automatically by
.IR nile .
The
.I output point
is the location in the text where the next character written by
a program to
.B /dev/cons
will appear; afterwards, the output point is the null string
beyond the new character.
The output point is also the location in the text of the next character
that will be read (directly from the text in the window,
not from an intervening buffer)
by a program from
.BR /dev/cons .
When such a read will occur is, however, under control of
.I nile
and the user.
.PP
In general there is text in the window after the output point,
usually placed there by typing but occasionally by the editing
operations described below.
A pending read of
.B /dev/cons
will block until the text after the output point contains
a newline, whereupon the read may
acquire the text, up to and including the newline.
After the read, as described above, the output point will be at
the beginning of the next line of text.
In normal circumstances, therefore, typed text is delivered
to programs a line at a time.
Changes made by typing or editing before the text is read will not
be seen by the program reading it.
If the program in the window does not read the terminal,
for example if it is a long-running computation, there may
accumulate multiple lines of text after the output point;
changes made to all this text will be seen when the text
is eventually read.
This means, for example, that one may edit out newlines in
unread text to forestall the associated text being read when
the program finishes computing.
This behavior is very different from most systems.
.PP
Even when there are newlines in the output text,
.I nile
will not honor reads if the window is in
.I hold
.IR mode ,
which is indicated by a white cursor and blue text and border.
The ESC character toggles hold mode.
Some programs, such as
.IR mail (1),
automatically turn on hold mode to simplify the editing of multi-line text;
type ESC when done to allow
.I mail
to read the text.
.PP
An EOT character (control-D) behaves exactly like newline except
that it is not delivered to a program when read.
Thus on an empty line an EOT serves to deliver an end-of-file indication:
the read will return zero characters.
Like newlines, unread EOTs may be successfully edited out of the text.
The BS character (control-H) erases the character before the selected text.
The ETB character (control-W) erases any nonalphanumeric characters, then
the alphanumeric word just before the selected text.
`Alphanumeric' here means non-blanks and non-punctuation.
The NAK character (control-U) erases the text after the output point,
and not yet read by a program, but not more than one line.
All these characters are typed on the keyboard and hence replace
the selected text; for example, typing a BS with a word selected
places the word in the snarf buffer, removes it from the screen,
and erases the character before the word.
.PP
An ACK character (control-F) or Insert character triggers file name completion
for the preceding string (see
.IR complete (2)).
.PP
Typing a left or right arrow moves the cursor one character in that direction.
Typing an SOH character (control-A) moves the cursor to the beginning of the
current line; an ENQ character (control-E) moves to the end.
.PP
Text may be moved vertically within the window.
A scroll bar on the left of the window shows in its clear portion what fragment of the
total output text is visible on the screen, and in its gray part what
is above or below view;
it measures characters, not lines.
Mousing inside the scroll bar moves text:
clicking button 1 with the mouse pointing inside the scroll bar
brings the line at the top of the
window to the cursor's vertical location;
button 3 takes the line at the cursor to the top of the window;
button 2, treating the scroll bar as a ruler, jumps to the indicated portion
of the stored text.
Holding a button pressed in the scroll bar will cause the text
to scroll continuously until the button is released.
Also, a page down
or down-arrow
scrolls forward
half a window, and page up or up-arrow scrolls back.
Typing the home key scrolls to the top of the window; typing the end key scrolls
to the bottom.
.PP
The DEL character sends an
.L interrupt
note to all processes in the window's process group.
Unlike the other characters, the DEL, VIEW, and up- and down-arrow
keys do not affect the selected text.
The left (right) arrow key moves the selection to one character
before (after) the current selection.
.PP
Normally, written output to a window will cause the window to scroll
to the output point if if its not visible; a 
wctl
 message toggles between this behavior and blocking the write.
.PP
Other operations may be selected from a menu on button 2.
The
.B plumb
menu item sends the contents of the selection (not the snarf buffer) to the
.IR plumber (4).
If the selection is empty, it sends the white-space-delimited text
containing the selection (typing cursor).
A typical use of this feature is to tell the editor to find the source of an error
by plumbing the file and line information in a compiler's diagnostic.
.PP
The
.B send
copies the snarf buffer to just after the output point, adding a final newline
if missing.
.B Send
will place text after the output point; the text so placed
will behave exactly as described above.  Therefore when pasting
text containing newlines after the output point, it may be prudent
to turn on hold mode first.
.PP
.B Look
will find the next instance of the selected text (or the text in the snarf
buffer if none is selected) in the window and select it, wrapping around the
buffer if needed.
.SS Menuless operation
When invoked with
.BR -m ,
.I nile
will operate in menuless (sic) mode. In this mode, the behavior of the
mouse buttons in text windows is modified such that button 2 will execute
.I send
and button 3 will execute
.IR plumb ,
as if the button 2 menu items described above had been selected.
Button 2 will also execute
.I send
in the current window, if any, when clicked on the background.
Button 3 on the background will continue to behave as described above.
.PP
In this mode, the
.I look
item from the button 2 menu and all the items on the button 3
menu are not available. The
.I Delete
and
.I Hide
functions are still available via the wctl file (see
.IR rio (4)). A version of
.IR winwatch (1)
exists which adds these window management functions.
.PP
Even in this mode, the list of hidden windows on button 1 is still available
and operates as described above.
.SS Raw text windows
Opening or manipulating certain files served by
.IR nile
suppresses some of the services supplied to ordinary text windows.
While the file
.B /dev/mouse
is open, any mouse operations are the responsibility of another program
running in the window.  Thus,
.I nile
refrains from maintaining
the scroll bar,
supplying text editing or menus, interpreting the
VIEW key as a request to scroll, and also turns scrolling on.
.PP
The file
.B /dev/consctl
controls interpretation of keyboard input.
In particular, a raw mode may be set:
in a raw-input window, no typed keyboard characters are special,
they are not echoed to the screen, and all are passed
to a program immediately upon reading, instead of being gathered into
lines.
.SS Graphics windows
A program that holds
.B /dev/mouse
and
.B /dev/consctl
open after putting the console in raw mode
has complete control of the window:
it interprets all mouse events, gets all keyboard characters,
and determines what appears on the screen.
.SH FILES
.TF /srv/riowctl.\fIuser\fP.\fIpid\fP
.TP
.B /lib/font/bit/*
font directories
.TP
.B /mnt/wsys
Files served by
.I nile
(also unioned in
.B /dev
in a window's name space, before the terminal's real
.B /dev
files)
.TP
.B /srv/rio.\fIuser\fP.\fIpid\fP
Server end of
.IR nile .
.TP
.B /srv/riowctl.\fIuser\fP.\fIpid\fP
Named pipe for
.I wctl
messages.
.SH SOURCE
.TF /usr/a/src/cmd/nile
.TP
.B /usr/a/src/cmd/nile
.TP
.B /rc/bin/label
.TP
.B /rc/bin/window
.TP
.B /rc/bin/wloc
.SH "SEE ALSO"
.IR rio (4),
.IR rc (1),
.IR cpu (1),
.IR sam (1),
.IR mail (1),
.IR proof (1),
.IR graphics (2),
.IR frame (2),
.IR window (2),
.IR notify (2),
.IR cons (3),
.IR draw (3),
.IR mouse (3),
.IR keyboard (6)
.SH BUGS
.I Nile
is derrived from 
.IR rio (1);
some traces of the former name remain, to keep diffs clean. Most of these are
in function names, but the names of the files in
.B /srv
still reflect the former name. Fixing this would also involve changing
.B /rc/bin/window
and any other scripts that mount the file system directly.
.PP
The
.I look
menu item is currently a no-op.
.PP
The standard input of
.I window
is redirected to the newly created window, so there is no way to pipe the output
of a program to the standard input of the new window.
In some cases,
.IR plumb (1)
can be used to work around this limitation.