--- rxvt-unicode/doc/rxvt.7.txt 2005/12/17 20:55:45 1.26 +++ rxvt-unicode/doc/rxvt.7.txt 2006/01/16 14:48:39 1.44 @@ -20,9 +20,134 @@ . FREQUENTLY ASKED QUESTIONS + The new selection selects pieces that are too big, how can I select + single words? + Yes. For example, if you want to select alphanumeric words, you can + use the following resource: + + URxvt.selection.pattern-0: ([[:word:]]+) + + If you click more than twice, the selection will be extended more + and more. + + To get a selection that is very similar to the old code, try this + pattern: + + URxvt.selection.pattern-0: ([^"&'()*,;<=>?@[\\\\]^`{|})]+) + + Please also note that the *LeftClick Shift-LeftClik* combination + also selects words like the old code. + + I don't like the new selection/popups/hotkeys/perl, how do I + change/disable it? + You can disable the perl extension completely by setting the + perl-ext-common resource to the empty string, which also keeps + rxvt-unicode from initialising perl, saving memory. + + If you only want to disable specific features, you first have to + identify which perl extension is responsible. For this, read the + section PREPACKAGED EXTENSIONS in the rxvtperl(3) manpage. For + example, to disable the selection-popup and option-popup, specify + this perl-ext-common resource: + + URxvt.perl-ext-common: default,-selection-popup,-option-popup + + This will keep the default extensions, but disable the two popup + extensions. Some extensions can also be configured, for example, + scrollback search mode is triggered by M-s. You can move it to any + other combination either by setting the searchable-scrollback + resource: + + URxvt.searchable-scrollback: CM-s + + Isn't rxvt supposed to be small? Don't all those features bloat? + I often get asked about this, and I think, no, they didn't cause + extra bloat. If you compare a minimal rxvt and a minimal urxvt, you + can see that the urxvt binary is larger (due to some encoding tables + always being compiled in), but it actually uses less memory (RSS) + after startup. Even with "--disable-everything", this comparison is + a bit unfair, as many features unique to urxvt (locale, encoding + conversion, iso14755 etc.) are already in use in this mode. + + text data bss drs rss filename + 98398 1664 24 15695 1824 rxvt --disable-everything + 188985 9048 66616 18222 1788 urxvt --disable-everything + + When you "--enable-everything" (which _is_ unfair, as this involves + xft and full locale/XIM support which are quite bloaty inside libX11 + and my libc), the two diverge, but not unreasnobaly so. + + text data bss drs rss filename + 163431 2152 24 20123 2060 rxvt --enable-everything + 1035683 49680 66648 29096 3680 urxvt --enable-everything + + The very large size of the text section is explained by the + east-asian encoding tables, which, if unused, take up disk space but + nothing else and can be compiled out unless you rely on X11 core + fonts that use those encodings. The BSS size comes from the 64k + emergency buffer that my c++ compiler allocates (but of course + doesn't use unless you are out of memory). Also, using an xft font + instead of a core font immediately adds a few megabytes of RSS. Xft + indeed is responsible for a lot of RSS even when not used. + + Of course, due to every character using two or four bytes instead of + one, a large scrollback buffer will ultimately make rxvt-unicode use + more memory. + + Compared to e.g. Eterm (5112k), aterm (3132k) and xterm (4680k), + this still fares rather well. And compared to some monsters like + gnome-terminal (21152k + extra 4204k in separate processes) or + konsole (22200k + extra 43180k in daemons that stay around after + exit, plus half a minute of startup time, including the hundreds of + warnings it spits out), it fares extremely well *g*. + + Why C++, isn't that unportable/bloated/uncool? + Is this a question? :) It comes up very often. The simple answer is: + I had to write it, and C++ allowed me to write and maintain it in a + fraction of the time and effort (which is a scarce resource for me). + Put even shorter: It simply wouldn't exist without C++. + + My personal stance on this is that C++ is less portable than C, but + in the case of rxvt-unicode this hardly matters, as its portability + limits are defined by things like X11, pseudo terminals, locale + support and unix domain sockets, which are all less portable than + C++ itself. + + Regarding the bloat, see the above question: It's easy to write + programs in C that use gobs of memory, an certainly possible to + write programs in C++ that don't. C++ also often comes with large + libraries, but this is not necessarily the case with GCC. Here is + what rxvt links against on my system with a minimal config: + + libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x00002aaaaabc3000) + libc.so.6 => /lib/libc.so.6 (0x00002aaaaadde000) + libdl.so.2 => /lib/libdl.so.2 (0x00002aaaab01d000) + /lib64/ld-linux-x86-64.so.2 (0x00002aaaaaaab000) + + And here is rxvt-unicode: + + libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x00002aaaaabc3000) + libgcc_s.so.1 => /lib/libgcc_s.so.1 (0x00002aaaaada2000) + libc.so.6 => /lib/libc.so.6 (0x00002aaaaaeb0000) + libdl.so.2 => /lib/libdl.so.2 (0x00002aaaab0ee000) + /lib64/ld-linux-x86-64.so.2 (0x00002aaaaaaab000) + + No large bloated libraries (of course, none were linked in + statically), except maybe libX11 :) + + Does it support tabs, can I have a tabbed rxvt-unicode? + rxvt-unicode does not directly support tabs. It will work fine with + tabbing functionality of many window managers or similar tabbing + programs, and its embedding-features allow it to be embedded into + other programs, as witnessed by doc/rxvt-tabbed or the upcoming + "Gtk2::URxvt" perl module, which features a tabbed urxvt (murxvt) + terminal as an example embedding application. + How do I know which rxvt-unicode version I'm using? The version number is displayed with the usage (-h). Also the escape sequence "ESC [ 8 n" sets the window title to the version number. + When using the rxvtc client, the version displayed is that of the + daemon. I am using Debian GNU/Linux and have a problem... The Debian GNU/Linux package of rxvt-unicode in sarge contains large @@ -39,6 +164,49 @@ also a bug in the Debian version and it serves as a reminder for other users that might encounter the same issue. + I am maintaining rxvt-unicode for distribution/OS XXX, any + recommendation? + You should build one binary with the default options. configure now + enables most useful options, and the trend goes to making them + runtime-switchable, too, so there is usually no drawback to enbaling + them, except higher disk and possibly memory usage. The perl + interpreter should be enabled, as important functionality (menus, + selection, likely more in the future) depends on it. + + You should not overwrite the "perl-ext-common" snd "perl-ext" + resources system-wide (except maybe with "defaults"). This will + result in useful behaviour. If your distribution aims at low memory, + add an empty "perl-ext-common" resource to the app-defaults file. + This will keep the perl interpreter disabled until the user enables + it. + + If you can/want build more binaries, I recommend building a minimal + one with "--disable-everything" (very useful) and a maximal one with + "--enable-everything" (less useful, it will be very big due to a lot + of encodings built-in that increase download times and are rarely + used). + + I need to make it setuid/setgid to support utmp/ptys on my OS, is this + safe? + Likely not. While I honestly try to make it secure, and am probably + not bad at it, I think it is simply unreasonable to expect all of + freetype + fontconfig + xft + xlib + perl + ... + rxvt-unicode + itself to all be secure. Also, rxvt-unicode disables some options + when it detects that it runs setuid or setgid, which is not nice. + Besides, with the embedded perl interpreter the possibility for + security problems easily multiplies. + + Elevated privileges are only required for utmp and pty operations on + some systems (for example, GNU/Linux doesn't need any extra + privileges for ptys, but some need it for utmp support). It is + planned to mvoe this into a forked handler process, but this is not + yet done. + + So, while setuid/setgid operation is supported and not a problem on + your typical single-user-no-other-logins unix desktop, always + remember that its an awful lot of code, most of which isn't checked + for security issues regularly. + When I log-in to another system it tells me about missing terminfo data? The terminal description used by rxvt-unicode is not as widely available as that for xterm, or even rxvt (for which the same @@ -488,7 +656,7 @@ 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(7) + or Shift keys are depressed. What's with this bold/blink stuff? If no bold colour is set via "colorBD:", bold will invert text using @@ -584,7 +752,7 @@ $ stty erase ^? $ rxvt - Toggle with "ESC [ 36 h" / "ESC [ 36 l" as documented in rxvt(7). + Toggle with "ESC [ 36 h" / "ESC [ 36 l". For an existing rxvt-unicode: @@ -1086,10 +1254,6 @@ h Send Mouse X & Y on button press. l No mouse reporting. - "Ps = 10" (rxvt) - h menuBar visible - l menuBar invisible - "Ps = 25" h Visible cursor {cnorm/cvvis} l Invisible cursor {civis} @@ -1148,6 +1312,10 @@ h Scroll to bottom when a key is pressed l Don't scroll to bottom when a key is pressed + "Ps = 1021" (rxvt) + h Bold/italic implies high intensity (see option -is) + l Font styles have no effect on intensity (Compile styles) + "Ps = 1047" h Use Alternate Screen Buffer l Use Normal Screen Buffer - clear Alternate Screen Buffer if returning from it @@ -1179,8 +1347,8 @@ Ps = 12 Change colour of text cursor foreground to Pt Ps = 13 Change colour of mouse foreground to Pt Ps = 17 Change colour of highlight characters to Pt - Ps = 18 Change colour of bold characters to Pt - Ps = 19 Change colour of underlined characters to Pt + Ps = 18 Change colour of bold characters to Pt [deprecated, see 706] + Ps = 19 Change colour of underlined characters to Pt [deprecated, see 707] Ps = 20 Change default background to Pt Ps = 39 Change default foreground colour to Pt. Ps = 46 Change Log File to Pt unimplemented @@ -1188,346 +1356,20 @@ Ps = 50 Set fontset to Pt, with the following special values of Pt (rxvt) #+n change up n #-n change down n if n is missing of 0, a value of 1 is used empty change to font0 n change to font n Ps = 55 Log all scrollback buffer and all of screen to Pt Ps = 701 Change current locale to Pt, or, if Pt is ?, return the current locale (Compile frills). - Ps = 703 Menubar command Pt (Compile menubar). Ps = 704 Change colour of italic characters to Pt Ps = 705 Change background pixmap tint colour to Pt (Compile transparency). + Ps = 706 Change colour of bold characters to Pt + Ps = 707 Change colour of underlined characters to Pt Ps = 710 Set normal fontset to Pt. Same as Ps = 50. Ps = 711 Set bold fontset to Pt. Similar to Ps = 50 (Compile styles). Ps = 712 Set italic fontset to Pt. Similar to Ps = 50 (Compile styles). Ps = 713 Set bold-italic fontset to Pt. Similar to Ps = 50 (Compile styles). Ps = 720 Move viewing window up by Pt lines, or clear scrollback buffer if Pt = 0 (Compile frills). Ps = 721 Move viewing window down by Pt lines, or clear scrollback buffer if Pt = 0 (Compile frills). + Ps = 777 Call the perl extension with the given string, which should be of the form extension:parameters (Compile perl). -menuBar - The exact syntax used is *almost* solidified. In the menus, DON'T try to - use menuBar commands that add or remove a menuBar. - - Note that in all of the commands, the */path/* *cannot* be omitted: use - ./ to specify a menu relative to the current menu. - - Overview of menuBar operation - For the menuBar XTerm escape sequence "ESC ] 703 ; Pt ST", the syntax of - "Pt" can be used for a variety of tasks: - - At the top level is the current menuBar which is a member of a circular - linked-list of other such menuBars. - - The menuBar acts as a parent for the various drop-down menus, which in - turn, may have labels, separator lines, menuItems and subMenus. - - The menuItems are the useful bits: you can use them to mimic keyboard - input or even to send text or escape sequences back to rxvt. - - The menuBar syntax is intended to provide a simple yet robust method of - constructing and manipulating menus and navigating through the menuBars. - - The first step is to use the tag [menu:*name*] which creates the menuBar - called *name* and allows access. You may now or menus, subMenus, and - menuItems. Finally, use the tag [done] to set the menuBar access as - readonly to prevent accidental corruption of the menus. To re-access the - current menuBar for alterations, use the tag [menu], make the - alterations and then use [done] - - - - Commands - [menu:+*name*] - access the named menuBar for creation or alteration. If a new - menuBar is created, it is called *name* (max of 15 chars) and the - current menuBar is pushed onto the stack - - [menu] - access the current menuBar for alteration - - [title:+*string*] - set the current menuBar's title to *string*, which may contain the - following format specifiers: - - B<%n> rxvt name (as per the B<-name> command-line option) - B<%v> rxvt version - B<%%> literal B<%> character - - [done] - set menuBar access as readonly. End-of-file tag for [read:+*file*] - operations. - - [read:+*file*] - read menu commands directly from *file* (extension ".menu" will be - appended if required.) Start reading at a line with [menu] or - [menu:+*name* and continuing until [done] is encountered. - - Blank and comment lines (starting with #) are ignored. Actually, - since any invalid menu commands are also ignored, almost anything - could be construed as a comment line, but this may be tightened up - in the future ... so don't count on it!. - - [read:+*file*;+*name*] - The same as [read:+*file*], but start reading at a line with - [menu:+*name*] and continuing until [done:+*name*] or [done] is - encountered. - - [dump] - dump all menuBars to the file /tmp/rxvt-PID in a format suitable for - later rereading. - - [rm:name] - remove the named menuBar - - [rm] [rm:] - remove the current menuBar - - [rm*] [rm:*] - remove all menuBars - - [swap] - swap the top two menuBars - - [prev] - access the previous menuBar - - [next] - access the next menuBar - - [show] - Enable display of the menuBar - - [hide] - Disable display of the menuBar - - [pixmap:+*name*] - [pixmap:+*name*;*scaling*] - (set the background pixmap globally - - A Future implementation *may* make this local to the menubar) - - [:+*command*:] - ignore the menu readonly status and issue a *command* to or a menu - or menuitem or change the ; a useful shortcut for setting the quick - arrows from a menuBar. - - - - Adding and accessing menus - The following commands may also be + prefixed. - - /+ access menuBar top level - - ./+ access current menu level - - ../+ - access parent menu (1 level up) - - ../../ - access parent menu (multiple levels up) - - */path/*menu - add/access menu - - */path/*menu/* - add/access menu and clear it if it exists - - */path/*{-} - add separator - - */path/*{item} - add item as a label - - */path/*{item} action - add/alter *menuitem* with an associated *action* - - */path/*{item}{right-text} - add/alter *menuitem* with right-text as the right-justified text and - as the associated *action* - - */path/*{item}{rtext} action - add/alter *menuitem* with an associated *action* and with rtext as - the right-justified text. - - Special characters in *action* must be backslash-escaped: - \a \b \E \e \n \r \t \octal - - or in control-character notation: - ^@, ^A .. ^Z .. ^_, ^? - - To send a string starting with a NUL (^@) character to the program, - start *action* with a pair of NUL characters (^@^@), the first of which - will be stripped off and the balance directed to the program. Otherwise - if *action* begins with NUL followed by non-+NUL characters, the leading - NUL is stripped off and the balance is sent back to rxvt. - - As a convenience for the many Emacs-type editors, *action* may start - with M- (eg, M-$ is equivalent to \E$) and a CR will be appended if - missed from M-x commands. - - As a convenience for issuing XTerm ESC ] sequences from a menubar (or - quick arrow), a BEL (^G) will be appended if needed. - - For example, - M-xapropos is equivalent to \Exapropos\r - - and \E]703;mona;100 is equivalent to \E]703;mona;100\a - - The option {*right-rtext*} will be right-justified. In the absence of a - specified action, this text will be used as the *action* as well. - - For example, - /File/{Open}{^X^F} is equivalent to /File/{Open}{^X^F} ^X^F - - The left label *is* necessary, since it's used for matching, but - implicitly hiding the left label (by using same name for both left and - right labels), or explicitly hiding the left label (by preceeding it - with a dot), makes it possible to have right-justified text only. - - For example, - /File/{Open}{Open} Open-File-Action - - or hiding it - /File/{.anylabel}{Open} Open-File-Action - - - - Removing menus - -/*+ - remove all menus from the menuBar, the same as [clear] - - -+*/path*menu+ - remove menu - - -+*/path*{item}+ - remove item - - -+*/path*{-} - remove separator) - - -/path/menu/* - remove all items, separators and submenus from menu - - - - Quick Arrows - The menus also provide a hook for *quick arrows* to provide easier user - access. If nothing has been explicitly set, the default is to emulate - the curror keys. The syntax permits each arrow to be altered - individually or all four at once without re-entering their common - beginning/end text. For example, to explicitly associate cursor actions - with the arrows, any of the following forms could be used: - - +*Right* - +*Left* - +*Up* - +*Down* - Define actions for the respective arrow buttons - - +*Begin* - +*End* - Define common beginning/end parts for *quick arrows* which used in - conjunction with the above constructs - - For example, define arrows individually, - \E[A - - \E[B - - \E[C - - \E[D - - or all at once - \E[AZ<>\E[BZ<>\E[CZ<>\E[D - - or more compactly (factoring out common parts) - \E[AZ<>BZ<>CZ<>D - - - - Command Summary - A short summary of the most *common* commands: - - [menu:name] - use an existing named menuBar or start a new one - - [menu] - use the current menuBar - - [title:string] - set menuBar title - - [done] - set menu access to readonly and, if reading from a file, signal EOF - - [done:name] - if reading from a file using [read:file;name] signal EOF - - [rm:name] - remove named menuBar(s) - - [rm] [rm:] - remove current menuBar - - [rm*] [rm:*] - remove all menuBar(s) - - [swap] - swap top two menuBars - - [prev] - access the previous menuBar - - [next] - access the next menuBar - - [show] - map menuBar - - [hide] - unmap menuBar - - [pixmap;file] - [pixmap;file;scaling] - set a background pixmap - - [read:file] - [read:file;name] - read in a menu from a file - - [dump] - dump out all menuBars to /tmp/rxvt-PID - - / access menuBar top level - - ./ - ../ - ../../ - access current or parent menu level - - /path/menu - add/access menu - - /path/{-} - add separator - - /path/{item}{rtext} action - add/alter menu item - - -/* remove all menus from the menuBar - - -/path/menu - remove menu items, separators and submenus from menu - - -/path/menu - remove menu - - -/path/{item} - remove item - - -/path/{-} - remove separator - - BeginRightLeftUpDownEnd - menu quick arrows - XPM For the XPM XTerm escape sequence "ESC ] 20 ; Pt ST" then value of "Pt" can be the name of the background pixmap followed by a sequence of @@ -1777,10 +1619,10 @@ at start of rxvt execution. This option requires --enable-utmp to also be specified. - --enable-xpm-background (default: off) + --enable-xpm-background (default: on) Add support for XPM background pixmaps. - --enable-transparency (default: off) + --enable-transparency (default: on) Add support for inheriting parent backgrounds thus giving a fake transparency to the term. @@ -1792,10 +1634,6 @@ Add support for tinting of transparent backgrounds (requires "--enable-transparency"). - --enable-menubar (default: off) - Add support for our menu bar system (this interacts badly with - dynamic locale switching currently). - --enable-rxvt-scroll (default: on) Add support for the original rxvt scrollbar. @@ -1829,22 +1667,6 @@ --disable-resources Removes any support for resource checking. - --enable-xgetdefault - Make resources checking via XGetDefault() instead of our small - version which only checks ~/.Xdefaults, or if that doesn't exist - then ~/.Xresources. - - Please note that nowadays, things like XIM will automatically pull - in and use the full X resource manager, so the overhead of using it - might be very small, if nonexistant. - - --enable-strings (default: off) - Add support for our possibly faster memset() function and other - various routines, overriding your system's versions which may have - been hand-crafted in assembly or may require extra libraries to link - in. (this breaks ANSI-C rules and has problems on many GNU/Linux - systems). - --disable-swapscreen Remove support for secondary/swap screen. @@ -1858,17 +1680,21 @@ MWM-hints EWMH-hints (pid, utf8 names) and protocols (ping) - seperate underline colour - settable border widths and borderless switch - settable extra linespacing + seperate underline colour (-underlineColor) + settable border widths and borderless switch (-w, -b, -bl) + settable extra linespacing /-lsp) iso-14755-2 and -3, and visual feedback backindex and forwardindex escape sequence window op and some xterm/OSC escape sequences - tripleclickwords - settable insecure mode + tripleclickwords (-tcw) + settable insecure mode (-insecure) keysym remapping support - cursor blinking and underline cursor - -embed and -pty-fd options + cursor blinking and underline cursor (-cb, -uc) + XEmbed support (-embed) + user-pty (-pty-fd) + hold on exit (-hold) + skip builtin block graphics (-sbg) + sgr modes 90..97 and 100..107 --enable-iso14755 (default: on) Enable extended ISO 14755 support (see rxvt(1), or doc/rxvt.1.txt). @@ -1911,6 +1737,13 @@ --enable-pointer-blank (default: on) Add support to have the pointer disappear when typing or inactive. + --enable-perl (default: off) + Enable an embedded perl interpreter. See the rxvtperl(3) manpage + (doc/rxvtperl.txt) for more info on this feature, or the files in + src/perl-ext/ for the extensions that are installed by default. The + perl interpreter that is used can be specified via the "PERL" + environment variable when running configure. + --with-name=NAME (default: urxvt) Set the basename for the installed binaries, resulting in "urxvt", "urxvtd" etc.). Specify "--with-name=rxvt" to replace with "rxvt".