readme

Unix下的MUD客户端程序

Pressing Arrow Up will activate a command history window. In that window,
you can use arrow keys, PageUp/Down and Home/End to move. Typing any letter
will jump to the first line with that letter. Typing it again will jump to
the next line (the search wraps, so pressing 'a' on the last line with 'a'
will take you to the first line with 'a'). Pressing return selects that
line and executes the command, pressing Escape leaves the window and
pressing arrow-right selects the line, but does not execute it, so you can
do further editing on it.

If you don't like the command history window, you can disable it using the
historywindow option.

History is saved between sessions in the file ~/.mcl/history. This can be
disabled using the save_history option in .mclrc.

The scrollback buffer allocates memory for 10000 scrollback lines per
default. If you have a newer libc, the memory will not be allocated until
actually used (check the resident size on ps). Note that due due to the way
that previous scrollback is shifted when the scrollback buffer gets full,
it is not recommended to use more scrollback than physical memory in
the machine. Each 1000 lines of scrollback occupy 156 kilobyte of memory
(each 80 character wide line contains 80 characters and 80 attribute bytes).

Although mcl copies the entire screen each time it updates it, CPU usage
is much better than that of tintin; even with heavy input mcl does not go
above 0.2% CPU time of a 486dx4-100 (note that with many actions and
perl scripts active groping the mud output this may no longer be true ;)

The scrollback can be saved using the #save command.

Note that commands that are shorter than 5 characters are not saved in the
command history. This number can be changed using the -w option.


Prompt
------

mcl understands the TELNET GA sequence. If you enable GA using config
+telnetga (or Prompt +telnetga on AR), mcl will snarf a prompt when it
appears and place it in the input line. It will start at the GA sequence and
go back until it finds a newline.  Mcl also understands the telnet EOR
sequence, behaving in the same way as it does for the GA sequence.

You might want to change your MUD code so that the TELNET GA is sent in more
places than just the normal prompt, e.g. send it after the pager prompt and
after asking someone about their password.

Color is stripped from the prompt. Also, mcl resets the color to default
after receving a prompt, to avoid color bleeding.

Like tinyfuge, mcl responds to a IAC WILL EOR request from a MUD by sending
IAC DO EOR back. This will typically enable TELNET GA.

The option "showprompt" controls whether the prompt is also echoed in the main
window.

If your MUD does not send the GA/EOR sequence, you can try extracting
the prompt yourself. See the file contrib/dumbprompt.pl file.


Stat window
-----------

Using Alt-S (or by setting autostatwindow) you can bring up a network
connection status window in the upper right corner of the screen. This
feature was provided by Oliver Jowett, which is the only one that knows
what those numbers REALLY mean: :)

The network status monitor looks at one of the /proc pseudo-files to get
information about the internal state of the connection to the mud. Four
values are displayed:

transmit queue    receive queue     timer/retransmit count

Transmit queue: This is how many characters have been sent by mcl,
                but are yet to reach the mud.

Receive queue:  This is how many characters have been sent by the mud,
                but are yet to be processed by mcl. This should always be 0.

The next two values require a small explanation of how TCP works when the
network begins to fail. The kernel sends a packet to the mud containing
your command. It then waits for confirmation from the mud that it has
been received correctly. If the command packet goes missing, then the
kernel will time out and resend the packet. How long it takes to resend
the packet increases after each loss, until it's waiting 120s between
retransmits.

Timer:            This is how long the kernel will wait before sending the
                  command again.
Retransmit count: This is how many times the kernel has already resent
                  this packet without the mud confirming that it has
                  received it.

If the 'timer' field gets high, then you may be better off disconnecting
and reconnecting, rather than wait out the lag.

On the far left side of the timer a window, a C will appear if your
connection to the MUD is compressed.

Beneath the Network Status and timer window is the input/output bytes
window. This counts the amount of bytes sent from the MUD to you (number
before the slash) and the amount of bytes received sent from you to the
MUD (number after the slash). k and m denote kilo and megabytes.


Options
-------

mcl [options] [mud alias]

Each of the options can be specified on the command line as well as in the
configuration file. The command line options override those in the
configuration file. The default value is supplied in parens.

histwordsize        -w      Minimum number of characters a command must have to
                            qualify for saving in history (5)

scrollback          -l      Number of lines in the scrollback buffer (10000)

histsize            -H      Number of history lines saved

showprompt          -s      Should the full prompt be shown in output screen?

echoinput           -e      Should your input be echoed in the output screen?

beep                -b      Beep on error. 0 disables it, 1-10 changes
                            frequency.

readonly            -r      Don't auto save the configuration file

nodefaults                  When saving the configuration file, do not save
                            options the value of which is default

historywindow       -W      Number of lines in the history window. If 0, the
                            old way of history cycling is used.

tabsize             -T      How much space is there between tab stops?

mudbeep             -B      Should beeps from the MUD be honored? If 0, they
                            are ignored (this does not affect the "beep"
                            setting)

statcolor                   Color of the connection status window (see
                            "Color values")

inputcolor                  Color of the input line

statuscolor                 Color of the status line

autostatwin                 Automatically bring up the stat window

speedwalk                   Enable/disable speedwalk

speedwalk_character         What character forces the rest of the string to
                            be considered a speedwalk. Default is '.'

timercolor                  Color of the clock/timer window

autotimerwin                Automatically bring up the timer window

timerstate                  Select default timer state (0 = full clock and
                            timer, 1 = clock, full timer, 2 = clock, timer, 
                            3 = full clock, 4 = clock, 5 = full timer, 
                            6 = timer)

save_history                Save input line history between sessions in the
                            file ~/.mcl/history ? (0 or 1, default: 1)

borg                        Should mcl connect to a a central place
                            (abandoned.org) on startup and check for a new
                            client version? If this option is set, mcl will
                            also report some statistics to that place (e.g.
                            time used, bytes sent/written). This is used for
                            just that, statistics shown on the mcl page,
                            but if it bothers you, turn it off.

borg_verbose                Should mcl display more information gained from
                            the central place than just if a new version has
                            appeared? This information could be typically:
                            how many other mcl users are using mcl currently,
                            how much total time has been spent in mcl etc.

interp_debug           -D   0 or 1 - controls whether those @@ Loading
                            messages appear.

copyover                    0 or 1. Use the new "hot" restart of mcl
                            where the descriptor is not closed.

multiinput                  0 or 1 - do you want the input line that grows
                            as text is typed into it?

snarf_prompt                Change the prompt when a new once is received

expand_semicolon            Usually the ; character (used to execute multiple
                            commands) is honored only inside aliases. When
                            this option is set to 1, it is also honored on
                            the command line. Use \; to escape the character.

plugins                -p   What plugins to load? This decides whether you will
                            use Perl or Python for scripting. Default is perl.
                            If you have multiple plugins, seperate the names
                            by commas.

commandcharacter            Change the leading character from # to something
                            else (described in detail later)

escapecharacter             Change the escape character that can be used at
                            the beginning of line (default: \) to something
                            else
                       -x   This option executes the command following it
                            when mcl starts up. It can be specified multiple
                            times.
                            

mcl will write the configuration file when you quit it, including all the
options, so it might be easier just to start mcl up once then quit, and edit
the ~/.mcl/mclrc file. Note that the modified-time of the configuration file
is saved when it is loaded: when mcl exits, it verifies that the file has not
been changed since it was loaded before writing.

Options pertaining to the Chat subsystem are descriged in the file doc/Chat.


Color values
------------

Following values can be used for the color settings:

Color      Normal    Bold
-----      ------    ----
Black           0       8
Blue            1       9
Green           2       A
Cyan            3       B
Red             4       C
Magenta         5       D
Yellow          6       E
White           7       F


The first hex digit is the background color, the second foreground. Remember
to prefix the number with 0x! For example:

statcolor=0x03

will make the window black, with cyan numbers. 0x3E would give a cyan
background, and bright yellow numbers. Note that the bold code can be used
only in the foreground: if set in background, it will cause blinking.


Aliases
-------

mcl supports aliases since version 0.41.2. Aliases are typically added by
hand to the mclrc configuration file.  Aliases placed outside of any MUD
definitions become global aliases; available in any MUD session. Aliases
placed just inside a MUD {} section are local to that MUD. An alias is defined
as follows:

Alias <alias name> <commands>

Alias name is one string of characters. If that word is encountered first on
a command line, it is replaced with the <commands> part. A few characters
have special meaning: ; is replaced with a newline, allowing for multiple
commands to be executed. % allows for argument expansion. %0 means all
arguments following the command, %n means exactly the nth argument. %-n
means arguments from 1 to the nth, and %+n arguments n and whatever follows.

The %+n notation is useful for commands that take a word and a string as
parameter, e.g.:

Alias tell say I told %+2 to %1; tell %1 %+2

You can view currently active aliases by using Alt-A. You can view aliases for
a specific MUD by using Alt-O to list all MUDs, then pressing Alt-A while
selecting a MUD.

You can use #commands in aliases, as well as other aliases.

You can also define addition global aliases on the fly while in mcl, using
the #alias command, which works exactly like Alias in the configuratino file.

If you use an non-alphanumeric character as alias name (e.g. one of .$!@%^&)
you can use that alias without putting a space after it (I like to alias
% to #eval for example, so I can do %2**42 to find out what 2 to the 42nd
power is...)


Additional variables that can be expanded
-----------------------------------------

Certain codes in the form of % followed by a letter have a special meaning.
They can be used just about everywhere.

Letter              Function
h                   Hostname of the MUD you are currently connected to
p                   Remote port of current session
P                   Local port of current session
n                   Name of the current session
f                   mudFTP port of current session (%p + 6)
H                   Hour, 00-23
m                   Minute, 00-59
M                   Abbreviated month name (Jan, Feb)
w                   Abbreviated weekday name (Mon, Sun)
t                   Full date and time
d                   Day of the month
y                   Year (two last digits)