Merge remote-tracking branch 'origin/master'

1 files changed, 87 insertions, 119 deletions

diff --git a/src/command/command.c b/src/command/command.c
index e810f8af..491bf5f2 100644
--- a/src/command/command.c
+++ b/src/command/command.c
@@ -112,18 +112,13 @@ static struct cmd_t command_defs[] =
 {
     { "/help",
         cmd_help, parse_args, 0, 1, NULL,
-        { "/help [area|command]", "Get help on using Profanity.",
+        { "/help [area|command]", "Help on using Profanity.",
         { "/help [area|command]",
-          "-------------------------",
-          "Use with no arguments to get a help summary.",
-          "Supply an area to see help for commands related to specific features.",
-          "Supply a command (without the leading slash) to see help for that command.",
-          "",
-          "Example : /help commands",
-          "Example : /help presence",
-          "Example : /help who",
-          "",
-          "For more detailed help, see the user guide at http://www.profanity.im/userguide.html.",
+          "--------------------",
+          "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'.",
+          "Use with no arguments to see a list of areas.",
           NULL } } },
 
     { "/about",
@@ -136,21 +131,15 @@ static struct cmd_t command_defs[] =
 
     { "/connect",
         cmd_connect, parse_args, 0, 5, NULL,
-        { "/connect [account] [server value] [port value]", "Login to a chat service.",
+        { "/connect [account] [server value] [port value]", "Account login.",
         { "/connect [account] [server value] [port value]",
           "----------------------------------------------",
-          "Connect to an XMPP service using the specified account.",
-          "Use the server property to specify a server if required.",
-          "Change the default port (5222, or 5223 for SSL) with the port property.",
-          "An account is automatically created if one does not exist.",
-          "If no account is specified, then the default account is used."
-          "See the /account command for more details.",
-          "",
-          "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",
+          "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).",
+          "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.",
           NULL  } } },
 
     { "/disconnect",
@@ -163,48 +152,40 @@ static struct cmd_t command_defs[] =
 
     { "/msg",
         cmd_msg, parse_args_with_freetext, 1, 2, NULL,
-        { "/msg contact|nick [message]", "Start chat with user.",
+        { "/msg contact|nick [message]", "Start chat with a user.",
         { "/msg contact|nick [message]",
           "---------------------------",
-          "Open a chat window for the contact and send the message if one is supplied.",
-          "When in a chat room, supply a nickname to start private chat with a room member.",
+          "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",
+          "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",
         cmd_roster, parse_args_with_freetext, 0, 3, NULL,
-        { "/roster [online|show|hide|by|size|add|remove|nick|clearnick] [offline|resource] [percent] [group|presence|none] [jid] [nickname]", "Manage your roster.",
-        { "/roster [online|show|hide|by|size|add|remove|nick|clearnick] [offline|resource] [percent] [group|presence|none] [jid] [nickname]",
-          "-------------------------------------------------------------------------------------------------------------------------",
-          "View, add to, and remove from your roster.",
+        { "/roster [command] [args..]", "Manage your roster.",
+        { "/roster [command] [args..]",
+          "--------------------------",
+          "Manage your roster, and roster display settings.",
+          "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.",
           "Passing no arguments lists all contacts in your roster.",
-          "online        - Show all online contacts in your roster.",
-          "show          - Show the roster panel in the console window.",
-          "hide          - Hide the roster panel.",
-          "show offline  - Show offline contacts in the roster panel.",
-          "hide offline  - Hide offline contacts in the roster panel.",
-          "show resource - Show contact's connected resources 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           - Add a new item, jid is required, nickname is optional.",
-          "remove        - Removes a contact, jid is required.",
-          "nick          - Changes a contacts nickname, both jid and nickname are required,",
-          "clearnick     - Removes the current nickname, jid is required.",
-          "",
-          "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",
@@ -213,31 +194,22 @@ static struct cmd_t command_defs[] =
         { "/group [show|add|remove] [group] [contact]",
           "------------------------------------------",
           "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.",
           "Passing no argument will list all roster groups.",
-          "The 'show' command takes 'group' as an argument, and lists all roster items in that group.",
-          "The 'add' command takes 'group' and 'contact' arguments, and adds the contact to the group.",
-          "The 'remove' command takes 'group' and 'contact' arguments and removes the contact from the group,",
-          "",
-          "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",
         cmd_info, parse_args, 0, 1, NULL,
-        { "/info [contact|nick]", "Show basic information about a contact, room, or room member.",
+        { "/info [contact|nick]", "Show information about a contact, room, or room member.",
         { "/info [contact|nick]",
           "--------------------",
-          "Show basic information about a contact, room, or room member.",
-          "If in the console, a contact must be specified.",
-          "If in a chat window the parameter is not required, the current recipient will be used.",
-          "If in a chat room, providing no arguments will display information about the room.",
-          "If in a chat room, supplying a nick will show information about the occupant.",
-          "",
-          "Example : /info mybuddy@chat.server.org",
-          "Example : /info kai",
+          "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.",
+          "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.",
           NULL } } },
 
     { "/caps",
@@ -245,14 +217,10 @@ static struct cmd_t command_defs[] =
         { "/caps [fulljid|nick]", "Find out a contacts client software capabilities.",
         { "/caps [fulljid|nick]",
           "--------------------",
-          "Find out a contact, or room members client software capabilities.",
-          "If in the console window or a regular chat window, a full JID is required.",
-          "If in a chat room, the nickname is required.",
-          "If in private chat, 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)",
+          "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.",
+          "If in private chat initiated from a chat room, no parameter is required.",
           NULL } } },
 
     { "/software",
@@ -260,15 +228,11 @@ static struct cmd_t command_defs[] =
         { "/software [fulljid|nick]", "Find out software version information about a contacts resource.",
         { "/software [fulljid|nick]",
           "------------------------",
-          "Find out a contact, or room members software version information, if such requests are supported.",
-          "If in the console window or a regular chat window, a full JID is required.",
-          "If in a chat room, the nickname is required.",
-          "If in private chat, no parameter is required.",
+          "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.",
+          "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",
@@ -277,22 +241,21 @@ static struct cmd_t command_defs[] =
         { "/status [contact|nick]",
           "----------------------",
           "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.",
           "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",
         cmd_resource, parse_args, 1, 2, &cons_resource_setting,
-        { "/resource set|off|title|message [resource]", "Set the contact's resource.",
+        { "/resource set|off|title|message [resource]", "Set the contact's resource, display settings.",
         { "/resource set|off|title|message [resource]",
           "------------------------------------------",
-          "Set the resource to use when chatting to a contact and manage resource display settings.",
-          "set resource   - Set the resource.",
+          "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 from which a message was recieved.",
+          "message on|off - Show or hide the resource when showing an incoming message.",
           NULL } } },
 
     { "/join",
@@ -301,15 +264,12 @@ static struct cmd_t command_defs[] =
         { "/join room[@server] [nick value] [password value]",
           "-------------------------------------------------",
           "Join a chat room at the conference server.",
-          "If nick is specified you will join with this nickname.",
-          "Otherwise the account preference 'muc.nick' will be used which by default is the localpart of your JID (before the @).",
-          "If no server is supplied, the account preference 'muc.service' is used, which is 'conference.<domain-part>' by default.",
+          "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",
@@ -325,8 +285,9 @@ static struct cmd_t command_defs[] =
         { "/invite contact [message]", "Invite contact to chat room.",
         { "/invite contact [message]",
           "-------------------------",
-          "Send a direct invite to the specified contact to the current chat room.",
-          "If a message is supplied it will be sent as the reason for the invite.",
+          "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.",
           NULL } } },
 
     { "/invites",
@@ -334,9 +295,7 @@ static struct cmd_t command_defs[] =
         { "/invites", "Show outstanding chat room invites.",
         { "/invites",
           "--------",
-          "Show all rooms that you have been invited to, and have not yet been accepted or declind.",
-          "Use \"/join <room>\" to accept a room invitation.",
-          "Use \"/decline <room>\" to decline a room invitation.",
+          "Show all rooms that you have been invited to, and not accepted or declind.",
           NULL } } },
 
     { "/decline",
@@ -344,7 +303,8 @@ static struct cmd_t command_defs[] =
         { "/decline room", "Decline a chat room invite.",
         { "/decline room",
           "-------------",
-          "Decline invitation to a chat room, the room will no longer be in the list of outstanding invites.",
+          "Decline a chat room ivivation.",
+          "room - The room for the invite you wish to decline.",
           NULL } } },
 
     { "/room",
@@ -352,6 +312,7 @@ static struct cmd_t command_defs[] =
         { "/room accept|destroy|config", "Room configuration.",
         { "/room accept|destroy|config",
           "---------------------------",
+          "Chat room configuration.",
           "accept  - Accept default room configuration.",
           "destroy - Reject default room configuration.",
           "config  - Edit room configuration.",
@@ -362,6 +323,7 @@ static struct cmd_t command_defs[] =
         { "/kick nick [reason]", "Kick occupants from chat rooms.",
         { "/kick nick [reason]",
           "-------------------",
+          "Kick occupants from chat rooms.",
           "nick   - Nickname of the occupant to kick from the room.",
           "reason - Optional reason for kicking the occupant.",
           NULL } } },
@@ -371,6 +333,7 @@ static struct cmd_t command_defs[] =
         { "/ban jid [reason]", "Ban users from chat rooms.",
         { "/ban jid [reason]",
           "-----------------",
+          "Ban users from chat rooms.",
           "jid    - Bare JID of the user to ban from the room.",
           "reason - Optional reason for banning the user.",
           NULL } } },
@@ -380,6 +343,7 @@ static struct cmd_t command_defs[] =
         { "/subject set|clear [subject]", "Set or clear room subject.",
         { "/subject set|clear [subject]",
           "----------------------------",
+          "Set or clear room subject.",
           "set subject  - Set the room subject.",
           "clear        - Clear the room subject.",
           NULL } } },
@@ -389,6 +353,7 @@ static struct cmd_t command_defs[] =
         { "/affiliation set|list [affiliation] [jid] [reason]", "Manage room affiliations.",
         { "/affiliation set|list [affiliation] [jid] [reason]",
           "--------------------------------------------------",
+          "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.",
           "The affiliation may be one of owner, admin, member, outcast or none.",
@@ -399,6 +364,7 @@ static struct cmd_t command_defs[] =
         { "/role set|list [role] [nick] [reason]", "Manage room roles.",
         { "/role set|list [role] [nick] [reason]",
           "-------------------------------------",
+          "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.",
           "The role may be one of moderator, participant, visitor or none.",
@@ -409,10 +375,11 @@ static struct cmd_t command_defs[] =
         { "/occupants show|hide|default|size [show|hide] [percent]", "Show or hide room occupants.",
         { "/occupants show|hide|default|size [show|hide] [percent]",
           "-------------------------------------------------------",
-          "show    - Show the occupants panel in chat rooms.",
-          "hide    - Hide the occupants panel in chat rooms.",
-          "default - Whether occupants are shown by default in new rooms, 'show' or 'hide'",
-          "size    - Percentage of the screen taken by the occupants list in rooms (1-99).",
+          "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).",
           NULL } } },
 
     { "/form",
@@ -420,13 +387,14 @@ static struct cmd_t command_defs[] =
         { "/form show|submit|cancel|help [tag]", "Form handling.",
         { "/form show|submit|cancel|help [tag]",
           "-----------------------------------",
+          "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.",
           NULL } } },
 
-    { "/rooms",
+    { "/rooms", // TODO help review
         cmd_rooms, parse_args, 0, 1, NULL,
         { "/rooms [conference-service]", "List chat rooms.",
         { "/rooms [conference-service]",
@@ -3051,4 +3019,4 @@ command_docgen(void)
     fclose(toc_fragment);
     fclose(main_fragment);
     g_list_free(cmds);
-}
\ No newline at end of file
+}