--- rxvt-unicode/doc/rxvt.1.pod 2004/08/12 22:22:30 1.3 +++ rxvt-unicode/doc/rxvt.1.pod 2004/08/16 02:09:28 1.12 @@ -14,8 +14,49 @@ 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.) and the FAQ section at the end of this document. +=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 othwerwise), 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.) and the FAQ section at the +end of this document. =head1 OPTIONS @@ -122,6 +163,9 @@ be smaller, but not larger. A reasonable default font list is always appended to it. resource B. +See also the question "How does rxvt-unicode choose fonts?" in the FAQ +section. + =item B<-rb>|B<+rb> Enable "real bold" support. When this option is on, bold text will be @@ -532,9 +576,9 @@ =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 @@ -549,16 +593,6 @@ 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@@>] - =item B I Save I lines in the scrollback buffer [default 64]. This @@ -755,26 +789,75 @@ =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 + +This allows you to enter unicode characters using their hexcode. -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. +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 beenm 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. + +=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 @@ -832,38 +915,155 @@ =back -=head1 ENVIRONMENT +=head1 FREQUENTLY ASKED QUESTIONS (FAQ) -B<@@RXVT_NAME@@> sets the environment variables B, B -and B. The environment variable B is set to the X -window id number of the B<@@RXVT_NAME@@> window and it also uses and -sets the environment variable B to specify which display -terminal to use. B<@@RXVT_NAME@@> uses the environment variables -B and B to find XPM files. +=over 4 -=head1 FILES +=item How do I know which rxvt-unicode version I'm using? -=over 4 +The version number is displayed with the usage (-h). For rxvt-unicode +version 2.14 and later, the escape sequence C sets the window +title to the version number. -=item B +=item Rxvt-unicode does not seem to understand the selected encoding? -System file for login records. +=item Unicode does not seem to work? -=item B +If you encounter strange problems like typing an accented character but +getting two unrelated other characters or similar, or if program output is +subtly garbled, then you should check your locale settings. -Color names. +Rxvt-unicode must be started with the same C setting as the +programs. Often rxvt-unicode is started in the C locale, while the +login script running within the rxvt-unicode window changes the locale to +sth. else, e.h. C. Needless to say, this is not going to work. -=back +The best thing is to fix your startup environment, as you will likely run +into other problems. If nothing works you can try this in your .profile. -=head1 FREQUENTLY ASKED QUESTIONS (FAQ) + printf '\e]701;%s\007' "$LC_CTYPE" -=over 4 +If this doesn't work, then maybe you use a C specification not +supported on your systems. Some systems have a C comamnd which +displays this. If it displays sth. like: -=item How do I know which rxvt-unicode version I'm using? + locale: Cannot set LC_CTYPE to default locale: ... -The version number is displayed with the usage (-h). For rxvt-unicode -version 2.14 and later, the escape sequence C sets the window -title to the version number. +Then the locale you specified is not supported on your system. + +If nothing works and you are sure that everything is set correctly then +you will need to remember a little known fact: Some programs just don't +support locales :( + +=item Why do the characters look ugly? + +=item How does rxvt-unicode choose fonts? + +Most fonts do not contain the full range of Unicode, which is +fine. Chances are that the font you (or the admin/package maintainer of +your system/os) have specified does not cover all the characters you want +to display. + +B makes a best-effort try at finding a replacement +font. Often the result is fine, but sometimes the chosen font looks +bad. In that case, select a font of your taste and add it to the font +list, e.g.: + + @@RXVT_NAME@@ -fn basefont,font2,font3... + +When rxvt-unicode sees a character, it will first look at the base +font. If the base font does not contain the character, it will go to the +next font, and so on. + +The only limitation is that all the fonts must not be larger than the base +font, as the base font defines the principial cell size, which must be the +same due to the way terminals work. + +=item Why do some chinese characters look so different than others? + +This is because there is a difference between script and language -- +rxvt-unicode does not know which language the text that is output +is, as it only knows the unicode character codes. If rxvt-unicode +first sees a japanese character, it might choose a japanese font for +it. Subseqzuent japanese characters will take that font. Now, many chinese +characters aren't represented in japanese fonts, so when the first +non-japanese character comes up, rxvt-unicode will look for a chinese font +-- unfortunately at this point, it will still use the japanese font for +japanese characters that are also chinese. + +The workaround is easy: just tag a chinese font at the end of your font +list (see the previous question). The key is to view the font list as +a preference list: If you expect more japanese, list a japanese font +first. If you expect more chinese, put a chinese font first. + +In the future it might be possible to switch preferences at runtime (the +internal data structure has no problem with using different fonts for +the same character at the same time, but no interface for this has been +designed yet). + +=item How does rxvt-unicode determine the encoding to use? + +=item Is there an option to switch encodings? + +Unlike some other terminals, rxvt-unicode has no encoding switch, and no +specific "utf-8" mode, such as xterm. In fact, it doesn't even know about +UTF-8 or any other encodings with respect to terminal I/O. + +The reasons is that there exists a perfectly fine mechanism for selecting +the encoding, doing I/O and (most important) communicating this to all +applications so everybody agrees on character properties such as width and +code number. This mechanism is the I. + +Rxvt-unicode uses the C locale category to select encoding. All +programs doing the same (that is, most) will automatically agree in the +interpretation of characters. + +Unfortunately, there is no system-independent way to select locales, nor +is there a standard on how locale specifiers will look like. + +On most systems, the content of the C environment variable +contains an arbitrary string which corresponds to an already-installed +locale. Common names for locales are C, C, +C, i.e. C, but other forms +(i.e. C or C) are also common. + +Rxvt-unicode ignores all other locale categories, and except for +the encoding, ignores country or language-specific settings, +i.e. C and C are the same for rxvt-unicode. + +If you want to use a specific encoding you have to make sure you start +rxvt-unicode with the correct C category. + +=item Can I switch locales at runtime? + +Yes, using an escape sequence. Try sth. like this, which sets +rxvt-unicode's idea of C. + + printf '\e]701;%s\007' ja_JP.SJIS + +See also the previous question. + +Sometimes this capability is rather handy when you want to work in one +locale (e.g. C) but some programs don't support UTF-8. For +example, I use this script to start C, which first switches to a +locale supported by xjdic and back later: + + printf '\e]701;%s\007' ja_JP.SJIS + xjdic -js + printf '\e]701;%s\007' de_DE.UTF-8 + +=item Can I switch the fonts at runtime? + +Yes, using an escape sequence. Try sth. like this, which has the same +effect as using the C<-fn> switch, and takes effect immediately: + + printf '\e]50;%s\007' "9x15bold,xft:Kochi Gothic" + +This is useful if you e.g. work primarily with japanese (and prefer a +japanese font), but you have to switch to chinese temporarily, where +japanese fonts would only be in your way. + +You can think of this as a kind of manual ISO-2022 switching. =item Mouse cut/paste suddenly no longer works. @@ -1076,6 +1276,29 @@ =back +=head1 ENVIRONMENT + +B<@@RXVT_NAME@@> sets the environment variables B, B +and B. The environment variable B is set to the X +window id number of the B<@@RXVT_NAME@@> window and it also uses and +sets the environment variable B to specify which display +terminal to use. B<@@RXVT_NAME@@> uses the environment variables +B and B to find XPM files. + +=head1 FILES + +=over 4 + +=item B + +System file for login records. + +=item B + +Color names. + +=back + =head1 SEE ALSO @@RXVT_NAME@@(7), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5) @@ -1094,11 +1317,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@@>