--- a/mcabber/doc/mcabber.1	Sat May 13 22:21:20 2006 +0200
+++ b/mcabber/doc/mcabber.1	Sat May 13 22:26:15 2006 +0200
@@ -34,15 +34,6 @@
 You also need to have an existing Jabber account to use this software, as it cannot (un)register accounts yet\&.
 
 
-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\&.
-
-
-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\&.
-
-
-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\&.
-
-
 Here are some of the features of mcabber:
 
 .TP 3
@@ -62,7 +53,7 @@
  Input line history: Any message or command entered is in the input line history and can be reused easily\&.
 .TP
 \(bu
- External actions: Some events (like receiving a message) can trigger an external action, for example a shell script (you need to enable it in your configuration file)\&. A sample events script ("eventcmd") is provided with mcabber source code, in the contrib directory\&.
+ External actions: 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\&.
 .LP
 
 .SH "OPTIONS"
@@ -73,7 +64,21 @@
 
 .TP
 \-f configfile
-Use configuration file configfile 
+Use configuration file configfile
+
+.SH "WINDOWS/PANES"
+
+
+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\&.
+
+
+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\&.
+
+
+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\&.
+
+
+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"
 
@@ -89,6 +94,7 @@
 
 To send a message, move to the choosen 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\&.
 
+
 Here is a quick description of the key bindings:
 
 Ctrl\-a		Go to the beginning of the input line
@@ -123,12 +129,51 @@
 
 Ctrl\-q		Jump to the next unread message
 
+Additional key bindings may be specified using the /bind command described
+in the COMMANDS section\&.
 
-.SH "COMMANDS"
+.SH "MCABBER'S ROSTER"
+
+
+The first listed resource 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\&.
+
+
+Group names are displayed above the resources that are within them, and are indicated by \fI\-\-\-\fR to the left of the name\&.
+
+
+For every real Jabber resource, the roster displays four pieces of information: the resource's name or alias, its online status, its authorization status, and whether there are unread messages from the resource waiting for you\&.
+
+
+The online status is one of the following:
 
-.TP
-\fB/add\fR [jid [nickname]]
-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\&.
+ \fBo\fR	online
+ \fBf\fR	free for chat
+ \fBa\fR	away
+ \fBn\fR	not available (labeled \fIextended away\fR in some clients)
+ \fBd\fR	do not disturb
+ \fBi\fR	invisible (displayed only for your resource)
+ \fB_\fR	offline (or invisible to you)
+ \fB?\fR	unknown, usually meaning you are not authorized to see this resource's status
+ \fBx\fR	a conference room in which you are not participating
+ \fBC\fR	a conference room in which you are participating
+
+
+The authorization status indicates whether a resource is authorized to receive your online status updates, and is displayed by the brackets surrounding the resource's online status\&. Square brackets, like \fI[o]\fR, indicate that this resource is authorized to receive your status\&. Curly braces, like \fI{o}\fR, indicate that they are not authorized to receive your status\&.
+
+
+When there are unread messages from the resource which you have not looked at, a hash mark (\fI#\fR) appears in the leftmost section of the roster for that resource\&. The hash mark disappears once you view that resource's message log\&.
+
+
+Examples:
+
+ \fB \-\-\- Buds\fR	This is a group named \fIBuds\fR
+ \fB#[o] John\fR   	John is online, can see your status, and sent you a message that you did not read yet
+ \fB {?} Sally\fR  	Neither you nor Sally have authorized each other to see your online status
+ \fB {a} Jane\fR   	Jane is away, but she cannot see your online status
+ \fB#[C] x@y\&.c\fR	You are participating in x@y\&.c conference room, and there are unread messages
+
+
+.SH "COMMANDS RELATED TO MCABBER"
 
 .TP
 \fB/alias\fR name = command line
@@ -139,17 +184,6 @@
 Example: "/alias away = status away"\&.
 
 .TP
-\fB/authorization\fR allow|cancel|request|request_unsubscribe [jid]
-Manage the presence subscriptions\&.
-
-If no jid is provided, the current buddy is used\&.
-
- \fBallow\fR  	allow the buddy to receive your presence updates
- \fBcancel\fR 	cancel the buddy' subscription to your presence updates
- \fBrequest\fR	request a subscription to the buddy's presence updates
- \fBrequest_unsubscribe\fR request unsubscription from the buddy's presence updates
-
-.TP
 \fB/bind\fR keycode = command line
 Bind a command line to the key with the "keycode" code number\&.
 
@@ -178,14 +212,20 @@
 The clear command is actually an alias for "/buffer clear"\&.
 
 .TP
+\fB/quit\fR
+Disconnect and leave mcabber(1)\&.
+
+.TP
+\fB/version\fR
+Display mcabber version
+
+.SH "COMMANDS RELATED TO THE SERVER AND CONNECTION"
+
+.TP
 \fB/connect\fR
 Establish connection to the Jabber server\&.
 
 .TP
-\fB/del\fR
-Delete the current buddy from our roster, unsubscribe from its presence notification and unsubscribe it from ours\&.
-
-.TP
 \fB/disconnect\fR
 Terminate connection to the Jabber server\&. Note: the roster is only available when the connection to the server is active, so the buddylist is empty when disconnected\&.
 
@@ -199,6 +239,31 @@
  \fBlist\fR	list all pending events
 
 .TP
+\fB/rawxml\fR send
+ \fBsend\fR string: send string (raw XML format) to the Jabber server\&. No check is done on the string provided\&. BEWARE! Use this only if you know what you are doing, or you could terminate the connection\&.
+
+.SH "COMMANDS RELATED TO THE ROSTER AND JABBER RESOURCES"
+
+.TP
+\fB/add\fR [jid [nickname]]
+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\&.
+
+.TP
+\fB/authorization\fR allow|cancel|request|request_unsubscribe [jid]
+Manage the presence subscriptions\&.
+
+If no jid is provided, the current buddy is used\&.
+
+ \fBallow\fR  	allow the buddy to receive your presence updates
+ \fBcancel\fR 	cancel the buddy' subscription to your presence updates
+ \fBrequest\fR	request a subscription to the buddy's presence updates
+ \fBrequest_unsubscribe\fR request unsubscription from the buddy's presence updates
+
+.TP
+\fB/del\fR
+Delete the current buddy from our roster, unsubscribe from its presence notification and unsubscribe it from ours\&.
+
+.TP
 \fB/group\fR fold|unfold|toggle
 The group command changes the current group display\&.
 
@@ -235,10 +300,6 @@
  \fBabort\fR          	leave multi\-line mode without sending the message
 
 .TP
-\fB/rawxml\fR send
- \fBsend\fR string: send string (raw XML format) to the Jabber server\&. No check is done on the string provided\&. BEWARE! Use this only if you know what you are doing, or you could terminate the connection\&.
-
-.TP
 \fB/rename\fR nickname
 Rename current buddy to the given nickname\&. This command does not work for groups, at the moment (but you can move the buddies to another group with the "/move" command)\&.
 
@@ -312,14 +373,10 @@
 
 Note: The jid can include a resource (i\&.e\&. user@server/resource)\&.
 
-.TP
-\fB/version\fR
-Display mcabber version
-
 .SH "CONFIGURATION FILE"
 
 
-See the provided sample configuration file, which should be self\-documented\&.
+See the provided sample configuration file, which should be self\-documenting\&.
 
 .SH "FILES"
 
@@ -327,11 +384,9 @@
 The following files can be used by mcabber(1):
 
 .nf
-
 $HOME/\&.mcabber/mcabberrc    Default configuration file
 $HOME/\&.mcabberrc            Configuration file used if no other has been found
 $HOME/\&.mcabber/histo/       Default directory for storing chat history files, if enabled
-
 .fi
 
 .SH "BUGS"