--- rxvt-unicode/doc/rxvt.1.pod 2004/08/12 21:30:14 1.2 +++ rxvt-unicode/doc/rxvt.1.pod 2004/09/08 17:10:23 1.30 @@ -8,14 +8,59 @@ =head1 DESCRIPTION -B, version B<@@RXVTVERSION@@>, is a colour vt102 terminal +B, version B<@@RXVT_VERSION@@>, is a colour vt102 terminal emulator intended as an I(1) replacement for users who do not require features such as Tektronix 4014 emulation and toolkit-style configurability. As a result, B uses much less swap space -- a significant advantage on a machine serving many X sessions. -See also @@RXVT_NAME@@(7) for technical reference documentation (escape -sequences etc.). +=head1 FREQUENTLY ASKED QUESTIONS + +See @@RXVT_NAME@@(7) (try C) for a list of frequently +asked questions and answer to them and some common problems. + +=head1 RXVT-UNICODE VS. RXVT + +Unlike the original rxvt, B stores all text in Unicode +internally. That means it can store and display most scripts in the +world. Being a terminal emulator, however, some things are very difficult, +especially cursive scripts such as arabic, vertically written scripts +like mongolian or scripts requiring extremely complex combining rules, +like tibetan or devenagari. Don't expect pretty output when using these +scripts. Most other scripts, latin, cyrillic, kanji, thai etc. should work +fine, though. A somewhat difficult case are left-to-right scripts, such +as hebrew: B adopts the view that bidirectional algorithms +belong into the application, not the terminal emulator (too many things -- +such as cursor-movement while editing -- break otherwise), but that might +change. + +If you are looking for a terminal that supports more exotic scripts, let +me recommend C, which is a very userfriendly, lean and clean +terminal emulator. In fact, the reason rxvt-unicode was born was solely +because the author couldn't get C to use one font for latin1 and +another for japanese. + +Therefore another design rationale was the use of multiple fonts to +display characters: The idea of a single unicode font which many other +programs force onto it's users never made sense to me: You should be able +to choose any font for any script freely. + +Apart from that, rxvt-unicode is also much better internationalised than +it's predecessor, supports things such as XFT and ISO 14755 that are handy +in i18n-environments, is faster, and has a lot less bugs than the original +rxvt. This all in addition to dozens of other small improvements. + +It is still faithfully following the original rxvt idea of being lean +and nice on resources: for example, you can still configure rxvt-unicode +without most of it's features to get a lean binary. It also comes with +a client/daemon pair that lets you open any number of terminal windows +from within a single process, which makes startup time very fast and +drastically reduces memory usage. See @@RXVT_NAME@@d(1) (daemon) and +@@RXVT_NAME@@c(1) (client). + +It also makes technical information about escape sequences (which have +been extended) easier accessible: see @@RXVT_NAME@@(7) for technical +reference documentation (escape sequences etc.). =head1 OPTIONS @@ -23,15 +68,15 @@ below. In keeping with the smaller-is-better philosophy, options may be eliminated or default values chosen at compile-time, so options and defaults listed may not accurately reflect the version installed on -your system. `rxvt -h' gives a list of major compile-time options on +your system. `@@RXVT_NAME@@ -h' gives a list of major compile-time options on the I line. Option descriptions may be prefixed with which compile option each is dependent upon. e.g. `Compile I:' requires -I on the I line. Note: `rxvt -help' gives a list of all +I on the I line. Note: `@@RXVT_NAME@@ -help' gives a list of all command-line options compiled into your version. Note that B<@@RXVT_NAME@@> permits the resource name to be used as a long-option (--/++ option) so the potential command-line options are -far greater than those listed. For example: `rxvt --loginShell --color1 +far greater than those listed. For example: `@@RXVT_NAME@@ --loginShell --color1 Orange'. The following options are available: @@ -111,24 +156,34 @@ =item B<-bd> I -The colour of the border between the xterm scrollbar and the text; +The colour of the border around the text area and between the scrollbar and the text; resource B. -=item B<-fn> I +=item B<-fn> I -Select the fonts to be used. This is a comma seperated list of font -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. resource B. +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 characters. The +first font defines the cell size for characters; other fonts might be +smaller, but not (in general) larger. A reasonable default font list is +always appended to it. See resource B for details. -=item B<-rb>|B<+rb> +See also the question "How does rxvt-unicode choose fonts?" in the FAQ +section of @@RXVT_NAME@@(7). -Enable "real bold" support. When this option is on, bold text will be -displayed using the first available bold font in the font list. Bold -fonts should thus be specified in the font list after their -corresponding regular fonts. If no bold font can be found, a regular -font will be used. resource B. +=item B<-fb> I + +Compile font-styles: The bold font list to use when bold characters are to +be printed. See resource B for details. + +=item B<-fi> I + +Compile font-styles: The italic font list to use when bold characters are to +be printed. See resource B for details. + +=item B<-fbi> I + +Compile font-styles: The bold italic font list to use when bold characters are to +be printed. See resource B for details. =item B<-name> I @@ -207,7 +262,7 @@ =item B<-bl> Compile I: Set MWM hints to request a borderless window, i.e. -if honoured by the WM, the rxvt window will not have window +if honoured by the WM, the rxvt-unicode window will not have window decorations; resource B. =item B<-lsp> I @@ -288,7 +343,7 @@ =item B<-xrm> I -No effect on rxvt. Simply passes through an argument to be made +No effect on rxvt-unicode. Simply passes through an argument to be made available in the instance's argument list. Appears in I in some window managers. @@ -347,11 +402,19 @@ 3=yellow, 4=blue, 5=magenta, 6=cyan, 7=white, but the actual colour names used are listed in the B section. +Colours higher than 15 cannot be set using resources (yet), but can be +changed using an escape command (see @@RXVT_NAME@@(7)). + +Colours 16-79 form a standard 4x4x4 colour cube (the same as xterm with +88 colour support). Colours 80-87 are evenly spaces grey steps. + =item B I -Use the specified colour to display bold characters when the foreground -colour is the default. This option will be ignored if B is -enabled. +=item B I + +Use the specified colour to display bold or italic characters when the +foreground colour is the default. If font styles are not available +(Compile styles) and this option is unset, reverse video is used instead. =item B I @@ -418,6 +481,11 @@ Use the specified colour for the scrollbar's trough area [default #969696]. Only relevant for normal (non XTerm/NeXT) scrollbar. +=item B I + +The colour of the border around the text area and between the scrollbar +and the text. + =item B I Use the specified XPM file (note the `.xpm' extension is optional) for @@ -442,22 +510,67 @@ menus), in addition to the paths specified by the B and B environment variables. -=item B I +=item B I -Select the fonts to be used. This is a comma seperated list of font +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 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 B<-fn>. -=item B I +Each font can either be a standard X11 core font (XLFD) name, with +optional prefix C or a Xft font (Compile xft), prefixed with C. + +In addition, each font can be prefixed with additional hints and +specifications enclosed in square brackets (C<[]>). The only available +hint currently is C, and this is only used for Xft +fonts. + +For example, this font resource + + 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, \ + xft:Code2000:antialias=false + +specifies five fonts to be used. The first one is C<9x15bold> (actually +the iso8859-1 version of the second font), which is the base font (because +it is named first) and thus defines the character cell grid to be 9 pixels +wide and 15 pixels high. + +the second font is just used to add additional unicode characters not in +the base font, likewise the third, which is unfortunately non-bold, but +the bold version of the font does contain less characters, so this is a +useful supplement. + +The third font is an Xft font with aliasing turned off, and the characters +are limited to the B codeset (i.e. japanese kanji). The font +contains other characters, but we are not interested in them. + +The last font is a useful catch-all font that supplies most of the +remaining unicode characters. -B: Enable "real bold" support. When this option is on, bold text -will be displayed using the first available bold font in the font list. -Bold fonts should thus be specified in the font list after their -corresponding regular fonts. If no bold font can be found, a regular -font will be used. option B<-rb>. B: Display bold text in a -regular font, using the color specified with B; option B<+rb>. +=item B I + +=item B I + +=item B I + +The font list to use for displaying B, I or B<< I >> characters, respectively. + +If specified and non-empty, then the syntax is the same as for the +B-resource, and the given font list will be used as is, which makes +it possible to substitute completely different font styles for bold and +italic. + +If unset (the default), a suitable font list will be synthesized by +"morphing" the normal text font list into the desired shape. If that is +not possible, replacement fonts of the desired shape will be tried. + +If set, but empty, then this specific style is disabled and the normal +text font will being used for the given style. =item B I @@ -467,8 +580,8 @@ =item B I -Set scrollbar style to B<@@RXVT_NAME@@>, B, B, B or -B +Set scrollbar style to B, B, B or B. B is +the author's favourite.. =item B I @@ -532,32 +645,22 @@ =item B I -B: scroll to bottom when tty receives output; option B<+si>. +B: scroll to bottom when tty receives output; option B<-si>. B: do not scroll to bottom when tty receives output; option -B<-si>. +B<+si>. =item B I -B: scroll with scrollback buffer when tty recieves new lines (and +B: scroll with scrollback buffer when tty receives new lines (and B is False); option B<+sw>. B: do not scroll with scrollback buffer when tty recieves new lines; option B<-sw>. =item B I -B: scroll to bottom when a non-special key is pressed. Special -keys are those which are intercepted by rxvt for special handling and -are not passed onto the shell; option B<-sk>. B: do not scroll -to bottom when a non-special key is pressed; option B<+sk>. - -=item B I - -If enabled, use B<@@HOTKEY@@->I to toggle to a smaller font -[default B<@@HOTKEY@@-@@SMALLFONT@@>] - -=item B I - -If enabled, use B<@@HOTKEY@@->I to toggle to a bigger font -[default B<@@HOTKEY@@-@@BIGFONT@@>] +B: scroll to bottom when a non-special key is pressed. Special keys +are those which are intercepted by rxvt-unicode for special handling and +are not passed onto the shell; option B<-sk>. B: do not scroll to +bottom when a non-special key is pressed; option B<+sk>. =item B I @@ -577,7 +680,7 @@ =item B I Set MWM hints to request a borderless window, i.e. if honoured by the -WM, the rxvt window will not have window decorations; option B<-bl>. +WM, the rxvt-unicode window will not have window decorations; option B<-bl>. =item B I @@ -657,11 +760,11 @@ extension to be able to input japanese characters while staying in another locale. option B<-imlocale>. -=item B +=item B I 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, wether +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 @@ -678,7 +781,7 @@ =item B I -Specify the reply rxvt sends to the shell when an ENQ (control-E) +Specify the reply rxvt-unicode sends to the shell when an ENQ (control-E) character is passed through. It may contain escape values as described in the entry on B following. @@ -745,6 +848,10 @@ double-click to select a word; Left triple-click to select the entire line. +Starting a selection while pressing the B key (or B keys) +(Compile: frills) will create a rectangular selection instead of a normal +one. + =item B: Pressing and releasing the Middle mouse button (or B) in @@ -755,26 +862,80 @@ =head1 CHANGING FONTS -You can change fonts on-the-fly, which is to say cycle through the -default font and others of various sizes, by using B and -B. Or, alternatively (if enabled) with -B<@@HOTKEY@@-@@BIGFONT@@> and B<@@HOTKEY@@-@@SMALLFONT@@>, where the -actual key can be selected using resources -B/B. +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.: + + printf '\e]701;%s\007' "9x15bold,xft:Kochi Gothic" + +rxvt-unicode will automatically re-apply these fonts to the output so far. =head1 ISO 14755 SUPPORT -Partial ISO 14755-support is implemented. that means that pressing +ISO 14755 is a standard for entering and viewing unicode characters +and character codes using the keyboard. It consists of 4 parts. The +first part is available rxvt-unicode has been compiled with +C<--enable-frills>, the rest is available when rxvt-unicode was compiled +with C<--enable-iso14755>. + +=over 4 + +=item 5.1: Basic method -Section 5.1: Control and Shift together enters unicode input -mode. Entering hex digits composes a Unicode character, pressing space or -releasing the modifiers commits the keycode and every other key cancels -the current input character. - -Section 5.2: Pressing and immediately releasing Control and Shift together -enters keycap entry mode for the next key: pressing a function key (tab, -return etc..) will enter the unicode character corresponding to the given -key. +This allows you to enter unicode characters using their hexcode. + +Start by pressing and holding both C and C, then enter +hex-digits (between one and six). Releasing C and C will +commit the character as if it were typed directly. While holding down +C and C you can also enter multiple characters by pressing +C, which will commit the current character and lets you start a new +one. + +As an example of use, imagine a business card with a japanese e-mail +address, which you cannot type. Fortunately, the card has the e-mail +address printed as hexcodes, e.g. C<671d 65e5>. You can enter this easily +by pressing C and C, followed by C<6-7-1-D-SPACE-6-5-E-5>, +followed by releasing the modifier keys. + +=item 5.2: Keyboard symbols entry method + +This mode lets you input characters representing the keycap symbols of +your keyboard, if representable in the current locale encoding. + +Start by pressing C and C together, then releasing +them. The next special key (cursor keys, home etc.) you enter will not +invoke it's usual function but instead will insert the corresponding +keycap symbol. The symbol will only be entered when the key has been +released, otherwise pressing e.g. C would enter the symbol for +C, although your intention might have been to enter a +reverse tab (Shift-Tab). + +=item 5.3: Screen-selection entry method + +While this is implemented already (it's basically the selection +mechanism), it could be extended by displaying a unicode character map. + +=item 5.4: Feedback method for identifying displayed characters for later input + +This method lets you display the unicode character code associated with +characters already displayed. + +You enter this mode by holding down C and C together, then +pressing and holding the left mouse button and moving around. The unicode +hex code(s) (it might be a combining character) of the character under the +pointer is displayed until you release C and C. + +In addition to the hex codes it will display the font used to draw this +character - due to implementation reasons, characters combined with +combining characters, line drawing characters and unknown characters will +always be drawn using the built-in support font. + +=back + +With respect to conformance, rxvt-unicode is supposed to be compliant to +both scenario A and B of ISO 14755, including part 5.2. =head1 LOGIN STAMP @@ -825,7 +986,7 @@ =over 4 -=item B +=item B<@@RXVT_NAME@@ -fg Black -bg White -rv> would yield White on Black, while on I(1) it would yield Black on White. @@ -855,11 +1016,9 @@ =back -=head1 SEEALSO - -I(1), I(1), I(1), I(1), I(4), I(4), I(5) +=head1 SEE ALSO -See rxvtRef.html rxvtRef.txt for detailed information on recognized escape sequences and menuBar syntax, etc. +@@RXVT_NAME@@(7), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5) =head1 BUGS @@ -875,11 +1034,11 @@ =item Project Coordinator -@@RXVTMAINT@@ L<@@RXVT_MAINTEMAIL@@> +@@RXVT_MAINT@@ L<@@RXVT_MAINTEMAIL@@> =item Web page maintainter -@@RXVTWEBMAINT@@ L<@@RXVT_WEBMAINTEMAIL@@> +@@RXVT_WEBMAINT@@ L<@@RXVT_WEBMAINTEMAIL@@> L<@@RXVT_WEBPAGE@@>