--- rxvt-unicode/doc/rxvt.1.txt 2005/02/14 18:50:57 1.15 +++ rxvt-unicode/doc/rxvt.1.txt 2006/01/02 20:35:39 1.31 @@ -6,7 +6,7 @@ rxvt [options] [-e command [ args ]] DESCRIPTION - rxvt-unicode, version 5.1, is a colour vt102 terminal emulator intended + rxvt-unicode, version 6.2, 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 @@ -95,19 +95,27 @@ -j|+j Turn on/off jump scrolling; resource jumpScroll. - -ip|+ip + -ip|+ip | -tr|+tr Turn on/off inheriting parent window's pixmap. Alternative form is -tr; resource inheritPixmap. -fade *number* - Fade the text by the given percentage when focus is lost. resource - fading. + Fade the text by the given percentage when focus is lost. Small + values fade a little only, 100 completely replaces all colours by + the fade colour; resource fading. + + -fadecolor *colour* + Fade to this colour when fading is used (see -fade). The default + colour is black. resource fadeColor. -tint *colour* Tint the transparent background pixmap with the given colour when - transparency is enabled with -tr or -ip. See also the -sh option - that can be used to brighten or darken the image in addition to - tinting it. + transparency is enabled with -tr or -ip. This only works for + non-tiled backgrounds, currently. See also the -sh option that can + be used to brighten or darken the image in addition to tinting it; + resource *tintColor*. Example: + + rxvt -tr -tint blue -sh 40 -sh *number* Darken (0 .. 100) or lighten (-1 .. -100) the transparent background image in addition to tinting it (i.e. -tint must be @@ -169,6 +177,11 @@ characters are to be printed. See resource boldItalicFont for details. + -is|+is + Compile font-styles: Bold/Italic font styles imply high intensity + foreground/background (default). See resource intensityStyles for + details. + -name *name* Specify the application name under which resources are to be obtained, rather than the default executable file name. Name should @@ -206,7 +219,7 @@ Put scrollbar on right/left; resource scrollBar_right. -st|+st - Display normal (non XTerm/NeXT) scrollbar without/with a trough; + Display rxvt (non XTerm/NeXT) scrollbar without/with a trough; resource scrollBar_floating. -ptab|+ptab @@ -261,6 +274,12 @@ run the program specified by the SHELL environment variable or, failing that, *sh(1)*. + Please note that you must specify a program with arguments. If you + want to run shell commands, you have to specify the shell, like + this: + + rxvt -e sh -c "shell commands" + -title *text* Window title (-T still respected); the default title is the basename of the program specified after the -e option, if any, otherwise the @@ -313,10 +332,16 @@ Turn on/off secondary screen scroll (default enabled); resource secondaryScroll. - -keysym.*sym*: *string* + -hold|+hold + Turn on/off hold window after exit support. If enabled, rxvt will + not immediately destroy its window when the program executed within + it exits. Instead, it will wait till it is being killed or closed by + the user; resource hold. + + -keysym.*sym* *string* Remap a key symbol. See resource keysym. - -embed: *windowid* + -embed *windowid* Tells rxvt to embed it's windows into an already-existing window, which enables applications to easily embed a terminal. @@ -333,6 +358,44 @@ terminal. This works regardless of wether the "-embed" option was used or not. + Here is a short Gtk2-perl snippet that illustrates how this option + can be used (a longer example is in doc/embed): + + my $rxvt = new Gtk2::Socket; + $rxvt->signal_connect_after (realize => sub { + my $xid = $_[0]->window->get_xid; + system "rxvt -embed $xid &"; + }); + + -pty-fd *fileno* + 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 + without having to run a program within it. + + If this switch is given, rxvt will not create any utmp/wtmp entries + and will not tinker with pty/tty permissions - you have to do that + yourself if you want that. + + Here is a example in perl that illustrates how this option can be + used (a longer example is in doc/pty-fd): + + use IO::Pty; + use Fcntl; + + my $pty = new IO::Pty; + fcntl $pty, F_SETFD, 0; # clear close-on-exec + system "rxvt -pty-fd " . (fileno $pty) . "&"; + close $pty; + + # now communicate with rxvt + my $slave = $pty->slave; + while (<$slave>) { print $slave "got <$_>\n" } + + -pe *string* + Colon-separated list of perl extension scripts to use in this + terminal instance. See resource perl-ext. + RESOURCES (available also as long-options) Note: `rxvt --help' gives a list of all resources (long options) compiled into your version. @@ -435,10 +498,16 @@ pixmap. fading: *number* - Fade the text by the given percentage when focus is lost. + Fade the text by the given percentage when focus is lost; option + -fade. + + fadeColor: *colour* + Fade to this colour, when fading is used (see fading:). The default + colour is black; option -fadecolor. tintColor: *colour* - Tint the transparent background pixmap with the given colour. + Tint the transparent background pixmap with the given colour; option + -tint. shading: *number* Darken (0 .. 100) or lighten (-1 .. -100) the transparent background @@ -449,7 +518,7 @@ troughColor: *colour* Use the specified colour for the scrollbar's trough area [default - #969696]. Only relevant for normal (non XTerm/NeXT) scrollbar. + #969696]. Only relevant for rxvt (non XTerm/NeXT) scrollbar. borderColor: *colour* The colour of the border around the text area and between the @@ -482,7 +551,7 @@ names that are used in turn when trying to display Unicode characters. The first font defines the cell size for characters; other fonts might be smaller, but not larger. A reasonable default - font list is always appended to it. option -fn. + 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 @@ -538,6 +607,13 @@ If set, but empty, then this specific style is disabled and the normal text font will being used for the given style. + intensityStyles: *boolean* + When font styles are not enabled, or this option is enabled (True, + option -is, the default), bold and italic font styles imply high + intensity foreground/backround colours. Disabling this option + (False, option +is) disables this behaviour, the high intensity + colours are not reachable. + selectstyle: *mode* Set mouse selection style to old which is 2.20, oldword which is xterm style with 2.20 old word selection, or anything else which @@ -545,7 +621,7 @@ scrollstyle: *mode* Set scrollbar style to rxvt, plain, next or xterm. plain is the - author's favourite.. + author's favourite. title: *string* Set window title string, the default title is the command-line @@ -580,6 +656,15 @@ Print to initiate a screen dump to the printer and Ctrl-Print or Shift-Print to include the scrollback as well. + The string will be interpreted as if typed into the shell as-is. + + Example: + + URxvt*print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX) + + This creates a new file in your home directory with the screen + contents everytime you hit "Print". + scrollBar: *boolean* True: enable the scrollbar [default]; option -sb. False: disable the scrollbar; option +sb. @@ -602,8 +687,8 @@ scrollWithBuffer: *boolean* True: scroll with scrollback buffer when tty receives new lines (and - scrollTtyOutput is False); option +sw. False: do not scroll with - scrollback buffer when tty recieves new lines; option -sw. + scrollTtyOutput is False); option -sw. False: do not scroll with + scrollback buffer when tty recieves new lines; option +sw. scrollTtyKeypress: *boolean* True: scroll to bottom when a non-special key is pressed. Special @@ -665,6 +750,8 @@ pointerBlankDelay: *number* Specifies number of seconds before blanking the pointer [default 2]. + Use a large number (e.g. 987654321) to effectively disable the + timeout. backspacekey: *string* The string to send when the backspace key is pressed. If set to DEC @@ -693,7 +780,7 @@ 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. + staying in another locale; option -imlocale. imFont: *fontset* Specify the font-set used for XIM styles "OverTheSpot" or @@ -706,19 +793,22 @@ 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. + 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 could be abused if somebody gets 8-bit-clean access to your display, - whether throuh a mail client displaying mail bodies unfiltered or - though write(1). Therefore, these sequences are disabled by default. - (Note that other terminals, including xterm, have these sequences - enabled by default). You can enable them by setting this boolean - resource or specifying -insecure as an option. At the moment, this - enabled display-answer, locale, findfont, icon label and window - title requests as well as dynamic menubar dispatch. + whether through a mail client displaying mail bodies unfiltered or + through write(1) or any other means. Therefore, these sequences are + disabled by default. (Note that many other terminals, including + xterm, have these sequences enabled by default, which doesn't make + it safer, though). + + You can enable them by setting this boolean resource or specifying + -insecure as an option. At the moment, this enables display-answer, + locale, findfont, icon label and window title requests as well as + dynamic menubar dispatch. modifier: *modifier* Set the key to be interpreted as the Meta key to: alt, meta, hyper, @@ -738,6 +828,12 @@ scrollback buffer and switching to/from the secondary screen will instead scroll the screen up. + hold: *bool* + Turn on/off hold window after exit support. If enabled, rxvt will + not immediately destroy its window when the program executed within + it exits. Instead, it will wait till it is being killed or closed by + the user. + keysym.*sym*: *string* Compile *frills*: Associate *string* with keysym *sym*. The intervening resource name keysym. cannot be omitted. @@ -791,6 +887,25 @@ URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 + 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 + being defined. That means that defining a key map for "a" will + automatically provide definitions for "Meta-a", "Shift-a" and so on, + unless some of those are defined mappings themselves. + + Unfortunately, this will override built-in key mappings. For example + if you overwrite the "Insert" key you will disable rxvt's + "Shift-Insert" mapping. To re-enable that, you can poke "holes" into + the user-defined keymap using the "builtin:" replacement: + + URxvt.keysym.Insert: + URxvt.keysym.S-Insert: builtin: + + The first line defines a mapping for "Insert" and *any* combination + of modifiers. The second line re-establishes the default mapping for + "Shift-Insert". + 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: @@ -804,6 +919,24 @@ URxvt.keysym.M-C-3: command:\033[8;25;80t URxvt.keysym.M-C-4: command:\033[8;48;110t + perl-ext: *string* + Colon-separated list of perl extension scripts to use in this + terminal instance. Each extension is looked up in the library + directories, loaded if necessary, and bound to the current terminal + instance; option -pe. + + perl-eval: *string* + Perl code to be evaluated when all extensions have been registered. + See the rxvtperl(3) manpage. + + perl-lib: *path* + 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-ext/. + + See the rxvtperl(3) manpage. + 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 @@ -839,7 +972,9 @@ Starting a selection while pressing the Meta key (or Meta+Ctrl keys) (Compile: *frills*) will create a rectangular selection instead of a - normal one. + normal one. In this mode, every selected row becomes its own line in + the selection, and trailing whitespace is visually underlined and + removed from the selection. Insertion: Pressing and releasing the Middle mouse button (or Shift-Insert) in @@ -853,7 +988,7 @@ You can, however, switch fonts at runtime using escape sequences (and therefore using the menubar), e.g.: - printf '\e]701;%s\007' "9x15bold,xft:Kochi Gothic" + printf '\e]710;%s\007' "9x15bold,xft:Kochi Gothic" rxvt-unicode will automatically re-apply these fonts to the output so far. @@ -1009,7 +1144,7 @@ RXVT_SOCKET The unix domain socket path used by rxvtc(1) and rxvtd(1). - Default "$HOME/.rxvt-unicode-