jtalk: user manual

Every day use

In this section, we assume that jtalk is set up, and that jtalkd is running and connected to Jabber servers. If it is not, see below to do it.

To call Somebody, open a new command line terminal, and type jtalk somebody@jabber.org. You will get a prompt. Everything you type at this prompt will be sent to Somebody, and everything Somebody sends you will be displayed above the prompt.

jtalk is the default front-end. At this time, it is readline-based jtalk, and no other exists, but it may change.

Unlike the Unix talk system, starting jtalk somebody@jabber.org will not notify Somebody that you want to talk to him. You have to actually send him a line, maybe "Hi." or "Are you there?".

Unlike the Unix talk system, Jabber, and therefore jtalk, works on a line-by-line basis and not on a char-by-char basis. You must validate a line with enter to actually send it.

jtalk understands IRC-like commands starting with /. If you want to send a line that actually starts with /, put an extra slash at the start.

Old messages and logging

All messages, both incoming and outgoing, are saved in ~/.jtalk/jid. Each message in those files is written as a trivial XML tree, with the additionnal guarantee that the element is at a beginning of line.

Furthermore, jtalk keeps messages in memory up to about 1 megaoctet.

When a new conversation is established, a few previous messages from the same peer are sent to the front-end to give some context. This context goes back to about one hour before the older undelivered message, or one hour before the most recent message if there are no undelivered ones.

Conversations with more than two people

Most Jabber clients provide only one-to-one chat (plus chatrooms for some). jtalk can simulate one-to-a-few chat: if several contacts are given on the command line, they are all included in the conversation, and outgoing messages are sent to each of them.

Please note that the contacts get no information about each other. If they use other clients, they will probably be confused to get messages that are not directed to them.

Command line arguments

By default, command line arguments (to the front-end) are names of contacts to include in the conversation. As a special case, any option starting with a slash will be interpreted as a jtalk command line. Please note that it will be re-split according to jtalk rules.

For example, the command line jtalk "/who tech" /quit </dev/null can be used in a shell script to just get a list of contacts.

Multiple accounts

If several accounts are set-up in jtalk, jtalk will try to smartly decide which one to use for each contact. The criteria are the existence of previous, possibly undelivered, messages to this contact, ant whether the connection is currently broken.

It is possible to explicitely select the source connection using the /from command: jtalk "/from me@jabber.org" he@jabber.org.

Starting jtalkd

To connect to your Jabber accounts and be able to send and receive messages, you have to start jtalkd. One jtalkd must be started per Jabber user on the system.

If invoked without option, jtalkd will simply run in foreground. Options are available to change that behavior:

-k
Instead of starting, jtalkd will try to kill an already-running jtalkd. If the option is given twice, jtalkd will repeatedly try to kill it until it is indeed dead. If the option is given thrice, jtalkd will continue to start after it is dead; else it will just exit.
-l
Instead of starting, jtalkd will print the PID of an already-running jtalkd.
-f
jtalkd will cleanly detach itself in the background.
-d pid
jtalkd will watch the process pid and exit when it exits. If pid is 0, the PID of the parent process will be used instead.

So if you want to start jtalkd along with your X11 session, you can put jtalkd -d 0 in your .xinitrc ou .xsession file.

Setting up jtalk

Setting up ~/.jtalk

The first time jtalk is started, it creates a directory ~/.jtalk which will keep the socket, the init file and the discussions transcripts. The socket itself lives in a subdirectory ~/.jtalk/socket. You chan change the path using the JTALK_BASE environment variable.

Setting up Jabber accounts and default options

Just after it has started, jtalkd reads ~/.jtalk/init as a list of commands (without the initial slash). This init file is useful to set default options (at this time, there are none), and, more importantly, to configure Jabber accounts. See the /account command description.

Commands

/account

The /account command takes a sequence of key[=value] options.

server=
the Jabber server. Required.
user=
the user name. Required.
pass=
the password. Spaces and % must be escaped as %20 and %25; others characters can be escaped the same way. Non-ASCII characters must be encoded as UTF-8. Required.
resource=
the resource; defaults to "jtalk".
jid=
the Jabber Id. Useful only if it is different from user@server.
tls
enable TLS (aka SSL)
port=
the TCP port; defaults to 5222 (5223 for TLS).

/from

This command sets the connection to use as a source for the next contacts. It can take one argument, the Jabber Id of the account, or zero, tu let jtalk use its standard algorithm.

/who

This command lists known contacts which are online or have undelivered messages. The “O” flag marks online contacts, the “U” flag marks undelivered messages. Undelivered messages are messages that have never been sent to a conversation; they may have been sent to a terminal, or only truncated.

The tech can be added to get a more script-friendly output.

/sorter

This command allows to sort and prioritize messages that may be displayed asynchronously in the user's terminal. The principle is the following: jtalk has a list of “sorters”, that can match a message or not, and have an asociated integer value, and a priority.

A message gets an importance value which is the sum of the values of the matching sorters of maximum priority, plus a builtin base value in the range [-5, 5]. If the importance value of a message is non-negative, the message is displayed. If the importance value if 10 or more, there is a bell.

The syntax to define a sorter is:

/sorter add [name name] val value [priority priority] on match condition

The name is just a convenient way to identify a rule, to later delete it (not implemented yet). The priority defaults to 0. The match condition is a bit more complicated.

Each message has a few key-values pairs on which one can put conditions. The match condition can be key regexp, to match messages where the value associated to key matches the regular expression. The regular expression use the Perl syntax.

Match conditions can be combined with logical connector using a prefix notation: & subcondition-1 subcondition-2 for a logical AND, | subcondition-1 subcondition-2 for a logical OR, and ! subcondition for a logical NOT. The prefix notation is a bit awkward, but it avoids the need for parentheses and is simple to parse.

For example, to make new messages bell, but forget spams, one can write: 

/sorter add name beep value 10 on type unconnected.message
/sorter add name spam1 value -100 on & type message text prOn

Here is a quick list of the possible messages: