--- rxvt-unicode/doc/rxvt.1.pod 2004/08/12 20:42:12 1.1 +++ rxvt-unicode/doc/rxvt.1.pod 2004/08/14 03:00:32 1.5 @@ -4,31 +4,68 @@ =head1 SYNOPSIS -B<@@RXVTNAME@@> [options] [-e command [ args ]] +B<@@RXVT_NAME@@> [options] [-e command [ args ]] =head1 DESCRIPTION -B, version B<@@RXVTVERSION@@>, is a colour vt102 terminal +B, version B<@@RXVT_VERSION@@>, is a colour vt102 terminal emulator intended as an I(1) replacement for users who do not require features such as Tektronix 4014 emulation and toolkit-style configurability. As a result, B uses much less swap space -- a significant advantage on a machine serving many X sessions. +=head1 RXVT-UNICODE VS. RXVT + +Unlike the original rxvt, B stores all text in Unicode +internally. That means it can store and display most scripts in the +world. Being a terminal emulator, however, some things are very difficult, +especially cursive scripts such as arabic, vertically written scripts +like mongolian or scripts requiring extremely complex combining rules, +like tibetan or devenagari. Don't expect pretty output when using these +scripts. Most other scripts, latin, cyrillic, kanji, thai etc. should work +fine, though. A somewhat difficult case are left-to-right scripts, such +as hebrew: B adopts the view that bidirectional algorithms +belong into the application, not the terminal emulator (too many things -- +such as cursor-movement -- break othwerwise). + +Another design rationale was the use of multiple fonts to display +characters: The idea of a single unicode font which many other programs +force onto it's users never made sense to me: You should be able to choose +any font for any script. + +Apart from that, rxvt-unicode is also much better internationalised than +it's predecessor, supports things such as XFT and ISO 14755 that are handy +in i18n-environments, is faster, and has a lot less bugs than the original +rxvt. This all in addition to dozens of other small improvements. + +It is still faithfully following the original rxvt idea of being lean +and nice on resources: for example, you can still configure rxvt-unicode +without most of it's features to get a lean binary. It also comes with +a client/daemon pair that lets you open any number of terminal windows +from within a single process, which makes startup time very fast and +drastically reduces memory usage. See @@RXVT_NAME@@d(1) (daemon) and +@@RXVT_NAME@@c(1) (client). + +It also makes technical information about escape sequences (which have +been extended) easier accessible: see @@RXVT_NAME@@(7) for technical +reference documentation (escape sequences etc.) and the FAQ section at the +end of this document. + =head1 OPTIONS -The B<@@RXVTNAME@@> options (mostly a subset of I's) are listed +The B<@@RXVT_NAME@@> options (mostly a subset of I's) are listed below. In keeping with the smaller-is-better philosophy, options may be eliminated or default values chosen at compile-time, so options and defaults listed may not accurately reflect the version installed on -your system. `rxvt -h' gives a list of major compile-time options on +your system. `@@RXVT_NAME@@ -h' gives a list of major compile-time options on the I line. Option descriptions may be prefixed with which compile option each is dependent upon. e.g. `Compile I:' requires -I on the I line. Note: `rxvt -help' gives a list of all +I on the I line. Note: `@@RXVT_NAME@@ -help' gives a list of all command-line options compiled into your version. -Note that B<@@RXVTNAME@@> permits the resource name to be used as a +Note that B<@@RXVT_NAME@@> permits the resource name to be used as a long-option (--/++ option) so the potential command-line options are -far greater than those listed. For example: `rxvt --loginShell --color1 +far greater than those listed. For example: `@@RXVT_NAME@@ --loginShell --color1 Orange'. The following options are available: @@ -119,6 +156,9 @@ be smaller, but not larger. A reasonable default font list is always appended to it. resource B. +See also the question "How does rxvt-unicode choose fonts?" in the FAQ +section. + =item B<-rb>|B<+rb> Enable "real bold" support. When this option is on, bold text will be @@ -204,7 +244,7 @@ =item B<-bl> Compile I: Set MWM hints to request a borderless window, i.e. -if honoured by the WM, the rxvt window will not have window +if honoured by the WM, the rxvt-unicode window will not have window decorations; resource B. =item B<-lsp> I @@ -221,7 +261,7 @@ =item B<-e> I -Run the command with its command-line arguments in the B<@@RXVTNAME@@> +Run the command with its command-line arguments in the B<@@RXVT_NAME@@> window; also sets the window title and icon name to be the basename of the program being executed if neither I<-title> (I<-T>) nor I<-n> are given on the command line. If this option is used, it must be the last @@ -285,7 +325,7 @@ =item B<-xrm> I -No effect on rxvt. Simply passes through an argument to be made +No effect on rxvt-unicode. Simply passes through an argument to be made available in the instance's argument list. Appears in I in some window managers. @@ -293,27 +333,27 @@ =head1 RESOURCES (available also as long-options) -Note: `@@RXVTNAME@@ --help' gives a list of all resources (long +Note: `@@RXVT_NAME@@ --help' gives a list of all resources (long options) compiled into your version. -There are two different methods that @@RXVTNAME@@ can use to get the +There are two different methods that @@RXVT_NAME@@ can use to get the Xresource data: using the X libraries (Xrm*-functions) or internal Xresources reader (B<~/.Xdefaults>). For the first method (ie. -B<@@RXVTNAME@@ -h> lists B), you can set and change the +B<@@RXVT_NAME@@ -h> lists B), you can set and change the resources using X11 tools like B. Many distribution do also load settings from the B<~/.Xresources> file when X starts. -If compiled with internal Xresources support (i.e. B<@@RXVTNAME@@ -h> -lists B<.Xdefaults>) then B<@@RXVTNAME@@> accepts application defaults +If compiled with internal Xresources support (i.e. B<@@RXVT_NAME@@ -h> +lists B<.Xdefaults>) then B<@@RXVT_NAME@@> accepts application defaults set in XAPPLOADDIR/URxvt (compile-time defined: usually B) and resources set in B<~/.Xdefaults>, or B<~/.Xresources> if B<~/.Xdefaults> does not exist. -Note that when reading X resources, B<@@RXVTNAME@@> recognizes two +Note that when reading X resources, B<@@RXVT_NAME@@> recognizes two class names: B and B. The class name B allows -resources common to both B<@@RXVTNAME@@> and the original I to be +resources common to both B<@@RXVT_NAME@@> and the original I to be easily configured, while the class name B allows resources -unique to B<@@RXVTNAME@@>, notably colours and key-handling, to be -shared between different B<@@RXVTNAME@@> configurations. If no +unique to B<@@RXVT_NAME@@>, notably colours and key-handling, to be +shared between different B<@@RXVT_NAME@@> configurations. If no resources are specified, suitable defaults will be used. Command-line arguments can be used to override resource settings. The following resources are allowed: @@ -464,8 +504,8 @@ =item B I -Set scrollbar style to B<@@RXVTNAME@@>, B, B, B or -B +Set scrollbar style to B, B, B or B. B is +the author's favourite.. =item B I @@ -529,9 +569,9 @@ =item B I -B: scroll to bottom when tty receives output; option B<+si>. +B: scroll to bottom when tty receives output; option B<-si>. B: do not scroll to bottom when tty receives output; option -B<-si>. +B<+si>. =item B I @@ -541,10 +581,10 @@ =item B I -B: scroll to bottom when a non-special key is pressed. Special -keys are those which are intercepted by rxvt for special handling and -are not passed onto the shell; option B<-sk>. B: do not scroll -to bottom when a non-special key is pressed; option B<+sk>. +B: scroll to bottom when a non-special key is pressed. Special keys +are those which are intercepted by rxvt-unicode for special handling and +are not passed onto the shell; option B<-sk>. B: do not scroll to +bottom when a non-special key is pressed; option B<+sk>. =item B I @@ -574,7 +614,7 @@ =item B I Set MWM hints to request a borderless window, i.e. if honoured by the -WM, the rxvt window will not have window decorations; option B<-bl>. +WM, the rxvt-unicode window will not have window decorations; option B<-bl>. =item B I @@ -675,7 +715,7 @@ =item B I -Specify the reply rxvt sends to the shell when an ENQ (control-E) +Specify the reply rxvt-unicode sends to the shell when an ENQ (control-E) character is passed through. It may contain escape values as described in the entry on B following. @@ -705,9 +745,9 @@ =head1 THE SCROLLBAR -Lines of text that scroll off the top of the B<@@RXVTNAME@@> window +Lines of text that scroll off the top of the B<@@RXVT_NAME@@> window (resource: B) and can be scrolled back using the scrollbar -or by keystrokes. The normal B<@@RXVTNAME@@> scrollbar has arrows and +or by keystrokes. The normal B<@@RXVT_NAME@@> scrollbar has arrows and its behaviour is fairly intuitive. The B is without arrows and its behaviour mimics that of I @@ -745,7 +785,7 @@ =item B: Pressing and releasing the Middle mouse button (or B) in -an B<@@RXVTNAME@@> window causes the current text selection to be +an B<@@RXVT_NAME@@> window causes the current text selection to be inserted as if it had been typed on the keyboard. =back @@ -759,17 +799,31 @@ actual key can be selected using resources B/B. +=head1 ISO 14755 SUPPORT + +Partial ISO 14755-support is implemented. that means that pressing + +Section 5.1: Control and Shift together enters unicode input +mode. Entering hex digits composes a Unicode character, pressing space or +releasing the modifiers commits the keycode and every other key cancels +the current input character. + +Section 5.2: Pressing and immediately releasing Control and Shift together +enters keycap entry mode for the next key: pressing a function key (tab, +return etc..) will enter the unicode character corresponding to the given +key. + =head1 LOGIN STAMP -B<@@RXVTNAME@@> tries to write an entry into the I(5) file so +B<@@RXVT_NAME@@> tries to write an entry into the I(5) file so that it can be seen via the I command, and can accept messages. -To allow this feature, B<@@RXVTNAME@@> must be installed setuid root on +To allow this feature, B<@@RXVT_NAME@@> must be installed setuid root on some systems. =head1 COLORS AND GRAPHICS In addition to the default foreground and background colours, -B<@@RXVTNAME@@> can display up to 16 colours (8 ANSI colours plus +B<@@RXVT_NAME@@> can display up to 16 colours (8 ANSI colours plus high-intensity bold/blink versions of the same). Here is a list of the colours with their B names. @@ -808,20 +862,287 @@ =over 4 -=item B +=item B<@@RXVT_NAME@@ -fg Black -bg White -rv> would yield White on Black, while on I(1) it would yield Black on White. =back +=head1 FREQUENTLY ASKED QUESTIONS (FAQ) + +=over 4 + +=item How do I know which rxvt-unicode version I'm using? + +The version number is displayed with the usage (-h). For rxvt-unicode +version 2.14 and later, the escape sequence C sets the window +title to the version number. + +=item Why do the characters look ugly? + +=item How does rxvt-unicode choose fonts? + +Most fonts do not contain the full range of Unicode, which is +fine. Chances are that the font you (or the admin/package maintainer of +your system/os) have specified does not cover all the characters you want +to display. + +B makes a best-effort try at finding a replacement +font. Often the result is fine, but sometimes the chosen font looks +bad. In that case, select a font of your taste and add it to the font +list, e.g.: + + @@RXVT_NAME@@ -fn basefont,font2,font3... + +When rxvt-unicode sees a character, it will first look at the base +font. If the base font does not contain the character, it will go to the +next font, and so on. + +The only limitation is that all the fonts must not be larger than the base +font, as the base font defines the principial cell size, which must be the +same due to the way terminals work. + +=item Why do some chinese characters look so different than others? + +This is because there is a difference between script and language -- +rxvt-unicode does not know which language the text that is output +is, as it only knows the unicode character codes. If rxvt-unicode +first sees a japanese character, it might choose a japanese font for +it. Subseqzuent japanese characters will take that font. Now, many chinese +characters aren't represented in japanese fonts, so when the first +non-japanese character comes up, rxvt-unicode will look for a chinese font +-- unfortunately at this point, it will still use the japanese font for +japanese characters that are also chinese. + +The workaround is easy: just tag a chinese font at the end of your font +list (see the previous question). The key is to view the font list as +a preference list: If you expect more japanese, list a japanese font +first. If you expect more chinese, put a chinese font first. + +In the future it might be possible to switch preferences at runtime (the +internal data structure has no problem with using different fonts for +the same character at the same time, but no interface for this has been +designed yet). + +=item Mouse cut/paste suddenly no longer works. + +Make sure that mouse reporting is actually turned off since killing +some editors prematurely may leave the mouse in mouse report mode. I've +heard that tcsh may use mouse reporting unless it otherwise specified. A +quick check is to see if cut/paste works when the Alt or Shift keys are +depressed. See @@RXVT_NAME@@(7) + +=item What's with this bold/blink stuff? + +If no bold colour is set via C, bold will invert text using the +standard foreground colour. + +For the standard background colour, blinking will actually make the +text blink when compiled with C<--enable-blinking>. with standard +colours. Without C<--enable-blinking>, the blink attribute will be +ignored. + +On ANSI colours, bold/blink attributes are used to set high-intensity +foreground/background colors. + +color0-7 are the low-intensity colors. + +color8-15 are the corresponding high-intensity colors. + +=item I don't like the screen colors. How do I change them? + +You can change the screen colors at run-time using F<~/.Xdefaults> +resources (or as long-options). + +Here are values that are supposed to resemble a VGA screen, +including the murky brown that passes for low-intensity yellow: + + Rxvt*color0: #000000 + Rxvt*color1: #A80000 + Rxvt*color2: #00A800 + Rxvt*color3: #A8A800 + Rxvt*color4: #0000A8 + Rxvt*color5: #A800A8 + Rxvt*color6: #00A8A8 + Rxvt*color7: #A8A8A8 + + Rxvt*color8: #000054 + Rxvt*color9: #FF0054 + Rxvt*color10: #00FF54 + Rxvt*color11: #FFFF54 + Rxvt*color12: #0000FF + Rxvt*color13: #FF00FF + Rxvt*color14: #00FFFF + Rxvt*color15: #FFFFFF + +=item What's with the strange Backspace/Delete key behaviour? + +Assuming that the physical Backspace key corresponds to the +BackSpace keysym (not likely for Linux ... see the following +question) there are two standard values that can be used for +Backspace: C<^H> and C<^?>. + +Historically, either value is correct, but rxvt-unicode adopts the debian +policy of using C<^?> when unsure, because it's the one only only correct +choice :). + +Rxvt-unicode tries to inherit the current stty settings and uses the value +of `erase' to guess the value for backspace. If rxvt-unicode wasn't +started from a terminal (say, from a menu or by remote shell), then the +system value of `erase', which corresponds to CERASE in , will +be used (which may not be the same as your stty setting). + +For starting a new rxvt-unicode: + + # use Backspace = ^H + $ stty erase ^H + $ @@RXVT_NAME@@ + + # use Backspace = ^? + $ stty erase ^? + $ @@RXVT_NAME@@ + +Toggle with "ESC[36h" / "ESC[36l" as documented in @@RXVT_NAME@@(7). + +For an existing rxvt-unicode: + + # use Backspace = ^H + $ stty erase ^H + $ echo -n "^[[36h" + + # use Backspace = ^? + $ stty erase ^? + $ echo -n "^[[36l" + +This helps satisfy some of the Backspace discrepancies that occur, but +if you use Backspace = C<^H>, make sure that the termcap/terminfo value +properly reflects that. + +The Delete key is a another casualty of the ill-defined Backspace problem. +To avoid confusion between the Backspace and Delete keys, the Delete +key has been assigned an escape sequence to match the vt100 for Execute +(ESC[3~) and is in the supplied termcap/terminfo. + +Some other Backspace problems: + +some editors use termcap/terminfo, +some editors (vim I'm told) expect Backspace = ^H, +GNU Emacs (and Emacs-like editors) use ^H for help. + +Perhaps someday this will all be resolved in a consistent manner. + +=item I don't like the key-bindings. How do I change them? + +There are some compile-time selections available via configure. Unless +you have run "configure" with the C<--disable-resources> option you can +use the `keysym' resource to alter the keystrings associated with keysym +0xFF00 - 0xFFFF (function, cursor keys, etc). + +Here's an example for a tn3270 session started using `@@RXVT_NAME@@ -name tn3270' + + !# ----- special uses ------: + ! tn3270 login, remap function and arrow keys. + tn3270*font: *clean-bold-*-*--15-* + + ! keysym - used by rxvt only + ! Delete - ^D + tn3270*keysym.0xFFFF: \004 + + ! Home - ^A + tn3270*keysym.0xFF50: \001 + ! Left - ^B + tn3270*keysym.0xFF51: \002 + ! Up - ^P + tn3270*keysym.0xFF52: \020 + ! Right - ^F + tn3270*keysym.0xFF53: \006 + ! Down - ^N + tn3270*keysym.0xFF54: \016 + ! End - ^E + tn3270*keysym.0xFF57: \005 + + ! F1 - F12 + tn3270*keysym.0xFFBE: \e1 + tn3270*keysym.0xFFBF: \e2 + tn3270*keysym.0xFFC0: \e3 + tn3270*keysym.0xFFC1: \e4 + tn3270*keysym.0xFFC2: \e5 + tn3270*keysym.0xFFC3: \e6 + tn3270*keysym.0xFFC4: \e7 + tn3270*keysym.0xFFC5: \e8 + tn3270*keysym.0xFFC6: \e9 + tn3270*keysym.0xFFC7: \e0 + tn3270*keysym.0xFFC8: \e- + tn3270*keysym.0xFFC9: \e= + + ! map Prior/Next to F7/F8 + tn3270*keysym.0xFF55: \e7 + tn3270*keysym.0xFF56: \e8 + +=item I'm using keyboard model XXX that has extra Prior/Next/Insert keys. +How do I make use of them? For example, the Sun Keyboard type 4 +has the following mappings that rxvt-unicode doesn't recognize. + + KP_Insert == Insert + F22 == Print + F27 == Home + F29 == Prior + F33 == End + F35 == Next + +Rather than have rxvt-unicode try to accomodate all the various possible keyboard +mappings, it is better to use `xmodmap' to remap the keys as required for +your particular machine. + +=item How do I distinguish if I'm running rxvt-unicode or a regular xterm? +I need this to decide about setting colors etc. + +rxvt and rxvt-unicode always export the variable "COLORTERM", so you can +check and see if that is set. Note that several programs, JED, slrn, +Midnight Commander automatically check this variable to decide whether or +not to use color. + +=item How do I set the correct, full IP address for the DISPLAY variable? + +If you've compiled rxvt-unicode with DISPLAY_IS_IP and ahve enabled +insecure mode then it is possible to use the following shell script +snippets to correctly set the display. If your version of rxvt-unicode +wasn't also compiled with ESCZ_ANSWER (as assumed in these snippets) then +the COLORTERM variable can be used to distinguish rxvt-unicode from a +regular xterm. + +Courtesy of Chuck Blake with the following shell script +snippets: + + # Bourne/Korn/POSIX family of shells: + [ ${TERM:-foo} = foo ] && TERM=xterm # assume an xterm if we don't know + if [ ${TERM:-foo} = xterm ]; then + stty -icanon -echo min 0 time 15 # see if enhanced rxvt or not + echo -n '^[Z' + read term_id + stty icanon echo + if [ ""${term_id} = '^[[?1;2C' -a ${DISPLAY:-foo} = foo ]; then + echo -n '^[[7n' # query the rxvt we are in for the DISPLAY string + read DISPLAY # set it in our local shell + fi + fi + +=item How do I compile the manual pages for myself? + +You need to have a recent version of perl installed as F, +one that comes with F, F and F. Then go to +the doc subdirectory and enter C. + +=back + =head1 ENVIRONMENT -B<@@RXVTNAME@@> sets the environment variables B, B +B<@@RXVT_NAME@@> sets the environment variables B, B and B. The environment variable B is set to the X -window id number of the B<@@RXVTNAME@@> window and it also uses and +window id number of the B<@@RXVT_NAME@@> window and it also uses and sets the environment variable B to specify which display -terminal to use. B<@@RXVTNAME@@> uses the environment variables +terminal to use. B<@@RXVT_NAME@@> uses the environment variables B and B to find XPM files. =head1 FILES @@ -838,11 +1159,9 @@ =back -=head1 SEEALSO - -I(1), I(1), I(1), I(1), I(4), I(4), I(5) +=head1 SEE ALSO -See rxvtRef.html rxvtRef.txt for detailed information on recognized escape sequences and menuBar syntax, etc. +@@RXVT_NAME@@(7), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5) =head1 BUGS @@ -852,23 +1171,19 @@ Click-and-drag doesn't work with X11 mouse report overriding. -=head1 FTP LOCATION - -rxvt-+@@RXVTVERSION@@.tar.gz can be found at the following ftp sites L<@@RXVTFTPSITE@@>(@@RXVTFTPSITE@@) - =head1 CURRENT PROJECT COORDINATOR =over 4 =item Project Coordinator -@@RXVTMAINT@@ L<@@RXVTMAINTEMAIL@@> +@@RXVTMAINT@@ L<@@RXVT_MAINTEMAIL@@> =item Web page maintainter -@@RXVTWEBMAINT@@ L<@@RXVTWEBMAINTEMAIL@@> +@@RXVTWEBMAINT@@ L<@@RXVT_WEBMAINTEMAIL@@> -L<@@RXVTWEBPAGE@@>(@@RXVTWEBPAGE@@) +L<@@RXVT_WEBPAGE@@> =back