--- rxvt-unicode/doc/rxvt.7.pod 2006/01/02 19:36:07 1.67 +++ rxvt-unicode/doc/rxvt.7.pod 2006/01/16 15:12:48 1.85 @@ -26,6 +26,46 @@ =over 4 +=item 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 I combination also +selects words like the old code. + +=item 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 +B 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 +B in the @@RXVT_NAME@@perl(3) manpage. For +example, to disable the B and B, specify +this B 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 B. You can move it to any +other combination either by setting the B resource: + + URxvt.searchable-scrollback: CM-s + =item 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 @@ -64,7 +104,7 @@ 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 aminute of +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*. @@ -134,6 +174,45 @@ bug in the Debian version and it serves as a reminder for other users that might encounter the same issue. +=item I am maintaining rxvt-unicode for distribution/OS XXX, any recommendation? + +You should build one binary with the default options. F +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 C snd C resources +system-wide (except maybe with C). This will result in useful +behaviour. If your distribution aims at low memory, add an empty +C 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 C<--disable-everything> (very useful) and a maximal one with +C<--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). + +=item 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. + =item 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 @@ -539,7 +618,7 @@ You can specify separate locales for the input method and the rest of the terminal, using the resource C: - URxvt*imlocale: ja_JP.EUC-JP + URxvt.imlocale: ja_JP.EUC-JP Now you can start your terminal with C and still use your input method. Please note, however, that you will not be able to @@ -595,7 +674,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_NAME@@(7) +depressed. =item What's with this bold/blink stuff? @@ -694,7 +773,7 @@ $ stty erase ^? $ @@RXVT_NAME@@ -Toggle with C / C as documented in @@RXVT_NAME@@(7). +Toggle with C / C. For an existing rxvt-unicode: @@ -822,8 +901,8 @@ The rest of this document describes various technical aspects of B. First the description of supported command sequences, -followed by menu and pixmap support and last by a description of all -features selectable at C time. +followed by pixmap support and last by a description of all features +selectable at C time. =head1 Definitions @@ -1401,15 +1480,6 @@ =end table -=item B<< C >> (B) - -=begin table - - B<< C >> menuBar visible - B<< C >> menuBar invisible - -=end table - =item B<< C >> =begin table @@ -1599,8 +1669,8 @@ B<< C >> Change colour of text cursor foreground to B<< C >> B<< C >> Change colour of mouse foreground to B<< C >> B<< C >> Change colour of highlight characters to B<< C >> - B<< C >> Change colour of bold characters to B<< C >> - B<< C >> Change colour of underlined characters to B<< C >> + B<< C >> Change colour of bold characters to B<< C >> [deprecated, see 706] + B<< C >> Change colour of underlined characters to B<< C >> [deprecated, see 707] B<< C >> Change default background to B<< C >> B<< C >> Change default foreground colour to B<< C >>. B<< C >> Change Log File to B<< C >> I @@ -1608,486 +1678,22 @@ B<< C >> Set fontset to B<< C >>, with the following special values of B<< C >> (B) B<< C<#+n> >> change up B<< C >> B<< C<#-n> >> change down B<< C >> if B<< C >> is missing of 0, a value of 1 is used I change to font0 B<< C >> change to font B<< C >> B<< C >> Log all scrollback buffer and all of screen to B<< C >> B<< C >> Change current locale to B<< C >>, or, if B<< C >> is B<< C >>, return the current locale (Compile frills). - B<< C >> Menubar command B<< C >> (Compile menubar). B<< C >> Change colour of italic characters to B<< C >> B<< C >> Change background pixmap tint colour to B<< C >> (Compile transparency). + B<< C >> Change colour of bold characters to B<< C >> + B<< C >> Change colour of underlined characters to B<< C >> B<< C >> Set normal fontset to B<< C >>. Same as C. B<< C >> Set bold fontset to B<< C >>. Similar to C (Compile styles). B<< C >> Set italic fontset to B<< C >>. Similar to C (Compile styles). B<< C >> Set bold-italic fontset to B<< C >>. Similar to C (Compile styles). B<< C >> Move viewing window up by B<< C >> lines, or clear scrollback buffer if C (Compile frills). B<< C >> Move viewing window down by B<< C >> lines, or clear scrollback buffer if C (Compile frills). + B<< C >> Call the perl extension with the given string, which should be of the form C (Compile perl). =end table =back -X - -=head1 menuBar - -B<< The exact syntax used is I solidified. >> -In the menus, B try to use menuBar commands that add or remove a -menuBar. - -Note that in all of the commands, the B<< I >> I be -omitted: use B<./> to specify a menu relative to the current menu. - -=head2 Overview of menuBar operation - -For the menuBar XTerm escape sequence C, the syntax -of C 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 B<< [menu:I] >> which creates -the menuBar called I and allows access. You may now or menus, -subMenus, and menuItems. Finally, use the tag B<[done]> to set the -menuBar access as B to prevent accidental corruption of the -menus. To re-access the current menuBar for alterations, use the tag -B<[menu]>, make the alterations and then use B<[done]> - -X - -=head2 Commands - -=over 4 - -=item B<< [menu:+I] >> - -access the named menuBar for creation or alteration. If a new menuBar -is created, it is called I (max of 15 chars) and the current -menuBar is pushed onto the stack - -=item B<[menu]> - -access the current menuBar for alteration - -=item B<< [title:+I] >> - -set the current menuBar's title to I, 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 - -=item B<[done]> - -set menuBar access as B. -End-of-file tag for B<< [read:+I] >> operations. - -=item B<< [read:+I] >> - -read menu commands directly from I (extension ".menu" will be -appended if required.) Start reading at a line with B<[menu]> or B<< -[menu:+I >> and continuing until B<[done]> is encountered. - -Blank and comment lines (starting with B<#>) 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!. - -=item B<< [read:+I;+I] >> - -The same as B<< [read:+I] >>, but start reading at a line with -B<< [menu:+I] >> and continuing until B<< [done:+I] >> or -B<[done]> is encountered. - -=item B<[dump]> - -dump all menuBars to the file B in a format suitable for -later rereading. - -=item B<[rm:name]> - -remove the named menuBar - -=item B<[rm] [rm:]> - -remove the current menuBar - -=item B<[rm*] [rm:*]> - -remove all menuBars - -=item B<[swap]> - -swap the top two menuBars - -=item B<[prev]> - -access the previous menuBar - -=item B<[next]> - -access the next menuBar - -=item B<[show]> - -Enable display of the menuBar - -=item B<[hide]> - -Disable display of the menuBar - -=item B<< [pixmap:+I] >> - -=item B<< [pixmap:+I;I] >> - -(set the background pixmap globally - -B<< A Future implementation I make this local to the menubar >>) - -=item B<< [:+I:] >> - -ignore the menu readonly status and issue a I to or a menu or -menuitem or change the ; a useful shortcut for setting the quick arrows -from a menuBar. - -=back - -X - -=head2 Adding and accessing menus - -The following commands may also be B<+> prefixed. - -=over 4 - -=item B - -access menuBar top level - -=item B<./+> - -access current menu level - -=item B<../+> - -access parent menu (1 level up) - -=item B<../../> - -access parent menu (multiple levels up) - -=item B<< Imenu >> - -add/access menu - -=item B<< Imenu/* >> - -add/access menu and clear it if it exists - -=item B<< I{-} >> - -add separator - -=item B<< I{item} >> - -add B as a label - -=item B<< I{item} action >> - -add/alter I with an associated I - -=item B<< I{item}{right-text} >> - -add/alter I with B as the right-justified text -and as the associated I - -=item B<< I{item}{rtext} action >> - -add/alter I with an associated I and with B as -the right-justified text. - -=back - -=over 4 - -=item Special characters in I must be backslash-escaped: - -B<\a \b \E \e \n \r \t \octal> - -=item or in control-character notation: - -B<^@, ^A .. ^Z .. ^_, ^?> - -=back - -To send a string starting with a B (B<^@>) character to the -program, start I with a pair of B characters (B<^@^@>), -the first of which will be stripped off and the balance directed to the -program. Otherwise if I begins with B followed by -non-+B characters, the leading B is stripped off and the -balance is sent back to rxvt. - -As a convenience for the many Emacs-type editors, I may start -with B (eg, B is equivalent to B<\E$>) and a B will be -appended if missed from B commands. - -As a convenience for issuing XTerm B sequences from a menubar (or -quick arrow), a B (B<^G>) will be appended if needed. - -=over 4 - -=item For example, - -B is equivalent to B<\Exapropos\r> - -=item and - -B<\E]703;mona;100> is equivalent to B<\E]703;mona;100\a> - -=back - -The option B<< {I} >> will be right-justified. In the -absence of a specified action, this text will be used as the I -as well. - -=over 4 - -=item For example, - -B is equivalent to B - -=back - -The left label I 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. - -=over 4 - -=item For example, - -B - -=item or hiding it - -B - -=back - -X - -=head2 Removing menus - -=over 4 - -=item B<< -/*+ >> - -remove all menus from the menuBar, the same as B<[clear]> - -=item B<< -+Imenu+ >> - -remove menu - -=item B<< -+I{item}+ >> - -remove item - -=item B<< -+I{-} >> - -remove separator) - -=item B<-/path/menu/*> - -remove all items, separators and submenus from menu - -=back - -X - -=head2 Quick Arrows - -The menus also provide a hook for I 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: - -=over 4 - -=item B<< +I >> - -=item B<< +I >> - -=item B<< +I >> - -=item B<< +I >> - -Define actions for the respective arrow buttons - -=item B<< +I >> - -=item B<< +I >> - -Define common beginning/end parts for I which used in -conjunction with the above constructs - -=back - -=over 4 - -=item For example, define arrows individually, - - \E[A - - \E[B - - \E[C - - \E[D - -=item or all at once - - \E[AZ<>\E[BZ<>\E[CZ<>\E[D - -=item or more compactly (factoring out common parts) - - \E[AZ<>BZ<>CZ<>D - -=back - -X - -=head2 Command Summary - -A short summary of the most I commands: - -=over 4 - -=item [menu:name] - -use an existing named menuBar or start a new one - -=item [menu] - -use the current menuBar - -=item [title:string] - -set menuBar title - -=item [done] - -set menu access to readonly and, if reading from a file, signal EOF - -=item [done:name] - -if reading from a file using [read:file;name] signal EOF - -=item [rm:name] - -remove named menuBar(s) - -=item [rm] [rm:] - -remove current menuBar - -=item [rm*] [rm:*] - -remove all menuBar(s) - -=item [swap] - -swap top two menuBars - -=item [prev] - -access the previous menuBar - -=item [next] - -access the next menuBar - -=item [show] - -map menuBar - -=item [hide] - -unmap menuBar - -=item [pixmap;file] - -=item [pixmap;file;scaling] - -set a background pixmap - -=item [read:file] - -=item [read:file;name] - -read in a menu from a file - -=item [dump] - -dump out all menuBars to /tmp/rxvt-PID - -=item / - -access menuBar top level - -=item ./ - -=item ../ - -=item ../../ - -access current or parent menu level - -=item /path/menu - -add/access menu - -=item /path/{-} - -add separator - -=item /path/{item}{rtext} action - -add/alter menu item - -=item -/* - -remove all menus from the menuBar - -=item -/path/menu - -remove menu items, separators and submenus from menu - -=item -/path/menu - -remove menu - -=item -/path/{item} - -remove item - -=item -/path/{-} - -remove separator - -=item BeginRightLeftUpDownEnd - -menu quick arrows - -=back X =head1 XPM @@ -2407,11 +2013,11 @@ F) at start of rxvt execution. This option requires --enable-utmp to also be specified. -=item --enable-xpm-background (default: off) +=item --enable-xpm-background (default: on) Add support for XPM background pixmaps. -=item --enable-transparency (default: off) +=item --enable-transparency (default: on) Add support for inheriting parent backgrounds thus giving a fake transparency to the term. @@ -2424,11 +2030,6 @@ Add support for tinting of transparent backgrounds (requires C<--enable-transparency>). -=item --enable-menubar (default: off) - -Add support for our menu bar system (this interacts badly with -dynamic locale switching currently). - =item --enable-rxvt-scroll (default: on) Add support for the original rxvt scrollbar. @@ -2470,24 +2071,6 @@ Removes any support for resource checking. -=item --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. - -=item --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). - =item --disable-swapscreen Remove support for secondary/swap screen. @@ -2503,17 +2086,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, -pty-fd and -hold 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 =item --enable-iso14755 (default: on) @@ -2568,9 +2155,11 @@ =item --enable-perl (default: off) -Enable an embedded perl interpreter. See the B manpage -(F) for more info on this feature, or the files in -F for the extensions that are installed by default. +Enable an embedded perl interpreter. See the B<@@RXVT_NAME@@perl(3)> +manpage (F) for more info on this feature, or the files +in F for the extensions that are installed by default. The +perl interpreter that is used can be specified via the C environment +variable when running configure. =item --with-name=NAME (default: urxvt)