readme

Unix下的MUD客户端程序

Introduction
------------

I wrote mcl because I needed a fast MUD client that had scroll back built in.
I hacked together a scroll back support for tintin, using less, but that
messed up when color codes were received and it was pretty slow to pipe the
saved data to less each time it was activated.

Also, tintin had a problem when a line was not received in one packet: it
would always change to a new line so long outputs looked very weird.

With embedded Perl and Python support, I am confident that mcl can do
everything tintin (and even most other clients) ever have done.

Requirements
------------

The fastest mode of operation is under a Virtual Console found under Linux.
However, since version 0.51.00, mcl supports normal TTY output to any
VT100/ANSI comptaible console - for example an Xterm. For best results,
use a black background and white foreground (e.g. xterm -bg black -fg white).

Sine mcl does not depend on /dev/vcsa anymore, it means it can run
under any Unix OS.


Installation
------------

To compile, follow the steps in INSTALL. That is run:

./configure
make
make install

If you want the Perl scripting support, you need glibc as well as a libperl -
the latter should be in your standard Perl package.

Perl and Python support are compiled as shared object plugins, thus they
do not take up any memory unless you explicitly load them. Still, you can
disable them at configure time if you want (see the INSTALL file).


Running in Virtual Console Mode
-------------------------------

Move the 'mcl' binary to some location like /usr/local/bin. If you want
non-root users to use it in Virtual Console mode (Linux only), execute for
example:

 chown root.tty mcl                 
 chmod 2755 mcl                     

Or type 'make install'. NOTE: I've heard that later version of the 'login'
program automaticall change permissions on /dev/vcsa so that it is no longer
necessary for mcl to run as SETGID. Also, some versions of RedHat make
the devices writable by anyone.

This will make mcl be run as group 'tty' when it runs. This assumes that
your /dev/vcsa* files are owned by group tty though.

Make sure that /dev/vcsa* exist. If you want to run as non-root, make sure
they are owned by group tty and are writable by that group. If the files do
not exist, you'll have to create them:

 mknod /dev/vcsa1 c 7 129
 mknod /dev/vcsa2 c 7 130

etc. The vcsa devices should be available from Linux 1.1.92 onward.

If you are wondering, the vcsa devices allow direct access to the Virtual
Console Screens and Attributes (there is a set of vcs devices, which do the
same except they do not show attributes).

You must also move the plugin files to either /usr/local/lib/mcl/plugins/
or ~/.mcl/plugins/. Make install does that for you automatically too. The
compiled plugin files are in the subdirectory o/plugins/.

You probably also want to move the contents of the samples/ directory
distributed with mcl to ~/.mcl and consider which of the scripts in the
contrib/ subdirectory to autoload (i.e. move to the auto/ directory so
they are automatically loaded when mcl starts). If a file does not exist
in the ~/.mcl/ directory, mcl will try to load the script from
/usr/local/lib/mcl or /usr/lib/mcl.


Running in TTY mode
-------------------

This is somewhat slower. It's bearable in local XTerm, but may not be over
a telnet connection that is anything but a direct network connection.

mcl uses the two-byte Escape [ control code. If you use mcl from a terminal
that understands the CSI control code (which is one byte), you can try modifying
Screen.cc to use the shorter code (look for CSI in the file).

mcl tries to use a scrolling region whenever possible to scroll text. Since
the TTY Screen is at a much lower level than windows that scroll, it is done
via heuristics.

mcl uses terminfo to find keyboard combinations. There are some that are
still missing however, and I'm not sure they can be found using terminfo at
all.

Under xterm or under rxvt, mcl will modify the title bar of the xterm to
display connection state. If your terminal understands that escape
code (CSI 2 ; <text> BEL) and mcl does not send it, you probably need to modify
Curses.cc and add that to the list of terms that are considered xterms.

If you have problems using Alt and another key under xterm, add the following
to your ~/.XDefaults file:
 
*XTerm*VT100.eightBitInput: false

For rxvt:

Rxvt*meta8: false


Setup
-----

You need to set up the MUDs you connect to in the file ~/.mcl/mclrc. This is
best illustrated with an example:

MUD ar {
  Host abandoned.org 4444
  Commands Drylock;qwerty; ;
}

The first line defines a new MUD, "ar". It uses the C-like notation of
a block, started by { (which must be on the same line!) and ending on
} (which must be on a line by itself).

The configuration options inside that affect only that MUD.

Host: supplies hostname and portnumber of the MUD
Commands: Optional. Specifies what commands will be sent to the MUD
once a connection is established (you could put username/password in here).

Aliases, actions and macros you specify inside the MUD record will be valid
for that MUD only (and for any MUDs that inherit from this MUD) (see
later "MUD Inheritance" chapter).

You can specify other information in the configuration file - see the
"Options" chapter.

You can override the default resource filename by setting the environment
variable MCLRC to the absolute location (note that you cannot use ~ to
specify your home directory).

In addition, the embedded script use the  file ~/.mcl/config.lang as a
place to store their configuration. (i.e. Perl writes to ~/.mcl/config.perl,
Python to ~/.mcl/config.python etc.)


Running
-------

Then run mcl, with the name of the MUD to connect to as parameter.
Connecting is asynchronous, so you can do other things in the client while
waiting. There isn't much to do though, but I thought counting down looked
nifty :)

The top line is a status line. Messages from the client appear up there. The
messages disappear after 5 seconds.

The bottom line is the input line. Most editing keywords you'd expect to
work work: arrow keys to edit the command line, arrow up to enter command
line history recall window. See "Keys" for a comprehensive list.

If the MUD you want to connect to is not one that is in the database, and
you do not wish it to be there, you can just specify hostname/port number
on the command like (eg. "mcl abandoned.org 4444").

If you leave out the MUD name on the command line, you will be able to
specify it while in the client by using Alt-O or #open.

After mcl starts up, it will load the "sys/init.pl" script file (see the file
doc/Embedded about embedded language support). You don't want to modify
that file - modify localinit.pl instead which is called within sys/init.pl.


Commands
--------

There is a number of commands, that start with #, that are not send to the
MUD but rather interpreted by mcl. You can change the # character into something
else like / by using the commandcharacter option in the configuration file.

#open <mud name>        Connects to that MUD
#reopen                 Connects to the last MUD you connected to
#close                  Stops the current session
#quit                   Stops the session and leaves the program
#help                   Not very helpful
#exec                   Execute a command in a window
#echo                   Show something in the output window (do not send it)
#window                 Create a window
#print                  Print to a window created by #window
#clear                  Clear above window
#kill                   Kill a window created by #window
#send                   Send data to MUD, without newline
#bell                   Sound the bell
#status                 Change the status line to the argument given
#alias                  Remove an alias or add a new alias
#macro                  Add/remove/change a macro
#run                    Run the given embedded function (see the file doc/Embedded)
#eval                   Evaluate any embedded code, print result on screen
#load                   Load some embedded code from a file
#prompt                 Set the prompt (useful when you don't have GA/EOR)
#setinput               Set the input line
#save                   Save the scrollback. Use the -c switch to save in color.
#writeconfig            Save the configuration file, even if readonly option is set. If
                        parameter given, use that as a filename rather than the default
                        filename

#disable                Disable/Enable one of: actions, aliases, speedwalk, 
#enable                 and macros. This enables/disables ALL of those, not a single one.

#chat.*                 There is a number of commands that allow you to perform various
                        tasks related to the built-in peer-to-peer chat system of mcl
                        They are described in the file doc/Chat.

In addition, a line that starts with \ (which can be changed using the escapecharacter in
the configuration file) is sent as-is to the MUD.

Keys
----

Alt-O                   See a menu of MUDs. Return connects, E edits the
                        currently selected MUD's data. Alt-A shows the
                        aliases of that MUD.

Alt-C                   Same as #close

Alt-A                   Show currently active aliases. First the aliases for
                        this particular MUD are shown, the global aliases.

Alt-I                   Show currently active actions.

Alt-M                   Show currently active keyboard macros.

Alt-S                   Toggle network status window

Control-T               Show timer window. Repeated ^T will change the
                        format of the window, then finally remove it

Alt-V                   Print version information

Alt-H                   Show active chat connections

Alt-Q                   Same as #quit

Alt-R                   Same as #reopen

Alt-T                   Restart. Reexecutes mcl. This feature is mainly
                        useful for development, but could be helpful if you 
                        have a read-only config file which you want to
                        reread. You have to invoke mcl with the full path name
                        for this to work, or have it in your $PATH.

PageUp                  Scroll one half-page up in scroll back buffer

PageDown                Scroll one half-page down

Arrow Up/Down           In scroll back: scroll one line up/down
                        Outside: activate command history

Arrow Left/Right        Move cursor left/right on the input line. New text
                        is inserted where the cursor is, pushing old text to 
                        the right.

Control-A/Control-E     Go to the beginning/end of the input line

Control-J               Delete until the end of the line

Control-U               Delete until the beginning of the line

Control-C               Delete current line and insert into the command
                        history, but do NOT send it to the MUD. You can
                        later recall the command as usual.

Control-W               Delete the word to the left                        

Delete                  Delete the character over the cursor

Backspace               Delete the character to the left of the cursor

Home                    Go to the beginning of buffer

End                     Go to the end and leave scroll back mode

Pause                   Enter scroll back mode, but don't scroll anywhere
                        This is a toggle, pressing Pause again leaves it.

Escape                  Clear input line

Alt-/                   Search through scrollback backwards from current
                        position


PageUp, PageDown, Home and Pause all enter scroll back mode if it is not
active already. Pressing PageDown or Arrow Down when at the end of
scrollback exits it.

You can type commands while in scroll back, though you will not see the
output.