From 04c283c55188bda7d0cdd87c345cbe5603552f09 Mon Sep 17 00:00:00 2001 From: mathieui Date: Wed, 9 Nov 2011 12:17:20 +0100 Subject: The plugins are no longer in a separate branch --- doc/en/plugins.txt | 1 - 1 file changed, 1 deletion(-) (limited to 'doc') diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt index 47ab7f01..706a7e50 100644 --- a/doc/en/plugins.txt +++ b/doc/en/plugins.txt @@ -1,7 +1,6 @@ Plugins ======= -Currently, the plugins are in a plugin branch on the git repo. Location -------- -- cgit v1.2.3 From 103ddd762d7ed98ce263604de9979002e3ca47b3 Mon Sep 17 00:00:00 2001 From: mathieui Date: Wed, 9 Nov 2011 14:51:48 +0100 Subject: Updated plugin doc --- doc/en/plugins.txt | 56 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 51 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt index 706a7e50..079e258b 100644 --- a/doc/en/plugins.txt +++ b/doc/en/plugins.txt @@ -94,7 +94,53 @@ CAUTION: TODO [[events-list]] Events list ----------- -CAUTION: TODO + +SleekXMPP events +~~~~~~~~~~~~~~~~ + +For the sleekxmpp events, please refer to the https://github.com/fritzy/SleekXMPP/wiki/Event-Index[sleekxmpp event index]. + + +Poezio events +~~~~~~~~~~~~~ + +*muc_say*:: +message+, +tab+ + +The handlers for this event are called whenever you say something in a MUC (through the /say command or by direct input). The parameters given to the handlers anre: + +* _message_: Message to be sent +* _tab_: Tab in which the message will be sent + +*private_say*:: +message+, +tab+ + +The handlers for this event are called whenever you say something in a private conversaton in a MUC (through the /say command or by direct input). The parameters given to the handlers are: + +* _message_: Message to be sent +* _tab_: Tab in which the message will be sent + +*conversation_say*:: +message+, +tab+ + +The handlers for this event are called whenever you say something in direct conversation (through the /say command or by direct input). The parameters given to the handler are: + +* _message_: Message to be sent +* _tab_: Tab in which the message will be sent + +*muc_msg*:: +message+, +tab+ + +The handlers for this event are called whenever you receive a message in a MUC. The parameters given to the handler are: + +* _message_: Message received +* _tab_: Tab in which the message was received + +*private_msg*:: +message+, +tab+ + +The handlers for this event are called whenever you receive a message in a private conversation in a MUC. The parameters given to the handler are: + +* _message_: Message received +* _tab_: Tab in which the message was received + +*conversation_msg*:: +message+, +tab+ + +The handlers for this event are called whenever you receive a message in a direct conversation. The parameters given to the handler are: + +* _message_: Message received +* _tab_: Tab in which the message was received + +CAUTION: Plugins are in an experimental state and this API might change slightly in a near future. You have to be aware of that while making a plugin. Examples -------- @@ -108,7 +154,7 @@ class Plugin(BasePlugin): def init(self): self.add_command('hello', self.command_hello, "Usage: /hello\nHello: Send 'Hello World!'", None) - def command_hello(self, args): + def command_hello(self, arg): self.core.send_message('Hello World!') --------------- ===================================================================== @@ -121,11 +167,11 @@ class Plugin(BasePlugin): --------------- class Plugin(BasePlugin): def init(self): - self.add_event_handler('groupchat_message', self.on_groupchat_message) + self.add_event_handler('muc_msg', self.on_groupchat_message) - def on_groupchat_message(self, message): + def on_groupchat_message(self, message, tab): if message['mucnick'] == "Partauche": - self.core.send_message('tg', to=message.getMucroom()) + tab.command_say('tg') --------------- ===================================================================== -- cgit v1.2.3 From b462ef658508d98d1d9ee5d7ee6b92e33b2571ff Mon Sep 17 00:00:00 2001 From: mathieui Date: Wed, 9 Nov 2011 15:05:55 +0100 Subject: Update plugins doc & 80 cols --- doc/en/plugins.txt | 76 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 50 insertions(+), 26 deletions(-) (limited to 'doc') diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt index 079e258b..6e829d5f 100644 --- a/doc/en/plugins.txt +++ b/doc/en/plugins.txt @@ -19,13 +19,15 @@ Methods Overridden methods ~~~~~~~~~~~~~~~~~~ -The *Plugin* class has several method that you can override for your own convenience +The *Plugin* class has several method that you can override for your own + convenience [[init]] *init*:: +self+ + This method is called when the plugin is loaded, this is where you call the other methods, for example <>, and initialize -everything to make your plugin actually do something. <>, <> +everything to make your plugin actually do something. <>, + <> *cleanup*:: +self+ + Called when the plugin is unloaded (or when poezio is exited). Clean everything @@ -43,23 +45,23 @@ This method adds a global command to poezio. For example you can add a /foo command that the user could call when the plugin is loaded, by calling this method with _foo_ as its _name_ argument. <> -* _name_: (string) the name of the command (for example, if it is 'plugintest', it can -add a /plugintest command) +* _name_: (string) the name of the command (for example, if it is 'plugintest', + it can add a /plugintest command) * _handler_: (function) the function to be called when the command is executed. the handler takes *args* as a parameter, which is a string of what is entered after the command. Split *args* (with _common.shell_split_) to use that as command arguments. -* _help_: (string) the help message available for that command through the _/help_ -command. -* _completion_: (function) the completion for the args of that command. It takes -an input object as its only argument. This function should call the -_auto_completion()_ method on the input object, passing a list of possible strings -for the completion and returning the value of that call directly. -Everything else is handled by that _auto_completion()_ method (checking what strings -match, how to cycle between matches, etc). If you don’t want any special completion -for that command, just pass None (the default value). - -*add_event_handler**: +self+, +event_name+, +handler+ + +* _help_: (string) the help message available for that command through the + _/help_ command. +* _completion_: (function) the completion for the args of that command. It + takes an input object as its only argument. This function should call the +_auto_completion()_ method on the input object, passing a list of possible + strings for the completion and returning the value of that call directly. +Everything else is handled by that _auto_completion()_ method (checking what + strings match, how to cycle between matches, etc). If you don’t want any + special completion for that command, just pass None (the default value). + +*add_event_handler**: +self+, +event_name+, +handler+ +position+ This methods adds a callback that will be called whenever the given event occurs. <> @@ -67,7 +69,12 @@ occurs. <> This can be a sleekxmpp event, or a poezio event. See the list of <>. * _handler_: The method that will be called whenever the event occurs. -It must accept the arguments specified for that event in the <>. +It must accept the arguments specified for that event in the + <>. +* _position_: Optional, this argument will specify the position of the handler + in the handler list for this event. It is 0 by default, and will only be used + with the internal poezio events described below. + Attributes ---------- @@ -77,14 +84,20 @@ Config By default, each plugin has a PluginConfig object accessible with *self.config*. *PluginConfig.read*:: +self+ + -Reads the config file from $XDG_CONFIG_HOME/poezio/plugins/plugin_name.cfg, it is called upon initialization, so you should not need it. +Reads the config file from $XDG_CONFIG_HOME/poezio/plugins/plugin_name.cfg, it + is called upon initialization, so you should not need it. *PluginConfig.write*:: +self+ + Writes the config to the same file mentioned previously. Core ~~~~ -Each plugin has a reference to the Core object accessible with *self.core*, that allows you to do about anything with poezio. Remember to use it only when you need it, and to use the functions described in this documentation only, even if much more is available. If your plugin needs to do something not available with these methods, please do a feature request instead of doing some dirty hacks with some other methods. +Each plugin has a reference to the Core object accessible with *self.core*, + that allows you to do about anything with poezio. Remember to use it only when + you need it, and to use the functions described in this documentation only, + even if much more is available. If your plugin needs to do something not + available with these methods, please do a feature request instead of doing + some dirty hacks with some other methods. Core methods ^^^^^^^^^^^^ @@ -98,49 +111,60 @@ Events list SleekXMPP events ~~~~~~~~~~~~~~~~ -For the sleekxmpp events, please refer to the https://github.com/fritzy/SleekXMPP/wiki/Event-Index[sleekxmpp event index]. +For the sleekxmpp events, please refer to the + https://github.com/fritzy/SleekXMPP/wiki/Event-Index[sleekxmpp event index]. Poezio events ~~~~~~~~~~~~~ *muc_say*:: +message+, +tab+ + -The handlers for this event are called whenever you say something in a MUC (through the /say command or by direct input). The parameters given to the handlers anre: +The handlers for this event are called whenever you say something in a MUC + (through the /say command or by direct input). The parameters given to the + handlers are: * _message_: Message to be sent * _tab_: Tab in which the message will be sent *private_say*:: +message+, +tab+ + -The handlers for this event are called whenever you say something in a private conversaton in a MUC (through the /say command or by direct input). The parameters given to the handlers are: +The handlers for this event are called whenever you say something in a private + conversaton in a MUC (through the /say command or by direct input). The + parameters given to the handlers are: * _message_: Message to be sent * _tab_: Tab in which the message will be sent *conversation_say*:: +message+, +tab+ + -The handlers for this event are called whenever you say something in direct conversation (through the /say command or by direct input). The parameters given to the handler are: +The handlers for this event are called whenever you say something in direct + conversation (through the /say command or by direct input). The parameters + given to the handler are: * _message_: Message to be sent * _tab_: Tab in which the message will be sent *muc_msg*:: +message+, +tab+ + -The handlers for this event are called whenever you receive a message in a MUC. The parameters given to the handler are: +The handlers for this event are called whenever you receive a message in a MUC. + The parameters given to the handler are: * _message_: Message received * _tab_: Tab in which the message was received *private_msg*:: +message+, +tab+ + -The handlers for this event are called whenever you receive a message in a private conversation in a MUC. The parameters given to the handler are: +The handlers for this event are called whenever you receive a message in a + private conversation in a MUC. The parameters given to the handler are: * _message_: Message received * _tab_: Tab in which the message was received *conversation_msg*:: +message+, +tab+ + -The handlers for this event are called whenever you receive a message in a direct conversation. The parameters given to the handler are: +The handlers for this event are called whenever you receive a message in a + direct conversation. The parameters given to the handler are: * _message_: Message received * _tab_: Tab in which the message was received -CAUTION: Plugins are in an experimental state and this API might change slightly in a near future. You have to be aware of that while making a plugin. +CAUTION: Plugins are in an experimental state and this API might change + slightly in a near future. You have to be aware of that while making a plugin. Examples -------- -- cgit v1.2.3 From 7f322e7d8885c33540b33b2147a02333a252673d Mon Sep 17 00:00:00 2001 From: mathieui Date: Wed, 9 Nov 2011 22:07:38 +0100 Subject: Plugin options in the config file --- doc/en/configure.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'doc') diff --git a/doc/en/configure.txt b/doc/en/configure.txt index 94f8e121..ef710690 100644 --- a/doc/en/configure.txt +++ b/doc/en/configure.txt @@ -263,3 +263,14 @@ Configuration options Defines if all tabs are resized at the same time (if set to false) or if they are really resized only when needed (if set to true). “true” should be the most comfortable value + +*plugins_autoload*:: [empty] + + Space separated list of plugins to load on startup. + +*plugins_dir*:: [empty] + + If plugins_dir is not set, plugins will be loaded from $XDG_DATA_HOME/poezio/plugins + You can specify another directory to use. It will be created if it does not + exist. + -- cgit v1.2.3 From b43a2ff4a23ae0bc032ac704e504db44daa76022 Mon Sep 17 00:00:00 2001 From: mathieui Date: Wed, 9 Nov 2011 23:17:20 +0100 Subject: Doc for the new events --- doc/en/plugins.txt | 60 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 48 insertions(+), 12 deletions(-) (limited to 'doc') diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt index 6e829d5f..32fe45c3 100644 --- a/doc/en/plugins.txt +++ b/doc/en/plugins.txt @@ -123,45 +123,81 @@ The handlers for this event are called whenever you say something in a MUC (through the /say command or by direct input). The parameters given to the handlers are: -* _message_: Message to be sent -* _tab_: Tab in which the message will be sent +* _message_: Message to be sent. +* _tab_: Tab in which the message will be sent. *private_say*:: +message+, +tab+ + The handlers for this event are called whenever you say something in a private conversaton in a MUC (through the /say command or by direct input). The parameters given to the handlers are: -* _message_: Message to be sent -* _tab_: Tab in which the message will be sent +* _message_: Message to be sent. +* _tab_: Tab in which the message will be sent. *conversation_say*:: +message+, +tab+ + The handlers for this event are called whenever you say something in direct conversation (through the /say command or by direct input). The parameters given to the handler are: -* _message_: Message to be sent -* _tab_: Tab in which the message will be sent +* _message_: Message to be sent. +* _tab_: Tab in which the message will be sent. *muc_msg*:: +message+, +tab+ + The handlers for this event are called whenever you receive a message in a MUC. The parameters given to the handler are: -* _message_: Message received -* _tab_: Tab in which the message was received +* _message_: Message received. +* _tab_: Tab in which the message was received. *private_msg*:: +message+, +tab+ + The handlers for this event are called whenever you receive a message in a private conversation in a MUC. The parameters given to the handler are: -* _message_: Message received -* _tab_: Tab in which the message was received +* _message_: Message received. +* _tab_: Tab in which the message was received. *conversation_msg*:: +message+, +tab+ + The handlers for this event are called whenever you receive a message in a direct conversation. The parameters given to the handler are: -* _message_: Message received -* _tab_: Tab in which the message was received +* _message_: Message received. +* _tab_: Tab in which the message was received. + +*normal_chatstate*:: +message+, +tab+ + +The handlers for this events are called whenever you receive a chatstate in a + direct conversation. The parameters given to this handler are: + +* _message_: Chatstate received. +* _tab_: Tab of the concerned conversation + +*muc_chatstate*:: +message+, +tab+ + +The handlers for this events are called whenever you receive a chatstate in a + MUC. The parameters given to this handler are: + +* _message_: Chatstate received. +* _tab_: Tab of the concerned MUC. + +*private_chatstate*:: +message+, +tab+ + +The handlers for this events are called whenever you receive a chatstate in a + private conversation in a MUC. The parameters given to this handler are: + +* _message_: Chatstate received. +* _tab_: Tab of the concerned conversation. + +*normal_presence*:: +presence+, +resource+ + +The handlers for this events are called whenever you receive a presence from + one of your contacts. The parameters given to this handler are: + +* _presence_: Presence received. +* _resource_: The resource that emitted the presence. + +*muc_presence*:: +presence+, +tab+ + +The handlers for this events are called whenever you receive a presence from + someone in a MUC. The parameters given to this handler are: + +* _presence_: Presence received. +* _tab_: Tab of the concerned MUC. + CAUTION: Plugins are in an experimental state and this API might change slightly in a near future. You have to be aware of that while making a plugin. -- cgit v1.2.3 From d3d4bd156cb8a76d5406f7b6c690bbb09e55afde Mon Sep 17 00:00:00 2001 From: mathieui Date: Thu, 10 Nov 2011 15:17:01 +0100 Subject: Doc for the new API function --- doc/en/plugins.txt | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) (limited to 'doc') diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt index 32fe45c3..4cef6db9 100644 --- a/doc/en/plugins.txt +++ b/doc/en/plugins.txt @@ -45,6 +45,41 @@ This method adds a global command to poezio. For example you can add a /foo command that the user could call when the plugin is loaded, by calling this method with _foo_ as its _name_ argument. <> +* _name_: (string) the name of the command (for example, if it is 'plugintest', + it can add a /plugintest command) +* _handler_: (function) the function to be called when the command is executed. +the handler takes *args* as a parameter, which is a string of what +is entered after the command. Split *args* (with _common.shell_split_) to use +that as command arguments. +* _help_: (string) the help message available for that command through the + _/help_ command. +* _completion_: (function) the completion for the args of that command. It + takes an input object as its only argument. This function should call the +_auto_completion()_ method on the input object, passing a list of possible + strings for the completion and returning the value of that call directly. +Everything else is handled by that _auto_completion()_ method (checking what + strings match, how to cycle between matches, etc). If you don’t want any + special completion for that command, just pass None (the default value). + +*del_command*:: +self+, +name+ + +This command removes a tab command added by your plugin. + +* _name_: (string) the name of the command you want to remove. + + +*add_tab_command*:: +self+, +tab_type+, +name+, +handler+, +help+, +completion+ + +This method adds a tab-custom command to poezio. For example you can add /dou +command that the user could call in a specific tab when the plugin is loaded. + + +* _tab_type_: You have to _import tabs_ in order to get tabs types. The + following are possible: +** _tabs.MucTab_: The MultiUserChat tabs +** _tabs.PrivateTab_: The Private tabs +** _tabs.ConversationTab_: The Roster tab +** _tabs.RosterInfoTab_: The MultiUserChat, Private, and Conversation tabs +** _tabs.ChatTab_: The MultiUserChat, Private, and Conversation tabs +** _tabs.MucListTab_: The MultiUserChat list tabs * _name_: (string) the name of the command (for example, if it is 'plugintest', it can add a /plugintest command) * _handler_: (function) the function to be called when the command is executed. @@ -76,6 +111,7 @@ It must accept the arguments specified for that event in the with the internal poezio events described below. + Attributes ---------- -- cgit v1.2.3 From 2dc4ec3badcf12d8208aa623a283ebc77b04ee63 Mon Sep 17 00:00:00 2001 From: mathieui Date: Thu, 10 Nov 2011 17:20:47 +0100 Subject: Doc for custom_host and custom_port (config file and asciidoc) --- doc/en/configure.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'doc') diff --git a/doc/en/configure.txt b/doc/en/configure.txt index ef710690..5928ef3e 100644 --- a/doc/en/configure.txt +++ b/doc/en/configure.txt @@ -264,6 +264,18 @@ Configuration options or if they are really resized only when needed (if set to true). “true” should be the most comfortable value +*custom_host*:: [empty] + + A custom host that will be used instead of the DNS records for the server + (anonymous or the jid’s) defined above. + You should not need this in a "normal" use case. + +*custom_port*:: [empty] + + A custom port to use instead of the 5222. + This option can be combined with custom_host. + You should not need this in a "normal" use case. + *plugins_autoload*:: [empty] Space separated list of plugins to load on startup. -- cgit v1.2.3 From 50d5c6b8b26dd66342a66ccd84bc8f68709bc724 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Fri, 11 Nov 2011 17:57:00 +0100 Subject: Fix a little error in the plugins doc --- doc/en/plugins.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt index 4cef6db9..c4eceb1a 100644 --- a/doc/en/plugins.txt +++ b/doc/en/plugins.txt @@ -1,7 +1,6 @@ Plugins ======= - Location -------- @@ -243,7 +242,7 @@ Examples [[example-1]] .Add a simple command that sends "Hello World!" into the conversation -===================================================================== +================================================================= [source,python] --------------- class Plugin(BasePlugin): @@ -253,7 +252,7 @@ class Plugin(BasePlugin): def command_hello(self, arg): self.core.send_message('Hello World!') --------------- -===================================================================== +================================================================= [[example-2]] -- cgit v1.2.3 From cd3390d91143b01f0409c2eb1c58fa6c989169b7 Mon Sep 17 00:00:00 2001 From: mathieui Date: Fri, 11 Nov 2011 22:16:23 +0100 Subject: Doc for /presence --- doc/en/usage.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc') diff --git a/doc/en/usage.txt b/doc/en/usage.txt index f11ab5ed..cca84e1d 100644 --- a/doc/en/usage.txt +++ b/doc/en/usage.txt @@ -211,6 +211,8 @@ These commands work in *any* tab. */theme*:: Reload the theme defined in the config file. +*/presence *:: Send a directed presence. + */list [server.tld]*:: Get the list of public chatrooms in the specified server . -- cgit v1.2.3 From cb8c04fd2add8606aace28bba5775cc13cd659b6 Mon Sep 17 00:00:00 2001 From: mathieui Date: Fri, 11 Nov 2011 22:38:40 +0100 Subject: Also the doc --- doc/en/usage.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/en/usage.txt b/doc/en/usage.txt index cca84e1d..b2ed14e4 100644 --- a/doc/en/usage.txt +++ b/doc/en/usage.txt @@ -211,7 +211,7 @@ These commands work in *any* tab. */theme*:: Reload the theme defined in the config file. -*/presence *:: Send a directed presence. +*/presence [type] [status]*:: Send a directed presence to _jid_ using _type_ and _status_ if provided. */list [server.tld]*:: Get the list of public chatrooms in the specified server . -- cgit v1.2.3 From ec7f0601c95cc89ba1427f6b8dc9ca06a49c4a11 Mon Sep 17 00:00:00 2001 From: mathieui Date: Fri, 11 Nov 2011 23:00:51 +0100 Subject: Doc for /rawxml --- doc/en/usage.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc') diff --git a/doc/en/usage.txt b/doc/en/usage.txt index b2ed14e4..7671c628 100644 --- a/doc/en/usage.txt +++ b/doc/en/usage.txt @@ -213,6 +213,8 @@ These commands work in *any* tab. */presence [type] [status]*:: Send a directed presence to _jid_ using _type_ and _status_ if provided. +*/rawxml*:: Send a custom XML stanza. + */list [server.tld]*:: Get the list of public chatrooms in the specified server . -- cgit v1.2.3 From a6bcb244f71996de6b873a4148bff081e5fb55eb Mon Sep 17 00:00:00 2001 From: mathieui Date: Sat, 12 Nov 2011 00:01:47 +0100 Subject: Doc for /xhtml --- doc/en/usage.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc') diff --git a/doc/en/usage.txt b/doc/en/usage.txt index 7671c628..30bdf886 100644 --- a/doc/en/usage.txt +++ b/doc/en/usage.txt @@ -246,6 +246,8 @@ These commands will work in any conversation tab (MultiUserChat, Private, or to begin with a _/_). Note that you can also send message starting with a _/_ by starting it with _//_. +*/xhtml *:: Send a custom xhtml message to the current tab. + MultiUserChat tab commands ~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 507c87ed88bb3715317c0ca8dc6b76780cb54b04 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sat, 12 Nov 2011 02:44:11 +0100 Subject: Doc for the new event --- doc/en/plugins.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'doc') diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt index c4eceb1a..a2d32607 100644 --- a/doc/en/plugins.txt +++ b/doc/en/plugins.txt @@ -233,6 +233,13 @@ The handlers for this events are called whenever you receive a presence from * _presence_: Presence received. * _tab_: Tab of the concerned MUC. +*send_normal_presence*:: +presence+ + +The handlers for this events are called whenever you send a presence “normal” +presence, i.e. a presence for your contacts or some direct JIDs, but *not* in a +MUC. The parameters given to this handler are: + +* _presence_: The presence about to be sent. + CAUTION: Plugins are in an experimental state and this API might change slightly in a near future. You have to be aware of that while making a plugin. -- cgit v1.2.3 From a78ac3f4bf2661c929866ae6f6fdfcee21bdb682 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sat, 12 Nov 2011 02:45:20 +0100 Subject: Put SleekXMPP events at the end of the plugins doc. --- doc/en/plugins.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt index a2d32607..b97e46d6 100644 --- a/doc/en/plugins.txt +++ b/doc/en/plugins.txt @@ -143,13 +143,6 @@ CAUTION: TODO Events list ----------- -SleekXMPP events -~~~~~~~~~~~~~~~~ - -For the sleekxmpp events, please refer to the - https://github.com/fritzy/SleekXMPP/wiki/Event-Index[sleekxmpp event index]. - - Poezio events ~~~~~~~~~~~~~ @@ -241,6 +234,13 @@ MUC. The parameters given to this handler are: * _presence_: The presence about to be sent. +SleekXMPP events +~~~~~~~~~~~~~~~~ + +For the sleekxmpp events, please refer to the + https://github.com/fritzy/SleekXMPP/wiki/Event-Index[sleekxmpp event index]. + + CAUTION: Plugins are in an experimental state and this API might change slightly in a near future. You have to be aware of that while making a plugin. -- cgit v1.2.3 From 744af2459d7d3a3c7a7e9d1f3861d4d494a837ba Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sat, 12 Nov 2011 03:42:07 +0100 Subject: Add three new events to modify a message JUST before we send it. It is NOT safe, and the doc says that pretty clearly. It is used to encrypt messages just before sending them (this way we can remove ALL potential in-clear bodies). --- doc/en/plugins.txt | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'doc') diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt index b97e46d6..87f09cb7 100644 --- a/doc/en/plugins.txt +++ b/doc/en/plugins.txt @@ -154,6 +154,17 @@ The handlers for this event are called whenever you say something in a MUC * _message_: Message to be sent. * _tab_: Tab in which the message will be sent. +*muc_say_after*:: +message+, +tab+ + +The handlers for this event are called whenever you say something in a MUC + (through the /say command or by direct input). The difference with muc_say is + just that *muc_say_after* hook is called AFTER the xhtm-im body has been + generated. So you *MUST* not insert any color attribute in the body using this + hook. The hook is less safe that *muc_say* and most of the time you should not + use it at all. The parameters given to the handlers are: + +* _message_: Message to be sent. +* _tab_: Tab in which the message will be sent. + *private_say*:: +message+, +tab+ + The handlers for this event are called whenever you say something in a private conversaton in a MUC (through the /say command or by direct input). The @@ -162,6 +173,20 @@ The handlers for this event are called whenever you say something in a private * _message_: Message to be sent. * _tab_: Tab in which the message will be sent. +*private_say_after*:: +message+, +tab+ + +The handlers for this event are called whenever you say something in a MUC + (through the /say command or by direct input). The difference with private_say + is just that *private_say_after* hook is called AFTER the xhtm-im body has + been generated and the message has been displayed on the conversation, this + means that if you modify the body, the message that will be sent will not be + the same that the one displayed in the text buffer. So you *MUST* not insert + any color attribute in the body using this hook. The hook is less safe that + *private_say* and most of the time you should not use it at all. The + parameters given to the handlers are: + +* _message_: Message to be sent. +* _tab_: Tab in which the message will be sent. + *conversation_say*:: +message+, +tab+ + The handlers for this event are called whenever you say something in direct conversation (through the /say command or by direct input). The parameters @@ -170,6 +195,20 @@ The handlers for this event are called whenever you say something in direct * _message_: Message to be sent. * _tab_: Tab in which the message will be sent. +*conversation_say_after*:: +message+, +tab+ + +The handlers for this event are called whenever you say something in a MUC + (through the /say command or by direct input). The difference with + *conversation_say* is just that *conversation_say_after* hook is called AFTER + the xhtm-im body has been generated and the message has been displayed on the + conversation, this means that if you modify the body, the message that will be + sent will not be the same that the one displayed in the text buffer. So you + *MUST* not insert any color attribute in the body using this hook. The hook is + less safe that *conversation_say* and most of the time you should not use it at + all. The parameters given to the handlers are: + +* _message_: Message to be sent. +* _tab_: Tab in which the message will be sent. + *muc_msg*:: +message+, +tab+ + The handlers for this event are called whenever you receive a message in a MUC. The parameters given to the handler are: -- cgit v1.2.3 From 4aa6eb63753ea5d5e5c2bb7d212f0b16606b22ab Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sat, 12 Nov 2011 06:42:29 +0100 Subject: Add a doc page for the GPG plugin. --- doc/en/plugins/gpg.txt | 100 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 doc/en/plugins/gpg.txt (limited to 'doc') diff --git a/doc/en/plugins/gpg.txt b/doc/en/plugins/gpg.txt new file mode 100644 index 00000000..31f2b80d --- /dev/null +++ b/doc/en/plugins/gpg.txt @@ -0,0 +1,100 @@ +GPG +=== + +This plugin implements the +link:http://xmpp.org/extensions/xep-0027.html[XEP-0027] “Current Jabber OpenPGP +Usage”. + +This is a plugin used to encrypt one-to-one conversation using the PGP +encryption method. You can use it if you want really good privacy. Without this +encryption, your messages are encrypted *at least* from your client (poezio) to +your server. The message is decrypted by your server and you cannot control the +encryption method of your messages from your server to your contact’s server +(unless you are your own server’s administrator), nor from your contact’s +server to your contact’s client. + +This plugin does end-to-end encryption. This means that *only* your contact can +decrypt your messages, and it is fully encrypted during *all* its travel +through the internet. + +Note that if you are having an encrypted conversation with a contact, you can +*not* send XHTML-IM messages to him. They will be remove and be replaced by +plain text messages. + +Installation and configuration +------------------------------ + +You should autoload this plugin, as it will send your signed presence directly +on login, making it easier for your contact’s clients that you are supporting +GPG encryption. To do that, use the _plugins_autoload_ configuration option. + +You need to create a plugin configuration file. Create a file named _gpg.cfg_ +into your plugins configuration directory (_~/.config/poezio/plugins_ by +default), and fill it like this: + +[source,python] +--------------------------------------------------------------------- +[Poezio] +keyid = 091F9C78 +passphrase = your OPTIONAL passphrase + +[keys] +example@jabber.org = E3CFCDE2 +juliet@xmpp.org = EF27ABCD +--------------------------------------------------------------------- + +The *Poezio* section is about your key. You need to specify the keyid, for the +key you want to use. You can as well provide a passphrase. If you don’t, you +should use a gpg agent or something like that that will ask your passphrase +whenever you need it. + +The *keys* section contains your contact’s id keys. For each contact you want +to have encrypted conversations with, add her/his JID associated with the keyid +of his/her key. + +And that’s it, now you need to talk directly to the *full* jid of your +contacts. Poezio doesn’t let you encrypt messages whom recipients is a bare +JID. + +Additionnal information on GnuPG +-------------------------------- + +Create a key +~~~~~~~~~~~~ + +To create a personal key, use +================== +gpg --gen-key +================== +and fill the instructions + + +Keyid +~~~~~ +The keyid (required in the gpg.cfg configuration file) is a 8 character-long +key. You can get the ones you created or imported by using the command +======================= +gpg --list-keys +======================= +You will get something like + +--------------------------------------------------------------------- +pub 4096R/01234567 2011-11-11 +uid Your Name Here (comment) +sub 4096R/AAFFBBCC 2011-11-11 + +pub 2048R/12345678 2011-11-12 [expire: 2011-11-22] +uid A contact’s name (comment) +sub 2048R/FFBBAACC 2011-11-12 [expire: 2011-11-22] +--------------------------------------------------------------------- + +In this example, the keyids are *01234567* and *12345678*. + +Share your key +~~~~~~~~~~~~~~ +Use +=========================== +gpg --send-keys --keyserver pgp.mit.edu +=========================== +to upload you public key on a public server. + -- cgit v1.2.3 From 05ef3594894e0bcbe80b98e81c2a2659ea01855f Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sat, 12 Nov 2011 07:19:58 +0100 Subject: Two missing words. --- doc/en/plugins/gpg.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/en/plugins/gpg.txt b/doc/en/plugins/gpg.txt index 31f2b80d..9e87b6c7 100644 --- a/doc/en/plugins/gpg.txt +++ b/doc/en/plugins/gpg.txt @@ -25,8 +25,9 @@ Installation and configuration ------------------------------ You should autoload this plugin, as it will send your signed presence directly -on login, making it easier for your contact’s clients that you are supporting -GPG encryption. To do that, use the _plugins_autoload_ configuration option. +on login, making it easier for your contact’s clients to know that you are +supporting GPG encryption. To do that, use the _plugins_autoload_ configuration +option. You need to create a plugin configuration file. Create a file named _gpg.cfg_ into your plugins configuration directory (_~/.config/poezio/plugins_ by -- cgit v1.2.3