-*- mode: casey-html -*-
Time-stamp: <2002-01-16 11:59:01 crabbkw>
--------------------------------------------------------------------------
This documentation is out of date. Use the documentation from in the
docs directory.

make install
will install imcom in /usr/local/share/imcom and create a link to it in
/usr/local/bin/imcom
--------------------------------------------------------------------------

What is IMCom
     IMCom is console Jabber Client written in Python. It in many ways
resembles micq because that is the ICQ client that I used before
switching to jabber.

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

What does IMCom require
     IMCom first and foremost requires a python interpreter which can
be obtained at www.python.org. I have tested only with python 2.0. It
may work with python 1.x and it may work with python 2.1, I don't know
though. Also, this has only been tested on the linux C Python version
2.0. If someone is willing to test on other platforms/version please
contact me.
IMCom requires the pyexpat or expat module for python. Note that while
the windows binary distribution of python includes the expat parser
the linux source by default doesn't build in support for expat. You
have to edit the Setup file in the Modules subdirectory of the source
tree and specify where the expat library and includes are kept. For
more information about building python with expat support read the
python README and the Modules/Setup.in file from the python source
tree.
The expat library itself can be found here:
    http://www.jclark.com/xml/expat.html

It is highly recommended, but not required, to have the readline
module for python installed as well.
Readline needs to be explicitly compiled in under unix.
Windows does not ship with readline, but supposedly there is a working
implementation here:
http://newcenturycomputers.net/projects/readline.html

IMCom supports
  * Account Creation
  * Roster Management (adding, removing users)
  * Status changing
  * VCard retrieval (very basic)
  * Logging
  * Auto-reconnecting on disconnect
  * Command and color customization
  * Primitive group support
  * Transport Registration (icq, aim, msn, etc)
  * File Transfer

IMCom does NOT support
  * Group Chat
  * VCard submission
  * Searching for users
  * SSL Connections.

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

Where can I get IMCom
http://imcom.floobin.cx       Documentation
http://imcom.floobin.cx/src   Archives
http://discobob.dyndns.org/~crabbkw/imcom/  Bleeding Edge Source

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

How do I start IMCom?
There are two programs in the IMCom suite right now,
 * the command-line interface, which is started by python CLI.py
 * the account-creation utility which is started by
     python AccountCreator.py
Note that while the client has been fairly well tested, the
AccountCreator has not.

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

How do I use IMCom
IMCom is command driven, the default commands are the following:

      /msg              /msg airog hello
      Sends a message a user. The username can either be a nickname
      you have specified or a fully qualified Jabber ID. This has two
      modes, single-line mode and multi-line mode. In single-line mode
      it takes a username and a message to send. In multi-line mode
      hit enter after typing the username and it will display a
      different prompt: [msg]: Type a period on a line by itself to
      send the message, or a hash( # ) on a line by itself to cancel
      the message.

      e
      Displays a list of users currently online.

      w
      Displays the status of everyone on your roster.

      /info             /info airog@jabber.zollers.net
      Retrieves the VCard of a user. It will display only the
      Fullname, Given Name, Family Name and Nick Name. It takes either
      a nickname or a fully qualified JID.

      /add              /add airog@jabber.zollers.net airog
      Adds a user to your roster, requesting permission if need
      be. The first parameter is the fully qualified Jabber ID, the
      second parameter is the nickname to give the JID.

      /remove           /remove airog
      Removes a user from your roster. The user may be specified as a
      nickname or a fully qualified Jabber ID.

      /online           /online
      Sets your current status to online.

      /chat             /chat
      Sets your current status to free for chat

      /away             /away I've stepped out for a minute
      Sets your current status to Away with the reason specified.

      /xa               /xa I'm going to bed
      Sets your current status to eXtended Away with the reason
      specified. Extended Away is equivalent to Not Available.

      /dnd              /dnd I'm doing homework
      Sets your current status to Do Not Disturb with the reason
      specified.

      /quit
      Quits the program.

      //                // I'm doing well
      Sends a message to the last person you messaged. This command
      has similar functionality and options as /msg

      /r                /r I'm doing well, yourself?
      Sends a message to the last person who messaged you. This
      command has similar functionality and options as /msg

      /set              /set colors off
      Sets boolean variables as to how IMCom behaves. The boolean
      values accepted as true are "true", "yes". Everything else is
      interpreted as false. Currently the following variables are
      supported:
      * statusshow  Whether or not to show status updates
      * colors      Whether or not to use colors
      * debug       Whether or not to output debugging information
      * ringbell    Whether or not to ring the terminal bell on incoming msg

     /auth              /auth airog@jabber.zollers.net
     Sends authorization to a user so that they can add you to their
     roster. The user may be specified by either nick or fully
     qualified Jabber ID.

     !                  ! ls ~
     Executes the rest of the line as a command.

     /rename            /rename airog@jabber.zollers.net casey
     Gives a new nickname to a roster item. The first parameter can be
     either a nickname or a fully qualified Jabber ID, the second
     parameter is literally the new nickname.

     /delete            /delete airog@jabber.zollers.net
     Completely removes all information about a user from your
     roster. Note that you can remove people's subscription to your
     presence by doing this. This command is not recommended general
     use.

     /listprofiles
     Lists all the profiles currently in the configuation file.

     /switchprofile     /switchprofile seifer
     Switches profile to the named profile.

     /show              /show lurker
     Lists all users in a particular group. Without an argument, lists
     all the groups that exist.

     /addgroup          /addgroup airog lurker
     Add a user to a group

     /delgroup          /delgroup airog lurker
     Remove a user from a group

     /setgroup          /setgroup airog lurker
     Set a users group to be just the group specified.

     /membership        /membership airog
     Shows the list of groups a person belongs to.

     /agents            /agents
     Retrieves a list of all transports available on the server.

     /agenthelp         /reghelp icq.floobin.cx
     Gets help on registering for a transport on the server.
     This step is REQUIRED in the registration process.

     /agentreg          /agentreg icq.floobin.cx 1227636 airog yeahright
     Registers with a transport on your server. The agenthelp command must
     be issued before this command will be successful, the agenthelp command
     will tell you the exact format of this command as it changes from time
     to time.

     /sendfile          /sendfile airog /home/crabbkw/testme.txt
     Sends a file to a user. The transport MUST support file transfer
     for the file to send. ICQ, AIM, MSN transport DO NOT SUPPORT file
     transfer.

     /getfile           /getfile airog
     Initiates a file transfer when someone is trying to send you a
     file. The file will be saved in ~/.imcom/files

     /saveprefs         /saveprefs
     Saves your preferences.

     /alias             /alias today ! date
     Creates a textual substitution alias. The example above creates
     the aliased command today, which runs the date program.
     /alias by itself will list the aliases which currently exist

     /unalias           /unalias today
     Removes an existing alias. Remember to save your preferences
     after creating or removing an alias

     /help
     Show the commands available and a brief description of them.


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

How do I customize IMCom
    IMCom is a very customizable program. The commands and colors are both
completely customizable by tweaking the configuration file. The
configuration file is in pure XML. The configuration file is stored in
~/.imcom/imcomrc

The following is a complete example of a configuration file.

<imcom default='jabber.org'>
        <command>
                <msg>/msg</msg>
                <e>e</e>
                <w>w</w>
                <info>/info</info>
                <add>/add</add>
                <remove>/remove</remove>
                <online>/online</online>
                <chat>/online</chat>
                <away>/away</away>
                <xa>/xa</xa>
                <dnd>/dnd</dnd>
                <quit>/quit</quit>
                <reply>//</reply>
                <respond>/r</respond>
                <set>/set</set>
                <auth>/auth</auth>
                <bang>!</bang>
                <rename>/rename</rename>
                <delete>/delete</delete>
                <listprofiles>/listprofiles</listprofiles>
                <switchprofile>/switchprofile</switchprofile>
                <show>/show</show>
                <addgroup>/addgroup</addgroup>
                <delgroup>/delgroup</delgroup>
                <setgroup>/setgroup</setgroup>
                <membership>/membership</membership>
                <agents>/agents</agents>
                <agenthelp>/agenthelp</agenthelp>
                <agentreg>/agentreg</agentreg>
                <getfile>/getfile</getfile>
                <sendfile>/sendfile</sendfile>
                <alias>/alias</alias>
                <unalias>/unalias</unalias>
                <saveprefs>/saveprefs</saveprefs>
                <help>/help</help>
        </command>
       <profile name='jabber.org' debug='false' statusshow='true'
    ssl='false' colors='true' ringbell='true'>
                <server>jabber.org</server>
                <port>5222</port>
                <user>testuser</user>
                <password>yeahright</password>
                <resource>at home</resource>
                <command>
                        <msg>/msg</msg>
                        <e>e</e>
                        <w>w</w>
                        <info>/info</info>
                        <add>/add</add>
                        <remove>/remove</remove>
                        <online>/online</online>
                        <chat>/online</chat>
                        <away>/away</away>
                        <xa>/xa</xa>
                        <dnd>/dnd</dnd>
                        <quit>/quit</quit>
                        <reply>//</reply>
                        <respond>/r</respond>
                        <set>/set</set>
                        <auth>/auth</auth>
                        <bang>!</bang>
                        <rename>/rename</rename>
                        <delete>/delete</delete>
                        <listprofiles>/listprofiles</listprofiles>
                        <switchprofile>/switchprofile</switchprofile>
                        <show>/show</show>
                        <addgroup>/addgroup</addgroup>
                        <delgroup>/delgroup</delgroup>
                        <setgroup>/setgroup</setgroup>
                        <membership>/membership</membership>
                        <agents>/agents</agents>
                        <agenthelp>/agenthelp</agenthelp>
                        <agentreg>/agentreg</agentreg>
                        <getfile>/getfile</getfile>
                        <sendfile>/sendfile</sendfile>
                        <alias>/alias</alias>
                        <unalias>/unalias</unalias>
                        <saveprefs>/saveprefs</saveprefs>
                        <help>/help</help>
                </command>
                <color>
                        <user>brightgreen</user>
                        <status>yellow</status>
                        <error>brightred</error>
                        <messagebody>cyan</messagebody>
                        <time>blue</time>
                        <desc>purple</desc>
                        <sep>brightblue</sep>
                        <default>white</default>
                        <key>green</key>
                </color>
       </profile>
</imcom>

    You do not have to specify all the subelements under command or color,
the defaults will be used for all subelements not appearing. The
command has a section outside profiles. This is the global command
section applying to all profiles. The profile command section will
override the imcom profile section.

    The following values are valid for colors:
    * darkgray
    * brightred
    * brightgreen
    * yellow
    * brightblue
    * purple
    * brightcyan
    * white
    * black
    * red
    * green
    * brown
    * blue
    * magenta
    * cyan
    * lightgray

    The following are subelements of color:
    * user        the color to use for all JIDs and nicknames
    * status      the color to use for all status information
    * error       the color to use when an error occurs
    * messagebody the color to use for a message body
    * time        the color used to display time stamps
    * desc        the color used for all descriptions
    * sep         the color used for all separators
    * key         the color used for keys in key, value pairs
    * default     the color used by everything else

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

What do you mean group support?

Each user can belong to 0 or more groups. To show the groups a
particular person belongs to use the membership command.
Example:
        /membership airog
This would return the list of groups the user airog belongs to.

To see which users belong to a particular group use the show command.
Example:
        /show lurker
This would return a list which looks very similar to the roster list
except that it only shows users which are members of the group lurker.

To see a list of the groups that you have just use the show command
with no arguments.
Example:
        /show
This would return the list of groups currently in existance.

Note that you never actually have to create a group. Simply adding a
user to a non-existing group will create that group.

There is currently one special group. The lurker group is used for
people who you want to have Nick<->JID matching on, but don't want to
see status updates for or even on your roster at all. For instance, I
use the lurker group for people who I have on my list twice, once with
their icq user and once with their jabber user. I add their icq user
to my lurker group so I never see it unless I really want to. I also
use it for people who I very rarely talk to. People who are a member
of the lurker group will only ever show up if you use the show command
to show the members of group lurker. If a user (bob) belongs to both
lurker group and school group, and you use the show command to list
the members of the school group bob will not appear in that list
because he is a lurker. The only list a lurker will show up in is the
lurker list.

To add a user to a group use the addgroup command. It will create the
group if necessary.

To remove a user from a group use the delgroup command. It will remove
the group if no users exist in the group anymore.

To set a user belonging to just one group use the setgroup command. It
will create the group if necessary.


------------------------------------------------------------------------
File Transfer information.

To send a file user:              /sendfile airog myfile.txt
To receive a file from a user:    /getfile airog
To refuse receipt of a file simply ignore it.

Files are saved in ~/.imcom/files

------------------------------------------------------------------------
$0 through $9

The person who most recently evented you is stored in $0 through $9.
Events include messages, auth requests, file requests, basically everything
EXCEPT status changes.

This is an advanced feature and not yet well tested at of version 0.62.
It is useful when random3409783408@jabber.org messages you because you
can then just
/info $0
To get info on random3409783408@jabber.org.

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

This is another advanced feature that was requested. Basically aliases
are textual-substitution commands. That is, you can shorten one
command line to a single command. For instance, say you are running on
a unix system and want to bind the command /cls to clear the
screen. You could
/alias /clear ! clear
Which would create the alias /clear, which would literally run
! clear

Let say I message user bob often. I could
/alias /bob /msg bob
which would allow me to
/bob hi!
Sending the message "hi!" to bob.

To get a list of aliases use just
/alias

To remove an alias use
/unalias <alias-name>
eg: /unalias /bob

To save aliases to your preferences issue a saveprefs command, which
defaults to /saveprefs


------------------------------------------------------------------------
Who maintains IMCom

    Casey Crabb (crabbkw@rose-hulman.edu) maintains IMCom and
enthusiastically accepts bug reports, especially if they are
reproducible. Feature requests are also taken into consideration and
potentially added to the list of things to do.
