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

Comparing rxvt-unicode/doc/rxvt.7.pod (file contents):
Revision 1.177 by root, Sat May 30 08:53:48 2009 UTC vs.
Revision 1.206 by sf-exg, Sat Dec 11 22:59:02 2010 UTC

 This tries to create a new terminal, and if fails with exit status 2,
 meaning it couldn't connect to the daemon, it will start the daemon and
 re-run the command. Subsequent invocations of the script will re-use the
 existing daemon.
-=head3 How do I distinguish whether I'm running rxvt-unicode or a regular xterm? I need this to decide about setting colors etc.
+=head3 How do I distinguish whether I'm running rxvt-unicode or a regular
+xterm? I need this to decide about setting colours etc.
 The original rxvt and rxvt-unicode always export the variable "COLORTERM",
 so you can check and see if that is set. Note that several programs, JED,
 slrn, Midnight Commander automatically check this variable to decide
-whether or not to use color.
+whether or not to use colour.
 =head3 How do I set the correct, full IP address for the DISPLAY variable?
 If you've compiled rxvt-unicode with DISPLAY_IS_IP and have enabled
 insecure mode then it is possible to use the following shell script
 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
+in C that use gobs of memory, and 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)
 =head2 Rendering, Font & Look and Feel Issues
 =head3 I can't get transparency working, what am I doing wrong?
-First of all, please address all transparency related issues to Sasha Vasko at
+First of all, transparency isn't officially supported in rxvt-unicode, so
-sasha@aftercode.net and do not bug the author about it. Also, if you can't
+you are mostly on your own. Do not bug the author about it (but you may
-get it working consider it a rite of passage: ... and you failed.
+bug everybody else). Also, if you can't get it working consider it a rite
+of passage: ... and you failed.
 Here are four ways to get transparency. B<Do> read the manpage and option
 descriptions for the programs mentioned and rxvt-unicode. Really, do it!
 1. Use transparent mode:
    Esetroot wallpaper.jpg
    @@URXVT_NAME@@ -tr -tint red -sh 40
 That works. If you think it doesn't, you lack transparency and tinting
 support, or you are unable to read.
+This method requires that the background-setting program sets the
+_XROOTPMAP_ID or ESETROOT_PMAP_ID property. Compatible programs
+are Esetroot, hsetroot and feh.
 2. Use a simple pixmap and emulate pseudo-transparency. This enables you
 to use effects other than tinting and shading: Just shade/tint/whatever
 your picture with gimp or any other tool:
    convert wallpaper.jpg -blur 20x20 -modulate 30 background.jpg
    @@URXVT_NAME@@ -pixmap "background.jpg;:root"
-That works. If you think it doesn't, you lack AfterImage support, or you
+That works. If you think it doesn't, you lack libAfterImage or GDK-PixBuf support, or you
 are unable to read.
 3. Use an ARGB visual:
    @@URXVT_NAME@@ -depth 32 -fg grey90 -bg rgba:0000/0000/4444/cccc
 For the standard background colour, blinking will actually make
 the text blink when compiled with C<--enable-text-blink>. Without
 C<--enable-text-blink>, the blink attribute will be ignored.
 On ANSI colours, bold/blink attributes are used to set high-intensity
-foreground/background colors.
+foreground/background colours.
-color0-7 are the low-intensity colors.
+color0-7 are the low-intensity colours.
-color8-15 are the corresponding high-intensity colors.
+color8-15 are the corresponding high-intensity colours.
-=head3 I don't like the screen colors.  How do I change them?
+=head3 I don't like the screen colours.  How do I change them?
-You can change the screen colors at run-time using F<~/.Xdefaults>
+You can change the screen colours at run-time using F<~/.Xdefaults>
 resources (or as long-options).
 Here are values that are supposed to resemble a VGA screen,
 including the murky brown that passes for low-intensity yellow:
    URxvt.color12:  #0000FF
    URxvt.color13:  #FF00FF
    URxvt.color14:  #00FFFF
    URxvt.color15:  #FFFFFF
-And here is a more complete set of non-standard colors.
+And here is a more complete set of non-standard colours.
    URxvt.cursorColor:  #dc74d1
    URxvt.pointerColor: #dc74d1
    URxvt.background:   #0e0e0e
    URxvt.foreground:   #4ad5e1
 rxvt-unicode will continue without an input method.
 In this case either do not specify a B<preeditStyle> or specify more than
 one pre-edit style, such as B<OverTheSpot,Root,None>.
+If it still doesn't work, then maybe your input method doesn't support
+compose sequences - to fall back to the built-in one, make sure you don't
+specify an input method via C<-im> or C<XMODIFIERS>.
 =head3 I cannot type C<Ctrl-Shift-2> to get an ASCII NUL character due to ISO 14755
 Either try C<Ctrl-2> alone (it often is mapped to ASCII NUL even on
 international keyboards) or simply use ISO 14755 support to your
 advantage, typing <Ctrl-Shift-0> to get a ASCII NUL. This works for other
 Historically, either value is correct, but rxvt-unicode adopts the debian
 policy of using C<^?> when unsure, because it's the one and only correct
 choice :).
-Rxvt-unicode tries to inherit the current stty settings and uses the value
+It is possible to toggle between C<^H> and C<^?> with the DECBKM
-of `erase' to guess the value for backspace.  If rxvt-unicode wasn't
+private mode:
-started from a terminal (say, from a menu or by remote shell), then the
-system value of `erase', which corresponds to CERASE in <termios.h>, will
-be used (which may not be the same as your stty setting).
-For starting a new rxvt-unicode:
    # use Backspace = ^H
    $ stty erase ^H
-   $ @@URXVT_NAME@@
+   $ echo -n "^[[?67h"
    # use Backspace = ^?
    $ stty erase ^?
-   $ @@URXVT_NAME@@
-Toggle with C<ESC [ 36 h> / C<ESC [ 36 l>.
-For an existing rxvt-unicode:
-   # use Backspace = ^H
-   $ stty erase ^H
-   $ echo -n "^[[36h"
-   # use Backspace = ^?
-   $ stty erase ^?
-   $ echo -n "^[[36l"
+   $ echo -n "^[[?67l"
 This helps satisfy some of the Backspace discrepancies that occur, but
 if you use Backspace = C<^H>, make sure that the termcap/terminfo value
 properly reflects that.
 develop for myself mostly, so I actually use most of the extensions I
 write.
 The selection stuff mainly makes the selection perl-error-message aware
 and tells it to convert perl error messages into vi-commands to load the
-relevant file and go tot he error line number.
+relevant file and go to the error line number.
    URxvt.scrollstyle:      plain
    URxvt.secondaryScroll:  true
 As the documentation says: plain is the preferred scrollbar for the
 purposes, it works, and gives a different look, as my normal (Non-bold)
 font is already bold, and I want to see a difference between bold and
 normal fonts.
 Please note that I used the C<urxvt> instance name and not the C<URxvt>
-class name. Thats because I use different configs for different purposes,
+class name. That is because I use different configs for different purposes,
 for example, my IRC window is started with C<-name IRC>, and uses these
 defaults:
    IRC*title:              IRC
    IRC*geometry:           87x12+535+542
 stuff while keeping a very small window. If somebody pastes something
 complicated (e.g. japanese), I temporarily switch to a larger font.
 The above is all in my C<.Xdefaults> (I don't use C<.Xresources> nor
 C<xrdb>). I also have some resources in a separate C<.Xdefaults-hostname>
-file for different hosts, for example, on ym main desktop, I use:
+file for different hosts, for example, on my main desktop, I use:
    URxvt.keysym.C-M-q: command:\033[3;5;5t
    URxvt.keysym.C-M-y: command:\033[3;5;606t
    URxvt.keysym.C-M-e: command:\033[3;1605;5t
    URxvt.keysym.C-M-c: command:\033[3;1605;606t
 runtime-switchable, too, so there is usually no drawback to enabling 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<perl-ext-common> snd C<perl-ext> resources
+You should not overwrite the C<perl-ext-common> and C<perl-ext> resources
 system-wide (except maybe with C<defaults>). This will result in useful
 behaviour. If your distribution aims at low memory, add an empty
 C<perl-ext-common> resource to the app-defaults file. This will keep the
 perl interpreter disabled until the user enables it.
 The solution is to upgrade your system or switch to a better one. A
 possibly working workaround is to use a wcwidth implementation like
 http://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c
-=head3 I want 256 colors
-Are you sure you need 256 colors? 88 colors should be enough for most
-purposes. If you really need more, there is an unsupported patch for
-it in the doc directory, but please do not ask for it to be applied.
 =head1 RXVT-UNICODE TECHNICAL REFERENCE
 The rest of this document describes various technical aspects of
 B<rxvt-unicode>. First the description of supported command sequences,
 followed by pixmap support and last by a description of all features
 =over 4
 =item B<< C<c> >>
-The literal character c.
+The literal character c (potentially a multi-byte character).
 =item B<< C<C> >>
 A single (required) character.
 =item B<< C<ESC => >>
 Application Keypad (SMKX). See also next sequence.
-=item B<<< C<< ESC >> >>>
+=item B<<< C<< ESC > >> >>>
 Normal Keypad (RMKX)
 B<Note:> If the numeric keypad is activated, eg, B<Num_Lock> has been
 pressed, numbers or control functions are generated by the numeric keypad
 	B<< C<Ps = 32 / 42> >>	fg/bg Green
 	B<< C<Ps = 33 / 43> >>	fg/bg Yellow
 	B<< C<Ps = 34 / 44> >>	fg/bg Blue
 	B<< C<Ps = 35 / 45> >>	fg/bg Magenta
 	B<< C<Ps = 36 / 46> >>	fg/bg Cyan
-	B<< C<Ps = 38;5 / 48;5> >>	set fg/bg to color #m (ISO 8613-6)
+	B<< C<Ps = 38;5 / 48;5> >>	set fg/bg to colour #m (ISO 8613-6)
 	B<< C<Ps = 37 / 47> >>	fg/bg White
 	B<< C<Ps = 39 / 49> >>	fg/bg Default
 	B<< C<Ps = 90 / 100> >>	fg/bg Bright Black
 	B<< C<Ps = 91 / 101> >>	fg/bg Bright Red
 	B<< C<Ps = 92 / 102> >>	fg/bg Bright Green
 =item B<< C<Pm = 66> >>
 =begin table
-	B<< C<h> >>	Application Keypad (DECPAM) == C<ESC =>
+	B<< C<h> >>	Application Keypad (DECKPAM/DECPAM) == C<ESC =>
-	B<< C<l> >>	Normal Keypad (DECPNM) == C<< ESC > >>
+	B<< C<l> >>	Normal Keypad (DECKPNM/DECPNM) == C<< ESC > >>
 =end table
 =item B<< C<Pm = 67> >>
 	B<< C<h> >>	Send Mouse X & Y on button press and release, and motion.
 	B<< C<l> >>	No mouse reporting.
 =end table
+=item B<< C<Pm = 1005> >> (X11 XTerm) (Compile frills)
+Try to avoid this mode, it doesn't work sensibly in non-UTF-8 locales. Use
+mode C<1015> instead.
+Unlike XTerm, coordinates larger than 2015) will work fine.
+=begin table
+	B<< C<h> >>	Enable mouse coordinates in locale-specific encoding.
+	B<< C<l> >>	Enable mouse coordinates as binary octets.
+=end table
 =item B<< C<Pm = 1010> >> (B<rxvt>)
 =begin table
 	B<< C<h> >>	Don't scroll to bottom on TTY output
 =begin table
 	B<< C<h> >>	Scroll to bottom when a key is pressed
 	B<< C<l> >>	Don't scroll to bottom when a key is pressed
+=end table
+=item B<< C<Pm = 1015> >> (B<rxvt-unicode>) (Compile frills)
+Changes all mouse reporting codes to use decimal parameters instead of
+octets or characters.
+This mode should be enabled I<before> actually enabling mouse reporting,
+for semi-obvious reasons.
+The sequences received for various modes are as follows:
+   ESC [ M o o o    !1005, !1015 (three octets)
+   ESC [ M c c c    1005, !1015 (three characters)
+   ESC [ Pm M       1015 (three or more numeric paramaters)
+The three parameters are C<code>, C<x> and C<y>. Code is the numeric code
+as for the other modes (but encoded as a decimal number), C<x> and C<y>
+are the coordinates (1|1 is the upper left corner, just as with cursor
+positioning).
+Example: Shift-Button-1 press at top row, column 80.
+   ESC [ 5 ; 80 ; 1 M
+One can use this feature by simply enabling it and then looking for
+parameters to the C<ESC [ M> reply - if there are any, this mode is
+active, otherwise one of the old reporting styles is used.
+Other (to be implemented) reply sequences will use a similar encoding.
+In the future, more parameters might get added (pixel coordinates for
+example - anybody out there who needs this?).
+=begin table
+	B<< C<h> >>	Enable new mouse coordinate reporting.
+	B<< C<l> >>	Use old-style C<CSI M C C C> encoding.
 =end table
 =item B<< C<Pm = 1021> >> (B<rxvt>)
 	B<< C<Ps = 4> >>	B<< C<Pt> >> is a semi-colon separated sequence of one or more semi-colon separated B<number>/B<name> pairs, where B<number> is an index to a colour and B<name> is the name of a colour. Each pair causes the B<number>ed colour to be changed to B<name>. Numbers 0-7 corresponds to low-intensity (normal) colours and 8-15 corresponds to high-intensity colours. 0=black, 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan, 7=white
 	B<< C<Ps = 10> >>	Change colour of text foreground to B<< C<Pt> >>
 	B<< C<Ps = 11> >>	Change colour of text background to B<< C<Pt> >>
 	B<< C<Ps = 12> >>	Change colour of text cursor foreground to B<< C<Pt> >>
 	B<< C<Ps = 13> >>	Change colour of mouse foreground to B<< C<Pt> >>
-	B<< C<Ps = 17> >>	Change colour of highlight characters to B<< C<Pt> >>
+	B<< C<Ps = 17> >>	Change background colour of highlight characters to B<< C<Pt> >>
-	B<< C<Ps = 18> >>	Change colour of bold characters to B<< C<Pt> >> [deprecated, see 706]
+	B<< C<Ps = 19> >>	Change foreground colour of highlight characters to B<< C<Pt> >>
-	B<< C<Ps = 19> >>	Change colour of underlined characters to B<< C<Pt> >> [deprecated, see 707]
-	B<< C<Ps = 20> >>	Change background pixmap parameters (see section BACKGROUND IMAGE) (Compile AfterImage).
+	B<< C<Ps = 20> >>	Change background pixmap parameters (see section BACKGROUND IMAGE) (Compile afterimage or pixbuf).
 	B<< C<Ps = 39> >>	Change default foreground colour to B<< C<Pt> >>. [deprecated, use 10]
 	B<< C<Ps = 46> >>	Change Log File to B<< C<Pt> >> I<unimplemented>
 	B<< C<Ps = 49> >>	Change default background colour to B<< C<Pt> >>. [deprecated, use 11]
 	B<< C<Ps = 50> >>	Set fontset to B<< C<Pt> >>, with the following special values of B<< C<Pt> >> (B<rxvt>) B<< C<#+n> >> change up B<< C<n> >> B<< C<#-n> >> change down B<< C<n> >> if B<< C<n> >> is missing of 0, a value of 1 is used I<empty> change to font0 B<< C<n> >> change to font B<< C<n> >>
 	B<< C<Ps = 55> >>	Log all scrollback buffer and all of screen to B<< C<Pt> >> [disabled]
 =back
 =head1 BACKGROUND IMAGE
 For the BACKGROUND IMAGE XTerm escape sequence B<< C<ESC ] 20 ; Pt ST> >> the value
-of B<< C<Pt> >> can be the name of the background image file followed by a
+of B<< C<Pt> >> can be one of the following commands:
-sequence of scaling/positioning commands separated by semi-colons. The
-scaling/positioning commands are as follows:
 =over 4
-=item query scale/position
+=item B<< C<?> >>
-B<?>
+display scale and position in the title
+=item B<< C<;WxH+X+Y> >>
-=item change scale and position
+change scale and/or position
-B<WxH+X+Y>
+=item B<< C<FILE;WxH+X+Y> >>
-B<WxH+X> (== B<WxH+X+X>)
+change background image
-B<WxH> (same as B<WxH+50+50>)
-B<W+X+Y> (same as B<WxW+X+Y>)
-B<W+X> (same as B<WxW+X+X>)
-B<W> (same as B<WxW+50+50>)
-=item change position (absolute)
-B<=+X+Y>
-B<=+X> (same as B<=+X+Y>)
-=item change position (relative)
-B<+X+Y>
-B<+X> (same as B<+X+Y>)
-=item rescale (relative)
-B<Wx0> -> B<W *= (W/100)>
-B<0xH> -> B<H *= (H/100)>
-=back
-For example:
-=over 4
-=item B<\E]20;funky.jpg\a>
-load B<funky.jpg> as a tiled image
-=item B<\E]20;mona.jpg;100\a>
-load B<mona.jpg> with a scaling of 100%
-=item B<\E]20;;200;?\a>
-rescale the current pixmap to 200% and display the image geometry in
-the title
 =back
 X<Mouse>
 Note: B<Shift> + B<F1>-B<F10> generates B<F11>-B<F20>
 For the keypad, use B<Shift> to temporarily override Application-Keypad
 setting use B<Num_Lock> to toggle Application-Keypad setting if
 B<Num_Lock> is off, toggle Application-Keypad setting. Also note that
-values of B<Home>, B<End>, B<Delete> may have been compiled differently on
+values of B<BackSpace>, B<Delete> may have been compiled differently on
 your system.
 =begin table
 		B<Normal>	B<Shift>	B<Control>	B<Ctrl+Shift>
 =over 4
 =item --enable-everything
-Add (or remove) support for all non-multichoice options listed in "./configure
+Add (or remove) support for all non-multichoice options listed
---help".
+in C<./configure --help>, except for C<--enable-assert> and
+C<--enable-256-color>.
 You can specify this and then disable options you do not like by
 I<following> this with the appropriate C<--disable-...> arguments,
 or you can start with a minimal configuration by specifying
 C<--disable-everything> and than adding just the C<--enable-...> arguments
 you want.
 =item --enable-xft (default: enabled)
-Add support for Xft (anti-aliases, among others) fonts. Xft fonts are
+Add support for Xft (anti-aliased, among others) fonts. Xft fonts are
 slower and require lots of memory, but as long as you don't use them, you
 don't pay for them.
 =item --enable-font-styles (default: on)
 =item --enable-combining (default: on)
 Enable automatic composition of combining characters into
 composite characters. This is required for proper viewing of text
-where accents are encoded as seperate unicode characters. This is
+where accents are encoded as separate unicode characters. This is
 done by using precomposited characters when available or creating
 new pseudo-characters when no precomposed form exists.
 Without --enable-unicode3, the number of additional precomposed
 characters is somewhat limited (the 6400 private use characters will be
 F<lastlogin>) at start of rxvt execution.  This option requires
 --enable-utmp to also be specified.
 =item --enable-afterimage (default: on)
-Add support for libAfterImage to be used for transparency and background
+Add support for libAfterImage to be used for background
 images. It adds support for many file formats including JPG, PNG,
 SVG, TIFF, GIF, XPM, BMP, ICO, XCF, TGA and AfterStep image XML
 (L<http://www.afterstep.org/visualdoc.php?show=asimagexml>).
-This option also adds such eye candy as blending an image over the root
-background, as well as dynamic scaling and bluring of background images.
 Note that with this option enabled, @@RXVT_NAME@@'s memory footprint might
 increase by a few megabytes even if no extra features are used (mostly due
 to third-party libraries used by libAI). Memory footprint may somewhat be
 lowered if libAfterImage is configured without support for SVG.
+=item --enable-pixbuf (default: off)
+Add support for GDK-PixBuf to be used for background images.
+It adds support for many file formats including JPG, PNG,
+TIFF, GIF, XPM, BMP, ICO and TGA.
 =item --enable-transparency (default: on)
-Add support for backgrounds, creating illusion of transparency in the term.
+Add support for using the root pixmap as background to simulate transparency.
+Note that blur and blend effects depend on libAfterImage or on
+libXrender and on the availability of the RENDER extension in the X
+server.
 =item --enable-fading (default: on)
 Add support for fading the text when focus is lost.
 in combination with other switches) is:
   MWM-hints
   EWMH-hints (pid, utf8 names) and protocols (ping)
   urgency hint
-  seperate underline colour (-underlineColor)
+  separate underline colour (-underlineColor)
   settable border widths and borderless switch (-w, -b, -bl)
   visual depth selection (-depth)
-  settable extra linespacing /-lsp)
+  settable extra linespacing (-lsp)
   iso-14755 5.1 (basic) support
   tripleclickwords (-tcw)
   settable insecure mode (-insecure)
   keysym remapping support
   cursor blinking and underline cursor (-bc, -uc)
   XEmbed support (-embed)
   user-pty (-pty-fd)
   hold on exit (-hold)
   compile in built-in block graphics
   skip builtin block graphics (-sbg)
-  separate highlightcolor support (-hc)
+  separate highlight colour (-highlightColor, -highlightTextColor)
+  extended mouse reporting modes (1005 and 1015).
 It also enables some non-essential features otherwise disabled, such as:
   some round-trip time optimisations
-  nearest color allocation on pseudocolor screens
+  nearest colour allocation on pseudocolor screens
   UTF8_STRING support for selection
   sgr modes 90..97 and 100..107
   backindex and forwardindex escape sequences
   view change/zero scrollback escape sequences
   locale switching escape sequence
 environment variable when running configure. Even when compiled in,
 perl will I<not> be initialised when all extensions have been disabled
 C<-pe "" --perl-ext-common "">, so it should be safe to enable from a
 resource standpoint.
+=item --enable-assert (default: off)
+Enables the assertions in the code, normally disabled. This switch is only
+useful when developing rxvt-unicode.
+=item --enable-256-color (default: off)
+Force use of so-called 256 colour mode, to work around buggy applications
+that do not support termcap/terminfo, or simply improve support for
+applications hardcoding the xterm 256 colour table.
+This switch breaks termcap/terminfo compatibility to C<TERM=rxvt-unicode>,
+and consequently sets C<TERM> to C<rxvt-unicode-256color> by default
+(F<doc/etc/> contains termcap/terminfo definitions for both).
+It also results in higher memory usage and can slow down @@RXVT_NAME@@
+dramatically when more than six fonts are in use by a terminal instance.
 =item --with-afterimage-config=DIR
 Look for the libAfterImage config script in DIR.
 =item --with-name=NAME (default: urxvt)

Diff Legend

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

Comparing rxvt-unicode/doc/rxvt.7.pod (file contents): Revision 1.177 by root, Sat May 30 08:53:48 2009 UTC vs. Revision 1.206 by sf-exg, Sat Dec 11 22:59:02 2010 UTC

Diff Legend

Comparing rxvt-unicode/doc/rxvt.7.pod (file contents):
Revision 1.177 by root, Sat May 30 08:53:48 2009 UTC vs.
Revision 1.206 by sf-exg, Sat Dec 11 22:59:02 2010 UTC