--- rxvt-unicode/doc/rxvt.1.txt 2005/01/11 02:24:59 1.1 +++ rxvt-unicode/doc/rxvt.1.txt 2005/02/13 08:56:27 1.12 @@ -6,7 +6,7 @@ rxvt [options] [-e command [ args ]] DESCRIPTION - rxvt-unicode, version 4.8, is a colour vt102 terminal emulator intended + rxvt-unicode, version 5.0, is a colour vt102 terminal emulator intended as an *xterm*(1) replacement for users who do not require features such as Tektronix 4014 emulation and toolkit-style configurability. As a result, rxvt-unicode uses much less swap space -- a significant @@ -14,7 +14,9 @@ FREQUENTLY ASKED QUESTIONS See rxvt(7) (try "man 7 rxvt") for a list of frequently asked questions - and answer to them and some common problems. + and answer to them and some common problems. That document is also + accessible on the World-Wide-Web at + . RXVT-UNICODE VS. RXVT Unlike the original rxvt, rxvt-unicode stores all text in Unicode @@ -120,7 +122,7 @@ -pixmap *file[;geom]* Compile *XPM*: Specify XPM file for the background and also optionally specify its scaling with a geometry string. Note you may - need to add quotes to avoid special shell interpretation of the `;' + need to add quotes to avoid special shell interpretation of the ";" in the command-line; resource backgroundPixmap. -cr *colour* @@ -279,10 +281,20 @@ Compile *XIM*: input method name. resource inputMethod. -imlocale *string* - The locale to use for opening the IM. You can use an LC_CTYPE of - e.g. de_DE.UTF-8 for normal text processing but ja_JP.EUC-JP for the - input extension to be able to input japanese characters while - staying in another locale. + The locale to use for opening the IM. You can use an "LC_CTYPE" of + e.g. "de_DE.UTF-8" for normal text processing but "ja_JP.EUC-JP" for + the input extension to be able to input japanese characters while + staying in another locale. resource imLocale. + + -imfont *fontset* + Set the font set to use for the X Input Method, see resource imFont + for more info. + + -tcw + Change the meaning of triple-click selection with the left mouse + button. Instead of selecting a full line it will extend the + selection the end of the logical line only. resource + tripleclickwords. -insecure Enable "insecure" mode, which currently enables most of the escape @@ -301,6 +313,9 @@ Turn on/off secondary screen scroll (default enabled); resource secondaryScroll. + -keysym.*sym*: *string* + Remap a key symbol. See resource keysym. + -xrm *resourcestring* No effect on rxvt-unicode. Simply passes through an argument to be made available in the instance's argument list. Appears in @@ -314,8 +329,15 @@ data: using the X libraries (Xrm*-functions) or internal Xresources reader (~/.Xdefaults). For the first method (ie. rxvt -h lists XGetDefaults), you can set and change the resources using X11 tools like - xset. Many distribution do also load settings from the ~/.Xresources - file when X starts. + xrdb. Many distribution do also load settings from the ~/.Xresources + file when X starts. rxvt will consult the following files/resources in + order, with later settings overwriting earlier ones: + + 1. system-wide app-defaults file, either locale-dependent OR global + 2. app-defaults file in $XAPPLRESDIR + 3. RESOURCE_MANAGER property on root-window OR $HOME/.Xdefaults + 4. SCREEN_RESOURCES for the current screen + 5. $XENVIRONMENT file OR $HOME/.Xdefaults- If compiled with internal Xresources support (i.e. rxvt -h lists .Xdefaults) then rxvt accepts application defaults set in @@ -361,7 +383,7 @@ colorIT: *colour* Use the specified colour to display bold or italic characters when the foreground colour is the default. If font styles are not - available (Compile styles) and this option is unset, reverse video + available (Compile *styles*) and this option is unset, reverse video is used instead. colorUL: *colour* @@ -451,7 +473,7 @@ font list is always appended to it. option -fn. Each font can either be a standard X11 core font (XLFD) name, with - optional prefix "x:" or a Xft font (Compile xft), prefixed with + optional prefix "x:" or a Xft font (Compile *xft*), prefixed with "xft:". In addition, each font can be prefixed with additional hints and @@ -656,11 +678,24 @@ *name* of inputMethod to use; option -im. imLocale: *name* - The locale to use for opening the IM. You can use an LC_CTYPE of - e.g. de_DE.UTF-8 for normal text processing but ja_JP.EUC-JP for the - input extension to be able to input japanese characters while + The locale to use for opening the IM. You can use an "LC_CTYPE" of + e.g. "de_DE.UTF-8" for normal text processing but "ja_JP.EUC-JP" for + the input extension to be able to input japanese characters while staying in another locale. option -imlocale. + imFont: *fontset* + Specify the font-set used for XIM styles "OverTheSpot" or + "OffTheSpot". It must be a standard X font set (XLFD patterns + separated by commas), i.e. it's not in the same format as the other + font lists used in rxvt. The default will be set-up to chose *any* + suitable found found, preferably one or two pixels differing in size + to the base font. option -imfont. + + tripleclickwords: *boolean* + Change the meaning of triple-click selection with the left mouse + button. Instead of selecting a full line it will extend the + selection to the end of the logical line only. option -tcw. + insecure: *boolean* Enables "insecure" mode. Rxvt-unicode offers some escape sequences that echo arbitrary strings like the icon name or the locale. This @@ -692,13 +727,70 @@ instead scroll the screen up. keysym.*sym*: *string* - Associate *string* with keysym *sym* (0xFF00 - 0xFFFF). It may - contain escape values (\a: bell, \b: backspace, \e, \E: escape, \n: - newline, \r: return, \t: tab, \000: octal number) or control - characters (^?: delete, ^@: null, ^A ...) and may enclosed with - double quotes so that it can start or end with whitespace. The - intervening resource name keysym. cannot be omitted. This resource - is only available when compiled with KEYSYM_RESOURCE. + Compile *frills*: Associate *string* with keysym *sym*. The + intervening resource name keysym. cannot be omitted. + + The format of *sym* is "*(modifiers-)key*", where *modifiers* can be + any combination of ISOLevel3, AppKeypad, Control, NumLock, Shift, + Meta, Lock, Mod1, Mod2, Mod3, Mod4, Mod5, and the abbreviated I, K, + C, N, S, M, A, L, 1, 2, 3, 4, 5. + + The NumLock, Meta and ISOLevel3 modifiers are usually aliased to + whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 + Shift/AltGr keys are being mapped. AppKeypad is a synthetic modifier + mapped to the current application keymap mode state. + + The spellings of *key* can be obtained by using xev(1) command or + searching keysym macros from /usr/X11R6/include/X11/keysymdef.h and + omitting the prefix XK_. Alternatively you can specify *key* by its + hex keysym value (0x0000 - 0xFFFF). Note that the lookup of *sym*s + is not performed in an exact manner; however, the closest match is + assured. + + *string* may contain escape values ("\a": bell, "\b": backspace, + "\e", "\E": escape, "\n": newline, "\r": carriage return, "\t": tab, + "\000": octal number) or verbatim control characters ("^?": delete, + "^@": null, "^A" ...) and may be enclosed with double quotes so that + it can start or end with whitespace. + + Please note that you need to double the "\" when using + "--enable-xgetdefault", as X itself does it's own de-escaping (you + can use "\033" instead of "\e" (and so on), which will work with + both Xt and rxvt's own processing). + + You can define a range of keysyms in one shot by providing a + *string* with pattern list/PREFIX/MIDDLE/SUFFIX, where the delimeter + `/' should be a character not used by the strings. + + Its usage can be demonstrated by an example: + + URxvt.keysym.M-C-0x61: list|\033 + + The above line is equivalent to the following three lines: + + URxvt.keysym.Meta-Control-0x61: \033 + URxvt.keysym.Meta-Control-0x62: \033 + URxvt.keysym.Meta-Control-0x63: \033 + + If *string* takes the form of "command:STRING", the specified STRING + is interpreted and executed as rxvt's control sequence. For example + the following means "change the current locale to "zh_CN.GBK" when + Control-Meta-c is being pressed": + + URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 + + The following example will map Control-Meta-1 and Control-Meta-2 to + the fonts "suxuseuro" and "9x15bold", so you can have some limited + font-switching at runtime: + + URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007 + URxvt.keysym.M-C-2: command:\033]50;9x15bold\007 + + Other things are possible, e.g. resizing (see rxvt(7) for more + info): + + URxvt.keysym.M-C-3: command:\033[8;25;80t + URxvt.keysym.M-C-4: command:\033[8;48;110t THE SCROLLBAR Lines of text that scroll off the top of the rxvt window (resource: @@ -718,9 +810,9 @@ If mouse reporting mode is active, the normal scrollbar actions are disabled -- on the assumption that we are using a fullscreen - application. Instead, pressing Button1 and Button3 sends ESC[6~ (Next) - and ESC[5~ (Prior), respectively. Similarly, clicking on the up and down - arrows sends ESC[A (Up) and ESC[B (Down), respectively. + application. Instead, pressing Button1 and Button3 sends ESC [ 6 ~ + (Next) and ESC [ 5 ~ (Prior), respectively. Similarly, clicking on the + up and down arrows sends ESC [ A (Up) and ESC [ B (Down), respectively. TEXT SELECTION AND INSERTION The behaviour of text selection and insertion mechanism is similar to @@ -730,10 +822,11 @@ Left click at the beginning of the region, drag to the end of the region and release; Right click to extend the marked region; Left double-click to select a word; Left triple-click to select the - entire line. + entire logical line (which can span multiple screen lines), unless + modified by resource tripleclickwords. Starting a selection while pressing the Meta key (or Meta+Ctrl keys) - (Compile: frills) will create a rectangular selection instead of a + (Compile: *frills*) will create a rectangular selection instead of a normal one. Insertion: @@ -760,7 +853,7 @@ the rest is available when rxvt-unicode was compiled with "--enable-iso14755". - 5.1: Basic method + * 5.1: Basic method This allows you to enter unicode characters using their hexcode. Start by pressing and holding both "Control" and "Shift", then enter @@ -776,7 +869,7 @@ easily by pressing "Control" and "Shift", followed by "6-7-1-D-SPACE-6-5-E-5", followed by releasing the modifier keys. - 5.2: Keyboard symbols entry method + * 5.2: Keyboard symbols entry method This mode lets you input characters representing the keycap symbols of your keyboard, if representable in the current locale encoding. @@ -788,12 +881,12 @@ enter the symbol for "ISO Level 2 Switch", although your intention might have been to enter a reverse tab (Shift-Tab). - 5.3: Screen-selection entry method + * 5.3: Screen-selection entry method While this is implemented already (it's basically the selection mechanism), it could be extended by displaying a unicode character map. - 5.4: Feedback method for identifying displayed characters for later + * 5.4: Feedback method for identifying displayed characters for later input This method lets you display the unicode character code associated with characters already displayed. @@ -815,7 +908,8 @@ LOGIN STAMP rxvt tries to write an entry into the *utmp*(5) file so that it can be seen via the *who(1)* command, and can accept messages. To allow this - feature, rxvt must be installed setuid root on some systems. + feature, rxvt may need to be installed setuid root on some systems or + setgid to root or to some other group on others. COLORS AND GRAPHICS In addition to the default foreground and background colours, rxvt can @@ -857,16 +951,67 @@ on White. ENVIRONMENT - rxvt sets the environment variables TERM, COLORTERM and COLORFGBG. The - environment variable WINDOWID is set to the X window id number of the - rxvt window and it also uses and sets the environment variable DISPLAY - to specify which display terminal to use. rxvt uses the environment - variables RXVTPATH and PATH to find XPM files. + rxvt sets and/or uses the following environment variables: -FILES - /etc/utmp - System file for login records. + TERM + Normally set to "rxvt-unicode", unless overwritten at configure + time, via resources or on the commandline. + + COLORTERM + Either "rxvt", "rxvt-xpm", depending on wether rxvt was compiled + with XPM support, and optionally with the added extension "-mono" to + indicate that rxvt-unicode runs on a monochrome screen. + + COLORFGBG + Set to a string of the form "fg;bg" or "fg;xpm;bg", where "fg" is + the colour code used as default foreground/text colour (or the + string "default" to indicate that the default-colour escape sequence + is to be used), "bg" is the colour code used as default background + colour (or the string "default"), and "xpm" is the string "default" + if rxvt was compiled with XPM support. Libraries like "ncurses" and + "slang" can (and do) use this information to optimize screen output. + + WINDOWID + Set to the (decimal) X Window ID of the rxvt window (the toplevel + window, which usually has subwindows for the scrollbar, the terminal + window and so on). + + TERMINFO + Set to the terminfo directory iff rxvt was configured with + "--with-terminfo=PATH". + + DISPLAY + Used by rxvt to connect to the display and set to the correct + display in it's child processes. + + SHELL + The shell to be used for command execution, defaults to "/bin/sh". + + RXVTPATH + The path where rxvt looks for support files such as menu and xpm + files. + + PATH + Used in the same way as "RXVTPATH". + + RXVT_SOCKET + The unix domain socket path used by rxvtc(1) and rxvtd(1). + + Default "$HOME/.rxvt-unicode- AUTHORS