poezio/doc/en/plugins/index.txt

Poezio 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 _~/.local/share/poezio/plugins/_ dir (more
generally, the _$XDG_DATA_HOME/poezio/plugins/_ dir), but that can be changed
by setting the _plugins_dir_ option in the
link:../configure.html[configuration file] 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 _plugins_dir_.


Plugins autostart
-----------------
Use the _plugins_autoload_ option (from the
link:../configure.html[configuration file]) to select which plugins should be
loaded on startup. The value is a list of plugin names separated by spaces,
e.g.

.plugins_autoload example
---------
plugins_autoload = "gpg tell exec"
---------

Plugins 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 _/set_ command can be used, but it is not pleasant to set
multiple values with it).

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

.section example
--------------
[plugin_name]
key = value
other_key = other_value
--------------


Plugins index
-------------

[horizontal]
*Admin*:: link:admin.html[Room administration plugin]

    Creates convenient aliases for MUC administration.

*Alias*:: link:alias.html[Custom aliases plugin]

    Allows you to create your own aliases.

*Amsg*:: link:amsg.html[Message broadcast plugin]

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

*Day Change*:: link:day_change.html[Day change plugin]

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

*Exec*:: link:exec.html[System command plugin]

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

*Figlet*:: link:figlet.html[Figlet plugin]

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

*GPG*:: link:gpg.html[GnuPG plugin]

    Allows encrypted exchanges and presence signing using GnuPG.

*IQ Show*:: IQ showing plugin

    Shows the received IQs, for debugging purposes.

*Link*:: link:link.html[Link opener plugin]

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

*MPD Client*:: link:mpd_client.html[MPD client plugin]

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

*OTR*:: link:otr.html[Off-The-Record plugin]

    Allows encrypted and deniable exchanges using OTR.

*PacoKick*:: link:pacokick.html[Random kick plugin]

    Kicks a random user in the room.

*Ping*:: link:ping.html[XMPP Ping plugin]

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

*Quote*:: link:quote.html[Quoting 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*:: link:rainbow.html[Rainbow plugin]

    Sends your messages in rainbow colors using XHTML-IM.

*Reminder*:: link:reminder.html[Reminder plugin]

    Reminds you to do something every now and then.

*Screen Detach*:: link:screen_detach.html[Screen status plugin]

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

*Simple notify*:: link:simple_notify.html[Simple notification plugin]

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

*Status*:: link:status.html[Status aliases plugin]

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

*Tell*:: link:tell.html[Automated delayed messages plugin]

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

*Uptime*:: link:uptime.html[Uptime plugin]

    Gets the uptime of a XMPP server or a component.

*Replace*:: link:replace.html[Replace plugin]

    Replace some patterns in your messages.

*Time Marker*:: link:time_marker.html[Time marker plugin]

    Display the time between two messages.