************************************************************************
*    Please set tab stop to 4 for a best display of this file.
************************************************************************



		Congratulations! You have purchased an extremely fine
	device that would give you thousands of years of trouble-free 
	service, except	that you undoubtably will destroy it via some 
	typical bonehead consumer maneuver. Which is why we ask you
	to PLEASE FOR GOD'S SAKE READ THIS OWNER'S MANUAL CAREFULLY
	BEFORE YOU UNPACK THE DEVICE. YOU ALREADY UNPACKED IT, DIDN'T
	YOU? YOU UNPACKED IT AND PLUGGED IT IN AND TURNED IT ON AND 
	FIDDLED WITH THE KNOBS, AND NOW YOUR CHILD, THE	SAME CHILD WHO
	ONCE SHOVED A POLISH SAUSAGE INTO YOUR VIDEOCASSETTE RECORDER
	AND SET IT ON "FAST FORWARD", THIS CHILD ALSO IS FIDDLING
	WITH THE KNOBS, RIGHT?  AND YOU'RE JUST NOW STARTING TO READ 
	THE INSTRUCTIONS, RIGHT???  WE MIGHT AS WELL JUST BREAK THESE 
	DEVICES	RIGHT AT THE FACTORY BEFORE WE SHIP THEM OUT, YOU 
	KNOW THAT? 
				-- Dave	Barry, "Read This First!"



00   INTRODUCTION

Mrxvt is a multi-tabbed (like gnome-terminal/konsole) terminal emulator
for the X Window System. It targets to be light-weight, so the desktop
environment, like CDE, KDE or GTK is not required in order to run it.
It achieves this without losing the common useful features, like image
and pseudo-transparent background, multi-style scrollbars, XIM and CJK
support, etc.



01   A BRIEF HISTORY

You can safely skip this section if you do not have time.

For years, a multi-tabbed rxvt has been requested by the users with
no luck. Now, things have changed! Mrxvt (previously named as materm)
is a tabbed X terminal emulator based on aterm/rxvt. It's small,
fast, portable, feature rich and only depends on X library.

An early version of mrxvt is based on multi-aterm and named materm.
Multi-aterm was first developed by Alexis from 2002 based on aterm.
But the development seems to stop in 2004. So I took over the
project, began to hack it and renamed it to materm. I have made
lots of changes to the code since I dislike the original code
style. Hopefully, I have not broken too many things. ;-)

Due to the limits of aterm, many features are not well implemented,
such as XIM support. So after release 0.2, I decided to pick up the
latest rxvt as the base of new development branch. So the name of
the project is changed to mrxvt. This branch is completely new
compared to the branch prior to 0.2. I have found that rxvt coding
style is much better than aterm (except the indent is horrible ;-)),
and it is enjoyable to work on it. I have also ported many features
from aterm to mrxvt, like tinting. Be aware that some features in
the new branch are slightly different from release 0.2, e.g., color
background tinting is available for each individual terminal in
release 0.2, but is global from 0.3.0.



02   BUG REPORT AND FAQ

Bug reports are very welcome! Mrxvt by default is built with debug
support. So if you have gdb in your system, you may run mrxvt in
gdb with the source to track down the bug, and report it to me.

To save both your time and my time, please write down detailed steps
to replicate the bug. If I cannot replicate it by myself, I will
ignore it even it may destroy the universe.

Patches are extremely welcome! In addition, I may not have time to
update the documents by now. Feel free to help me and the users to
improve them.

If you run into certain problems, please read the FAQ file before
trying to contact me! Your question may be answered by FAQ already.
I most likely will dump your question to /dev/null if it is already
answered by FAQ.



03   BUILD AND INSTALL

To build and install from the source, please read INSTALL file! If
you want to disable the verbose debug information, run the configure
script as:

	$ ./configure --enable-whatever-options --disable-debug

A quick (lazy) choice is to configure mrxvt as the following. After
you --enable-everything, usually there is no need to enable other
options explicitly.

	$ ./configure --enable-everything --disable-debug



04   CONFIGURATION FILE

To run mrxvt with your own preferences, you can set X resources in
~/.Xdefaults. A sample xdefaults-sample.txt is included in the doc/
directory, and you can start to hack your own ~/.Xdefaults from it.
Most options in the ~/.Xdefaults can be replace by a (short) command
line option.



05   HOTKEY BINDINGS

Several hot key combinations are available for keyboard users. Please
read the doc/TIPS for a list of them. Be aware that they may be
changed in the near future in order to conform with gnome-terminal
and konsole.



06   CJK DISPLAY AND INPUT

To display and input Chinese (Korea/Japanese), you can do the
following:

	. Configure mrxvt with "--enable-gb --enable-big5 --enable-gbk
--enable-xim" options, and build it.

	. Install the correct CJK fonts. Mrxvt will try to look for some
default CJK font if you do not specify the CJK font using -fm option
or mfont X resource name. The default fonts are listed in encoding.h.
Notice that they are -fm and mfont, NOT -fn and font!!!

	. Set environment variable LC_CTYPE to zh_CN. Make sure to unset
environment variable LC_ALL, otherwise LC_CTYPE is overrided. Notice
that this setting is global for all the following commands you will
use in the same shell session. You can supply the environment variable
to mrxvt at runtime instead of setting it globally here. Keep reading
the following for details.

	. Set X resources in ~/.Xdefaults. Notice that the value of
inputMethod is case sensitive.

		mrxvt*mfont:              hanzigb16st
		mrxvt*xftmfont:           simsun
		mrxvt*xftSize:            14
		mrxvt*multichar_encoding: GB
		mrxvt*inputMethod:        SCIM

	. Start the SCIM X input server as usual

	. Execute mrxvt. You can supply the environment variable LC_CTYPE
and XMODIFIERS to mrxvt at runtime instead of setting them globally
as above. All you need to do is to run mrxvt as following:

		# the following command is for bash/ksh
		LC_CTYPE=zh_CN XMODIFIERS=@im=SCIM mrxvt &
		# the following command is for csh/tcsh
		env LC_CTYPE=zh_CN XMODIFIERS=@im=SCIM mrxvt &

	. Focus on the mrxvt window, click Ctrl_Space to invoke SCIM

Mrxvt is tested to work with SCIM, fcitx and gcin. It should work fine
with other X Input methods, like xcin, Chinput and miniChinput. It is
reported to work with French ascent as well.



07   FEATURES

Major features (* are new features compared with rxvt, + are enhanced
features compared with rxvt):

	* multi-tab support
	* runtime changedable tab title
	* simple session support for each terminal
	* built-in true translucent window support
	. pseudo-transparent terminal background
	* pseudo-transparent tabbar background
	* pseudo-transparent scrollbar background
	* pseudo-transparent menubar background
	+ user supplied background image per terminal
	* user supplied background image for tabbar
	* user supplied background image for scrollbar
	* user supplied background image for menubar
	+ xpm/jpeg/png background image
	* background color tinting, runtime changedable color and shade
	* color text shadow
	* fading and off-focus fading
	+ NeXT/Rxvt/Xterm/SGI/Plain style scrollbar
	. only depends on X, no GTK, no Qt
	. small and fast
	+ XIM and multi-languages (Chinese/Korea/Japanese) suppport
	* freetype font
	. multiple platforms
	. utmp/wtmp/lastlog logging

For a complete list of all features, please read README.configure file.



08   PORTABILITY

Here are tested platforms that mrxvt is known to work with:

	Slackware Linux 10.0
	RedHat Linux 9.0
	Debian Linux (Testing)
	Gentoo Linux (Testing)
	SuSE Linux 9
	SUN Solaris (SPARC) 8/9
	FreeBSD 5.2.1
	OpenBSD 3.5/3.6
	IRIX 6.5
	HP-UX
	Mac OS X 10.3 (Panther)
	Cygwin

If you cannot find mrxvt in your favorite system (especially open
source systems like Linux and BSD), you may try to contact the
system developers and request them to add it into the system. :-)



09   KNOWN ISSUES

Here are several known issues of mrxvt:

	. To build mrxvt on HP-UX, you need to disable logging features.

	. To build mrxvt on BSDs, you need to install iconv libraries.

	. Background image support requires libxpm, libpng and libjpeg
be installed.

	. Thai support is incomplete since I do not know too much about
it and do not have the Thai fonts.

	. XFT support is experimental by now. It requires freetype, xft
and fontconfig libraries be installed.

	. If swap screen option is disabled, screen scrolling may behave
randomly. ;-)  So the safe choice is to always enable it.

	. Tinting and pseudo-transparent are global since 0.3.0. Well,
we could implement tinting and pseudo-transparent for each individual
terminal (not a technical difficulty), but it will significantly
increase the X resources usage since each terminal needs at least
one pixmap.

	. Off-focus fading does not work under XFT. It does not work
perfectly well either under X11.



10   SECURITY ISSUES

Here are several security issues of mrxvt:

	By default, mrxvt binary is installed as setuid root. Although
	we have tried hard to avoid security problems raised by setuid
	root permission, we do not guarantee 100% safety. You have been
	warned!!!

	From 0.3.5, mrxvt supports utempter library, which means if you
	have installed the utempter library, you can remove the setuid
	root permission from mrxvt binary without losing the logging
	feature. But doing so may cause trouble to chown the tty on some
	systems.



11  COPYRIGHT

Mrxvt is licensed under GNU General Public License (GPL). You are free
to copy, modify and redistribute the source and binary of mrxvt under
GPL. But there is a issue with SCO Corp.:

	According to section 4 of the GPL, SCO Corporation of Lindon,
	Utah (formerly Caldera) has no rights to redistribute any
	versions of Mrxvt and/or Materm in any of their products,
	including (without limitation) OpenLinux, Skunkware, OpenServer,
	and UNIXWare.
