o5r/plan9port
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

some needed manual pages

Browse source
This commit is contained in:
rsc 2004-04-19 15:51:52 +00:00
parent 2b522d7aaa
commit ba19f6b5b4
2 changed files with 442 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

285
man/man1/9term.1 Normal file
View file

@ -0,0 +1,285 @@
.TH 9TERM 1
.SH NAME
9term, label \- terminal windows
.SH SYNOPSIS
.B 9term
[
.B -as
]
[
.B -f
.I font
]
[
.I cmd
...
]
.PP
.B label
.I name
.SH DESCRIPTION
.I 9term
is a terminal window program for the X Window System,
providing an interface similar to that used on Plan 9.
.SS Commands
The
.I 9term
command starts a new window.
.PP
The
.B -a
flag causes button 2 to send the selection immediately, like acme.
Otherwise button 2 brings up a menu, described below.
.PP
The
.B -s
option initializes windows so that text scrolls;
the default is not to scroll.
.PP
The
.I font
argument to
.B -f
names a font used to display text, both in
.IR 9term '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 9term
uses the imported value of
.B $font
if set; otherwise it uses the graphics system default.
.PP
.I 9term
runs the given command in the window, or
.B $SHELL
if no command is given.
.PP
The
.I label
command changes a window's identifying name by
echoing a special control code that both
.I 9term
and
.IR xterm (1)
understand.
.SS Text windows
Characters typed on the keyboard
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 9term .
The
.I output point
is the location in the text where the next character written by
a program to the terminal
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.
Since Unix does not make it possible to know when a program
is reading the terminal, lines are sent as they are completed
(when the user types a newline character).
.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 the terminal
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.
Because of the Unix issues mentioned above, a line of text is only editable
until it is completed with a newline character, or when hold mode
(see below) is enabled.
.PP
Even when there are newlines in the output text,
.I 9term
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
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 (3)).
.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.
.PP
Typing down-arrow scrolls forward
one third of a window, and up-arrow scrolls back.
Typing page-down scrolls forward
two thirds of a window, and page-up scrolls back.
Typing Home scrolls to the top of the window;
typing End scrolls to the end.
.PP
The DEL character sends an
.L interrupt
note to all processes in the window's process group.
Unlike the other characters, the DEL and 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
.I 9term
relies on the kernel's terminal processing to handle
EOT and DEL, so the terminal must be set up with EOT
as the ``eof'' character and DEL as the ``intr'' character.
.PP
Normally, written output to a window blocks when
the text reaches the end of the screen and the terminal
buffer fills;
a button 2 menu item toggles scrolling.
.PP
.I 9term
changes behavior according to
the terminal settings of the running programs.
Most programs run with echo enabled.
In this mode,
.I 9term
display and allows editing of the input.
Some programs, typically those reading passwords,
run with echo disabled.
In this mode,
.I 9term
passes keystrokes through directly, without
echoing them or buffering until a newline character.
These heuristics work well in many cases, but there
are a few common ones where they fall short.
First, programs using the GNU readline library typically
disable terminal echo and perform echoing themselves.
The most common example is the shell
.IR bash (1).
Disabling the use of readline with
.RB `` "set +o emacs" ''
.RI [ sic ]
usually restores the desired behavior.
Second, remote terminal programs such as
.IR ssh (1)
typically run with echo disabled, relying on the
remote system to echo characters as desired.
Plan 9's
.I ssh
has a
.B -C
flag to disable this, leaving the terminal in ``cooked'' mode.
For similar situations on Unix,
.IR 9term 's
button 2 menu has an entry to toggle the forced use of
cooked mode, despite the terminal settings.
In such cases, it is useful to run
.RB `` "stty -echo" ''
on the remote system to avoid seeing your input twice.
.PP
Editing operations are selected from a menu on button 2.
The
.B cut
operation deletes the selected text
from the screen and puts it in the snarf buffer;
.B snarf
copies the selected text to the buffer without deleting it;
.B paste
replaces the selected text with the contents of the buffer;
and
.B send
copies the snarf buffer to just after the output point, adding a final newline
if missing.
.B Paste
will sometimes and
.B send
will always 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
The
.B plumb
menu item sends the contents of the selection (not the snarf buffer) to the
.IR plumber (1).
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.
.SH SOURCE
.B /usr/local/plan9/src/cmd/9term
.SH BUGS
There should be a program to toggle the current window's hold mode.
.PP
Unix makes everything harder.

157
man/man1/rio.1 Normal file
View file

@ -0,0 +1,157 @@
.if t .ds 85 8\(12
.if n .ds 85 8-1/2
.TH RIO 1
.SH NAME
rio \- rio-like Window Manager for X
.SH SYNOPSIS
.B rio
[
.B \-grey
] [
.B \-version
] [
.B \-font
.I fname
] [
.B \-term
.I termprog
] [
.BR exit | restart
]
.SH DESCRIPTION
.I Rio
is a window manager for X which attempts to emulate the window management
policies of Plan 9's
.I rio
window manager.
.PP
The
.B \-grey
option makes the background light grey, as does \*(85.
Use this option for maximum authenticity.
.B \-font
.I fname
sets the font in
.IR rio 's
menu to
.IR fname ,
overriding the default.
.B \-term
.I termprog
specifies an alternative program to run when the
.I New
menu item is selected.
.B \-version
prints the current version on standard error, then exits.
.PP
To make
.I rio
exit, you have to run
.B "rio exit"
on the command line. There is no ``exit'' menu item.
.PP
One window is
.IR current ,
and is indicated with a dark border and 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 or 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 rio .
Releasing button 3 then selects an operation.
At this point, a gunsight or cross cursor indicates that
an operation is pending.
The button 3 menu operations are:
.TF Resize
.TP
.B New
Create a window.
Press button 3 where one corner of the new rectangle should
appear (cross cursor), and move the mouse, while holding down button 3, to the
diagonally opposite corner.
Releasing button 3 creates the window, and makes it current.
Very small windows may not be created.
The new window is created running
.IR termprog ,
by default
.IR 9term (1)
or, if
.I 9term
is not available,
.IR xterm (1).
.TP
.B Resize
Change the size and location of a window.
First click button 3 in the window to be changed
(gunsight cursor).
Then sweep out a window as for the
.B New
operation.
The window is made current.
.TP
.B Move
Move a window to another location.
After pressing and holding button 3 over the window to be moved (gunsight cursor),
indicate the new position by dragging the rectangle to the new location.
The window is made current.
Windows may be moved partially off-screen.
.TP
.B Delete
Delete a window. Click in the window to be deleted (gunsight cursor).
Deleting a window causes a
.L hangup
note to be sent to all processes in the window's process group
(see
.IR notify (3)).
.TP
.B Hide
Hide a window. Click in the window to be hidden (gunsight cursor);
it will be moved off-screen.
Each hidden window is given a menu entry in the button 3 menu
according to its current window system label.
.TP
.I label
Restore a hidden window.
.PD
.PP
Windows may also be arranged 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.
.PD
.SH BUGS
In
Plan 9's
.IR rio ,
clicking button 2 or button 3 to select a window also sends that
event to the window itself. This
.I rio
does not.
.PP
The command-line syntax is non-standard.
.PP
In Plan 9's
.IR rio ,
newly started applications take over the current window.
This
.I rio
starts a new window for each program.
(In X11, it appears to be impossible to know which window
starts a particular program.)
.PP
There is a currently a compiled-in limit of 128 hidden windows.
.SH "SEE ALSO"
.IR 9term (1),
.IR xterm (1).