From d676c2ee7b6207ff0b2a7b384052ab07c08bf43a Mon Sep 17 00:00:00 2001 From: mathieui Date: Sat, 13 Apr 2013 22:33:06 +0200 Subject: Move the plugins documentation (use automodule directive & docstrings) --- doc/source/index.rst | 2 +- doc/source/plugins/admin.rst | 5 +- doc/source/plugins/alias.rst | 6 ++ doc/source/plugins/amsg.rst | 6 ++ doc/source/plugins/day_change.rst | 6 ++ doc/source/plugins/display_corrections.rst | 6 ++ doc/source/plugins/double.rst | 6 ++ doc/source/plugins/exec.rst | 6 ++ doc/source/plugins/figlet.rst | 6 ++ doc/source/plugins/gpg.rst | 6 ++ doc/source/plugins/index.rst | 72 ++++++++++++++++++++ doc/source/plugins/iq_show.rst | 6 ++ doc/source/plugins/link.rst | 6 ++ doc/source/plugins/mpd_client.rst | 6 ++ doc/source/plugins/otr.rst | 6 ++ doc/source/plugins/pacokick.rst | 6 ++ doc/source/plugins/ping.rst | 6 ++ doc/source/plugins/quote.rst | 6 ++ doc/source/plugins/rainbow.rst | 6 ++ doc/source/plugins/reminder.rst | 6 ++ doc/source/plugins/replace.rst | 6 ++ doc/source/plugins/revstr.rst | 6 ++ doc/source/plugins/screen_detach.rst | 6 ++ doc/source/plugins/send_delayed.rst | 6 ++ doc/source/plugins/shuffle.rst | 6 ++ doc/source/plugins/simple_notify.rst | 6 ++ doc/source/plugins/status.rst | 6 ++ doc/source/plugins/tell.rst | 6 ++ doc/source/plugins/time_marker.rst | 6 ++ doc/source/plugins/uptime.rst | 6 ++ doc/stub/tabs.py | 8 +++ plugins/alias.py | 38 ++++++++++- plugins/amsg.py | 22 +++++- plugins/day_change.py | 12 ++++ plugins/display_corrections.py | 31 ++++++++- plugins/double.py | 12 ++++ plugins/exec.py | 44 +++++++++++- plugins/figlet.py | 20 ++++++ plugins/gpg/__init__.py | 104 +++++++++++++++++++++++++++++ plugins/iq_show.py | 13 ++++ plugins/link.py | 78 +++++++++++++++++++++- plugins/mpd_client.py | 51 +++++++++++++- plugins/otr.py | 95 ++++++++++++++++++++++++++ plugins/pacokick.py | 22 ++++++ plugins/ping.py | 32 +++++++++ plugins/quote.py | 30 +++++++++ plugins/rainbow.py | 23 +++++++ plugins/reminder.py | 57 ++++++++++++++++ plugins/replace.py | 64 +++++++++++++++++- plugins/revstr.py | 14 ++++ plugins/screen_detach.py | 12 ++++ plugins/shuffle.py | 14 ++++ plugins/simple_notify.py | 66 ++++++++++++++++++ plugins/status.py | 35 ++++++++++ plugins/time_marker.py | 29 +++++++- plugins/uptime.py | 22 ++++++ 56 files changed, 1172 insertions(+), 17 deletions(-) create mode 100644 doc/source/plugins/alias.rst create mode 100644 doc/source/plugins/amsg.rst create mode 100644 doc/source/plugins/day_change.rst create mode 100644 doc/source/plugins/display_corrections.rst create mode 100644 doc/source/plugins/double.rst create mode 100644 doc/source/plugins/exec.rst create mode 100644 doc/source/plugins/figlet.rst create mode 100644 doc/source/plugins/gpg.rst create mode 100644 doc/source/plugins/iq_show.rst create mode 100644 doc/source/plugins/link.rst create mode 100644 doc/source/plugins/mpd_client.rst create mode 100644 doc/source/plugins/otr.rst create mode 100644 doc/source/plugins/pacokick.rst create mode 100644 doc/source/plugins/ping.rst create mode 100644 doc/source/plugins/quote.rst create mode 100644 doc/source/plugins/rainbow.rst create mode 100644 doc/source/plugins/reminder.rst create mode 100644 doc/source/plugins/replace.rst create mode 100644 doc/source/plugins/revstr.rst create mode 100644 doc/source/plugins/screen_detach.rst create mode 100644 doc/source/plugins/send_delayed.rst create mode 100644 doc/source/plugins/shuffle.rst create mode 100644 doc/source/plugins/simple_notify.rst create mode 100644 doc/source/plugins/status.rst create mode 100644 doc/source/plugins/tell.rst create mode 100644 doc/source/plugins/time_marker.rst create mode 100644 doc/source/plugins/uptime.rst create mode 100644 doc/stub/tabs.py diff --git a/doc/source/index.rst b/doc/source/index.rst index f1eff613..1f2ce3f3 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -20,7 +20,7 @@ Poezio documentation dev/index .. - plugins + plugins/index dev Indices and tables diff --git a/doc/source/plugins/admin.rst b/doc/source/plugins/admin.rst index fc5875b4..5cd6c77c 100644 --- a/doc/source/plugins/admin.rst +++ b/doc/source/plugins/admin.rst @@ -1,7 +1,6 @@ .. _admin-plugin: -Room administration plugin -========================== - +Admin +===== .. automodule:: admin diff --git a/doc/source/plugins/alias.rst b/doc/source/plugins/alias.rst new file mode 100644 index 00000000..0832576e --- /dev/null +++ b/doc/source/plugins/alias.rst @@ -0,0 +1,6 @@ +.. _alias-plugin: + +Alias +===== + +.. automodule:: alias diff --git a/doc/source/plugins/amsg.rst b/doc/source/plugins/amsg.rst new file mode 100644 index 00000000..2a785034 --- /dev/null +++ b/doc/source/plugins/amsg.rst @@ -0,0 +1,6 @@ +.. _amsg-plugin: + +Amsg +==== + +.. automodule:: amsg diff --git a/doc/source/plugins/day_change.rst b/doc/source/plugins/day_change.rst new file mode 100644 index 00000000..5893b1f7 --- /dev/null +++ b/doc/source/plugins/day_change.rst @@ -0,0 +1,6 @@ +.. _daychange-plugin: + +Day change +========== + +.. automodule:: day_change diff --git a/doc/source/plugins/display_corrections.rst b/doc/source/plugins/display_corrections.rst new file mode 100644 index 00000000..5046a76e --- /dev/null +++ b/doc/source/plugins/display_corrections.rst @@ -0,0 +1,6 @@ +.. _displaycorrections-plugin: + +Display corrections +=================== + +.. automodule:: display_corrections diff --git a/doc/source/plugins/double.rst b/doc/source/plugins/double.rst new file mode 100644 index 00000000..e40fa575 --- /dev/null +++ b/doc/source/plugins/double.rst @@ -0,0 +1,6 @@ +.. _double-plugin: + +Double +====== + +.. automodule:: double diff --git a/doc/source/plugins/exec.rst b/doc/source/plugins/exec.rst new file mode 100644 index 00000000..3183e9bc --- /dev/null +++ b/doc/source/plugins/exec.rst @@ -0,0 +1,6 @@ +.. _exec-plugin: + +Exec +===== + +.. automodule:: exec diff --git a/doc/source/plugins/figlet.rst b/doc/source/plugins/figlet.rst new file mode 100644 index 00000000..c1490e1b --- /dev/null +++ b/doc/source/plugins/figlet.rst @@ -0,0 +1,6 @@ +.. _figlet-plugin: + +Figlet +====== + +.. automodule:: figlet diff --git a/doc/source/plugins/gpg.rst b/doc/source/plugins/gpg.rst new file mode 100644 index 00000000..747d8cb8 --- /dev/null +++ b/doc/source/plugins/gpg.rst @@ -0,0 +1,6 @@ +.. _gpg-plugin: + +GPG +=== + +.. automodule:: gpg diff --git a/doc/source/plugins/index.rst b/doc/source/plugins/index.rst index 5af1d7e0..7aad64c8 100644 --- a/doc/source/plugins/index.rst +++ b/doc/source/plugins/index.rst @@ -27,6 +27,8 @@ e.g. plugins_autoload = gpg:tell:exec +.. _plugin-configuration: + Plugin configuration -------------------- @@ -50,6 +52,7 @@ Plugin index ------------ .. glossary:: + :sorted: Admin :ref:`Documentation ` @@ -57,98 +60,167 @@ Plugin index Creates convenient aliases for MUC administration. Alias + :ref:`Documentation ` Allows you to create your own aliases. Amsg + :ref:`Documentation ` Allows a message to be broadcasted on all the rooms your are in. Caution: do not overuse. Day Change + :ref:`Documentation ` Logs the day change inside the buffers, to keep track of the days when backlogging. Display corrections + :ref:`Documentation ` Lists old versions of a corrected message. Exec + :ref:`Documentation ` Runs a system command an optionally sends the output as a message. Figlet + :ref:`Documentation ` Ascii-art writing (requires the ``figlet`` package on your system). GPG + :ref:`Documentation ` Allows encrypted exchanges and presence signing using GnuPG. IQ Show + :ref:`Documentation ` Shows the received IQs, for debugging purposes. Link + :ref:`Documentation ` Opens links in a web browser, locally or remotely using a FIFO and SSH. MPD Client + :ref:`Documentation ` Sends the current song (and optionally the progress inside the song) to the current (chat) tab. OTR + :ref:`Documentation ` Allows encrypted and deniable exchanges using OTR. PacoKick + :ref:`Documentation ` Kicks a random user in the room. Ping + :ref:`Documentation ` Sends a ping probe to an entity (XEP-0199) Quote + :ref:`Documentation ` Adds a /quote command to quote a message at HH:MM:SS and put it in the input (to prevent painful copy/pastes). Rainbow + :ref:`Documentation ` Sends your messages in rainbow colors using XHTML-IM. Reminder + :ref:`Documentation ` Reminds you to do something every now and then. Screen Detach + :ref:`Documentation ` Changes your status to _away_ if the screen poezio is in is detached. Simple notify + :ref:`Documentation ` Sends a notification with a command of your choice on (non-MUC) messages. Status + :ref:`Documentation ` Adds convenient aliases to /status (/away, etc). Tell + :ref:`Documentation ` Tells a message to a nick when he connects to a MUC. Uptime + :ref:`Documentation ` Gets the uptime of a XMPP server or a component. Replace + :ref:`Documentation ` Replace some patterns in your messages. Time Marker + :ref:`Documentation ` Display the time between two messages. + Revstr + :ref:`Documentation ` + + Reverse everything you say. + + Shuffle + :ref:`Documentation ` + + Shuffle everything you say. + + Double + :ref:`Documentation ` + + Double the first word of each sentence. + +.. toctree:: + :hidden: + + admin + alias + amsg + day_change + display_corrections + exec + figlet + gpg + link + mpd_client + otr + pacokick + ping + quote + rainbow + reminder + replace + screen_detach + send_delayed + simple_notify + status + tell + time_marker + uptime + revstr + double + shuffle + iq_show diff --git a/doc/source/plugins/iq_show.rst b/doc/source/plugins/iq_show.rst new file mode 100644 index 00000000..29ba420e --- /dev/null +++ b/doc/source/plugins/iq_show.rst @@ -0,0 +1,6 @@ +.. _iqshow-plugin: + +Iq show +======= + +.. automodule:: iq_show diff --git a/doc/source/plugins/link.rst b/doc/source/plugins/link.rst new file mode 100644 index 00000000..deac6f86 --- /dev/null +++ b/doc/source/plugins/link.rst @@ -0,0 +1,6 @@ +.. _link-plugin: + +Link +==== + +.. automodule:: link diff --git a/doc/source/plugins/mpd_client.rst b/doc/source/plugins/mpd_client.rst new file mode 100644 index 00000000..e6ee2399 --- /dev/null +++ b/doc/source/plugins/mpd_client.rst @@ -0,0 +1,6 @@ +.. _mpdclient-plugin: + +Mpd client +========== + +.. automodule:: mpd_client diff --git a/doc/source/plugins/otr.rst b/doc/source/plugins/otr.rst new file mode 100644 index 00000000..f48eba96 --- /dev/null +++ b/doc/source/plugins/otr.rst @@ -0,0 +1,6 @@ +.. _otr-plugin: + +OTR +=== + +.. automodule:: otr diff --git a/doc/source/plugins/pacokick.rst b/doc/source/plugins/pacokick.rst new file mode 100644 index 00000000..df84eea6 --- /dev/null +++ b/doc/source/plugins/pacokick.rst @@ -0,0 +1,6 @@ +.. _pacokick-plugin: + +Pacokick +======== + +.. automodule:: pacokick diff --git a/doc/source/plugins/ping.rst b/doc/source/plugins/ping.rst new file mode 100644 index 00000000..cef72f6e --- /dev/null +++ b/doc/source/plugins/ping.rst @@ -0,0 +1,6 @@ +.. _ping-plugin: + +Ping +==== + +.. automodule:: ping diff --git a/doc/source/plugins/quote.rst b/doc/source/plugins/quote.rst new file mode 100644 index 00000000..fb1ac2d0 --- /dev/null +++ b/doc/source/plugins/quote.rst @@ -0,0 +1,6 @@ +.. _quote-plugin: + +Quote +===== + +.. automodule:: quote diff --git a/doc/source/plugins/rainbow.rst b/doc/source/plugins/rainbow.rst new file mode 100644 index 00000000..fb01e8de --- /dev/null +++ b/doc/source/plugins/rainbow.rst @@ -0,0 +1,6 @@ +.. _rainbow-plugin: + +Rainbow +======= + +.. automodule:: rainbow diff --git a/doc/source/plugins/reminder.rst b/doc/source/plugins/reminder.rst new file mode 100644 index 00000000..cbf73470 --- /dev/null +++ b/doc/source/plugins/reminder.rst @@ -0,0 +1,6 @@ +.. _reminder-plugin: + +Reminder +======== + +.. automodule:: reminder diff --git a/doc/source/plugins/replace.rst b/doc/source/plugins/replace.rst new file mode 100644 index 00000000..5c7c594b --- /dev/null +++ b/doc/source/plugins/replace.rst @@ -0,0 +1,6 @@ +.. _replace-plugin: + +Replace +======= + +.. automodule:: replace diff --git a/doc/source/plugins/revstr.rst b/doc/source/plugins/revstr.rst new file mode 100644 index 00000000..bff5b660 --- /dev/null +++ b/doc/source/plugins/revstr.rst @@ -0,0 +1,6 @@ +.. _revstr-plugin: + +Revstr +====== + +.. automodule:: revstr diff --git a/doc/source/plugins/screen_detach.rst b/doc/source/plugins/screen_detach.rst new file mode 100644 index 00000000..d080c113 --- /dev/null +++ b/doc/source/plugins/screen_detach.rst @@ -0,0 +1,6 @@ +.. _screendetach-plugin: + +Screen detach +============= + +.. automodule:: screen_detach diff --git a/doc/source/plugins/send_delayed.rst b/doc/source/plugins/send_delayed.rst new file mode 100644 index 00000000..c2b3e681 --- /dev/null +++ b/doc/source/plugins/send_delayed.rst @@ -0,0 +1,6 @@ +.. _senddelayed-plugin: + +Send delayed +============ + +.. automodule:: send_delayed diff --git a/doc/source/plugins/shuffle.rst b/doc/source/plugins/shuffle.rst new file mode 100644 index 00000000..ef987deb --- /dev/null +++ b/doc/source/plugins/shuffle.rst @@ -0,0 +1,6 @@ +.. _shuffle-plugin: + +Shuffle +======= + +.. automodule:: shuffle diff --git a/doc/source/plugins/simple_notify.rst b/doc/source/plugins/simple_notify.rst new file mode 100644 index 00000000..78a45909 --- /dev/null +++ b/doc/source/plugins/simple_notify.rst @@ -0,0 +1,6 @@ +.. _simplenotify-plugin: + +Simple notify +============= + +.. automodule:: simple_notify diff --git a/doc/source/plugins/status.rst b/doc/source/plugins/status.rst new file mode 100644 index 00000000..7891ecc2 --- /dev/null +++ b/doc/source/plugins/status.rst @@ -0,0 +1,6 @@ +.. _status-plugin: + +Status +====== + +.. automodule:: status diff --git a/doc/source/plugins/tell.rst b/doc/source/plugins/tell.rst new file mode 100644 index 00000000..7f52db73 --- /dev/null +++ b/doc/source/plugins/tell.rst @@ -0,0 +1,6 @@ +.. _tell-plugin: + +Tell +==== + +.. automodule:: tell diff --git a/doc/source/plugins/time_marker.rst b/doc/source/plugins/time_marker.rst new file mode 100644 index 00000000..95552e1a --- /dev/null +++ b/doc/source/plugins/time_marker.rst @@ -0,0 +1,6 @@ +.. _timemarker-plugin: + +Time marker +=========== + +.. automodule:: time_marker diff --git a/doc/source/plugins/uptime.rst b/doc/source/plugins/uptime.rst new file mode 100644 index 00000000..94e38c28 --- /dev/null +++ b/doc/source/plugins/uptime.rst @@ -0,0 +1,6 @@ +.. _uptime-plugin: + +Uptime +====== + +.. automodule:: uptime diff --git a/doc/stub/tabs.py b/doc/stub/tabs.py new file mode 100644 index 00000000..70794313 --- /dev/null +++ b/doc/stub/tabs.py @@ -0,0 +1,8 @@ +class Tab(object): pass +class ChatTab(Tab): pass +class PrivateTab(ChatTab): pass +class MucTab(ChatTab): pass +class ConversationTab(ChatTab): pass +class RosterInfoTab(Tab): pass +class XMLTab(Tab): pass + diff --git a/plugins/alias.py b/plugins/alias.py index a3843f35..80efe5bc 100644 --- a/plugins/alias.py +++ b/plugins/alias.py @@ -1,7 +1,41 @@ """ -Alias plugin. +Installation +------------ +You only have to load the plugin: + +``/load alias`` + +Usage +----- + +This plugin defines two new global commands: :term:`/alias` and :term:`/unalias`. + +.. glossary:: + + /alias + **Usage:** ``/alias [args]`` + + This command will create a new command, named ``name`` (and callable with + ``/name``), that runs ``/command``, with ``[args]`` as fixed args for the command. + When you run the alias, you can also pass parameters to it, that will be fed + to the original command. + + Example: :: + + /alias toto say "koin " + + Will bind ``/say koin `` to ``/toto``, so this alias will work in any + Chat tab. If someone calls it with :: + + /toto koin + + Poezio will then execute ``/say koin koin``. + + /unalias + **Usage:** ``/unalias `` + + This command removes a defined alias. -Allows the creation and the removal of personal aliases. """ from plugin import BasePlugin diff --git a/plugins/amsg.py b/plugins/amsg.py index 57a37255..c330373f 100644 --- a/plugins/amsg.py +++ b/plugins/amsg.py @@ -1,5 +1,25 @@ -# A simple broadcast plugin +""" +This plugin broadcasts a message to all your joined rooms. +.. note:: With great power comes great responsability. + Use with moderation. + +Installation +------------ +You only have to load the plugin.:: + + /load amsg + +Command +------- + +.. glossary:: + + /amsg + **Usage:** ``/amsg `` + + +""" from plugin import BasePlugin from tabs import MucTab diff --git a/plugins/day_change.py b/plugins/day_change.py index 179bfd98..d9cd3197 100644 --- a/plugins/day_change.py +++ b/plugins/day_change.py @@ -1,3 +1,15 @@ +""" +This plugin adds a message at 00:00 in each of your chat tabs saying that the +date has changed. + +Installation +------------ +You only have to load the plugin.:: + + /load day_change + +""" + from gettext import gettext as _ from plugin import BasePlugin import datetime diff --git a/plugins/display_corrections.py b/plugins/display_corrections.py index cad5a327..c7617b3e 100644 --- a/plugins/display_corrections.py +++ b/plugins/display_corrections.py @@ -1,6 +1,33 @@ -# A plugin that adds the /display_corrections command, to view the previous -# versions of a corrected message. +""" +Lists old versions of a corrected message. +Installation +------------ +:: + + /load display_corrections + +Usage +----- + +.. glossary:: + + /display_corrections + **Usage:** ``/display_corrections [number]`` + + This command lists the old versions of a message. + + Without argument, it will list the last corrected message if there + is any. If you give an integer as an argument, ``/display_corrections`` + will go back gradually in the buffer to find the message matching + that number (starting from 1, for the last corrected message). + + If you are scrolling in the buffer, Poezio will list the corrected messages + starting from the first you can see. (although there are some problems with + multiline messages). + + +""" from plugin import BasePlugin from common import shell_split import tabs diff --git a/plugins/double.py b/plugins/double.py index 597ab242..02c7ddcd 100644 --- a/plugins/double.py +++ b/plugins/double.py @@ -1,3 +1,15 @@ +""" +Double the first word of any message you send in a :ref:`muctab`, making you appear retarded. + +Installation +------------ + +You only have to load the plugin: + +.. code-block:: none + + /load double +""" from plugin import BasePlugin class Plugin(BasePlugin): diff --git a/plugins/exec.py b/plugins/exec.py index 4dbe9590..10681713 100644 --- a/plugins/exec.py +++ b/plugins/exec.py @@ -1,4 +1,46 @@ -# A plugin that can execute a command and send the result in the conversation +""" +This plugin lets you execute a system command through poezio. + +Installation +------------ + +You only have to load the plugin. :: + + /load exec + +Usage +----- + +.. warning:: Running commands that start a daemon or an interface is not a good + idea. + +.. glossary:: + + /exec + **Usage:** ``/exec [-o|-O] `` + + Execute a system command. + + :: + + /exec command + + Will give you the result in the information buffer. + + :: + + /exec -o command + + Will send the result of the command into the current tab, if possible. + + :: + + /exec -O command + + Will send the result of the command and the command summary into the current + tab, if possible. + +""" from plugin import BasePlugin import os diff --git a/plugins/figlet.py b/plugins/figlet.py index eaf8dab3..9006f793 100644 --- a/plugins/figlet.py +++ b/plugins/figlet.py @@ -1,3 +1,23 @@ +""" +This plugin uses figlet to transform every message into a big ascii-art +message. + +Installation +------------ +You only have to load the plugin (and have :file:`figlet` installed, of course). +:: + + /load figlet + + +Usage +----- + +Say something in a Chat tab. + +.. note:: Can create fun things when used with :ref:`The rainbow plugin `. + +""" from plugin import BasePlugin import subprocess diff --git a/plugins/gpg/__init__.py b/plugins/gpg/__init__.py index 9fa8ee13..c6945e18 100644 --- a/plugins/gpg/__init__.py +++ b/plugins/gpg/__init__.py @@ -1,3 +1,107 @@ +""" +This plugin implements the `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 removed 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 to know that you are +supporting GPG encryption. To do that, use the :term:`plugins_autoload` configuration +option. + +You need to create a plugin configuration file. Create a file named :file:`gpg.cfg` +into your plugins configuration directory (:file:`~/.config/poezio/plugins` by +default), and fill it like this: + +.. code-block:: ini + + [gpg] + keyid = 091F9C78 + passphrase = your OPTIONAL passphrase + + [keys] + example@jabber.org = E3CFCDE2 + juliet@xmpp.org = EF27ABCD + +The ``gpg`` 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 + +.. code-block:: bash + + gpg --gen-key + +and follow 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 + +.. code-block:: bash + + gpg --list-keys + +You will get something like + +.. code-block:: none + + 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: + +.. code-block:: bash + + gpg --send-keys --keyserver pgp.mit.edu + +to upload you public key on a public server. + +.. _XEP-0027: http://xmpp.org/extensions/xep-0027.html + +""" from gpg import gnupg from sleekxmpp.xmlstream.stanzabase import JID diff --git a/plugins/iq_show.py b/plugins/iq_show.py index 06d06d8e..69bd2722 100644 --- a/plugins/iq_show.py +++ b/plugins/iq_show.py @@ -1,3 +1,16 @@ +""" +Show the exchanged IQs (useful for debugging). + +Installation +------------ + +Load the plugin: + +.. code-block:: none + + /load iq_show + +""" from plugin import BasePlugin from sleekxmpp.xmlstream.matcher import StanzaPath from sleekxmpp.xmlstream.handler import Callback diff --git a/plugins/link.py b/plugins/link.py index 9e8b6f97..a51a8bef 100644 --- a/plugins/link.py +++ b/plugins/link.py @@ -1,6 +1,80 @@ -# A plugin that adds the /link command, letting you open links that are pasted -# in the conversation, without having to click them. +""" +Opens links in a browser. +Installation +------------ + +First use case: local use +~~~~~~~~~~~~~~~~~~~~~~~~~ +If you use poezio on your workstation, this is for you. +You only have to load the plugin: :: + + /load link + +Second use case: remote use +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you use poezio through SSH, this is for you. + +.. note:: Small explanation: Poezio will create a `Unix FIFO`_ and send the commands in, + and you will have to run a dæmon locally with ssh, to get those commands. + +First, set the :term:`exec_remote` option in the config file to ``true``. Then select +the directory you want to put the fifo in (default is the current +directory, :file:`./`), the :file:`poezio.fifo` file will be created there. + +After that, load the plugin: :: + + /load link + +And open a link with :term:`/link` (as described below), this will create the FIFO. + +You need to grab poezio’s sources on your client computer, or at least the `daemon.py`_ +file. + +Finally, on your client computer, run the ssh command: + +.. code-block:: bash + + ssh toto@example.org "cat ~/poezio/poezio.fifo" | python3 daemon.py + +Usage +----- + +.. glossary:: + + /link + **Usage:** ``/link [num]`` + + This plugin adds a :term:`/link` command that will open the links in ``firefox``. If + you want to use another browser, you can use the :term:`/set` command to change the + :term:`browser` option. + + + :term:`/link` without argument will open the last received link, if any is found. + If an integer argument is given, /link will go back gradually in the buffer + to open the previous link, and so on. + + + If you are scrolling in the buffer, poezio will open the links starting from + the first you can see. (although there are some problems with multiline + messages). + +Options +------- + +:term:`exec_remote` + + To execute the command on your client + +.. glossary:: + + browser + Set the default browser started by the plugin + +.. _Unix FIFO: https://en.wikipedia.org/wiki/Named_pipe +.. _daemon.py: http://gitweb.louiz.org/?p=poezio;a=blob_plain;f=src/daemon.py;hb=HEAD + +""" import re from plugin import BasePlugin diff --git a/plugins/mpd_client.py b/plugins/mpd_client.py index 09a2e5d2..5991422c 100644 --- a/plugins/mpd_client.py +++ b/plugins/mpd_client.py @@ -1,4 +1,53 @@ -# a plugin adding a command to manipulate an MPD instance +""" +This plugin is here to send what you are listening to in a chat tab. + + + +Installation +------------ + +You need `python-mpd`_, in its python3 version. + +Then you can load the plugin. + +.. code-block:: none + + /load mpd_client + + +Configuration +------------- + +You have to put the following into :file:`mpd_client.cfg`, as explained in +the :ref:`plugin-configuration` section. + +.. note:: If you do not put anything, the plugin will try to connect to + :file:`localhost:6600` with no password. + +.. code-block:: ini + + [mpd_client] + host = the_mpd_host + port = 6600 + password = password if necessary + + +Usage +----- + +.. glossary:: + + /mpd + **Usage:** ``/mpd [full]`` + + The bare command will show the current song, artist, and album + + ``/mpd full`` will show the current song, artist, and album, + plus a nice progress bar in color. + +.. _python-mpd: https://github.com/Mic92/python-mpd2 + +""" from plugin import BasePlugin from common import shell_split diff --git a/plugins/otr.py b/plugins/otr.py index 4e900b84..9014a4c6 100644 --- a/plugins/otr.py +++ b/plugins/otr.py @@ -1,3 +1,98 @@ +""" + +.. warning:: THE OTR LIB IS IN AN EXPERIMENTAL STATE AND SHOULD NOT BE + CONSIDERED AS ENTIRELY RELIABLE + +This plugin implements `Off The Record messaging`_. + +This is a plugin used to encrypt one-to-one conversation using the OTR +encryption method. You can use it if you want good privacy, deniability, +authentication, and strong secrecy. 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 removed and be replaced by +plain text messages. + +Installation and configuration +------------------------------ + +To use the OTR plugin, you must first install libopenotr. + +If you use Archlinux, there is a `libopenotr-git`_ package on the AUR. + +If not, then you will have to install it by hand. + +First, clone the repo and go inside the created directory: + +.. code-block:: bash + + git clone https://github.com/teisenbe/libopenotr.git + cd libopenotr + +Then run autogen.sh and configure + +.. code-block:: bash + + sh autogen.sh + ./configure --enable-gaping-security-hole + +(as of now, you *should* have been warned enough that the library is not finished) + +Then compile & install the lib: + +.. code-block:: bash + + make + sudo make install + +Finally, install the python module: + +.. code-block:: bash + + python3 setup.py build + sudo python3 setup.py install + +Usage +----- + +To use OTR, make sure the plugin is loaded (if not, then do ``/load otr``). + +Once you are in a private conversation, you have to do a: + + +.. code-block:: none + + /otr start + +The status of the OTR encryption should appear in the bar between the chat and +the input as ``OTR: encrypted``. + + +Once you’re done, end the OTR session with + +.. code-block:: none + + /otr end + +Known problems +-------------- + +Empty messages send when changing status. + +.. _Off The Record messaging: http://wiki.xmpp.org/web/OTR +.. _libopenotr-git: https://aur.archlinux.org/packages.php?ID=57957 + +""" + import pyotr from sleekxmpp.xmlstream.stanzabase import JID diff --git a/plugins/pacokick.py b/plugins/pacokick.py index 358df013..bd285db8 100644 --- a/plugins/pacokick.py +++ b/plugins/pacokick.py @@ -1,3 +1,25 @@ +""" +This plugin adds a :term:`/pacokick` command, which is a random kick. + +Installation +------------ +You only have to load the plugin. + +.. code-block:: none + + /load pacokick + +Usage +----- + +.. glossary:: + + /pacokick + + Run the command in a room where you are a moderator to + kick someone randomly. +""" + from random import choice from tabs import MucTab diff --git a/plugins/ping.py b/plugins/ping.py index faf3e97d..c4f56c81 100644 --- a/plugins/ping.py +++ b/plugins/ping.py @@ -1,3 +1,35 @@ +""" +This plugin allows you to ping an entity. + +Installation +------------ +You only have to load the plugin. + +.. code-block:: none + + /load ping + +Command +------- + +.. glossary:: + + /ping + **Usage (globally):** ``/ping `` + + **Usage (in a MUC tab):** ``/ping `` + + **Usage (in a conversation tab):** ``/ping [jid]`` + + Globally, you can do ``/ping jid@example.com`` to get a ping. + + In a MUC, you can either do it to a JID or a nick (``/ping nick`` or ``/ping + jid@example.com``). + + In a private or a direct conversation, you can do ``/ping`` to ping + the current interlocutor. +""" + from plugin import BasePlugin from roster import roster from common import safeJID diff --git a/plugins/quote.py b/plugins/quote.py index 9b1fd9ad..829f251e 100644 --- a/plugins/quote.py +++ b/plugins/quote.py @@ -1,3 +1,33 @@ +""" +This plugin allows you to quote messages easily. + +Installation +------------ +You only have to load the plugin. + +.. code-block:: none + + /load quote + +Usage +------- + +.. glossary:: + + /quote + **Usage:** ``/quote `` + + Timestamp is in ``HH:MM:SS`` format, and can be completed with [tab]. + + Example: + + .. code-block:: none + + /quote 21:12:23 + + If there is a message at 21:12:23, it will be put in the input. If there + isn’t, you will get a warning. +""" from plugin import BasePlugin from xhtml import clean_text import common diff --git a/plugins/rainbow.py b/plugins/rainbow.py index 4a188b33..0937eeb7 100644 --- a/plugins/rainbow.py +++ b/plugins/rainbow.py @@ -1,3 +1,26 @@ +""" +This plugin colors each character of a message with a random color. + +Installation +------------ + +You only have to load the plugin. + +.. code-block:: none + + /load rainbow + +Usage +----- + +.. glossary:: + + /rainbow + + Say something in a Chat tab. + +.. note:: Can create fun things when used with :ref:`The figlet plugin `. +""" from plugin import BasePlugin import xhtml import random diff --git a/plugins/reminder.py b/plugins/reminder.py index 16a3f710..eb2f9801 100644 --- a/plugins/reminder.py +++ b/plugins/reminder.py @@ -1,3 +1,60 @@ +""" +Installation +------------ +You only have to load the plugin: + +.. code-block:: none + + /load reminder + +Usage +----- + +This plugin defines three new global commands: :term:`/remind`, +:term:`/done`, and :term:`/tasks`. + +.. glossary:: + + /remind + **Usage:** ``/remind