--- rxvt-unicode/doc/rxvt.1.txt 2005/04/22 02:09:39 1.21 +++ rxvt-unicode/doc/rxvt.1.txt 2006/01/20 22:49:34 1.50 @@ -6,7 +6,7 @@ rxvt [options] [-e command [ args ]] DESCRIPTION - rxvt-unicode, version 5.5, is a colour vt102 terminal emulator intended + rxvt-unicode, version 7.1, 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 @@ -140,7 +148,7 @@ -fn *fontlist* Select the fonts to be used. This is a comma separated list of font - names that are used in turn when trying to display Unicode + names that are checked in order when trying to find glyphs for characters. The first font defines the cell size for characters; other fonts might be smaller, but not (in general) larger. A (hopefully) reasonable default font list is always appended to it. @@ -157,16 +165,21 @@ 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 + 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 + foreground/background (default). See resource intensityStyles for details. -name *name* @@ -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 @@ -241,6 +254,16 @@ if honoured by the WM, the rxvt-unicode window will not have window decorations; resource borderLess. + -override-redirect + Compile *frills*: Sets override-redirect on the window; resource + override-redirect. + + -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 @@ -261,6 +284,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,6 +342,12 @@ Turn on/off secondary screen scroll (default enabled); resource secondaryScroll. + -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. @@ -342,7 +377,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 @@ -352,6 +387,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): @@ -367,17 +405,18 @@ my $slave = $pty->slave; while (<$slave>) { print $slave "got <$_>\n" } + -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 @@ -385,18 +424,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 @@ -469,10 +505,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 @@ -483,7 +525,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 @@ -500,23 +542,16 @@ will be magnified beyond 10 times its original size. The maximum permitted scale is 1000. [default 0x0+50+50] - menu: *file[;tag]* - Read in the specified menu file (note the `.menu' extension is - optional) and also optionally specify a starting tag to find. See - the reference documentation for details on the syntax for the - menuBar. - path: *path* - Specify the colon-delimited search path for finding files (XPM and - menus), in addition to the paths specified by the RXVTPATH and PATH - environment variables. + Specify the colon-delimited search path for finding XPM files. font: *fontlist* Select the fonts to be used. This is a comma separated list of font - names that are used in turn when trying to display Unicode + names that are checked in order when trying to find glyphs for 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. + other fonts might be smaller, but not (in general) larger. A + (hopefully) reasonable default 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 @@ -529,7 +564,7 @@ For example, this font resource - URxvt*font: 9x15bold,\ + URxvt.font: 9x15bold,\ -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso10646-1,\ -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1, \ [codeset=JISX0208]xft:Kochi Gothic:antialias=false, \ @@ -572,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 @@ -579,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 @@ -614,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. @@ -662,6 +713,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. @@ -729,7 +786,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 @@ -742,19 +799,21 @@ 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. modifier: *modifier* Set the key to be interpreted as the Meta key to: alt, meta, hyper, @@ -765,15 +824,21 @@ (control-E) character is passed through. It may contain escape values as described in the entry on keysym following. - secondaryScreen: *bool* + secondaryScreen: *boolean* Turn on/off secondary screen (default enabled). - secondaryScroll: *bool* + secondaryScroll: *boolean* Turn on/off secondary screen scroll (default enabled). If the this option is enabled, scrolls on the secondary screen will change the scrollback buffer and switching to/from the secondary screen will instead scroll the screen up. + hold: *boolean* + 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. @@ -801,10 +866,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 @@ -827,6 +892,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 @@ -859,6 +931,71 @@ URxvt.keysym.M-C-3: command:\033[8;25;80t URxvt.keysym.M-C-4: command:\033[8;48;110t + 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 registered. + See the rxvtperl(3) manpage. Due to security reasons, this resource + will be ignored when running setuid/setgid. + + 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/. Due to security reasons, this resource + will be ignored when running setuid/setgid. + + See the rxvtperl(3) manpage. + + selection.pattern-*idx*: *perl-regex* + Additional selection patterns, see the rxvtperl(3) manpage for + details. + + selection-autotransform.*idx*: *perl-transform* + Selection auto-transform patterns, see the rxvtperl(3) manpage for + details. + + 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* + Compile *frills*: Sets the WM_TRANSIENT_FOR property to the given + window id. + + override-redirect: *boolean* + Compile *frills*: Sets override-redirect for the terminal window, + making it almost invisible to window managers; option + -override-redirect. + 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 @@ -894,21 +1031,28 @@ 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 - an rxvt window causes the current text selection to be inserted as - if it had been typed on the keyboard. + Pressing and releasing the Middle mouse button in an rxvt window + causes the value of the PRIMARY selection (Shift for CLIPBOARD) to + be inserted as if it had been typed on the keyboard. Shift-Insert + causes the value of the PRIMARY selection to be inserted too. CHANGING FONTS Changing fonts (or font sizes, respectively) via the keypad is not yet supported in rxvt-unicode. Bug me if you need this. - You can, however, switch fonts at runtime using escape sequences (and - therefore using the menubar), e.g.: + You can, however, switch fonts at runtime using escape sequences, e.g.: + + printf '\e]710;%s\007' "9x15bold,xft:Kochi Gothic" - printf '\e]701;%s\007' "9x15bold,xft:Kochi Gothic" + You can use keyboard shortcuts, too: + + URxvt.keysym.M-C-1: command:\033]710;suxuseuro\007\033]711;suxuseuro\007 + URxvt.keysym.M-C-2: command:\033]710;9x15bold\007\033]711;9x15bold\007 rxvt-unicode will automatically re-apply these fonts to the output so far. @@ -1054,17 +1198,10 @@ 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- - Rewrote screen display and text selection routines. Project - Coordinator (changes.txt 2.4.6 - rxvt-unicode) + Rewrote screen display and text selection routines. + + Project Coordinator (changes.txt 2.4.6 - rxvt-unicode) Marc Alexander Lehmann - Forked rxvt-unicode, rewrote most of the display code and internal - character handling to store text in unicode, improve xterm - compatibility and apply numerous other bugfixes and extensions. + Forked rxvt-unicode, unicode support, rewrote almost all the code, + perl extension, random hacks, numerous bugfixes and extensions. Project Coordinator (Changes 1.0 -) + Emanuele Giaquinta + Pty/tty/utmp/wtmp rewrite, lots of random hacking and bugfixing. +