Merge branch 'master' into readline

1 files changed, 331 insertions, 279 deletions

diff --git a/src/command/command.c b/src/command/command.c
index eb511836..f057ba62 100644
--- a/src/command/command.c
+++ b/src/command/command.c
@@ -117,10 +117,14 @@ static struct cmd_t command_defs[] =
           "--------------------",
           "Help on using Profanity.",
           "",
-          "area    - Summary help for commands in a certain area of functionality.",
-          "command - Full help for a specific command, for example '/help connect'.",
+          "area    : Summary help for commands in a certain area of functionality.",
+          "command : Full help for a specific command, for example '/help connect'.",
           "",
           "Use with no arguments to see a list of areas.",
+          "",
+          "Example: /help commands",
+          "Example: /help presence",
+          "Example: /help who",
           NULL } } },
 
     { "/about",
@@ -138,12 +142,18 @@ static struct cmd_t command_defs[] =
           "----------------------------------------------",
           "Login to a chat service.",
           "",
-          "account      - The local account you wish to connect with, or a JID if connecting for the first time.",
-          "server value - Supply a server if it is different to the domain part of your JID.",
-          "port value   - The port to use if different to the default (5222, or 5223 for SSL).",
+          "account      : The local account you wish to connect with, or a JID if connecting for the first time.",
+          "server value : Supply a server if it is different to the domain part of your JID.",
+          "port value   : The port to use if different to the default (5222, or 5223 for SSL).",
           "",
           "If no account is specified, the default is used if one is configured.",
           "A local account is created with the JID as it's name if it doesn't already exist.",
+          "",
+          "Example: /connect",
+          "Example: /connect myuser@gmail.com",
+          "Example: /connect myuser@mycompany.com server talk.google.com",
+          "Example: /connect bob@someplace port 5678",
+          "Example: /connect me@chatty server chatty.com port 5443",
           NULL  } } },
 
     { "/disconnect",
@@ -161,12 +171,17 @@ static struct cmd_t command_defs[] =
           "---------------------------",
           "Send a one to one chat message, or a private message to a chat room occupant.",
           "",
-          "contact - The contact's JID, or nickname if one has been set in your roster.",
-          "nick    - A chat room occupant, to whom you wish to send a private message.",
-          "message - The message to send",
+          "contact : The contact's JID, or nickname if one has been set in your roster.",
+          "nick    : A chat room occupant, to whom you wish to send a private message.",
+          "message : The message to send",
           "",
           "If the message is omitted, a new chat window will be opened without sending a message.",
           "Use quotes if the nickname includes spaces.",
+          "",
+          "Example: /msg myfriend@server.com Hey, here's a message!",
+          "Example: /msg otherfriend@server.com",
+          "Example: /msg Bob Here is a private message",
+          "Example: /msg \"My Friend\" Hi, how are you?",
           NULL } } },
 
     { "/roster",
@@ -178,23 +193,30 @@ static struct cmd_t command_defs[] =
           "",
           "command - online|show|hide|by|size|add|remove|nick|clearnick",
           "",
-          "online         - Show all online contacts in your roster.",
-          "show           - Show the roster panel.",
-          "show offline   - Show offline contacts in the roster panel.",
-          "show resource  - Show contact's connected resources in the roster panel.",
-          "hide           - Hide the roster panel.",
-          "hide offline   - Hide offline contacts in the roster panel.",
-          "hide resource  - Hide contact's connected resources in the roster panel.",
-          "by group       - Group contacts in the roster panel by roster group.",
-          "by presence    - Group contacts in the roster panel by presence.",
-          "by none        - No grouping in the roster panel.",
-          "size           - Percentage of the screen taken up by the roster (1-99).",
-          "add jid [nick] - Add a new item to the roster.",
-          "remove jid     - Removes an item from the roster.",
-          "nick jid nick  - Change a contacts nickname.",
-          "clearnick jid  - Removes the current nickname.",
+          "online         : Show all online contacts in your roster.",
+          "show           : Show the roster panel.",
+          "show offline   : Show offline contacts in the roster panel.",
+          "show resource  : Show contact's connected resources in the roster panel.",
+          "hide           : Hide the roster panel.",
+          "hide offline   : Hide offline contacts in the roster panel.",
+          "hide resource  : Hide contact's connected resources in the roster panel.",
+          "by group       : Group contacts in the roster panel by roster group.",
+          "by presence    : Group contacts in the roster panel by presence.",
+          "by none        : No grouping in the roster panel.",
+          "size           : Percentage of the screen taken up by the roster (1-99).",
+          "add jid [nick] : Add a new item to the roster.",
+          "remove jid     : Removes an item from the roster.",
+          "nick jid nick  : Change a contacts nickname.",
+          "clearnick jid  : Removes the current nickname.",
           "",
           "Passing no arguments lists all contacts in your roster.",
+          "",
+          "Example: /roster (show your roster)",
+          "Example: /roster add someone@contacts.org (add the contact)",
+          "Example: /roster add someone@contacts.org Buddy (add the contact with nickname 'Buddy')",
+          "Example: /roster remove someone@contacts.org (remove the contact)",
+          "Example: /roster nick myfriend@chat.org My Friend",
+          "Example: /roster clearnick kai@server.com (clears nickname)",
           NULL } } },
 
     { "/group",
@@ -204,11 +226,17 @@ static struct cmd_t command_defs[] =
           "------------------------------------------",
           "View, add to, and remove from roster groups.",
           "",
-          "show group           - List all roster items a group.",
-          "add group contact    - Added a contact to a group.",
-          "remove group contact - Remove a contact from a group.",
+          "show group           : List all roster items a group.",
+          "add group contact    : Added a contact to a group.",
+          "remove group contact : Remove a contact from a group.",
           "",
           "Passing no argument will list all roster groups.",
+          "",
+          "Example: /group",
+          "Example: /group show friends",
+          "Example: /group add friends newfriend@server.org",
+          "Example: /group add family Brother (using contacts nickname)",
+          "Example: /group remove colleagues boss@work.com",
           NULL } } },
 
     { "/info",
@@ -218,11 +246,14 @@ static struct cmd_t command_defs[] =
           "--------------------",
           "Show information about a contact, room, or room member.",
           "",
-          "contact - The contact you wish to view information about.",
-          "nick    - When in a chat room, the occupant you wish to view information about.",
+          "contact : The contact you wish to view information about.",
+          "nick    : When in a chat room, the occupant you wish to view information about.",
           "",
           "Passing no argument in a chat window will use the current recipient.",
           "Passing no argument in a chat room will display information about the room.",
+          "",
+          "Example: /info mybuddy@chat.server.org",
+          "Example: /info kai",
           NULL } } },
 
     { "/caps",
@@ -232,10 +263,14 @@ static struct cmd_t command_defs[] =
           "--------------------",
           "Find out a contacts, or room members client software capabilities.",
           "",
-          "fulljid - If in the console or a chat window, the full JID for which you wish to see capabilities.",
-          "nick    - If in a chat room, nickname for which you wish to see capabilities.",
+          "fulljid : If in the console or a chat window, the full JID for which you wish to see capabilities.",
+          "nick    : If in a chat room, nickname for which you wish to see capabilities.",
           "",
           "If in private chat initiated from a chat room, no parameter is required.",
+          "",
+          "Example: /caps mybuddy@chat.server.org/laptop (contact's laptop resource)",
+          "Example: /caps mybuddy@chat.server.org/phone (contact's phone resource)",
+          "Example: /caps bruce (room member)",
           NULL } } },
 
     { "/software",
@@ -245,11 +280,15 @@ static struct cmd_t command_defs[] =
           "------------------------",
           "Find out a contact, or room members software version information.",
           "",
-          "fulljid - If in the console or a chat window, the full JID for which you wish to see software information.",
-          "nick    - If in a chat room, nickname for which you wish to see software information.",
+          "fulljid : If in the console or a chat window, the full JID for which you wish to see software information.",
+          "nick    : If in a chat room, nickname for which you wish to see software information.",
           "",
           "If in private chat initiated from a chat room, no parameter is required.",
           "If the contact's software does not support software version requests, nothing will be displayed.",
+          "",
+          "Example: /software mybuddy@chat.server.org/laptop (contact's laptop resource)",
+          "Example: /software mybuddy@chat.server.org/phone (contact's phone resource)",
+          "Example: /software bruce (room member)",
           NULL } } },
 
     { "/status",
@@ -259,10 +298,13 @@ static struct cmd_t command_defs[] =
           "----------------------",
           "Find out a contact, or room members presence information.",
           "",
-          "contact - The contact who's presence you which to see.",
-          "nick    - If in a chat room, the occupant who's presence you wish to see.",
+          "contact : The contact who's presence you which to see.",
+          "nick    : If in a chat room, the occupant who's presence you wish to see.",
           "",
           "If in a chat window the parameter is not required, the current recipient will be used.",
+          "",
+          "Example: /status buddy@server.com",
+          "Example: /status jon",
           NULL } } },
 
     { "/resource",
@@ -272,10 +314,10 @@ static struct cmd_t command_defs[] =
           "------------------------------------------",
           "Override chat session resource, and manage resource display settings.",
           "",
-          "set resource   - Set the resource to which messages will be sent.",
-          "off            - Let the server choose which resource to route messages to.",
-          "title on|off   - Show or hide the current resource in the titlebar.",
-          "message on|off - Show or hide the resource when showing an incoming message.",
+          "set resource   : Set the resource to which messages will be sent.",
+          "off            : Let the server choose which resource to route messages to.",
+          "title on|off   : Show or hide the current resource in the titlebar.",
+          "message on|off : Show or hide the resource when showing an incoming message.",
           NULL } } },
 
     { "/join",
@@ -285,13 +327,18 @@ static struct cmd_t command_defs[] =
           "-------------------------------------------------",
           "Join a chat room at the conference server.",
           "",
-          "room        - Bare room JID, the chat server is determined by the 'muc.service' account property, 'conference.<domainpart>' by default.",
-          "room@server - Full room JID.",
-          "nick value  - Nickname to use in the room",
-          "password value - Password if the room requires it.",
+          "room           : Bare room JID, the chat server is determined by the 'muc.service' account property, 'conference.<domainpart>' by default.",
+          "room@server    : Full room JID.",
+          "nick value     : Nickname to use in the room",
+          "password value : Password if the room requires it.",
           "",
           "If no nickname is specfied the account preference 'muc.nick' will be used which by default is the localpart of your JID.",
           "If the room doesn't exist, and the server allows it, a new one will be created.",
+          "",
+          "Example: /join jdev@conference.jabber.org",
+          "Example: /join jdev@conference.jabber.org nick mynick",
+          "Example: /join private@conference.jabber.org nick mynick password mypassword",
+          "Example: /join jdev (as user@jabber.org will join jdev@conference.jabber.org)",
           NULL } } },
 
     { "/leave",
@@ -309,8 +356,8 @@ static struct cmd_t command_defs[] =
           "-------------------------",
           "Send a direct invite to the current chat room.",
           "",
-          "contact - The contact you wish to invite",
-          "message - An optional message to send with the invite.",
+          "contact : The contact you wish to invite",
+          "message : An optional message to send with the invite.",
           NULL } } },
 
     { "/invites",
@@ -328,7 +375,7 @@ static struct cmd_t command_defs[] =
           "-------------",
           "Decline a chat room ivivation.",
           "",
-          "room - The room for the invite you wish to decline.",
+          "room : The room for the invite you wish to decline.",
           NULL } } },
 
     { "/room",
@@ -338,9 +385,9 @@ static struct cmd_t command_defs[] =
           "---------------------------",
           "Chat room configuration.",
           "",
-          "accept  - Accept default room configuration.",
-          "destroy - Reject default room configuration.",
-          "config  - Edit room configuration.",
+          "accept  : Accept default room configuration.",
+          "destroy : Reject default room configuration.",
+          "config  : Edit room configuration.",
           NULL } } },
 
     { "/kick",
@@ -350,8 +397,8 @@ static struct cmd_t command_defs[] =
           "-------------------",
           "Kick occupants from chat rooms.",
           "",
-          "nick   - Nickname of the occupant to kick from the room.",
-          "reason - Optional reason for kicking the occupant.",
+          "nick   : Nickname of the occupant to kick from the room.",
+          "reason : Optional reason for kicking the occupant.",
           NULL } } },
 
     { "/ban",
@@ -361,8 +408,8 @@ static struct cmd_t command_defs[] =
           "-----------------",
           "Ban users from chat rooms.",
           "",
-          "jid    - Bare JID of the user to ban from the room.",
-          "reason - Optional reason for banning the user.",
+          "jid    : Bare JID of the user to ban from the room.",
+          "reason : Optional reason for banning the user.",
           NULL } } },
 
     { "/subject",
@@ -372,8 +419,8 @@ static struct cmd_t command_defs[] =
           "----------------------------",
           "Set or clear room subject.",
           "",
-          "set subject  - Set the room subject.",
-          "clear        - Clear the room subject.",
+          "set subject  : Set the room subject.",
+          "clear        : Clear the room subject.",
           NULL } } },
 
     { "/affiliation",
@@ -383,8 +430,8 @@ static struct cmd_t command_defs[] =
           "--------------------------------------------------",
           "Manage room affiliations.",
           "",
-          "set affiliation jid [reason]- Set the affiliation of user with jid, with an optional reason.",
-          "list [affiliation]          - List all users with the specified affiliation, or all if none specified.",
+          "set affiliation jid [reason]: Set the affiliation of user with jid, with an optional reason.",
+          "list [affiliation]          : List all users with the specified affiliation, or all if none specified.",
           "",
           "The affiliation may be one of owner, admin, member, outcast or none.",
           NULL } } },
@@ -396,8 +443,8 @@ static struct cmd_t command_defs[] =
           "-------------------------------------",
           "Manage room roles.",
           "",
-          "set role nick [reason] - Set the role of occupant with nick, with an optional reason.",
-          "list [role]            - List all occupants with the specified role, or all if none specified.",
+          "set role nick [reason] : Set the role of occupant with nick, with an optional reason.",
+          "list [role]            : List all occupants with the specified role, or all if none specified.",
           "",
           "The role may be one of moderator, participant, visitor or none.",
           NULL } } },
@@ -409,10 +456,10 @@ static struct cmd_t command_defs[] =
           "-------------------------------------------------------",
           "Show or hide room occupants, and occupants panel display settings.",
           "",
-          "show              - Show the occupants panel in chat rooms.",
-          "hide              - Hide the occupants panel in chat rooms.",
-          "default show|hide - Whether occupants are shown by default in new rooms, 'show' or 'hide'",
-          "size percent      - Percentage of the screen taken by the occupants list in rooms (1-99).",
+          "show              : Show the occupants panel in chat rooms.",
+          "hide              : Hide the occupants panel in chat rooms.",
+          "default show|hide : Whether occupants are shown by default in new rooms, 'show' or 'hide'",
+          "size percent      : Percentage of the screen taken by the occupants list in rooms (1-99).",
           NULL } } },
 
     { "/form",
@@ -422,10 +469,10 @@ static struct cmd_t command_defs[] =
           "-----------------------------------",
           "Form configuration.",
           "",
-          "show             - Show the current form.",
-          "submit           - Submit the current form.",
-          "cancel           - Cancel changes to the current form.",
-          "help [tag]       - Display help for form, or a specific field.",
+          "show             : Show the current form.",
+          "submit           : Submit the current form.",
+          "cancel           : Cancel changes to the current form.",
+          "help [tag]       : Display help for form, or a specific field.",
           NULL } } },
 
     { "/rooms",
@@ -435,9 +482,12 @@ static struct cmd_t command_defs[] =
           "---------------------------",
           "List the chat rooms available at the specified conference service",
           "",
-          "conference-service - The conference service to query.",
+          "conference-service : The conference service to query.",
           "",
           "If no argument is supplied, the account preference 'muc.service' is used, 'conference.<domain-part>' by default.",
+          "",
+          "Example: /rooms conference.jabber.org",
+          "Example: /rooms (if logged in as me@server.org, is equivalent to /rooms conference.server.org)",
           NULL } } },
 
     { "/bookmark",
@@ -447,16 +497,16 @@ static struct cmd_t command_defs[] =
           "----------------------------",
           "Manage bookmarks and join bookmarked rooms.",
           "",
-          "command - list|add|update|remove|join",
+          "command : list|add|update|remove|join",
           "",
-          "list                              - List all bookmarks.",
-          "add room@server [prop value..]    - Add a bookmark for room@server with the following optional properties:",
-          "  nick value                      - Nickname used in the chat room",
-          "  password value                  - Password if required, may be stored in plaintext on your server",
-          "  autojoin on|off                 - Whether to join the room automatically on login.",
-          "update room@server [prop value..] - Update any of the above properties associated with the bookmark.",
-          "remove room@server                - Remove the bookmark for room@server.",
-          "join room@server                  - Join room using the properties associated with the bookmark.",
+          "list                              : List all bookmarks.",
+          "add room@server [prop value..]    : Add a bookmark for room@server with the following optional properties:",
+          "  nick value                      : Nickname used in the chat room",
+          "  password value                  : Password if required, may be stored in plaintext on your server",
+          "  autojoin on|off                 : Whether to join the room automatically on login.",
+          "update room@server [prop value..] : Update any of the above properties associated with the bookmark.",
+          "remove room@server                : Remove the bookmark for room@server.",
+          "join room@server                  : Join room using the properties associated with the bookmark.",
           "",
           "In a chat room, /bookmark with no arguments will bookmark the current room, setting autojoin to \"on\".",
           NULL } } },
@@ -468,9 +518,14 @@ static struct cmd_t command_defs[] =
           "---------------------",
           "Find out information about an entities supported services.",
           "",
-          "info   - List protocols and features supported by an entity.",
-          "items  - List items associated with an entity.",
-          "entity - Jabber ID.",
+          "info   : List protocols and features supported by an entity.",
+          "items  : List items associated with an entity.",
+          "entity : Jabber ID.",
+          "",
+          "Example: /disco info myserver.org",
+          "Example: /disco items myserver.org",
+          "Example: /disco items conference.jabber.org",
+          "Example: /disco info myfriend@server.com/laptop",
           NULL } } },
 
     { "/nick",
@@ -480,7 +535,10 @@ static struct cmd_t command_defs[] =
           "--------------",
           "Change the name by which other members of a chat room see you.",
           "",
-          "nickname - The new nickname.",
+          "nickname : The new nickname.",
+          "",
+          "Example: /nick kai hansen",
+          "Example: /nick bob",
           NULL } } },
 
     { "/win",
@@ -500,9 +558,9 @@ static struct cmd_t command_defs[] =
           "---------------------------------------",
           "Show a list of windows, or tidy or swap.",
           "",
-          "tidy               - Move windows so there are no gaps.",
-          "prune              - Close all windows with no unread messages, and then tidy as above.",
-          "swap source target - Swap windows, target may be an empty position.",
+          "tidy               : Move windows so there are no gaps.",
+          "prune              : Close all windows with no unread messages, and then tidy as above.",
+          "swap source target : Swap windows, target may be an empty position.",
           "",
           "Passing no argument will list all currently active windows and information about their usage.",
           NULL } } },
@@ -514,14 +572,19 @@ static struct cmd_t command_defs[] =
           "------------------------------------------------",
           "Manage subscriptions to contact presence.",
           "",
-          "request [jid] - Send a subscription request to the user.",
-          "allow [jid]   - Approve a contact's subscription reqeust.",
-          "deny [jid]    - Remove subscription for a contact, or deny a request",
-          "show [jid]    - Show subscriprion status for a contact.",
-          "sent          - Show all sent subscription requests pending a response.",
-          "received      - Show all received subscription requests awaiting your response.",
+          "request [jid] : Send a subscription request to the user.",
+          "allow [jid]   : Approve a contact's subscription reqeust.",
+          "deny [jid]    : Remove subscription for a contact, or deny a request",
+          "show [jid]    : Show subscriprion status for a contact.",
+          "sent          : Show all sent subscription requests pending a response.",
+          "received      : Show all received subscription requests awaiting your response.",
           "",
           "If jid is omitted, the contact of the current window is used.",
+          "",
+          "Example: /sub request myfriend@jabber.org",
+          "Example: /sub allow myfriend@jabber.org",
+          "Example: /sub request (whilst in chat with contact)",
+          "Example: /sub sent",
           NULL  } } },
 
     { "/tiny",
@@ -531,7 +594,9 @@ static struct cmd_t command_defs[] =
           "---------",
           "Send url as tinyurl in current chat.",
           "",
-          "url - The url to make tiny.",
+          "url : The url to make tiny.",
+          "",
+          "Example: /tiny http://www.profanity.im",
           NULL } } },
 
     { "/who",
@@ -541,14 +606,14 @@ static struct cmd_t command_defs[] =
           "--------------------------------------",
           "Show contacts/room occupants with chosen status, role or affiliation",
           "",
-          "status - online|offline|away|dnd|xa|chat|available|unavailable|any",
-          "  online      - Contacts that are online, chat, away, xa, dnd",
-          "  available   - Contacts that are available for chat - online, chat.",
-          "  unavailable - Contacts that are not available for chat - offline, away, xa, dnd.",
-          "  any         - Contacts with any status (same as calling with no argument).",
-          "role        - moderator|participant|visitor",
-          "affiliation - owner|admin|member",
-          "group       - Filter the results by the specfied group.",
+          "status : online|offline|away|dnd|xa|chat|available|unavailable|any",
+          "  online      : Contacts that are online, chat, away, xa, dnd",
+          "  available   : Contacts that are available for chat - online, chat.",
+          "  unavailable : Contacts that are not available for chat - offline, away, xa, dnd.",
+          "  any         : Contacts with any status (same as calling with no argument).",
+          "role        : moderator|participant|visitor",
+          "affiliation : owner|admin|member",
+          "group       : Filter the results by the specfied group.",
           NULL } } },
 
     { "/close",
@@ -558,9 +623,9 @@ static struct cmd_t command_defs[] =
           "---------------------",
           "Close the current window, or a number of windows.",
           "",
-          "num  - Close the specified window.",
-          "all  - Close all windows.",
-          "read - Close all windows that have no new messages.",
+          "num  : Close the specified window.",
+          "all  : Close all windows.",
+          "read : Close all windows that have no new messages.",
           "",
           "Passing no argument will close the current window.",
           NULL } } },
@@ -623,19 +688,15 @@ static struct cmd_t command_defs[] =
           "Configure time precision for the main window.",
           NULL } } },
 
-    { "/inpblock", // TODO review
+    { "/inpblock",
         cmd_inpblock, parse_args, 2, 2, &cons_inpblock_setting,
-        { "/inpblock timeout|dynamic [millis|on|off]", "Input blocking delay (dynamic or static).",
+        { "/inpblock timeout|dynamic [millis|on|off]", "Configure input blocking.",
         { "/inpblock timeout|dynamic [millis|on|off]",
           "-----------------------------------------",
           "How long to wait for input before checking for new messages or checking for state changes such as 'idle'.",
-          "timeout : Time to wait in milliseconds before reading input from the terminal buffer, defaults to 500.",
-          "        : Valid values are 1-1000.",
-          "dynamic : Start with a 0 timeout and increase the value dynamically up to the specified 'timeout'.",
-          "        : on|off",
-          "A higher timeout will result in less CPU usage, but a noticable delay for response to input.",
-          "A lower timeout will result in higher CPU usage, but faster response to input.",
-          "Using the dynamic setting, higher CPU usage will occur during activity, but over time the CPU usage will decrease whilst there is no activity.",
+          "",
+          "timeout millis : Time to wait (1-1000) in milliseconds before reading input from the terminal buffer, default: 1000.",
+          "dynamic on|off : Start with 0 millis and dynamically increase up to timeout when no activity, default: on.",
           NULL } } },
 
     { "/notify",
@@ -643,40 +704,29 @@ static struct cmd_t command_defs[] =
         { "/notify [type value]|[type setting value]", "Control various desktop noficiations.",
         { "/notify [type value]|[type setting value]",
           "-----------------------------------------",
-          "Settings for various desktop notifications where type is one of:",
-          "message         : Notificaitons for regular messages.",
-          "                : on|off",
-          "message current : Whether messages in the current window trigger notifications.",
-          "                : on|off",
-          "message text    : Show message text in message notifications.",
-          "                : on|off",
-          "room            : Notificaitons for chat room messages.",
-          "                : on|off|mention",
-          "room current    : Whether chat room messages in the current window trigger notifications.",
-          "                : on|off",
-          "room text       : Show message test in chat room message notifications.",
-          "                : on|off",
-          "remind          : Notification reminders of unread messages.",
-          "                : where value is the reminder period in seconds,",
-          "                : use 0 to disable.",
-          "typing          : Notifications when contacts are typing.",
-          "                : on|off",
-          "typing current  : Whether typing notifications are triggerd for the current window.",
-          "                : on|off",
-          "invite          : Notifications for chat room invites.",
-          "                : on|off",
-          "sub             : Notifications for subscription requests.",
-          "                : on|off",
-          "",
-          "Example : /notify message on        (enable message notifications)",
-          "Example : /notify message text on   (show message text in notifications)",
-          "Example : /notify room mention      (enable chat room notifications only on mention)",
-          "Example : /notify room current off  (disable room message notifications when window visible)",
-          "Example : /notify room text off     (do not show message text in chat room notifications)",
-          "Example : /notify remind 10         (remind every 10 seconds)",
-          "Example : /notify remind 0          (switch off reminders)",
-          "Example : /notify typing on         (enable typing notifications)",
-          "Example : /notify invite on         (enable chat room invite notifications)",
+          "Settings for various kinds of desktop notifications.",
+          "",
+          "message on|off         : Notificaitons for regular messages.",
+          "message current on|off : Whether messages in the current window trigger notifications.",
+          "message text on|off    : Show message text in message notifications.",
+          "room on|off|mention    : Notificaitons for chat room messages.",
+          "room current on|off    : Whether chat room messages in the current window trigger notifications.",
+          "room text on|off       : Show message text in chat room message notifications.",
+          "remind seconds         : Notification reminder period for unread messages, use 0 to disable.",
+          "typing on|off          : Notifications when contacts are typing.",
+          "typing current of|off  : Whether typing notifications are triggerd for the current window.",
+          "invite on|off          : Notifications for chat room invites.",
+          "sub on|off             : Notifications for subscription requests.",
+          "",
+          "Example: /notify message on (enable message notifications)",
+          "Example: /notify message text on (show message text in notifications)",
+          "Example: /notify room mention (enable chat room notifications only on mention)",
+          "Example: /notify room current off (disable room message notifications when window visible)",
+          "Example: /notify room text off (do not show message text in chat room notifications)",
+          "Example: /notify remind 10 (remind every 10 seconds)",
+          "Example: /notify remind 0 (switch off reminders)",
+          "Example: /notify typing on (enable typing notifications)",
+          "Example: /notify invite on (enable chat room invite notifications)",
           NULL } } },
 
     { "/flash",
@@ -684,8 +734,7 @@ static struct cmd_t command_defs[] =
         { "/flash on|off", "Terminal flash on new messages.",
         { "/flash on|off",
           "-------------",
-          "Make the terminal flash when incoming messages are received.",
-          "The flash will only occur if you are not in the chat window associated with the user sending the message.",
+          "Make the terminal flash when incoming messages are received in another window.",
           "If the terminal doesn't support flashing, it may attempt to beep.",
           NULL } } },
 
@@ -714,7 +763,7 @@ static struct cmd_t command_defs[] =
           "The setting can be overridden by the -a (--account) command line option.",
           "",
           "Example: /autoconnect set jc@stuntteam.org (autoconnect with the specified account).",
-          "Example: /autoconnect off                  (disable autoconnect).",
+          "Example: /autoconnect off (disable autoconnect).",
           NULL } } },
 
     { "/vercheck",
@@ -722,18 +771,18 @@ static struct cmd_t command_defs[] =
         { "/vercheck [on|off]", "Check for a new release.",
         { "/vercheck [on|off]",
           "------------------",
-          "Without a parameter will check for a new release.",
-          "Switching on or off will enable/disable a version check when Profanity starts, and each time the /about command is run.",
+          "Enable/disable a version check when Profanity starts, and each time the /about command is run.",
           NULL  } } },
 
     { "/titlebar",
         cmd_titlebar, parse_args, 2, 2, &cons_titlebar_setting,
         { "/titlebar show|goodbye on|off", "Manage the terminal window title.",
         { "/titlebar show|goodbye on|off",
-          "---------------------",
+          "-----------------------------",
           "Show or hide a title and exit message in the terminal window title.",
-          "show    - Show current logged in user, and unread messages in the title.",
-          "goodbye - Show a message in the title when exiting profanity.",
+          "",
+          "show    : Show current logged in user, and unread messages in the title.",
+          "goodbye : Show a message in the title when exiting profanity.",
           NULL  } } },
 
     { "/mouse",
@@ -741,12 +790,7 @@ static struct cmd_t command_defs[] =
         { "/mouse on|off", "Use profanity mouse handling.",
         { "/mouse on|off",
           "-------------",
-          "If set to 'on', profanity will handle mouse actions, which enables scrolling the main window with the mouse wheel.",
-          "To select text, use the shift key while selcting an area.",
-          "If set to 'off', profanity leaves mouse handling to the terminal implementation.",
-          "This feature is experimental, certain mouse click events may occasionally freeze",
-          "Profanity until a key is pressed or another mouse event is received",
-          "The default is 'off'.",
+          "This feature is experimental, default is 'off'.",
           NULL } } },
 
     { "/alias",
@@ -755,12 +799,17 @@ static struct cmd_t command_defs[] =
         { "/alias add|remove|list [name value]",
           "-----------------------------------",
           "Add, remove or show command aliases.",
-          "The alias will be available as a command, the leading '/' will be added if not supplied.",
-          "Example : /alias add friends /who online friends",
-          "Example : /alias add /q /quit",
-          "Example : /alias a /away \"I'm in a meeting.\"",
-          "Example : /alias remove q",
-          "Example : /alias list",
+          "",
+          "add name value : Add a new command alias.",
+          "remove name    : Remove a command alias.",
+          "list           : List all aliases.",
+          "",
+          "Example: /alias add friends /who online friends",
+          "Example: /alias add /q /quit",
+          "Example: /alias a /away \"I'm in a meeting.\"",
+          "Example: /alias remove q",
+          "Example: /alias list",
+          "",
           "The above aliases will be available as /friends and /a",
           NULL } } },
 
@@ -789,29 +838,30 @@ static struct cmd_t command_defs[] =
         { "/states on|off", "Send chat states during a chat session.",
         { "/states on|off",
           "--------------",
-          "Sending of chat state notifications during chat sessions.",
-          "Such as whether you have become inactive, or have closed the chat window.",
+          "Send chat state notifications during chat sessions.",
           NULL } } },
 
     { "/otr",
         cmd_otr, parse_args, 1, 3, NULL,
-        { "/otr gen|myfp|theirfp|start|end|trust|untrust|log|warn|libver|policy|secret|question|answer", "Off The Record encryption commands.",
-        { "/otr gen|myfp|theirfp|start|end|trust|untrust|log|warn|libver|policy|secret|question|answer",
-          "-------------------------------------------------------------------------------------------",
-          "gen - Generate your private key.",
-          "myfp - Show your fingerprint.",
-          "theirfp - Show contacts fingerprint.",
-          "start [contact] - Start an OTR session with the contact, or the current recipient if in a chat window and no argument supplied.",
-          "end - End the current OTR session,",
-          "trust - Indicate that you have verified the contact's fingerprint.",
-          "untrust - Indicate the the contact's fingerprint is not verified,",
-          "log - How to log OTR messages, options are 'on', 'off' and 'redact', with redaction being the default.",
-          "warn - Show when unencrypted messaging is being used in the title bar, options are 'on' and 'off' with 'on' being the default.",
-          "libver - Show which version of the libotr library is being used.",
-          "policy - manual, opportunistic or always.",
-          "secret [secret]- Verify a contacts identity using a shared secret.",
-          "question [question] [answer] - Verify a contacts identity using a question and expected anwser, if the question has spaces, surround with double quotes.",
-          "answer [answer] - Respond to a question answer verification request with your answer.",
+        { "/otr command [args..]", "Off The Record encryption commands.",
+        { "/otr command [args..]",
+          "---------------------",
+          "Off The Record encryption commands.",
+          "",
+          "gen                                : Generate your private key.",
+          "myfp                               : Show your fingerprint.",
+          "theirfp                            : Show contacts fingerprint.",
+          "start [contact]                    : Start an OTR session with contact, or current recipient if omitted.",
+          "end                                : End the current OTR session,",
+          "trust                              : Indicate that you have verified the contact's fingerprint.",
+          "untrust                            : Indicate the the contact's fingerprint is not verified,",
+          "log on|off|redact                  : OTR message logging, default: redact.",
+          "warn on|off                        : Show in the titlebar when unencrypted messaging is being used.",
+          "libver                             : Show which version of the libotr library is being used.",
+          "policy manual|opportunistic|always : Set the global OTR policy.",
+          "secret [secret]                    : Verify a contacts identity using a shared secret.",
+          "question [question] [answer]       : Verify a contacts identity using a question and expected anwser.",
+          "answer [answer]                    : Respond to a question answer verification request with your answer.",
           NULL } } },
 
     { "/outtype",
@@ -819,8 +869,7 @@ static struct cmd_t command_defs[] =
         { "/outtype on|off", "Send typing notification to recipient.",
         { "/outtype on|off",
           "---------------",
-          "Send an indication that you are typing to the chat recipient.",
-          "Chat states (/states) will be enabled if this setting is set.",
+          "Send typing notifications, chat states (/states) will be enabled if this setting is set.",
           NULL } } },
 
     { "/gone",
@@ -828,8 +877,7 @@ static struct cmd_t command_defs[] =
         { "/gone minutes", "Send 'gone' state to recipient after a period.",
         { "/gone minutes",
           "-------------",
-          "Send a 'gone' state to the recipient after the specified number of minutes."
-          "This indicates to the recipient's client that you have left the conversation.",
+          "Send a 'gone' state to the recipient after the specified number of minutes.",
           "A value of 0 will disable sending this chat state.",
           "Chat states (/states) will be enabled if this setting is set.",
           NULL } } },
@@ -845,14 +893,15 @@ static struct cmd_t command_defs[] =
 
     { "/log",
         cmd_log, parse_args, 1, 2, &cons_log_setting,
-        { "/log [property] [value]", "Manage system logging settings.",
-        { "/log [property] [value]",
-          "-----------------------",
-          "where   : Show the current log file location.",
-          "Property may be one of:",
-          "rotate  : Rotate log, accepts 'on' or 'off', defaults to 'on'.",
-          "maxsize : With rotate enabled, specifies the max log size, defaults to 1048580 (1MB).",
-          "shared  : Share logs between all instances, accepts 'on' or 'off', defaults to 'on'.",
+        { "/log where|rotate|maxsize|shared [value]", "Manage system logging settings.",
+        { "/log where|rotate|maxsize|shared [value]",
+          "----------------------------------------",
+          "Manage profanity logging settings.",
+          "",
+          "where         : Show the current log file location.",
+          "rotate on|off : Rotate log, default on.",
+          "maxsize bytes : With rotate enabled, specifies the max log size, defaults to 1048580 (1MB).",
+          "shared on|off : Share logs between all instances, default: on.",
           NULL } } },
 
     { "/reconnect",
@@ -879,23 +928,22 @@ static struct cmd_t command_defs[] =
         { "/ping [rarget]",
           "--------------",
           "Sends an IQ ping stanza to the specificed target.",
-          "If no target is supplied, your chat server will be used.",
+          "If no target is supplied, your chat server will be pinged.",
           NULL } } },
 
     { "/autoaway",
         cmd_autoaway, parse_args_with_freetext, 2, 2, &cons_autoaway_setting,
-        { "/autoaway setting value", "Set auto idle/away properties.",
-        { "/autoaway setting value",
-          "-----------------------",
-          "'setting' may be one of 'mode', 'time', 'message' or 'check', with the following values:",
-          "",
-          "mode    : idle - Sends idle time, whilst your status remains online.",
-          "          away - Sends an away presence.",
-          "          off - Disabled (default).",
-          "time    : Number of minutes before the presence change is sent, the default is 15.",
-          "message : Optional message to send with the presence change.",
-          "        : off - Disable message (default).",
-          "check   : on|off, when enabled, checks for activity and sends online presence, default is 'on'.",
+        { "/autoaway mode|time|message|check value", "Set auto idle/away properties.",
+        { "/autoaway mode|time|message|check value",
+          "---------------------------------------",
+          "Manage autoway properties.",
+          "",
+          "mode idle        : Sends idle time, status remains online.",
+          "mode away        : Sends an away presence.",
+          "mode off         : Disabled (default).",
+          "time minutes     : Number of minutes before the presence change is sent, default: 15.",
+          "message text|off : Optional message to send with the presence change, default: off (disabled).",
+          "check on|off     : When enabled, checks for activity and sends online presence, default: on.",
           "",
           "Example: /autoaway mode idle",
           "Example: /autoaway time 30",
@@ -908,9 +956,11 @@ static struct cmd_t command_defs[] =
         { "/priority value", "Set priority for the current account.",
         { "/priority value",
           "---------------",
-          "Set priority for the current account, presence will be sent when calling this command.",
-          "See the /account command for more specific priority settings per presence status.",
-          "value : Number between -128 and 127. Default value is 0.",
+          "Set priority for the current account.",
+          "",
+          "value : Number between -128 and 127, default: 0.",
+          "",
+          "See the /account command for specific priority settings per presence status.",
           NULL } } },
 
     { "/account",
@@ -919,6 +969,7 @@ static struct cmd_t command_defs[] =
         { "/account [command] [account] [property] [value]",
           "-----------------------------------------------",
           "Commands for creating and managing accounts.",
+          "",
           "list                         : List all accounts.",
           "show account                 : Show information about an account.",
           "enable account               : Enable the account, it will be used for autocomplete.",
@@ -930,43 +981,38 @@ static struct cmd_t command_defs[] =
           "set account property value   : Set 'property' of 'account' to 'value'.",
           "clear account property value : Clear 'property' of 'account'.",
           "",
-          "When connected, the /account command can be called with no arguments, to show current account settings.",
-          "",
-          "The set command may use one of the following for 'property'.",
-          "jid              : The Jabber ID of the account, the account name will be used if this property is not set.",
-          "server           : The chat server, if different to the domainpart of the JID.",
-          "port             : The port used for connecting if not the default (5222, or 5223 for SSL).",
-          "status           : The presence status to use on login, use 'last' to use whatever your last status was.",
-          "online|chat|away",
-          "|xa|dnd          : Priority for the specified presence.",
-          "resource         : The resource to be used.",
-          "password         : Password for the account, note this is currently stored in plaintext if set.",
-          "eval_password    : Shell command evaluated to retrieve password for the account.  Can be used to retrieve password from keyring.",
-          "muc              : The default MUC chat service to use.",
-          "nick             : The default nickname to use when joining chat rooms.",
-          "otr              : Override global OTR policy for this account: manual, opportunistic or always.",
-          "",
-          "The clear command works for password, port and server",
-          "",
-          "Example : /account add work",
-          "        : /account set work jid me@chatty",
-          "        : /account set work server talk.chat.com",
-          "        : /account set work port 5111",
-          "        : /account set work resource desktop",
-          "        : /account set work muc chatservice.mycompany.com",
-          "        : /account set work nick dennis",
-          "        : /account set work status dnd",
-          "        : /account set work dnd -1",
-          "        : /account set work online 10",
-          "        : /account rename work gtalk",
+          "Account properties.",
+          "",
+          "jid                     : The Jabber ID of the account, account name will be used if not set.",
+          "server                  : The chat server, if different to the domainpart of the JID.",
+          "port                    : The port used for connecting if not the default (5222, or 5223 for SSL).",
+          "status                  : The presence status to use on login, use 'last' to use your last status before logging out.",
+          "online|chat|away|xa|dnd : Priority for the specified presence.",
+          "resource                : The resource to be used.",
+          "password                : Password for the account, note this is currently stored in plaintext if set.",
+          "eval_password           : Shell command evaluated to retrieve password for the account. Can be used to retrieve password from keyring.",
+          "muc                     : The default MUC chat service to use.",
+          "nick                    : The default nickname to use when joining chat rooms.",
+          "otr                     : Override global OTR policy for this account: manual, opportunistic or always.",
+          "",
+          "Example: /account add me",
+          "Example: /account set me jid me@chatty",
+          "Example: /account set me server talk.chat.com",
+          "Example: /account set me port 5111",
+          "Example: /account set me muc chatservice.mycompany.com",
+          "Example: /account set me nick dennis",
+          "Example: /account set me status dnd",
+          "Example: /account set me dnd -1",
+          "Example: /account rename me gtalk",
           NULL  } } },
 
     { "/prefs",
         cmd_prefs, parse_args, 0, 1, NULL,
-        { "/prefs [area]", "Show configuration.",
-        { "/prefs [area]",
-          "-------------",
-          "Area is one of:",
+        { "/prefs [ui|desktop|chat|log|conn|presence]", "Show configuration.",
+        { "/prefs [ui|desktop|chat|log|conn|presence]",
+          "------------------------------------------",
+          "Show preferences for different areas of functionality.",
+          "",
           "ui       : User interface preferences.",
           "desktop  : Desktop notification preferences.",
           "chat     : Chat state preferences.",
@@ -974,7 +1020,7 @@ static struct cmd_t command_defs[] =
           "conn     : Connection handling preferences.",
           "presence : Chat presence preferences.",
           "",
-          "No argument shows all categories.",
+          "No argument shows all preferences.",
           NULL } } },
 
     { "/theme",
@@ -982,14 +1028,14 @@ static struct cmd_t command_defs[] =
         { "/theme list|set|colours [theme-name]", "Change colour theme.",
         { "/theme list|set|colours [theme-name]",
           "------------------------------------",
-          "Change the colour settings used.",
+          "Load a theme, includes colours and UI options.",
           "",
           "list           : List all available themes.",
-          "set theme-name : Load the named theme.\"default\" will reset to the default colours.",
+          "set theme-name : Load the named theme. 'default' will reset to the default theme.",
           "colours        : Show the colour values as rendered by the terminal.",
           "",
-          "Example : /theme list",
-          "Example : /theme set mycooltheme",
+          "Example: /theme list",
+          "Example: /theme set mycooltheme",
           NULL } } },
 
 
@@ -998,12 +1044,23 @@ static struct cmd_t command_defs[] =
         { "/statuses console|chat|muc setting", "Set preferences for presence change messages.",
         { "/statuses console|chat|muc setting",
           "----------------------------------",
-          "Configure how presence changes are displayed in various windows.",
-          "Settings:",
-          "  all - Show all presence changes.",
-          "  online - Show only online/offline changes.",
-          "  none - Don't show any presence changes.",
+          "Configure which presence changes are displayed in various windows.",
+          "",
+          "console : Configure what is displayed in the console window.",
+          "chat    : Configure what is displayed in chat windows.",
+          "muc     : Configure what is displayed in chat room windows.",
+          "",
+          "Available options are:",
+          "",
+          "all    : Show all presence changes.",
+          "online : Show only online/offline changes.",
+          "none   : Don't show any presence changes.",
+          "",
           "The default is 'all' for all windows.",
+          "",
+          "Example: /statuses console none",
+          "Example: /statuses chat online",
+          "Example: /statuses muc all",
           NULL } } },
 
     { "/xmlconsole",
@@ -1016,57 +1073,52 @@ static struct cmd_t command_defs[] =
 
     { "/away",
         cmd_away, parse_args_with_freetext, 0, 1, NULL,
-        { "/away [msg]", "Set status to away.",
-        { "/away [msg]",
-          "-----------",
+        { "/away [message]", "Set status to away.",
+        { "/away [message]",
+          "---------------",
           "Set your status to 'away' with the optional message.",
-          "Your current status can be found in the top right of the screen.",
           "",
-          "Example : /away Gone for lunch",
+          "Example: /away Gone for lunch",
           NULL } } },
 
     { "/chat",
         cmd_chat, parse_args_with_freetext, 0, 1, NULL,
-        { "/chat [msg]", "Set status to chat (available for chat).",
-        { "/chat [msg]",
-          "-----------",
+        { "/chat [message]", "Set status to chat (available for chat).",
+        { "/chat [message]",
+          "---------------",
           "Set your status to 'chat', meaning 'available for chat', with the optional message.",
-          "Your current status can be found in the top right of the screen.",
           "",
-          "Example : /chat Please talk to me!",
+          "Example: /chat Please talk to me!",
           NULL } } },
 
     { "/dnd",
         cmd_dnd, parse_args_with_freetext, 0, 1, NULL,
-        { "/dnd [msg]", "Set status to dnd (do not disturb).",
-        { "/dnd [msg]",
-          "----------",
+        { "/dnd [message]", "Set status to dnd (do not disturb).",
+        { "/dnd [message]",
+          "--------------",
           "Set your status to 'dnd', meaning 'do not disturb', with the optional message.",
-          "Your current status can be found in the top right of the screen.",
           "",
-          "Example : /dnd I'm in the zone",
+          "Example: /dnd I'm in the zone",
           NULL } } },
 
     { "/online",
         cmd_online, parse_args_with_freetext, 0, 1, NULL,
-        { "/online [msg]", "Set status to online.",
-        { "/online [msg]",
-          "-------------",
+        { "/online [message]", "Set status to online.",
+        { "/online [message]",
+          "-----------------",
           "Set your status to 'online' with the optional message.",
-          "Your current status can be found in the top right of the screen.",
           "",
-          "Example : /online Up the Irons!",
+          "Example: /online Up the Irons!",
           NULL } } },
 
     { "/xa",
         cmd_xa, parse_args_with_freetext, 0, 1, NULL,
-        { "/xa [msg]", "Set status to xa (extended away).",
-        { "/xa [msg]",
-          "---------",
+        { "/xa [message]", "Set status to xa (extended away).",
+        { "/xa [message]",
+          "-------------",
           "Set your status to 'xa', meaning 'extended away', with the optional message.",
-          "Your current status can be found in the top right of the screen.",
           "",
-          "Example : /xa This meeting is going to be a long one",
+          "Example: /xa This meeting is going to be a long one",
           NULL } } },
 };