poezio/doc/source/plugins/index.rst

Plugins
=======

Starting from the 0.7.5 version, poezio supports plugins.
Here is a quick howto and a plugin index.


Setting up plugins
------------------

Poezio seeks the plugins in the :file:`~/.local/share/poezio/plugins/` dir (more
generally, the :file:`$XDG_DATA_HOME/poezio/plugins/` dir), but that can be changed
by setting the :term:`plugins_dir` option to the directory where you want to
put your plugins.

This means that if you want to use a plugin, you have to copy it (the .py file or the directory) into :term:`plugins_dir`.


Plugin autoload
---------------

Use the :term:`plugins_autoload` optionto select which plugins should be
loaded on startup. The value is a list of plugin names separated by colons,
e.g.

.. code-block:: ini

    plugins_autoload = gpg:tell:exec

.. _plugin-configuration:

Plugin configuration
--------------------

Most plugins will manage their configuration internally, and you do not (and
should not) have to edit it, but some (e.g. mpd_client or gpg) require manual
editing (the :term:`/set` command can be used, but it is not pleasant to set
multiple values with it).

The plugin configuration directory is located in :file:`~/.config/poezio/plugins/`
(or :file:`$XDG_CONFIG_HOME/poezio/plugins/`) and the file related to a specific
plugin is named :file:`plugin_name.cfg`. The configuration options should usually be
inside a section named after the plugin (sections are delimited with ``[]``).

.. code-block:: ini

    [plugin_name]
    key = value
    other_key = other_value

Plugin index
------------

.. glossary::
    :sorted:

    Admin
        :ref:`Documentation <admin-plugin>`

        Creates convenient aliases for MUC administration.

    Alias
        :ref:`Documentation <alias-plugin>`

        Allows you to create your own aliases.

    Amsg
        :ref:`Documentation <amsg-plugin>`

        Allows a message to be broadcasted on all the rooms your are in.
        Caution: do not overuse.

    Day Change
        :ref:`Documentation <daychange-plugin>`

        Logs the day change inside the buffers, to keep track of the days when
        backlogging.

    Display corrections
        :ref:`Documentation <displaycorrections-plugin>`

        Lists old versions of a corrected message.

    Exec
        :ref:`Documentation <exec-plugin>`

        Runs a system command an optionally sends the output as a message.

    Figlet
        :ref:`Documentation <figlet-plugin>`

        Ascii-art writing (requires the ``figlet`` package on your system).

    GPG
        :ref:`Documentation <gpg-plugin>`

        Allows encrypted exchanges and presence signing using GnuPG.

    IQ Show
        :ref:`Documentation <iqshow-plugin>`

        Shows the received IQs, for debugging purposes.

    Link
        :ref:`Documentation <link-plugin>`

        Opens links in a web browser, locally or remotely using a FIFO and SSH.

    MPD Client
        :ref:`Documentation <mpdclient-plugin>`

        Sends the current song (and optionally the progress inside the song) to
        the current (chat) tab.

    OTR
        :ref:`Documentation <otr-plugin>`

        Allows encrypted and deniable exchanges using OTR.

    PacoKick
        :ref:`Documentation <pacokick-plugin>`

        Kicks a random user in the room.

    Ping
        :ref:`Documentation <ping-plugin>`

        Sends a ping probe to an entity (XEP-0199)

    Quote
        :ref:`Documentation <quote-plugin>`

        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 <rainbow-plugin>`

        Sends your messages in rainbow colors using XHTML-IM.

    Reminder
        :ref:`Documentation <reminder-plugin>`

        Reminds you to do something every now and then.

    Screen Detach
        :ref:`Documentation <screendetach-plugin>`

        Changes your status to _away_ if the screen poezio is in is detached.

    Simple notify
        :ref:`Documentation <simplenotify-plugin>`

        Sends a notification with a command of your choice on (non-MUC) messages.

    Spam
        :ref:`Documentation <spam-plugin>`

        Adds a subtle little advertising in your messages.

    Status
        :ref:`Documentation <status-plugin>`

        Adds convenient aliases to /status (/away, etc).

    Tell
        :ref:`Documentation <tell-plugin>`

        Tells a message to a nick when he connects to a MUC.

    Uptime
        :ref:`Documentation <uptime-plugin>`

        Gets the uptime of a XMPP server or a component.

    Replace
        :ref:`Documentation <replace-plugin>`

        Replace some patterns in your messages.

    Time Marker
        :ref:`Documentation <timemarker-plugin>`

        Display the time between two messages.

    Revstr
        :ref:`Documentation <revstr-plugin>`

        Reverse everything you say.

    Shuffle
        :ref:`Documentation <shuffle-plugin>`

        Shuffle everything you say.

    Double
        :ref:`Documentation <double-plugin>`

        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
    spam
    status
    tell
    time_marker
    uptime
    revstr
    double
    shuffle
    iq_show