From 0dd3b171e5049276b15b9287915aa7a124ae9420 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sat, 5 Nov 2011 04:20:03 +0100 Subject: Add plugins documentation. --- doc/en/plugins.txt | 132 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 doc/en/plugins.txt (limited to 'doc') diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt new file mode 100644 index 00000000..47ab7f01 --- /dev/null +++ b/doc/en/plugins.txt @@ -0,0 +1,132 @@ +Plugins +======= + +Currently, the plugins are in a plugin branch on the git repo. + +Location +-------- + +The plugins have to be present in '$XDG_DATA_HOME/poezio/plugins/plugin_name.py' +(or '~/.local/share' if not defined) + +Structure +--------- + +A plugin must always be a class named Plugin that inherits the +plugin.BasePlugin class defined into the *plugin* poezio module. + +Methods +------- + +Overridden methods +~~~~~~~~~~~~~~~~~~ +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. <>, <> + +*cleanup*:: +self+ + +Called when the plugin is unloaded (or when poezio is exited). Clean everything +that needs to be cleaned here. + +Callable methods +~~~~~~~~~~~~~~~~ +The BasePlugin has several methods that can be used. Here is a list of +all its methods that you could use in your plugin, describing what they +do, their arguments, and giving some example for each of them. + +[[add-command]] +*add_command*:: +self+, +name+, +handler+, +help+, +completion=None+ + +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). + +*add_event_handler**: +self+, +event_name+, +handler+ + +This methods adds a callback that will be called whenever the given event +occurs. <> + +* _event_name_: (string) The name of the event you want to ``monitor''. +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 <>. + +Attributes +---------- + +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. + +*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. + +Core methods +^^^^^^^^^^^^ +CAUTION: TODO + + +[[events-list]] +Events list +----------- +CAUTION: TODO + +Examples +-------- + +[[example-1]] +.Add a simple command that sends "Hello World!" into the conversation +===================================================================== +[source,python] +--------------- +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): + self.core.send_message('Hello World!') +--------------- +===================================================================== + +[[example-2]] + +.Adds an event handler that sends ``tg'' to a groupchat when a message is received from someone named ``Partauch'' +===================================================================== +[source,python] +--------------- +class Plugin(BasePlugin): + def init(self): + self.add_event_handler('groupchat_message', self.on_groupchat_message) + + def on_groupchat_message(self, message): + if message['mucnick'] == "Partauche": + self.core.send_message('tg', to=message.getMucroom()) +--------------- +===================================================================== + -- cgit v1.2.3 From 2f5d7124676fb1e32a0223bd968d671ac2f38333 Mon Sep 17 00:00:00 2001 From: mathieui Date: Tue, 8 Nov 2011 19:10:19 +0100 Subject: Doc: ChatTab and MUC commands --- doc/en/usage.txt | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'doc') diff --git a/doc/en/usage.txt b/doc/en/usage.txt index be6809ba..216e4852 100644 --- a/doc/en/usage.txt +++ b/doc/en/usage.txt @@ -57,3 +57,43 @@ These commands work in *any* tab. */bind *:: Bind a key to another key or to a "command". For example, "/bind ^H KEY_UP" makes Control + h behave the same way than the Up key. +Chat tab commands +^^^^^^^^^^^^^^^^^ + +These commands will work in any conversation tab (MultiUserChat, Private, or Conversation tabs). + +*/say *:: Just send the message (only useful it you want your message to begin with a "/"). + +MultiUserChat tab commands +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*/ignore *:: Ignore a specified nickname. + +*/unignore *:: Remove the specified nickname from the ignore list. + +*/kick [reason]*:: Kick the user with the specified nickname. You can also give an optional reason. + +*/topic *:: Change the subject of the room. You might want to knwow that entering "/topic [tab]" will autocomplete the topic. + +*/query [message]*:: Open a private conversation with . This nick has to be present in the room you’re currently in. If you specified a message after the nickname, it will be sent to this user. + +*/part [message]*:: Disconnect you from a room. You can specify an optional message. + +*/close [message]*:: Disconnect you from a room (if you are connected) and close the tab. You can specify an optional message if you are still connected. + +*/nick *:: Change your nickname in the current room. + +*/recolor*:: Re-assign a color to all the participants in the current room, based on the last time they talked. Use this if the participants currently talking have too many identical colors. + +*/cycle [message]*:: Leave the current room an rejoint it immediatly. You can specify an optional quit message. + +*/info *:: Display some information about the user in the room: his/her role, affiliation, status, and status message. + +*/version *:: Get the software version of the given nick in room or the given jid (usually its XMPP client and Operating System). + +*/configure*:: Configure the current room through a form. + +*/names*:: Get the list of the users in the room, their number, and the list of the people assuming different roles. + +*/clear*:: Clear the current buffer. + -- cgit v1.2.3 From 6779f7c7a46840b6323280596701cc7606f04a31 Mon Sep 17 00:00:00 2001 From: mathieui Date: Tue, 8 Nov 2011 19:17:38 +0100 Subject: Doc: PrivateTab and ConversationTab commands --- doc/en/usage.txt | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'doc') diff --git a/doc/en/usage.txt b/doc/en/usage.txt index 216e4852..872ff0eb 100644 --- a/doc/en/usage.txt +++ b/doc/en/usage.txt @@ -97,3 +97,25 @@ MultiUserChat tab commands */clear*:: Clear the current buffer. +Private tab commands +^^^^^^^^^^^^^^^^^^^^ + +*/info*:: Display some info about this user in the MultiUserChat. + +*/close*:: Close the tab. + +*/unquery*:: Close the tab. + +*/version*:: Get the software version of the current interlocutor (usually its XMPP client and Operating System). + +Normal Conversation tab commands +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*/info*:: Display the status of this contact. + +*/close*:: Close the tab. + +*/unquery*:: Close the tab. + +*/version*:: Get the software version of the current interlocutor (usually its XMPP client and Operating System). + -- cgit v1.2.3 From 696ce0f283ea95ddb88705c161691e2fa80c13b8 Mon Sep 17 00:00:00 2001 From: mathieui Date: Tue, 8 Nov 2011 19:38:50 +0100 Subject: Doc: Roster tab commands --- doc/en/usage.txt | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/en/usage.txt b/doc/en/usage.txt index 872ff0eb..e00b88de 100644 --- a/doc/en/usage.txt +++ b/doc/en/usage.txt @@ -57,6 +57,10 @@ These commands work in *any* tab. */bind *:: Bind a key to another key or to a "command". For example, "/bind ^H KEY_UP" makes Control + h behave the same way than the Up key. +NOTE: The following command will work everywhere, except in the Roster tab. + +*/close*:: Close the tab. + Chat tab commands ^^^^^^^^^^^^^^^^^ @@ -102,8 +106,6 @@ Private tab commands */info*:: Display some info about this user in the MultiUserChat. -*/close*:: Close the tab. - */unquery*:: Close the tab. */version*:: Get the software version of the current interlocutor (usually its XMPP client and Operating System). @@ -113,9 +115,30 @@ Normal Conversation tab commands */info*:: Display the status of this contact. -*/close*:: Close the tab. - */unquery*:: Close the tab. */version*:: Get the software version of the current interlocutor (usually its XMPP client and Operating System). +Roster tab commands +^^^^^^^^^^^^^^^^^^^ + +*/accept [jid]*:: Authorize the provided JID (or the selected contact in the roster) to see your presence. + +*/deny [jid]*:: Prevent the provided JID (or the selected contact in the roster) from seeing your presence. + +*/add *:: Add the specified JID to your roster and authorize him to see your presence. If he accepts you, the subscription will be mutual (and if he doesn’t, you can still /deny him). + +*/name *:: Set the given JID’s name. + +*/groupadd *:: Add the given JID to the given group (if the group does not exist, it will be created). + +*/groupremove *:: Remove the given JID from the given group (if the group is empty after that, it will get deleted). + +*/remove [jid]*:: Remove the specified JID from your roster. TThis will unsubscribe you from its presence, cancel it subscription to yours, and remove the item from your roster. + +NOTE: The following commands do not comply with any XEP or whatever, but they can still prove useful when you are migrating to an other JID. + +*/export [/path/to/file]*:: Export your contacts into /path/to/file if specified, or $HOME/poezio_contacts if not. + +*/import [/path/to/file]*:: Import your contacts from /path/to/file if specified, or $HOME/poezio_contacts if not. + -- cgit v1.2.3 From d28b70ccd4a29c6ef5b0f7f740ac04b4348669b4 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Tue, 8 Nov 2011 19:39:12 +0100 Subject: Some documentation improvements. --- doc/en/usage.txt | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) (limited to 'doc') diff --git a/doc/en/usage.txt b/doc/en/usage.txt index e00b88de..e7df6ce8 100644 --- a/doc/en/usage.txt +++ b/doc/en/usage.txt @@ -1,18 +1,27 @@ Usage ===== +This page is the main page of the documentation for poezio, explaining how to use it and describing its interfaces. + +Poezio is composed of tabs which can be of various types. Each tab type has +a distinct interface, list of commands and list of key shortcuts, in addition +to the global commands and key shortcuts. + Commands -------- -Command listing -~~~~~~~~~~~~~~~ +Commands start with the _/_ character and can take a list of any number +of arguments, separated by spaces. If an argument should contain a space, +you can use the _"_ character to surround this argument. -The commands are shown like this: +The commands described in this page are shown like this: +=========================================================== /command [optional argument] +=========================================================== Global commands -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ These commands work in *any* tab. @@ -41,7 +50,7 @@ These commands work in *any* tab. */status [status message]*:: Set your availability and (optionaly) your status message. The argument is one of "available, chat, away, afk, dnd, busy, xa" and the optional [status] argument will be your status message.' -*/bookmark [roomname][/nick]*:: Bookmark the specified room (you will then auto-join it on each poezio start). This commands uses the same syntax as /join. Type /help join for syntax examples. Note that when typing /bookmark on its own, the room will be bookmarked with the nickname you're currently using in this room (instead of default_nick). +*/bookmark [roomname][/nick]*:: Bookmark the specified room (you will then auto-join it on each poezio start). This commands uses almost the same syntax as /join. Type /help join for syntax examples. Note that when typing /bookmark on its own, the room will be bookmarked with the nickname you're currently using in this room (instead of default_nick). */set