--- rxvt-unicode/doc/rxvt.1.txt 2006/01/02 19:36:07 1.30 +++ rxvt-unicode/doc/rxvt.1.txt 2006/01/12 05:37:34 1.43 @@ -6,7 +6,7 @@ rxvt [options] [-e command [ args ]] DESCRIPTION - rxvt-unicode, version 6.2, is a colour vt102 terminal emulator intended + rxvt-unicode, version 7.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 @@ -165,20 +165,20 @@ FAQ section of rxvt(7). -fb *fontlist* - Compile font-styles: The bold font list to use when bold characters - are to be printed. See resource boldFont for details. + Compile *font-styles*: The bold font list to use when bold + characters are to be printed. See resource boldFont for details. -fi *fontlist* - Compile font-styles: The italic font list to use when bold + Compile *font-styles*: The italic font list to use when *italic* characters are to be printed. See resource italicFont for details. -fbi *fontlist* - Compile font-styles: The bold italic font list to use when bold - characters are to be printed. See resource boldItalicFont for - details. + Compile *font-styles*: The bold italic font list to use when *bold + italic* characters are to be printed. See resource boldItalicFont + for details. -is|+is - Compile font-styles: Bold/Italic font styles imply high intensity + Compile *font-styles*: Bold/Italic font styles imply high intensity foreground/background (default). See resource intensityStyles for details. @@ -254,6 +254,12 @@ if honoured by the WM, the rxvt-unicode window will not have window decorations; resource borderLess. + -sbg + Compile *frills*: Disable the usage of the built-in block + graphics/line drawing characters and just rely on what the specified + fonts provide. Use this if you have a good font and want to use its + block graphic glyphs; resource skipBuiltinGlyphs. + -lsp *number* Compile *frills*: Lines (pixel height) to insert between each row of the display. Useful to work around font rendering problems; resource @@ -367,7 +373,7 @@ system "rxvt -embed $xid &"; }); - -pty-fd *fileno* + -pty-fd *file descriptor* Tells rxvt NOT to execute any commands or create a new pty/tty pair but instead use the given filehandle as the tty master. This is useful if you want to drive rxvt as a generic terminal emulator @@ -377,6 +383,9 @@ and will not tinker with pty/tty permissions - you have to do that yourself if you want that. + As an extremely special case, specifying -1 will completely suppress + pty/tty operations. + Here is a example in perl that illustrates how this option can be used (a longer example is in doc/pty-fd): @@ -392,20 +401,18 @@ my $slave = $pty->slave; while (<$slave>) { print $slave "got <$_>\n" } - -perl *string* - Used by perl extension. See resource perl. + -pe *string* + Comma-separated list of perl extension scripts to use (or not to + use) in this terminal instance. See resource perl-ext for details. RESOURCES (available also as long-options) Note: `rxvt --help' gives a list of all resources (long options) compiled into your version. - There are two different methods that rxvt can use to get the Xresource - 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 - 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: + You can set and change the resources using X11 tools like 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 @@ -413,18 +420,15 @@ 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 - XAPPLOADDIR/URxvt (compile-time defined: usually - /usr/lib/X11/app-defaults/URxvt) and resources set in ~/.Xdefaults, or - ~/.Xresources if ~/.Xdefaults does not exist. Note that when reading X - resources, rxvt recognizes two class names: XTerm and URxvt. The class - name Rxvt allows resources common to both rxvt and the original *rxvt* - to be easily configured, while the class name URxvt allows resources - unique to rxvt, notably colours and key-handling, to be shared between - different rxvt 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: + Note that when reading X resources, rxvt recognizes two class names: + Rxvt and URxvt. The class name Rxvt allows resources common to both rxvt + and the original *rxvt* to be easily configured, while the class name + URxvt allows resources unique to rxvt, to be shared between different + rxvt 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 supported (you might want to check + the rxvtperl(3) manpage for additional settings by perl extensions not + documented here): geometry: *geom* Create the window with the specified X window geometry [default @@ -712,6 +716,12 @@ the WM, the rxvt-unicode window will not have window decorations; option -bl. + skipBuiltinGlyphs: *boolean* + Compile *frills*: Disable the usage of the built-in block + graphics/line drawing characters and just rely on what the specified + fonts provide. Use this if you have a good font and want to use its + block graphic glyphs; option -sbg. + termName: *termname* Specifies the terminal type name to be set in the TERM environment variable; option -tn. @@ -860,10 +870,10 @@ "^@": 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). + Please note that you need to double the "\" in resource files, as + Xlib 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 @@ -886,6 +896,13 @@ URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 + If *string* takes the form "perl:STRING", then the specified STRING + is passed to the "on_keyboard_command" perl handler. See the + rxvtperl(3) manpage. For example, the selection extension (activated + via "rxvt -pe selection") listens for "selection:rot13" events: + + URxvt.keysym.M-C-c: perl:selection:rot13 + Due the the large number of modifier combinations, a defined key mapping will match if at *at least* the specified identifiers are being set, and no other key mappings with those and more bits are @@ -918,22 +935,57 @@ URxvt.keysym.M-C-3: command:\033[8;25;80t URxvt.keysym.M-C-4: command:\033[8;48;110t - perl: *string* - Used by perl extension and is free for any use, as it is not - interpreted by rxvt-unicode itself; option perl. + perl-ext-common: *string* + perl-ext: *string* + Comma-separated list(s) of perl extension scripts (default: + "default") to use in this terminal instance; option -pe. + + Extension names can be prefixed with a "-" sign to prohibit using + them. This can be useful to selectively disable some extensions + loaded by default, or specified via the "perl-ext-common" resource. + For example, "default,-selection" will use all the default extension + except "selection". + + Extension names can also be followed by an argument in angle + brackets (e.g. "searchable-scrollback", which binds the hotkey + for searchable scorllback to Alt/Meta-s). Mentioning the same + extension multiple times with different arguments will pass multiple + arguments to the extension. + + Each extension is looked up in the library directories, loaded if + necessary, and bound to the current terminal instance. + + If both of these resources are the empty string, then the perl + interpreter will not be initialized. The idea behind two options is + that perl-ext-common will be used for extensions that should be + available to all instances, while perl-ext is used for specific + instances. perl-eval: *string* - Perl code to be evaluated when all extensions have been loaded. See - the rxvtperl(3) manpage. + Perl code to be evaluated when all extensions have been registered. + See the rxvtperl(3) manpage. Due to security reasons, this resource + will be ignored when running setuid/setgid. perl-lib: *path* - Additional directory that holds extension scripts that are loaded - and enabled for this terminal instance, in addition to scripts - stored in /opt/rxvt/lib/urxvt/perl-ext/, which are global to all - terminal instances. + Colon-separated list of additional directories that hold extension + scripts. When looking for extensions specified by the "perl" + resource, rxvt will first look in these directories and then in + /opt/rxvt/lib/urxvt/perl/. Due to security reasons, this resource + will be ignored when running setuid/setgid. See the rxvtperl(3) manpage. + searchable-scrollback: *keysym* + Sets the hotkey that starts the incremental scrollback buffer search + (default: "M-s"). + + urlLauncher: *string* + Specifies the program to be started with a URL argument. Used by the + "selection-popup" and "mark-urls" perl extensions. + + transient-for: *windowid* + Sets the WM_TRANSIENT_FOR property to the given window iw. + THE SCROLLBAR Lines of text that scroll off the top of the rxvt window (resource: saveLines) and can be scrolled back using the scrollbar or by