From ba19f6b5b46c539f9f2821d351837164b5824f04 Mon Sep 17 00:00:00 2001 From: rsc Date: Mon, 19 Apr 2004 15:51:52 +0000 Subject: some needed manual pages --- man/man1/9term.1 | 285 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 285 insertions(+) create mode 100644 man/man1/9term.1 (limited to 'man/man1/9term.1') diff --git a/man/man1/9term.1 b/man/man1/9term.1 new file mode 100644 index 00000000..932a067e --- /dev/null +++ b/man/man1/9term.1 @@ -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. -- cgit v1.2.3