'\" t

.\"     Title: mcabber

.\"    Author: [see the "AUTHOR" section]

.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>

.\"    Manual: \ \&

.\"  Language: English

.\"

.\" -----------------------------------------------------------------

.\" * Define some portability stuff

.\" -----------------------------------------------------------------

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" http://bugs.debian.org/507673

.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.ie \n(.g .ds Aq \(aq

.el       .ds Aq '

.\" -----------------------------------------------------------------

.\" * set default formatting

.\" -----------------------------------------------------------------

.\" disable hyphenation

.nh

.\" disable justification (adjust text to left margin only)

.ad l

.\" -----------------------------------------------------------------

.\" * MAIN CONTENT STARTS HERE *

.\" -----------------------------------------------------------------

.SH "NAME"

mcabber \- a simple Jabber (XMPP) console client

.SH "SYNOPSIS"

.sp

\fImcabber\fR [ \-h | \-V | \-f configfile ]

.SH "DESCRIPTION"

.sp

mcabber(1) is a small Jabber (XMPP) console client\&. For now it needs a configuration file to start, so please copy the sample mcabberrc file and adapt your connection settings\&.

.sp

You also need to have an existing Jabber account to use this software, as it cannot (un)register accounts yet\&.

.sp

Here are some of the features of mcabber:

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fISASL/SSL/TLS support\fR\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fIMUC support\fR

(Multi\-User Chat)\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fIPGP, OTR support\fR

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fIChat States\fR

support (typing notifications)

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fIHistory logging:\fR

If enabled (see the CONFIGURATION FILE section),

mcabber

can save discussions to text history log files\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fICommands completion:\fR

If possible,

mcabber

will try to complete your command line if you hit the Tab key\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fIInput line history:\fR

Any message or command entered is in the input line history and can be reused easily\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fIExternal actions:\fR

Some events (like receiving a message) can trigger an external action such as a shell script if you enable it in your configuration file\&. A sample events script ("eventcmd") is provided with

mcabber

source code, in the contrib directory\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fIModules:\fR

mcabber

can load modules (a\&.k\&.a\&. plugins) at runtime that extend its features\&.

.RE

.SH "OPTIONS"

.PP

\-h

.RS 4

Quick help usage message

.RE

.PP

\-V

.RS 4

Displays

mcabber

version and compile\-time definitions\&.

.RE

.PP

\-f configfile

.RS 4

Use configuration file

\fIconfigfile\fR

.RE

.SH "WINDOWS/PANES"

.sp

The mcabber(1) screen is divided into 4 regions\&. The \fIroster\fR, alias \fIbuddylist\fR, is on the left\&. The \fIchat window\fR, or chat buffer, is on the right\&. The \fIinput line\fR lies at the bottom of the screen, under a small \fIlog window\fR\&.

.sp

Two status lines surround the log window\&. The bottom status line is the "main status line" and reflects mcabber general status\&. The other line is the "chat status line" and shows the status of the currently selected buddy\&.

.sp

To display buddies chat buffers, you will have to enter \fIchat mode\fR\&. You can enter chat mode by pressing enter, and leave chat mode with the ESC key\&. Simply sending a message will also enable chat mode\&.

.sp

There are several advantages to the two\-mode implementation: first, it allows accurate "unread" message functionality, as described in the next section; without this, merely scrolling to a specific buddy will "read" the new messages of all buddies in\-between\&. Second, it allows quickly hiding the conversation with a single keystroke\&. Third, it allows jumping between the few buddies with whom you are conversing with the \fI/roster alternate\fR command described in another section, without having to manually scroll back and forth\&.

.SH "KEYS"

.sp

Text typing occurs in the \fIinput line\fR; basic operations are supported (left arrow, right arrow, home/end keys, insert, delete, backspace\&...)\&.

.sp

PageUp and PageDown keys are used to move in the roster\&.

.sp

Up and Down arrow keys can be used to move in the input line history; they jump to the previous/next line from the history beginning with the same string (from first column to the cursor column)\&.

.sp

To send a message, move to the chosen buddy in the buddylist, type your message and hit enter\&. If the line begins with a slash, this will be interpreted as a command (see the COMMAND section below)\&. Hit escape to leave the chat mode\&.

.sp

Here is a quick description of the default key bindings:

.PP

Esc

.RS 4

Disable chat mode

.RE

.PP

Ctrl\-a

.RS 4

Go to the beginning of the input line

.RE

.PP

Ctrl\-e

.RS 4

Go to the end of the input line

.RE

.PP

Ctrl\-l

.RS 4

Force a refresh

.RE

.PP

Up/Down

.RS 4

Move in the input line history

.RE

.PP

PgUp/PgDown

.RS 4

Move inside the roster (buddylist)

.RE

.PP

Tab

.RS 4

Complete current word, in the input line

.RE

.PP

Ctrl\-g

.RS 4

Cancel completion

.RE

.PP

Ctrl\-c

.RS 4

Abort multi\-line messages and completions

.RE

.PP

Ctrl\-d

.RS 4

Send/terminate a multi\-line message

.RE

.PP

Ctrl\-p/Ctrl\-n

.RS 4

Scroll up/down half a screen in the buffer window (chat mode)

.RE

.PP

Ctrl\-Left

.RS 4

Move the cursor back to the start of the current or previous word

.RE

.PP

Ctrl\-Right

.RS 4

Move the cursor forward to the end of the current or next word

.RE

.PP

Ctrl\-u

.RS 4

Delete from beginning of the line to the cursor

.RE

.PP

Ctrl\-k

.RS 4

Delete from the cursor to the end of line

.RE

.PP

Ctrl\-w

.RS 4

Backward kill word

.RE

.PP

Ctrl\-t

.RS 4

Transpose chars

.RE

.PP

Ctrl\-o

.RS 4

Accept line and put the next history line in the input line (accept\-line\-and\-down\-history)

.RE

.sp

Additional key bindings may be specified using the \fI/bind\fR command described in the COMMANDS section\&.

.SH "MCABBER\(cqS ROSTER"

.sp

The first listed item on the roster is \fI[status]\fR, which keeps a log of everything that appears in the short log window below the main chat area\&. While the log window was designed for showing the latest few elements, the dedicated \fI[status]\fR buffer allows more comfortable viewing of the log, as well as scrolling it in a standard manner\&.

.sp

Group names are displayed above the items that are within them, and are indicated by \fI\-\-\-\fR to the left of the name\&.

.sp

For every real Jabber contact, the roster displays four pieces of information: the buddy\(cqs name or alias, its online status, its authorization status, and whether there are unread messages from the buddy waiting for you\&.

.sp

The online status is one of the following:

.PP

\fIo\fR

.RS 4

online

.RE

.PP

\fIf\fR

.RS 4

free for chat

.RE

.PP

\fIa\fR

.RS 4

away

.RE

.PP

\fIn\fR

.RS 4

not available (labeled

\fIextended away\fR

in some clients)

.RE

.PP

\fId\fR

.RS 4

do not disturb

.RE

.PP

\fI_\fR

.RS 4

offline (or invisible to you)

.RE

.PP

\fI?\fR

.RS 4

unknown, usually meaning you are not authorized to see this buddy\(cqs status

.RE

.PP

\fIx\fR

.RS 4

a conference room in which you are not participating

.RE

.PP

\fIC\fR

.RS 4

a conference room in which you are participating

.RE

.sp

The authorization status indicates whether a buddy is authorized to receive your online status updates, and is displayed by the brackets surrounding the buddy\(cqs online status\&. Square brackets, like \fI[o]\fR, indicate that this buddy is authorized to receive your status\&. Curly braces, like \fI{o}\fR, indicate that they are not authorized to receive your status\&.

.sp

When there are unread messages from a buddy which you have not looked at, a hash mark (\fI#\fR) appears in the leftmost section of the roster for that buddy\&. The hash mark disappears once you view that buddy\(cqs message buffer\&. When the user attention is requested (or when you receive a message containing your nickname in a MUC room), the hash mark is replaced with the \fIattention sign\fR, an exclamation mark (\fI!\fR)\&.

.sp

Examples:

.PP

\fI\-\-\- Buds\fR

.RS 4

This is a group named

\fIBuds\fR

.RE

.PP

\fI#[o] John\fR

.RS 4

John is online, can see your status, and sent you a message that you did not read yet

.RE

.PP

\fI{?} Sally\fR

.RS 4

Neither you nor Sally have authorized each other to see your online status

.RE

.PP

\fI{a} Jane\fR

.RS 4

Jane is away, but she cannot see your online status

.RE

.PP

\fI#[C] x@y\&.c\fR

.RS 4

You are participating in x@y\&.c conference room, and there are unread messages

.RE

.SH "COMMANDS"

.sp

Please refer to the online help (command /help), it is probably more up\-to\-date than this manpage\&. Furthermore, help files have been translated into several languages\&. You will find an overview of the mcabber commands in this manual\&.

.SH "COMMANDS RELATED TO MCABBER"

.PP

/add [jid [nickname]]

.RS 4

Add the "jid" Jabber user to our roster (default group), and send a notification request to this buddy\&. If no nickname is specified, the jid is used\&. If no jid (or an empty string "") is provided or if jid is "\&.", the current buddy is used\&.

.PP

[\fIjid\fR [nickname]]

.RS 4

Add to our roster "jid" as "nickname"

.sp

.if n \{\

.RS 4

.\}

.nf

Example: "/add somebody@jabber\&.server\&.com Somebody"

.fi

.if n \{\

.RE

.\}

.RE

.RE

.PP

/alias [name [= command line]]

.RS 4

This command let you to add aliases which can simplify sophisticated commands\&.

You can manage your aliases by:

.PP

(without arguments)

.RS 4

Print list of currently defined aliases

.RE

.PP

\fIname\fR

.RS 4

Print the value of alias called "name"

.RE

.PP

\fIname\fR=

.RS 4

Unset alias called "name"

.RE

.PP

\fIname\fR = command line

.RS 4

Set alias called "name" with value "command line"

.sp

.if n \{\

.RS 4

.\}

.nf

Example: "/alias away = status away"

.fi

.if n \{\

.RE

.\}

.RE

.RE

.PP

/authorization allow|cancel|request|request_unsubscribe [jid]

.RS 4