[ViewVC] Diff of: cvs/rxvt-unicode/doc/rxvt.1.pod

Comparing rxvt-unicode/doc/rxvt.1.pod (file contents):
Revision 1.3 by root, Thu Aug 12 22:22:30 2004 UTC vs.
Revision 1.12 by root, Mon Aug 16 02:09:28 2004 UTC

…		…
12	emulator intended as an I<xterm>(1) replacement for users who do not	12	emulator intended as an I<xterm>(1) replacement for users who do not
13	require features such as Tektronix 4014 emulation and toolkit-style	13	require features such as Tektronix 4014 emulation and toolkit-style
14	configurability. As a result, B<rxvt-unicode> uses much less swap space --	14	configurability. As a result, B<rxvt-unicode> uses much less swap space --
15	a significant advantage on a machine serving many X sessions.	15	a significant advantage on a machine serving many X sessions.
16		16
17	See also @@RXVT_NAME@@(7) for technical reference documentation (escape	17	=head1 RXVT-UNICODE VS. RXVT
18	sequences etc.) and the FAQ section at the end of this document.	18
		19	Unlike the original rxvt, B<rxvt-unicode> stores all text in Unicode
		20	internally. That means it can store and display most scripts in the
		21	world. Being a terminal emulator, however, some things are very difficult,
		22	especially cursive scripts such as arabic, vertically written scripts
		23	like mongolian or scripts requiring extremely complex combining rules,
		24	like tibetan or devenagari. Don't expect pretty output when using these
		25	scripts. Most other scripts, latin, cyrillic, kanji, thai etc. should work
		26	fine, though. A somewhat difficult case are left-to-right scripts, such
		27	as hebrew: B<rxvt-unicode> adopts the view that bidirectional algorithms
		28	belong into the application, not the terminal emulator (too many things --
		29	such as cursor-movement while editing -- break othwerwise), but that might
		30	change.
		31
		32	If you are looking for a terminal that supports more exotic scripts, let
		33	me recommend C<mlterm>, which is a very userfriendly, lean and clean
		34	terminal emulator. In fact, the reason rxvt-unicode was born was solely
		35	because the author couldn't get C<mlterm> to use one font for latin1 and
		36	another for japanese.
		37
		38	Therefore another design rationale was the use of multiple fonts to
		39	display characters: The idea of a single unicode font which many other
		40	programs force onto it's users never made sense to me: You should be able
		41	to choose any font for any script freely.
		42
		43	Apart from that, rxvt-unicode is also much better internationalised than
		44	it's predecessor, supports things such as XFT and ISO 14755 that are handy
		45	in i18n-environments, is faster, and has a lot less bugs than the original
		46	rxvt. This all in addition to dozens of other small improvements.
		47
		48	It is still faithfully following the original rxvt idea of being lean
		49	and nice on resources: for example, you can still configure rxvt-unicode
		50	without most of it's features to get a lean binary. It also comes with
		51	a client/daemon pair that lets you open any number of terminal windows
		52	from within a single process, which makes startup time very fast and
		53	drastically reduces memory usage. See @@RXVT_NAME@@d(1) (daemon) and
		54	@@RXVT_NAME@@c(1) (client).
		55
		56	It also makes technical information about escape sequences (which have
		57	been extended) easier accessible: see @@RXVT_NAME@@(7) for technical
		58	reference documentation (escape sequences etc.) and the FAQ section at the
		59	end of this document.
19		60
20	=head1 OPTIONS	61	=head1 OPTIONS
21		62
22	The B<@@RXVT_NAME@@> options (mostly a subset of I<xterm>'s) are listed	63	The B<@@RXVT_NAME@@> options (mostly a subset of I<xterm>'s) are listed
23	below. In keeping with the smaller-is-better philosophy, options may be	64	below. In keeping with the smaller-is-better philosophy, options may be
…		…
119	Select the fonts to be used. This is a comma seperated list of font	160	Select the fonts to be used. This is a comma seperated list of font
120	names that are used in turn when trying to display Unicode characters.	161	names that are used in turn when trying to display Unicode characters.
121	The first font defines the cell size for characters; other fonts might	162	The first font defines the cell size for characters; other fonts might
122	be smaller, but not larger. A reasonable default font list is always	163	be smaller, but not larger. A reasonable default font list is always
123	appended to it. resource B<font>.	164	appended to it. resource B<font>.
		165
		166	See also the question "How does rxvt-unicode choose fonts?" in the FAQ
		167	section.
124		168
125	=item B<-rb>\|B<+rb>	169	=item B<-rb>\|B<+rb>
126		170
127	Enable "real bold" support. When this option is on, bold text will be	171	Enable "real bold" support. When this option is on, bold text will be
128	displayed using the first available bold font in the font list. Bold	172	displayed using the first available bold font in the font list. Bold
…		…
530	Align the B<top>, B<bottom> or B<centre> [default] of the scrollbar	574	Align the B<top>, B<bottom> or B<centre> [default] of the scrollbar
531	thumb with the pointer on middle button press/drag.	575	thumb with the pointer on middle button press/drag.
532		576
533	=item B<scrollTtyOutput:> I<boolean>	577	=item B<scrollTtyOutput:> I<boolean>
534		578
535	B<True>: scroll to bottom when tty receives output; option B<+si>.	579	B<True>: scroll to bottom when tty receives output; option B<-si>.
536	B<False>: do not scroll to bottom when tty receives output; option	580	B<False>: do not scroll to bottom when tty receives output; option
537	B<-si>.	581	B<+si>.
538		582
539	=item B<scrollWithBuffer:> I<boolean>	583	=item B<scrollWithBuffer:> I<boolean>
540		584
541	B<True>: scroll with scrollback buffer when tty recieves new lines (and	585	B<True>: scroll with scrollback buffer when tty recieves new lines (and
542	B<scrollTtyOutput> is False); option B<+sw>. B<False>: do not scroll	586	B<scrollTtyOutput> is False); option B<+sw>. B<False>: do not scroll
…		…
546		590
547	B<True>: scroll to bottom when a non-special key is pressed. Special keys	591	B<True>: scroll to bottom when a non-special key is pressed. Special keys
548	are those which are intercepted by rxvt-unicode for special handling and	592	are those which are intercepted by rxvt-unicode for special handling and
549	are not passed onto the shell; option B<-sk>. B<False>: do not scroll to	593	are not passed onto the shell; option B<-sk>. B<False>: do not scroll to
550	bottom when a non-special key is pressed; option B<+sk>.	594	bottom when a non-special key is pressed; option B<+sk>.
551
552	=item B<smallfont_key:> I<keysym>
553
554	If enabled, use B<@@HOTKEY@@->I<keysym> to toggle to a smaller font
555	[default B<@@HOTKEY@@-@@SMALLFONT@@>]
556
557	=item B<bigfont_key:> I<keysym>
558
559	If enabled, use B<@@HOTKEY@@->I<keysym> to toggle to a bigger font
560	[default B<@@HOTKEY@@-@@BIGFONT@@>]
561		595
562	=item B<saveLines:> I<number>	596	=item B<saveLines:> I<number>
563		597
564	Save I<number> lines in the scrollback buffer [default 64]. This	598	Save I<number> lines in the scrollback buffer [default 64]. This
565	resource is limited on most machines to 65535; option B<-sl>.	599	resource is limited on most machines to 65535; option B<-sl>.
…		…
753		787
754	=back	788	=back
755		789
756	=head1 CHANGING FONTS	790	=head1 CHANGING FONTS
757		791
758	You can change fonts on-the-fly, which is to say cycle through the	792	Changing fonts (or font sizes, respectively) via the keypad is not yet
759	default font and others of various sizes, by using B<Shift-KP_Add> and	793	supported in rxvt-unicode. Bug me if you need this.
760	B<Shift-KP_Subtract>. Or, alternatively (if enabled) with	794
761	B<@@HOTKEY@@-@@BIGFONT@@> and B<@@HOTKEY@@-@@SMALLFONT@@>, where the	795	You can, however, switch fonts at runtime using escape sequences (and
762	actual key can be selected using resources	796	therefore using the menubar), e.g.:
763	B<smallfont_key>/B<bigfont_key>.	797
		798	printf '\e]701;%s\007' "9x15bold,xft:Kochi Gothic"
		799
		800	rxvt-unicode will automatically re-apply these fonts to the output so far.
764		801
765	=head1 ISO 14755 SUPPORT	802	=head1 ISO 14755 SUPPORT
766		803
767	Partial ISO 14755-support is implemented. that means that pressing	804	ISO 14755 is a standard for entering and viewing unicode characters
		805	and character codes using the keyboard. It consists of 4 parts. The
		806	first part is available rxvt-unicode has been compiled with
		807	C<--enable-frills>, the rest is available when rxvt-unicode was compiled
		808	with C<--enable-iso14755>.
768		809
769	Section 5.1: Control and Shift together enters unicode input	810	=over 4
770	mode. Entering hex digits composes a Unicode character, pressing space or
771	releasing the modifiers commits the keycode and every other key cancels
772	the current input character.
773		811
774	Section 5.2: Pressing and immediately releasing Control and Shift together	812	=item 5.1: Basic method
775	enters keycap entry mode for the next key: pressing a function key (tab,	813
776	return etc..) will enter the unicode character corresponding to the given	814	This allows you to enter unicode characters using their hexcode.
777	key.	815
		816	Start by pressing and holding both C<Control> and C<Shift>, then enter
		817	hex-digits (between one and six). Releasing C<Control> and C<Shift> will
		818	commit the character as if it were typed directly. While holding down
		819	C<Control> and C<Shift> you can also enter multiple characters by pressing
		820	C<Space>, which will commit the current character and lets you start a new
		821	one.
		822
		823	As an example of use, imagine a business card with a japanese e-mail
		824	address, which you cannot type. Fortunately, the card has the e-mail
		825	address printed as hexcodes, e.g. C<671d 65e5>. You can enter this easily
		826	by pressing C<Control> and C<Shift>, followed by C<6-7-1-D-SPACE-6-5-E-5>,
		827	followed by releasing the modifier keys.
		828
		829	=item 5.2: Keyboard symbols entry method
		830
		831	This mode lets you input characters representing the keycap symbols of
		832	your keyboard, if representable in the current locale encoding.
		833
		834	Start by pressing C<Control> and C<Shift> together, then releasing
		835	them. The next special key (cursor keys, home etc.) you enter will not
		836	invoke it's usual function but instead will insert the corresponding
		837	keycap symbol. The symbol will only be entered when the key has been
		838	released, otherwise pressing e.g. C<Shift> would enter the symbol for
		839	C<ISO Level 2 Switch>, although your intention might have beenm to enter a
		840	reverse tab (Shift-Tab).
		841
		842	=item 5.3: Screen-selection entry method
		843
		844	While this is implemented already (it's basically the selection
		845	mechanism), it could be extended by displaying a unicode character map.
		846
		847	=item 5.4: Feedback method for identifying displayed characters for later input
		848
		849	This method lets you display the unicode character code associated with
		850	characters already displayed.
		851
		852	You enter this mode by holding down C<Control> and C<Shift> together, then
		853	pressing and holding the left mouse button and moving around. The unicode
		854	hex code(s) (it might be a combining character) of the character under the
		855	pointer is displayed until you release C<Control> and C<Shift>.
		856
		857	=back
		858
		859	With respect to conformance, rxvt-unicode is supposed to be compliant to
		860	both scenario A and B of ISO 14755, including part 5.2.
778		861
779	=head1 LOGIN STAMP	862	=head1 LOGIN STAMP
780		863
781	B<@@RXVT_NAME@@> tries to write an entry into the I<utmp>(5) file so	864	B<@@RXVT_NAME@@> tries to write an entry into the I<utmp>(5) file so
782	that it can be seen via the I<who(1)> command, and can accept messages.	865	that it can be seen via the I<who(1)> command, and can accept messages.
…		…
830	would yield White on Black, while on I<xterm>(1) it would yield Black	913	would yield White on Black, while on I<xterm>(1) it would yield Black
831	on White.	914	on White.
832		915
833	=back	916	=back
834		917
835	=head1 ENVIRONMENT
836
837	B<@@RXVT_NAME@@> sets the environment variables B<TERM>, B<COLORTERM>
838	and B<COLORFGBG>. The environment variable B<WINDOWID> is set to the X
839	window id number of the B<@@RXVT_NAME@@> window and it also uses and
840	sets the environment variable B<DISPLAY> to specify which display
841	terminal to use. B<@@RXVT_NAME@@> uses the environment variables
842	B<RXVTPATH> and B<PATH> to find XPM files.
843
844	=head1 FILES
845
846	=over 4
847
848	=item B</etc/utmp>
849
850	System file for login records.
851
852	=item B</usr/lib/X11/rgb.txt>
853
854	Color names.
855
856	=back
857
858	=head1 FREQUENTLY ASKED QUESTIONS (FAQ)	918	=head1 FREQUENTLY ASKED QUESTIONS (FAQ)
859		919
860	=over 4	920	=over 4
861		921
862	=item How do I know which rxvt-unicode version I'm using?	922	=item How do I know which rxvt-unicode version I'm using?
863		923
864	The version number is displayed with the usage (-h). For rxvt-unicode	924	The version number is displayed with the usage (-h). For rxvt-unicode
865	version 2.14 and later, the escape sequence C<ESC[8n> sets the window	925	version 2.14 and later, the escape sequence C<ESC[8n> sets the window
866	title to the version number.	926	title to the version number.
		927
		928	=item Rxvt-unicode does not seem to understand the selected encoding?
		929
		930	=item Unicode does not seem to work?
		931
		932	If you encounter strange problems like typing an accented character but
		933	getting two unrelated other characters or similar, or if program output is
		934	subtly garbled, then you should check your locale settings.
		935
		936	Rxvt-unicode must be started with the same C<LC_CTYPE> setting as the
		937	programs. Often rxvt-unicode is started in the C<C> locale, while the
		938	login script running within the rxvt-unicode window changes the locale to
		939	sth. else, e.h. C<en_GB.UTF-8>. Needless to say, this is not going to work.
		940
		941	The best thing is to fix your startup environment, as you will likely run
		942	into other problems. If nothing works you can try this in your .profile.
		943
		944	printf '\e]701;%s\007' "$LC_CTYPE"
		945
		946	If this doesn't work, then maybe you use a C<LC_CTYPE> specification not
		947	supported on your systems. Some systems have a C<locale> comamnd which
		948	displays this. If it displays sth. like:
		949
		950	locale: Cannot set LC_CTYPE to default locale: ...
		951
		952	Then the locale you specified is not supported on your system.
		953
		954	If nothing works and you are sure that everything is set correctly then
		955	you will need to remember a little known fact: Some programs just don't
		956	support locales :(
		957
		958	=item Why do the characters look ugly?
		959
		960	=item How does rxvt-unicode choose fonts?
		961
		962	Most fonts do not contain the full range of Unicode, which is
		963	fine. Chances are that the font you (or the admin/package maintainer of
		964	your system/os) have specified does not cover all the characters you want
		965	to display.
		966
		967	B<rxvt-unicode> makes a best-effort try at finding a replacement
		968	font. Often the result is fine, but sometimes the chosen font looks
		969	bad. In that case, select a font of your taste and add it to the font
		970	list, e.g.:
		971
		972	@@RXVT_NAME@@ -fn basefont,font2,font3...
		973
		974	When rxvt-unicode sees a character, it will first look at the base
		975	font. If the base font does not contain the character, it will go to the
		976	next font, and so on.
		977
		978	The only limitation is that all the fonts must not be larger than the base
		979	font, as the base font defines the principial cell size, which must be the
		980	same due to the way terminals work.
		981
		982	=item Why do some chinese characters look so different than others?
		983
		984	This is because there is a difference between script and language --
		985	rxvt-unicode does not know which language the text that is output
		986	is, as it only knows the unicode character codes. If rxvt-unicode
		987	first sees a japanese character, it might choose a japanese font for
		988	it. Subseqzuent japanese characters will take that font. Now, many chinese
		989	characters aren't represented in japanese fonts, so when the first
		990	non-japanese character comes up, rxvt-unicode will look for a chinese font
		991	-- unfortunately at this point, it will still use the japanese font for
		992	japanese characters that are also chinese.
		993
		994	The workaround is easy: just tag a chinese font at the end of your font
		995	list (see the previous question). The key is to view the font list as
		996	a preference list: If you expect more japanese, list a japanese font
		997	first. If you expect more chinese, put a chinese font first.
		998
		999	In the future it might be possible to switch preferences at runtime (the
		1000	internal data structure has no problem with using different fonts for
		1001	the same character at the same time, but no interface for this has been
		1002	designed yet).
		1003
		1004	=item How does rxvt-unicode determine the encoding to use?
		1005
		1006	=item Is there an option to switch encodings?
		1007
		1008	Unlike some other terminals, rxvt-unicode has no encoding switch, and no
		1009	specific "utf-8" mode, such as xterm. In fact, it doesn't even know about
		1010	UTF-8 or any other encodings with respect to terminal I/O.
		1011
		1012	The reasons is that there exists a perfectly fine mechanism for selecting
		1013	the encoding, doing I/O and (most important) communicating this to all
		1014	applications so everybody agrees on character properties such as width and
		1015	code number. This mechanism is the I<locale>.
		1016
		1017	Rxvt-unicode uses the C<LC_CTYPE> locale category to select encoding. All
		1018	programs doing the same (that is, most) will automatically agree in the
		1019	interpretation of characters.
		1020
		1021	Unfortunately, there is no system-independent way to select locales, nor
		1022	is there a standard on how locale specifiers will look like.
		1023
		1024	On most systems, the content of the C<LC_CTYPE> environment variable
		1025	contains an arbitrary string which corresponds to an already-installed
		1026	locale. Common names for locales are C<en_US.UTF-8>, C<de_DE.ISO-8859-15>,
		1027	C<ja_JP.EUC-JP>, i.e. C<language_country.encoding>, but other forms
		1028	(i.e. C<de> or C<german>) are also common.
		1029
		1030	Rxvt-unicode ignores all other locale categories, and except for
		1031	the encoding, ignores country or language-specific settings,
		1032	i.e. C<de_DE.UTF-8> and C<ja_JP.UTF-8> are the same for rxvt-unicode.
		1033
		1034	If you want to use a specific encoding you have to make sure you start
		1035	rxvt-unicode with the correct C<LC_CTYPE> category.
		1036
		1037	=item Can I switch locales at runtime?
		1038
		1039	Yes, using an escape sequence. Try sth. like this, which sets
		1040	rxvt-unicode's idea of C<LC_CTYPE>.
		1041
		1042	printf '\e]701;%s\007' ja_JP.SJIS
		1043
		1044	See also the previous question.
		1045
		1046	Sometimes this capability is rather handy when you want to work in one
		1047	locale (e.g. C<de_DE.UTF-8>) but some programs don't support UTF-8. For
		1048	example, I use this script to start C<xjdic>, which first switches to a
		1049	locale supported by xjdic and back later:
		1050
		1051	printf '\e]701;%s\007' ja_JP.SJIS
		1052	xjdic -js
		1053	printf '\e]701;%s\007' de_DE.UTF-8
		1054
		1055	=item Can I switch the fonts at runtime?
		1056
		1057	Yes, using an escape sequence. Try sth. like this, which has the same
		1058	effect as using the C<-fn> switch, and takes effect immediately:
		1059
		1060	printf '\e]50;%s\007' "9x15bold,xft:Kochi Gothic"
		1061
		1062	This is useful if you e.g. work primarily with japanese (and prefer a
		1063	japanese font), but you have to switch to chinese temporarily, where
		1064	japanese fonts would only be in your way.
		1065
		1066	You can think of this as a kind of manual ISO-2022 switching.
867		1067
868	=item Mouse cut/paste suddenly no longer works.	1068	=item Mouse cut/paste suddenly no longer works.
869		1069
870	Make sure that mouse reporting is actually turned off since killing	1070	Make sure that mouse reporting is actually turned off since killing
871	some editors prematurely may leave the mouse in mouse report mode. I've	1071	some editors prematurely may leave the mouse in mouse report mode. I've
…		…
1074	one that comes with F<pod2man>, F<pod2text> and F<pod2html>. Then go to	1274	one that comes with F<pod2man>, F<pod2text> and F<pod2html>. Then go to
1075	the doc subdirectory and enter C<make alldoc>.	1275	the doc subdirectory and enter C<make alldoc>.
1076		1276
1077	=back	1277	=back
1078		1278
		1279	=head1 ENVIRONMENT
		1280
		1281	B<@@RXVT_NAME@@> sets the environment variables B<TERM>, B<COLORTERM>
		1282	and B<COLORFGBG>. The environment variable B<WINDOWID> is set to the X
		1283	window id number of the B<@@RXVT_NAME@@> window and it also uses and
		1284	sets the environment variable B<DISPLAY> to specify which display
		1285	terminal to use. B<@@RXVT_NAME@@> uses the environment variables
		1286	B<RXVTPATH> and B<PATH> to find XPM files.
		1287
		1288	=head1 FILES
		1289
		1290	=over 4
		1291
		1292	=item B</etc/utmp>
		1293
		1294	System file for login records.
		1295
		1296	=item B</usr/lib/X11/rgb.txt>
		1297
		1298	Color names.
		1299
		1300	=back
		1301
1079	=head1 SEE ALSO	1302	=head1 SEE ALSO
1080		1303
1081	@@RXVT_NAME@@(7), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5)	1304	@@RXVT_NAME@@(7), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5)
1082		1305
1083	=head1 BUGS	1306	=head1 BUGS
…		…
1092		1315
1093	=over 4	1316	=over 4
1094		1317
1095	=item Project Coordinator	1318	=item Project Coordinator
1096		1319
1097	@@RXVTMAINT@@ L<@@RXVT_MAINTEMAIL@@>	1320	@@RXVT_MAINT@@ L<@@RXVT_MAINTEMAIL@@>
1098		1321
1099	=item Web page maintainter	1322	=item Web page maintainter
1100		1323
1101	@@RXVTWEBMAINT@@ L<@@RXVT_WEBMAINTEMAIL@@>	1324	@@RXVT_WEBMAINT@@ L<@@RXVT_WEBMAINTEMAIL@@>
1102		1325
1103	L<@@RXVT_WEBPAGE@@>	1326	L<@@RXVT_WEBPAGE@@>
1104		1327
1105	=back	1328	=back
1106		1329

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing rxvt-unicode/doc/rxvt.1.pod (file contents): Revision 1.3 by root, Thu Aug 12 22:22:30 2004 UTC vs. Revision 1.12 by root, Mon Aug 16 02:09:28 2004 UTC

Diff Legend

Comparing rxvt-unicode/doc/rxvt.1.pod (file contents):
Revision 1.3 by root, Thu Aug 12 22:22:30 2004 UTC vs.
Revision 1.12 by root, Mon Aug 16 02:09:28 2004 UTC