1************************************************************************
2* Please set tab stop to 4 for a best display of this file.
3************************************************************************
4
5
6
7 Congratulations! You have purchased an extremely fine
8 device that would give you thousands of years of trouble-free
9 service, except that you undoubtably will destroy it via some
10 typical bonehead consumer maneuver. Which is why we ask you
11 to PLEASE FOR GOD'S SAKE READ THIS OWNER'S MANUAL CAREFULLY
12 BEFORE YOU UNPACK THE DEVICE. YOU ALREADY UNPACKED IT, DIDN'T
13 YOU? YOU UNPACKED IT AND PLUGGED IT IN AND TURNED IT ON AND
14 FIDDLED WITH THE KNOBS, AND NOW YOUR CHILD, THE SAME CHILD WHO
15 ONCE SHOVED A POLISH SAUSAGE INTO YOUR VIDEOCASSETTE RECORDER
16 AND SET IT ON "FAST FORWARD", THIS CHILD ALSO IS FIDDLING
17 WITH THE KNOBS, RIGHT? AND YOU'RE JUST NOW STARTING TO READ
18 THE INSTRUCTIONS, RIGHT??? WE MIGHT AS WELL JUST BREAK THESE
19 DEVICES RIGHT AT THE FACTORY BEFORE WE SHIP THEM OUT, YOU
20 KNOW THAT?
21 -- Dave Barry, "Read This First!"
22
23
24
2500 INTRODUCTION
26
27Mrxvt is a multi-tabbed (like gnome-terminal/konsole) terminal emulator
28for the X Window System. It targets to be light-weight, so the desktop
29environment, like CDE, KDE or GTK is not required in order to run it.
30It achieves this without losing the common useful features, like tab,
31image and pseudo-transparent background, multi-style scrollbars, XIM
32and CJK support, etc.
33
34
35
3601 A BRIEF HISTORY
37
38You can safely skip this section if you do not have time.
39
40For years, a multi-tabbed rxvt has been requested by the users with
41no luck. Now, things have changed! Mrxvt (previously named as materm)
42is a tabbed X terminal emulator based on aterm/rxvt. It's small,
43fast, portable, feature rich and only depends on X library.
44
45An early version of mrxvt is based on multi-aterm v0.1 and named
46materm. Multi-aterm was first developed by Alexis from 2002 based
47on aterm. But the development seems to stop in 2004 without reaching
48a usable stable status. So I took over the project, began to hack it
49and renamed it to materm. I have made lots of changes to the code
50since I dislike the original code style. Hopefully, I have not
51broken too many things. ;-)
52
53Due to the limits of aterm, many features are not well implemented
54in materm, such as XIM support. So after release 0.2, I decided to
55pick up the latest rxvt as the base of new development branch. And
56the name of the project is changed to mrxvt. This branch is completely
57new compared to the branch prior to 0.2. I have found that rxvt coding
58style is much better than aterm (except the indent is horrible ;-)),
59and it is enjoyable to work on it. I have also ported many features
60from aterm and eterm to mrxvt, like tinting and text shadow. Be aware
61that some features in the new branch are slightly different from
62release 0.2, e.g., color background tinting is available for each
63individual terminal in release 0.2, but is global from 0.3.0.
64
65
66
6702 BUG REPORT AND FAQ
68
69Bug reports are very welcome! You can build mrxvt with debug
70support. So if you have gdb in your system, you may run mrxvt in
71gdb with the source to track down the bug, and report it to me.
72
73To save both your time and my time, please write down detailed steps
74to replicate the bug. If I cannot replicate it by myself, I will
75ignore it even if it may destroy the universe.
76
77Patches are extremely welcome since I am not familiar with many
78things, like multi-languages and accent.
79
80In addition, I may not have time to update the documents in time.
81Feel free to help me and the users to improve them. Translations
82are also welcome. Of course, not from C to C++ or something like
83that! You know my meaning of translations.
84
85If you run into certain problems, please read the FAQ file and the
86man page before trying to contact me! Your question may be answered
87by them already. I most likely will dump your question to /dev/null
88if it is already answered there.
89
90
91
9203 BUILD AND INSTALL
93
94To build and install from the source, please read INSTALL file!
95
96A quick (lazy) choice is to configure mrxvt as the following. After
97you --enable-everything, usually there is no need to enable other
98options explicitly. I have found that many distributions, like
99gentoo, enable other options with --enable-everything. This is NOT
100necessary in fact. The option is a shortcut to avoid a long list of
101configuration options. (Apparently few people pay attention to the
102README and README.configure. Shall we burn the README? ;-))
103
104 $ ./configure --enable-everything --disable-debug
105
106
107
10804 CONFIGURATION FILE
109
110To run mrxvt with your own preferences, you can set X resources in
111~/.mrxvtrc. A sample xdefaults-sample.txt is included in the doc/
112directory, and you can start to hack your own ~/.mrxvtrc from it.
113Alternative configuration files are ~/.Xdefaults and ~/.Xresources.
114Most options in the ~/.mrxvtrc can be replace by a (short) command
115line option - of course, if you like command line options.
116
117
118
11905 HOTKEY BINDINGS
120
121Several hot key combinations are available for keyboard users. Mrxvt
122is designed to be as flexible as possible. It can be surprising to
123see that many features can be altered during runtime using hotkeys
124or escape sequences. Please read the doc/TIPS for a list of them. Be
125aware that they may be changed in the near future because the
126shortage of combinations for all features. ;-)
127
128If you do not like the default hot key combinations, you can define
129the combinations by yourself. Please read the man page to find out
130how to define them.
131
132
133
13406 CJK DISPLAY AND INPUT
135
136To display and input Chinese (Korea/Japanese), you can do the
137following:
138
139 . Configure mrxvt with "--enable-cjk --enable-xim" options, and
140build it.
141
142 . Install the correct CJK fonts. Mrxvt will try to look for some
143default CJK fonts if you do not specify them using the -fm option
144or mfont X resource name. The default CJK fonts are listed in the
145src/encoding.h file. Notice that they are -fm and mfont, NOT -fn and
146font!!! If you use freetype font, use -xftfm option to specify the
147CJK font family. Notice that -fm and -xftfm options use different
148formats of font names. For details about the difference, read the FAQ
149file.
150
151 . Set environment variable LC_CTYPE to zh_CN. Make sure to unset
152environment variable LC_ALL, otherwise LC_CTYPE is overrided. Notice
153that this setting is global for all the following commands you will
154type in the same shell session. You can supply the environment variable
155to mrxvt at runtime instead of setting it globally here. Keep reading
156the following for details.
157
158 . Set X resources in ~/.mrxvtrc. Notice that the value of
159inputMethod is case sensitive.
160
161 mrxvt*mfont: hanzigb16st
162 mrxvt*xftmfont: simsun
163 mrxvt*xftSize: 14
164 mrxvt*multichar_encoding: GB
165 mrxvt*inputMethod: SCIM
166
167 . Start the SCIM X input server as usual. For example:
168
169 $ # for ksh/bash users
170 $ LC_ALL=zh_CN LANG=zh_CN scim -d
171 $ # for csh/tcsh users
172 $ env LC_ALL=zh_CN LANG=zh_CN scim -d
173
174 . Execute mrxvt. You can supply the environment variable LC_CTYPE
175and XMODIFIERS to mrxvt at runtime instead of setting them globally
176as above. All you need to do is to run mrxvt as following:
177
178 # the following command is for bash/ksh
179 LC_CTYPE=zh_CN XMODIFIERS=@im=SCIM mrxvt &
180 # the following command is for csh/tcsh
181 env LC_CTYPE=zh_CN XMODIFIERS=@im=SCIM mrxvt &
182
183 . Focus on the mrxvt window, click Ctrl_Space to invoke SCIM
184
185 . For Linux, set environment variable LC_ALL (for scim) and
186LC_CTYPE (for mrxvt) to zh_CN or zh_CN.gbk are both good for
187SCIM/fcitx input. For FreeBSD, they must be zh_CN.eucCN for fcitx
188input.
189
190Mrxvt is tested to work with SCIM, fcitx and gcin. It should work fine
191with other X Input methods, like xcin, Chinput and miniChinput. It is
192reported to work with French ascent as well.
193
194
195
19607 FEATURES
197
198Major features (* are new features compared with rxvt, + are enhanced
199features compared with rxvt):
200
201 * multi-tab support
202 * runtime changedable tab title and tab order
203 * simple command support (session) for each tab terminal
204 * input broadcasting to all tab terminals
205 * freetype font (Xft) support
206 * built-in true translucent window support
207 * user configurable keyboard shortcuts
208 . pseudo-transparent terminal background
209 * pseudo-transparent tabbar background
210 * pseudo-transparent scrollbar background
211 * pseudo-transparent menubar background
212 + user supplied background image per terminal
213 * user supplied background image for tabbar
214 * user supplied background image for scrollbar
215 * user supplied background image for menubar
216 + xpm/jpeg/png background image
217 * background color tinting
218 * runtime changedable tinting color and shading
219 * color text shadow and different shadow mode
220 * background fading and off-focus fading
221 + NeXT/Rxvt/Xterm/SGI/Plain style scrollbar
222 + XIM and multi-languages (Chinese/Japanese/Korean) suppport
223 . multiple platforms
224 . utmp/wtmp/lastlog logging
225 . only depends on X, no GTK, no Qt
226 . small and fast
227
228For a complete list of all features, please read README.configure file.
229
230
231
23208 PORTABILITY
233
234Here are tested platforms that mrxvt is known to work with:
235
236 Slackware Linux 8.1/10.0/10.1, -current
237 Slackintosh 10.1 (PPC)
238 RedHat Linux 9.0, Enterprise 3, Fedora Core 2/3
239 Debian Linux
240 Gentoo Linux
241 SuSE Linux 8.2, 9.0, 9.1, 9.2
242 SUN Solaris (SPARC) 7/8/9/10
243 FreeBSD 4.8/5.2.1/5.3
244 OpenBSD 3.5/3.6
245 NetBSD 2.0
246 IRIX 6.5
247 HP-UX
248 Tru64/OSF 5.1
249 Mac OS X 10.3 (Panther)
250 Cygwin
251
252If you cannot find mrxvt in your favorite system (especially open
253source systems like Linux and BSD), you may try to contact the
254system developers and request them to add it into the system. :-)
255
256
257
25809 KNOWN ISSUES
259
260Here are several known issues of mrxvt:
261
262 . UTF-8 is not supported yet.
263
264 . Some users report that they have problem to envoke the SCIM
265Chinese input method under Gentoo 2004.3 and Debian Sarge. I have
266no idea why this is the case because it always works for me. The
267solution? Dump Gentoo/Debian and turn to Slackware, or trace the
268program and send me patch. ;-)
269
270 . To build mrxvt on HP-UX, you need to disable logging features.
271
272 . Background image support requires libxpm, libpng or libjpeg
273be installed. The images are only tiled on the background of the
274terminal window. They cannot be scaled to fit the window size.
275
276 . XFT support requires freetype, xft and fontconfig libraries
277be installed. Multichar support under XFT requires GNU iconv library
278be installed, which is usually included in GLIBC for Linux systems.
279
280 . If swap screen option is disabled, screen scrolling may behave
281randomly. ;-) So the safe choice is to always enable it.
282
283 . Tinting and pseudo-transparent are global since 0.3.0. Well,
284we could implement tinting and pseudo-transparent for each individual
285terminal (not a technical difficulty), but it will significantly
286increase the X resources usage since each terminal needs at least
287one pixmap.
288
289 . Thai support is incomplete since I do not know too much about
290it and do not have the Thai fonts.
291
292 . Off-focus fading does not work under XFT in order to save
293resources. This may be fixed in the future.
294
295 . Certain characters, e.g., characters with accent in European
296languages may not be correctly displayed under XFT.
297
298 . If cursor blinking is enabled, to print the hold exit text on
299the screen may be delayed after several blinking. Similarly, the
300child may stay for a while before completely quits.
301
302
303
30410 SECURITY ISSUES
305
306Here are several security issues of mrxvt:
307
308 Before 0.3.10, by default, mrxvt binary is installed as setuid
309 root. Although we have tried hard to avoid security problems
310 raised by setuid root permission, we do not guarantee 100%
311 safety. You have been warned!!! From 0.3.10, mrxvt binary will
312 be installed without setuid root due to security concerns. Thus,
313 if mrxvt is not compiled with utempter library support, you will
314 lose the logging features.
315
316 From 0.3.5, mrxvt supports utempter library, which means if you
317 have installed the utempter library, you can remove the setuid
318 root permission from mrxvt binary without losing the logging
319 feature. But doing so may cause trouble to chown the tty on some
320 systems.
321
322
323
32411 COPYRIGHT
325
326Mrxvt is licensed under GNU General Public License (GPL). You are free
327to copy, modify and redistribute the source and binary of mrxvt under
328GPL. But there is a issue with SCO Corp.:
329
330 According to section 4 of the GPL, SCO Corporation of Lindon,
331 Utah (formerly Caldera) has no rights to redistribute any
332 versions of Mrxvt and/or Materm in any of their products,
333 including (without limitation) OpenLinux, Skunkware, OpenServer,
334 and UNIXWare.
335