        mIRC MUD/Telnet Client Script

        Copyright (c) 2000 Kimmo Kulovesi
        http://arkhan.cjb.net/

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
-------------------------------------------------------------------------------

    I know most people (me included) don't usually (= ever) bother to
read manuals, but... in this case I really, really, _really_ think you
should at least browse through the. This client is a bit harder to learn
than your average windows program, but I totally think it is worth it
(heck, I went and learned how to write mIRC scripts just so I could write
this client, think how much easier it is to read this manual? ;>).

    Ok, here we go. Sorry if the first few(?) chapters are
boring, I'll try to improve toward the interesting parts.


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

    (If your copy of mIRC is older than version 5.7, then
this is a good time to update - BEFORE you install this script. Just
download the latest version from " http://www.mirc.com/ ".)


    * Extract the followoing files to the directory where your mIRC
is installed:

        atelnet.mrc         (The main script)
        atelnet.cfg         (Configuration - EDIT THIS)
        attabword.cfg       (Tabwords - EDIT THIS)
        tcmds.cfg           (Popup menu)
        atelnet.ini         (Internal data - DON'T EDIT BY HAND - EVER)
        atelnet.txt         (This manual)


    * Open mIRC and select "Remote..." from the "Tools" menu. An editor
window should open.

    * From the editor window's "File" menu, select "Load" and "Script".
Switch "Files of type" to "Scripts (*.mrc)", and select "atelnet.mrc"
from the list.

    * mIRC will now ask if you wish to run the initialization commands.
You must answer "Yes", or the script will not be properly configured.

    * Close the editor window, and take a look at mIRC's status window.
If you did everything properly, there should be a list of commands for
the script displayed. If not, you probably did something wrong, or
your copy of mIRC is too old - try updating to the latest version from
"http://www.mirc.com/".


        Connecting
------------------

        /telnet <hostname>:<port>       Connect

    To connect to a telnet server, you simply use the command
"/telnet hostname", which connects you to the default telnet port (23).
Usually you will want to specify the port, too, so you can use either
"/telnet hostame:port" or "/telnet hostname port". For you mouse lovers,
you can also click with the right mouse button on the "Status" window and
select "Telnet" from there.

    Once connected, you can bring up a popup menu by clicking the second
(usually on the right) mouse button inside the telnet session window.
This menu will be used to access most of the script's functions. Explore
this menu and try the functions/settings as you please.

    To disconnect, either close the telnet window from the "[x]" in the
titlebar, or select "Disconnect" from the popup menu to terminate the
connection without closing the window. The window is also left open if the
server disconnects you (for example, when you send a "quit" command).

    You can also re-use a telnet window, if you get disconnected and want to
reconnect to the same server while maintaining that window and its settings.
Simply select "Reconnect" from the popup menu (or type "/rec").


        The Editbox
-------------------

    To send text over the telnet connection, you type it in the editbox at
the bottom of your telnet session window. The text is sent only after you
press ENTER, so you can use the standard editing keys to modify it meanwhile.
You can also press the UP/DOWN arrows to recall previous lines you have sent
- this is in my opinion the most useful feature of the editbox.


        Multi-line commands
---------------------------

        <line1>\<line2>\<etc>           Send multiple commands


    Sometimes you may wish to enter more than one command in a single line,
for example when you want to make sure that nothing has time to intervene
with your commands.

    To accomplish this, you can separate multiple commands on the same line,
by using backslashes ("\") between them. For example, to send the commands
"draw sword" and "kill dragon" (heh, right), you could type: "draw sword\kill
dragon" and then press enter to send them as two separate lines (without the
backslash, of course).

    This backslash-method also works in (telnet client) aliases and triggers,
both of which I will (attempt to) explain below. The downside for using this is
that in many keyboard layouts you must press "ALT GR" to get the backslash
character... For such users, and others, I recommend trying the Dvorak-layout -
use your favorite web search engine to find a string like: "+dvorak +keyboard
+layout" or whatever. Heh, alright, I know you Qwerty-users are too attached to
those infernal boards to dare the change for better... ;>


        Unparsed commands
-------------------------

        \<literal command>              Send a string without parsing it
        \                               Send an empty line
        // <literal string>             Send a without a trailing linefeed
        //                              Send a plain TAB-character


    Some of either the telnet client's or mIRC's internal commands may
collide with the string you wish to send out to the MUD, or you may want to
bypass an alias of your own. This is possible by prefixing the line with
a backslash.

    So, to send the line "/help" to the telnet server, you would have to
use "\/help", or "/help" would get caught as a local command. This way
you can also send backslashes, which otherwise would be parsed as multiple
commands: "\first line\more" is NOT send as "first line" and "more", but
literally as "first line\more".

    You can also use "\" alone to send an empty line - something that mIRC
refuses to do otherwise.

    Sometimes you may also wish to send strings to the server without a
trailing linefeed (that is, as if you had not pressed ENTER after the
string). This can be accomplished by typing "// <string>" where "<string>"
is obviously what you want to send. Notice the space between "//" and the
string - mIRC will parse "//string" into "/string" - not what we want.

    Typing "//" alone can be used to send a single TAB-character, as sending
one of those can be difficult (though not impossible) by other means.


        Tabwords
----------------

    Often the commands you use on MUDs seem to follow the old 2-98 rule - that
is, you use 2% of the commands 98% of the time. To make access to the most
frequently used commands, you can define "tabwords". When you type a couple of
the first letters of a word, and then press TAB, the word will be expanded to
the first matching tabword.

    That is, if you have defined a tabword "command", and you type "co" and
then press TAB, the "co" you typed will get replaced with "command". If
multiple tabwords have the same beginnig, you can cycle through them by
pressing TAB repeatedy.

    To define tabwords, simply open the file "ttabword.cfg" and place the
words there - one on each line. When you open a telnet session, the file
will be read and used to fill the list of tabwords.

    You can also enter tabwords dynamically for each session; It is nice for
mudders to have names of fellow characters in your list of tabwords. However,
entering all characters you know to the list of tabwords would not be very
practical. Therefore, you can specify new tabwords on the fly, while you play
the mud:

    If you use one of the commands: "tell", "look" or "greet" followed by
a word beginning with a capital letter, that word will be added as a tabword
- but only for that single session.

    For example, you see a friend of yours in a mud, called "Hername". Usually
you'd probably do something like "greet hern". However - refrain just once
from this habit, and type "greet Hername" (with a capital letter). After that
"Hername" is added as a tabword for that session - no more colliding
abbreviations or keywords, since you can quickly handle the expansion
locally.

    As mentioned above, you can also do the same tabword adding with "tell"
"look". Use whichever fits the situation.

    If you dislike the list of tabwords appearing next to your telnet session
window, it can also be hidden - this is useful for when you already remember
what you put in the list, and don't want to see it anymore. To hide the list,
or make it visible again after hiding it, select from the popup menu:
"Global settings" -> "Tabwords" -> "Show list in sessions" and then "No" for
making the list hidden, or "Yes" for showing it.

    ...Due to a feature(?) in mIRC, the above change only takes effect on
new sessions you open - not the current one.


        Speedwalking and Path Memory
------------------------------------

        /sw <directions>                Speedwalk a path
        /sw                             Get (and clear) the path memory
        /rw <directions>                Convert the directions to reverse
        /rw                             Get and reverse the path memory

        Special directions: "h" = "nw, "j" = "ne", "k" = "sw", "l" = "se"


    Speedwalking is a handy feature for MUD use - it allows to send long
queues of movement commands, in a single line. It is used with the "/sw"
command, followed by a string formatted as "<count><direction>".

    That is, to walk five steps north, you would do: "/sw 5n". But, you can
also specify longer strings at once, for example, to walk one step down,
two south, one west and fifteen north, you would use: "/sw d2sw15n".

    In addition to the standard "n", "s", "e", "w", "u", "d" directions,
speedwalking also supports four special directions:

        In path as  Sent as
        ----------- -------
        h           nw
        j           ne
        k           sw
        l           se
        <others>    <as is>

    Outgoing movement commands are also recognized for tracking purposes
(wether you enter them by hand or by speedwalking) - movement commands are
never echoed locally (to avoid clutter). Instead, they are shown in the
titlebar of the telnet session window, in a the same format which speedwalk
uses. For example, if you enter "n", "n", "sw", the end of the title bar
will show: "2nk".

    An "enter" command will show up as a dot (".") in the path - note that
to get that dot to appear you must type "enter" fully, even though MUDs
generally will recognize something like "ent".

    If you want to enter movement commands without changing that path,
you can do so by using "\<command>". For example, if you try to walk north
by sending an "n", but fail to notice that the door is shut, you may wish
to (after opening the door) send "\n", so that the duplicate direction does
not appear in the path.

    To fetch this path from the memory, you can type "/sw" with no parameters.
This will clear the path memory from the titlebar, and fill your editbox
with "/sw <path>", where "<path>" is the path just as seen in the topic. This
command is naturally not sent to the server, so you can simply press CTRL-C
to copy it for later use (see "Aliasing Speedwalk Paths", below).

    As you probably figured out, sending the path retrived from memory will
NOT get you to where you started. In fact, it is highly unlikely to get you
anywhere you want to go. To get from your current position to where you
started recording the path, you need to reverse the directions, so that the
order becomes reverse, and "n" becomes "s", etc...

    The "/rw" command is provided to do exactly that - it fills your editbox
with the speedwalk command for the reverse of the path. That is, if you enter
"/rw w3e", your editbox will be filled with the command "/sw 3we". That's
all there is to it... now you can either copypaste that command for use
in some alias, or press enter to send the directions.

    Like "/sw", "/rw" without parameters fetches the path memory from the
titlebar.


        Aliases
---------------

        /calias                         Edit/define/remove telnet aliases
        /calias <alias>                 Edit/define <alias>

        /alias <name> <command> ...     Define mIRC alias /<name>
        /alias <name>                   Remove mIRC alias /<name>

        /me <action>                    Predefined alias for "emote <action>"


    Since the telnet client runs under mIRC, there are actually two kinds
or aliases supported - mIRC aliases, and telnet aliases.

    Unlike mIRC aliases, telnet aliases do not begin with a slash ("/"),
which keeps them separate from other commands. When defining the aliases,
you can choose whichever naming scheme you want, from plain words to
something like ".alias".

    To create telnet aliases, simply use the "/calias" command, and a dialog
will be brought up, which allows you to define the alias, and view the list
of existing aliases. To remove an existing alias, just leave the "commands"
box empty. Instead of typing "/calias" you can also select "Aliases" from
the popup menu (right click in session window).

    If you prefer to command lines to dialogs (like I do), you can also
use the syntax "/calias <alias> <command(s)>". The dialog will still appear,
but the textboxes will be prefilled according to what you specified on the
command line - just press enter to approve the settings. In addition, if
you wish to edit an existing alias, type "/calias <alias>" - or use the
alias list in the dialog to select from the list.

    Note that aliases can also contain other telnet aliases in themselves,
which will also be expanded - this can be handy, but take care not to create
loops. If you create an alias: "dothis" and have it execute the command
"dothat", and then create an alias called "dothat" and have it execute the
command "dothis", then... well, you figure it out. Don't try this at home.

        ... You are just itching to try it, aren't you?

    Only the first word of each line is checked alias matches - this
ensures that speech, for example, will not get expanded into aliases.
Therefore, if you have an alias "hello", you can still do "say hello"
and the word "hello" there will not get interpreted as an alias. Aliases
also work on lines with multiple commands... consider this example:

    Alias: "good"  Commands: "greet\say Good"

    Now, with that alias, you enter the line: "good morning.\sit table"

It will get expanded into three lines: "greet", then "say Good morning.",
and finally "sit table".


        Aliasing Speedwalk Paths
--------------------------------

    If you want to create aliases for frequently used speedwalk paths, you'll
have to use mIRC aliases (since telnet-specific aliases are not parsed for
local commands). This is how:

    "/alias <pathname> totelnet cmd /sw <path>"

    So, if you wanted to create a path called "pubtohome", and the movement
commands were "se14n", you would do "/alias pubtohome totelnet cmd /sw se14n".
After this, you could walk the path by typing: "/pubtohome".

    If you also want the reverse path, use "/rw path" to get the command for
the reversed path for you, then simply use that path in a similar fashion,
perhaps imaginatively calling it "hometopub". ;>


        mIRC aliases with telnet
--------------------------------

    To send commands to the telnet from mIRC aliases, you need to do it
in a rather twisted way. You cannot just send the command directly, since
mIRC will want to interpret it. Therefore, I have made a silly alias to
get the telnet window to parse your commands. Do:

    "/telnet cmd <command>"

    For example, "/telnet cmd say This goes to telnet.\nod" is the same as
typing "say This goes to telnet.\nod" in the active telnet window.

    Ah, there. Notice the word "active". This command only works when you
are in a telnet window. If you are doing some diabolically complicated
scripting, you could use "/totelnet" followed by the sockname of the
connection related to the telnet window you wish to send to. If you didn't
understand that, you don't even want to know. Trust me. ;>


        String Replacement
--------------------------

        /creplace                       Edit/define/remove string replacements
        /creplace <replace>             Edit/define <replace>
        /trigs                          Toggle replacements on/off


    Sometimes it may be desireable to make modifications to incoming text.
Let us take this fictional example:

---
An exemplary-looking man is entering from the south.

An exemplary-looking man says in Harnic,
    "Good morning, I am John."

You tell an exemplary-looking man in Harnic,
    "Well met, John."
---

    Note two things that you might want to change in this text. First of
all, after you that "an exemplary-looking man" in called "John", you probably
would be happier if his name showed up instead of the description. Secondly,
since you both obviously are speaking "Harnic", you might consider removing
the "in Harnic" from cluttering your screen (after all, you'll still know
if someone _doesn't_ speak in Harnic).

    Then, the text would look like:

---
John is entering from the south.

John says,
    "Good morning, I am John."

You tell John,
    "Well met, John."
---

    ...Take your pick on which style you'd prefer to read countless pages
of, especially if often doing it when you should be asleep. ;>

    Fortunately (and very suprisingly? ;>), both goals can be easily
accomplished with the string replacement feature in the telnet client. However,
there is a subtle difference between the two replacements described in our
example. If done only once, neither of the two stands out. However, in the
long run, it would be tedious to use the dialogues for entering a name
for each character you meet. Therefore, two different ways of defining
string replacements are available - one for general use, one specifically
for character names (and alike, be they items or flowers or whatever).

    Let us define the replacement for "in Harnic" first. Actually, we also
want to remove the space before "in Harnic", too, so make that " in Harnic"
instead. The dialog and syntax are almost identical to alias definitions - use
"/creplace" to bring up the dialog. Enter " in Harnic" as the text to replace,
and for the text to replace with... ah, here you run into trouble.

    See, if you specify no text to replace with, it is assumed that you
don't want any replacement to be done for that string. There are two
alternatives for you in this case: The first is to go around the replacement:
specify an additional character for the replacement - in this case, you could
use the comma: replace " in Harnic," with ",".

    However, there are situations where you cannot do anything like that.
Therefore (as reminded by the replacement dialog), a special token can be
used for replacement: "@N^" is replaced with absolutely nothing in the
replacement string. Therefore, if you want to remove all occurences of the
string " in Harnic" entirely, use "@N^" for the replacement string.


    HINT: I recommend creating a string replacement for your MUD's default
prompt, that colorizes it to a lighter (easy to ignore) color. For example,
if the MUD gives you a prompt like "<75hp 80mvs>", you could create
replacements for "<75hp " (replace with: <CTRL-K>(color number)"<75hp") and
"mvs>" (replace with: <CTRL-K>"mvs>"). This way the prompt is colorized
when you have 75 hitpoints, but if you lose some of them, it is displayed
in the default color (making it easier to see).


    ...For the name <-> description replacement, there is an easier way,
however. Read on...


        Character names <-> descriptions
----------------------------------------

        /describe <name> <description>  Enter description for character <name>
        /look <partial name or desc>    Look for description/name in list
        /undesc <name>                  Remove description for <name>


    Since character names are the most common type of string replacement
people (alright, I) tend to use, I've implemented a set of commands just for
that purpose.

    They are very simple, so I will not confuse you with detailed
explanations. Instead, here is a list of examples on how to use them:

        /describe John an exemplary-looking man

                = Add (or change) description replacement for "John"

        /look john

                = Find all occurences of "john" in the replacements

        /look exempl

                = Find all occerences of "exempl" in the replacements

        /undesc John

                = Remove description for "John"


        Alternate descriptions database
---------------------------------------

    Using the "/describe" feature (as documented above) to replace character
descriptions with their names is unfortunately not very easy on the processor.
After all, for each name to be replaced, all incoming text has to be searched
for a match.

    Therefore, it is often preferable to only keep a few friends in the
replacement database. For keeping track of the rest of the characters you meet,
you can maintain as many alternate description databases as you wish, with
these four simple commands:

        /descf <filename>               Select filename for these ->
        /descf                          Show which file is currently in use
        /wdesc <name> <description>     Enter description for "<name>"
        /desc <search>                  Search file for description/name
        /rdesc <name>                   Remove description for "<name>"

    For example, to start a names database called "mudchars.dat", type:
"/descf mudchars.dat". To enter the example character "John" shown above to
that database, you would then use: "/wdesc John an exemplary-looking man".
"/wdesc" can also be used to change descriptions for existing names
(duplicates are not added).

    To find entries in the database, you can use "/desc" just as you would use
"/look" described above. You can also list _all_ entries in the database by
typing "/desc *". To remove a character from the database, use "/rdesc John"
(for our example character).


    HINT: You can also use these commands to maintain a searchable
database of other notes. For example, you could keep a list of
alchemical recipes like "/wdesc potion_strength ingredient1 ingredient2 ...".

    These commands work from all mIRC windows, so you can also use these for
other than MUD purposes (phone numbers, e-mail addresses, URLs, or whatever).
Furthermore, you can use mIRC aliases to make shorter commands for switching
database files.


        Logging
---------------

    You can log the sent and received text from a telnet session to a file.
You can either select the file yourself (by using "/log <filename>", or
selecting interactively from a dialog, selecting "Select logfile..." from
the popup menu (click right mouse button in telnet session window), or
you can have the name of the file generated automatically, based on the
name of the host you are on and the current date, by using "/log auto",
or "Logging on" from the popup menu.

    That is, for host "telnethost.com", started on February 21st, 2000, the log
would be: "telnethost_com_21Feb00.log". The directory for these logs can also
be specified in the configuration - it defaults to "logs", under the mIRC
directory. The directory specified must exist.

    You can specify automatical logging from "atelnet.cfg", which starts
logging at the same time as you connect, using a log file name formatted
as "hostname_ddMMMyy.log", just as if you entered the command "/log auto"
immediately after connecting.

    Try not to log to the same file from two sessions at once - the resulting
file gets rather messy. Autolog tries to avoid this automatically.


        Reminder of mIRC features
---------------------------------

    If, after all these features, you feel like something is missing -
I'd like to remind you to not ignore the features provided by mIRC. For
example - while this telnet client lacks an "address book" in it itself,
it is easy to implement one by simple use of mIRC commands;

    The most straightforward way is to use aliases. Simply use something
like "/alias tnhost telnet hostname.net 1234" - IN A mIRC WINDOW, not
a telnet window (since we want a mIRC alias, not a telnet alias). After
this, all you need to do is type "/tnhost" and you will be telnetted to
"hostname.net" port "1234".

    Another way would be to place the commands in menus. For example,
I never use the commands present in mIRC's modifiable "Commands" menu
- I rather type the commands or use popup menus. Therefore, one could
dedicate the entire "Commands" menu for Telnet addresses. Here is how:

    Select from mIRC's "Tools" menu -> "Popups". The editor window should
open. From that window's "View" menu, select "Menubar". Now, delete all
the text in that editor screen (or copy it to safety first - I doubt you'll
ever want to use those commands, though, since you can do the same things
a lot better from other menus).

    In the place of the text that was there, place (without the quotes):
"
T&elnet
Name of host1:/telnet address.to.host1.net:1234
Name of host2:/telnet address.to.host2.net:1234
"
    etc.
    This will replace the "Commands" menu with a "Telnet" menu. Neat. You
can even group hosts:

"
T&elnet
Group 1 of hosts
.Name of host1 in grop1:/telnet address.to.host1.net:1234
.Name of host2 in group1:/telnet address.to.host2.net:1234
Group 2
.Name of the only host in group2:/telnet address.to.host3.net:1234
Name of host which is not in any group:/telnet address.to.host4.net:1234
"

    So there.

    (Note: The current versions of mIRC are a bit strange about that
menu. You must have a mIRC child-window open (the status window, a channel
window, whatever), or mIRC will not respond to the menu commands.)


        Silly Commands That You Can Access Better from the Popup Menu
---------------------------------------------------------------------

        /close                          Disconnet (without closing the window)
        /rec                            Reconnect (re-use window)

        /log auto                       Start logging (generate filename)
        /log                            Stop logging
        /log <file>                     Start logging to specified file

        /trigs                          Toggle triggers/replacements on/off
        /lecho                          Toggle local echo on/off
        /lecho on                       Turn local echo on
        /lecho off                      Turn local echo off
        /cansi                          Toggle color scheme Custom/ANSI
        /status                         Show connection status

    (You DON'T have to memorize these commands. Just click inside a telnet
window with the right (second) mouse button, and you can use a popup menu
instead.)


        Calculator
------------------

        /calc <expression>              Calculator (use "a" for prev. answer)


    Heh. This doesn't really belong in this script at all, much less this
document, but... what the heck, I like it. "/calc" is just a simple mIRC
alias that... calculates. The fancy feature in this one is that it stores
the previous result in the variable "a"... therefore, you can do things
like:

"
    /calc (1 + 1) * 2           (that's... hmn... four ;>)
    /calc 1 + a * 2             (now, this is nine, because 1 + 4 * 2 = 1 + 8)
"

    Have fun. ;>


-------------------------------------------------------------------------------

E-mail me at arkhan@softhome.net if you have questions/bug reports/comments...

    If you like this script, tell a friend. Tell a few friends.
        Tell the world. ;>


