diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/commands.rst | 107 | ||||
| -rw-r--r-- | doc/source/conf.py | 16 | ||||
| -rw-r--r-- | doc/source/configuration.rst | 166 | ||||
| -rw-r--r-- | doc/source/dev/contributing.rst | 10 | ||||
| -rw-r--r-- | doc/source/dev/e2ee.rst | 52 | ||||
| -rw-r--r-- | doc/source/dev/events.rst | 2 | ||||
| -rw-r--r-- | doc/source/dev/index.rst | 1 | ||||
| -rw-r--r-- | doc/source/dev/overview.rst | 6 | ||||
| -rw-r--r-- | doc/source/dev/plugin.rst | 31 | ||||
| -rw-r--r-- | doc/source/dev/slix.rst | 4 | ||||
| -rw-r--r-- | doc/source/dev/xep.rst | 2 | ||||
| -rw-r--r-- | doc/source/install.rst | 39 | ||||
| -rw-r--r-- | doc/source/keys.rst | 13 | ||||
| -rw-r--r-- | doc/source/misc/client_certs.rst | 2 | ||||
| -rw-r--r-- | doc/source/misc/separate.rst | 2 | ||||
| -rw-r--r-- | doc/source/plugins/index.rst | 20 | ||||
| -rw-r--r-- | doc/source/plugins/sticker.rst | 6 | ||||
| -rw-r--r-- | doc/source/plugins/user_extras.rst | 6 | ||||
| -rw-r--r-- | doc/source/themes.rst | 12 | ||||
| -rw-r--r-- | doc/source/usage.rst | 26 |
20 files changed, 328 insertions, 195 deletions
diff --git a/doc/source/commands.rst b/doc/source/commands.rst index f28f992f..d1763084 100644 --- a/doc/source/commands.rst +++ b/doc/source/commands.rst @@ -14,7 +14,7 @@ You can get the same help as below from inside poezio with the :term:`/help` com .. note:: Use command parameters like this: - Do not use quotes if they are unnecessary (words without special chars or spaces) - - If the command takes several agrguments, you need to put quotes around arguments containing special chars such as backslashes or quotes + - If the command takes several arguments, you need to put quotes around arguments containing special chars such as backslashes or quotes - If the command always takes only one argument, then do not use quotes even for words containing special chars .. _global-commands: @@ -34,6 +34,12 @@ These commands work in *any* tab. available commands. If it has a valid command as an argument, this command will show the usage and the help for the given command. + /debug + **Usage:** ``/debug [filename] + + Reset logging and enable debugging to ``[filename]``. If the filename + is empty, debug logging will be disabled. + /join **Usage:** ``/join [room_name][@server][/nick] [password]`` @@ -56,7 +62,7 @@ These commands work in *any* tab. - ``/join / password`` /destroy_room - **Usage:** ``/destroy_room [room JID]`` + **Usage:** ``/destroy_room [room JID [reason [alternative venue]]]`` Try to destroy the room given as a parameter, or the current room is not parameter is given and the current tab is a chatroom. @@ -93,11 +99,20 @@ These commands work in *any* tab. Go to the matching tab. If the argument is a number, it goes to the tab with that number. Otherwise, it goes to the next tab whose name contains the given string. + /wup + + **Usage:** ``/wup <prefix>`` + + Go to the tab whose name starts with `prefix`. If multiple tabs start + with that prefix, no action is taken. + + (Mnemonic: Window by Unique Prefix) + /status **Usage:** ``/status <availability> [status message]`` Set your availability and - (optionaly) your status message. The <availability> argument is one of + (optionally) your status message. The <availability> argument is one of "available, chat, away, afk, dnd, busy, xa" and the optional [status] argument will be your status message.' @@ -209,6 +224,11 @@ These commands work in *any* tab. Get the software version of the given JID (usually its XMPP client and Operating System). + /ad-hoc + **Usage:** ``/ad-hoc <jid>`` + + List available ad-hoc commands on the given jid. + /invite **Usage:** ``/invite <jid> <room> [reason]`` @@ -218,27 +238,12 @@ These commands work in *any* tab. /invitations Show the pending invitations. - /activity - **Usage:** ``/activity [<general> [specific] [comment]]`` - - Send your current activity to your contacts (use the completion to cycle - through all the general and specific possible activities). - - Nothing means "stop broadcasting an activity". - - /mood - **Usage:** ``/mood [<mood> [comment]]`` - Send your current mood to your contacts (use the completion to cycle - through all the possible moods). - - Nothing means "stop broadcasting a mood". + /impromptu + **Usage:** ``/impromptu <jid> [jid ..]`` - /gaming - **Usage:** ``/gaming [<game name> [server address]]`` + Invite specified JIDs into a newly created room. - Send your current gaming activity to your contacts. - - Nothing means "stop broadcasting a gaming activity". + .. versionadded:: 0.13 /last_activity **Usage:** ``/activity <jid>`` @@ -309,6 +314,12 @@ These commands will work in any conversation tab (MultiUserChat, Private, or /clear Clear the current buffer. + /scrollback + /sb + **Usage:** ``/scrollback end home clear status goto <+|-linecount>|<linenum>|<timestamp>`` + + Allows to go to the given line or message in the window. + .. _muctab-commands: MultiUserChat tab commands @@ -318,11 +329,12 @@ MultiUserChat tab commands :sorted: /affiliation - **Usage:** ``/affiliation <nick> <affiliation>`` + **Usage:** ``/affiliation [<nick or jid> <affiliation>]`` - Sets the affiliation of the participant designated by **nick** to the - given **affiliation** (can be one of owner, admin, member, outcast - and none). + Sets the affiliation of the participant designated by **nick** or + **jid** to the given **affiliation** (can be one of owner, admin, + member, outcast and none). If not argument is provided, lists + room affiliations. /role **Usage:** ``/affiliation <nick> <role>`` @@ -337,8 +349,7 @@ MultiUserChat tab commands are considered identical if they only differ by the presence of one ore more **_** character at the beginning or the end. For example _Foo and Foo___ are considered aliases of the nick Foo) will then - always have the specified color, in all MultiUserChat tabs. This is - true whatever the value of **deterministic_nick_colors** is. + always have the specified color, in all MultiUserChat tabs. Use the completion to get a list of all the available color values. Use the special color **unset** to remove the attributed color on @@ -380,7 +391,7 @@ MultiUserChat tab commands Using the auto-completion of this command writes the current topic in the input, to help the user make a small change to the topic - whithout having to rewrite it all by hand. + without having to rewrite it all by hand. If no subject is specified as an argument, the current topic is displayed, unchanged. @@ -398,30 +409,46 @@ MultiUserChat tab commands Disconnect you from a room. You can specify an optional message. + This is similar to :term:`/leave`, but keeps the tab open and doesn’t + remove the bookmark, so restarting poezio or another client will reopen + this room. + + /leave + **Usage:** ``/leave [message]`` + + Disconnect you from a room, on all of your clients. You can specify an + optional message. + + This is similar to :term:`/part`, but closes the tab and removes its + bookmark, to make sure we don’t come back to this room the next time we + open poezio or another client. + + This is similar to :term:`/close`, but also removes the bookmark to + make sure we don’t come back to this room the next time we open poezio + or another client. + /nick **Usage:** ``/nick <nickname>`` Change your nickname in the current room. /recolor - **Usage:** ``/recolor [random]`` + **Usage:** ``/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. If a random argument is - given, the participants will be shuffled before they are assigned a color. + Re-assign a color to all the participants in the current room, + if the theme has changed. /cycle **Usage:** ``/cycle [message]`` - Leave the current room an rejoint it immediatly. You can + Leave the current room an rejoint it immediately. You can specify an optional quit message. /info **Usage:** ``/info <nickname>`` Display some information about the user in the room: - his/her role, affiliation, status, and status message. + their role, affiliation, status, and status message. /version **Usage:** ``/version <nickname or jid>`` @@ -472,6 +499,14 @@ Normal Conversation tab commands Get the software version of the current interlocutor (usually its XMPP client and Operating System). + /invite + **Usage:** ``/invite <jid> [jid ..]`` + + Invite specified JIDs, with this contact, into a newly + created room. + + .. versionadded:: 0.13 + .. _rostertab-commands: Contact list tab commands diff --git a/doc/source/conf.py b/doc/source/conf.py index 0396e88f..74547057 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -46,16 +46,16 @@ master_doc = 'index' # General information about the project. project = 'Poezio' -copyright = '%s, Mathieu Pasquet - Florent Le Coz - Emmanuel Gil Peyrot' % time.strftime('%Y') +copyright = '%s, Mathieu Pasquet - Florent Le Coz - Emmanuel Gil Peyrot - Maxime Buquet' % time.strftime('%Y') # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '0.13' +version = '0.14' # The full version, including alpha/beta/rc tags. -release = '0.13-dev' +release = '0.14' add_function_parentheses = True @@ -195,7 +195,7 @@ latex_elements = { # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'PoezioDoc.tex', 'Poezio Documentation', - 'Mathieu Pasquet - Florent Le Coz - Emmanuel Gil Peyrot', 'manual'), + 'Mathieu Pasquet - Florent Le Coz - Emmanuel Gil Peyrot - Maxime Buquet', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -225,11 +225,11 @@ latex_documents = [ # (source start file, name, description, authors, manual section). man_pages = [ ('configuration', 'poezio.cfg', 'Poezio Configuration File', - ['Mathieu Pasquet', 'Florent Le Coz', 'Emmanuel Gil Peyrot'], 7), + ['Mathieu Pasquet', 'Florent Le Coz', 'Emmanuel Gil Peyrot', 'Maxime Buquet'], 7), ('keys', 'poezio.keys', 'Poezio Key Bindings', - ['Mathieu Pasquet', 'Florent Le Coz', 'Emmanuel Gil Peyrot'], 7), + ['Mathieu Pasquet', 'Florent Le Coz', 'Emmanuel Gil Peyrot', 'Maxime Buquet'], 7), ('commands', 'poezio.commands', 'Poezio Commands', - ['Mathieu Pasquet', 'Florent Le Coz', 'Emmanuel Gil Peyrot'], 7), + ['Mathieu Pasquet', 'Florent Le Coz', 'Emmanuel Gil Peyrot', 'Maxime Buquet'], 7), ] # If true, show URL addresses after external links. @@ -243,7 +243,7 @@ man_pages = [ # dir menu entry, description, category) texinfo_documents = [ ('index', 'PoezioDoc', 'Poezio Documentation', - 'Mathieu Pasquet - Florent Le Coz - Emmanuel Gil Peyrot', 'PoezioDoc', 'Poezio Documentation', + 'Mathieu Pasquet - Florent Le Coz - Emmanuel Gil Peyrot - Maxime Buquet', 'PoezioDoc', 'Poezio Documentation', 'Miscellaneous'), ] diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index 6baa6a27..c28f38fa 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -10,8 +10,8 @@ or use the :term:`/set` command to edit some of its values directly from poezio. This file is also used to configure key bindings, but this is explained in the :ref:`keys-page` documentation file. -That file is read at each startup and the configuration is saved when poezio -is closed. +The configuration is read at each startup or when the `/reload` command is +issued, and it is updated after every `/set` command. This configuration file **requires** all global options to be in a section named [Poezio]. Some other options can be in optional sections and will @@ -133,6 +133,15 @@ Options related to account configuration, nickname… This option can be combined with :term:`custom_host`. You should not need this in a "normal" use case. + default_muc_service + + **Default value:** ``[empty]`` + + If specified, will be used instead of the MUC service provided by + the user domain. + + .. versionadded:: 0.13 + default_nick **Default value:** ``[empty]`` @@ -145,7 +154,7 @@ Options related to account configuration, nickname… **Default value:** ``anon.jeproteste.info`` The server to use for anonymous authentication; - make sure it supports anonymous authentification. + make sure it supports anonymous authentication. Note that this option doesn’t do anything at all if you’re using your own JID. @@ -315,37 +324,12 @@ to understand what is :ref:`carbons <carbons-details>` or as mobile networks). It can however increase bandwidth usage. It also requires server support. - enable_user_activity - - **Default value:** ``true`` - - Set this to ``false`` if you don’t want to receive the activity of your contacts. - - enable_user_gaming - - **Default value:** ``true`` - - Set this to ``false`` if you don’t want to receive the gaming activity of your contacts. - - enable_user_mood - - **Default value:** ``true`` - - Set this to ``false`` if you don’t want to receive the mood of your contacts. - enable_user_nick **Default value:** ``true`` Set to ``false`` if you don’t want your contacts to hint you their identity. - enable_user_tune - - **Default value:** ``true`` - - If this is set to ``false``, you will no longer be subscribed to tune events, - and the :term:`display_tune_notifications` option will be ignored. - go_to_previous_tab_on_alt_number **Default value:** ``false`` @@ -362,19 +346,18 @@ to understand what is :ref:`carbons <carbons-details>` or sender intended it as such. See :ref:`Message Correction <correct-feature>` for more information. - bookmark_on_join + synchronise_open_rooms - **Default value:** ``false`` + **Default value:** ``true`` - If ``true``, poezio will bookmark automatically every room that is joined with - a manual ``/join`` command. + If ``false``, poezio will not store the state of currently open rooms, + so that if you leave a room and restart poezio (or start another + client) it will reopen it. - force_remote_bookmarks + If ``true``, ``/join`` will create a bookmark with ``autojoin=true``, + and ``/leave`` will remove said bookmark. - **Default value:** ``false`` - - Try to retrieve your remote bookmarks, even when your server doesn’t advertise - support. + This was previously named ``bookmark_on_join``. use_bookmark_method @@ -398,40 +381,12 @@ to understand what is :ref:`carbons <carbons-details>` or Use this option to force the use of local bookmarks if needed. Anything but "false" will be counted as true. - display_gaming_notifications - - **Default value:** ``false`` - - If set to true, notifications about the games your are playing - will be displayed in the info buffer as 'Gaming' messages. - - display_tune_notifications - - **Default value:** ``false`` - - If set to true, notifications about the music your contacts listen to - will be displayed in the info buffer as 'Tune' messages. - - display_mood_notifications - - **Default value:** ``false`` - - If set to true, notifications about the mood of your contacts - will be displayed in the info buffer as 'Mood' messages. - - display_activity_notifications - - **Default value:** ``false`` - - If set to true, notifications about the current activity of your contacts - will be displayed in the info buffer as 'Activity' messages. - enable_xhtml_im **Default value:** ``true`` XHTML-IM is an XMPP extension letting users send messages containing - XHTML and CSS formating. We can use this to make colored text for example. + XHTML and CSS formatting. We can use this to make colored text for example. Set to ``true`` if you want to see colored (and otherwise formatted) messages. enable_css_parsing @@ -557,23 +512,14 @@ or the way messages are displayed. bottom in the list, if set to ``asc``, they will be displayed from bottom to top. - deterministic_nick_colors - - **Default value:** ``true`` - - Use a deterministic algorithm to choose the user colors in chatrooms if - set to ``true``. Otherwise the colors will be picked randomly. - - The value of this option affects the behavior of :term:`/recolor`. - nick_color_aliases **Default value:** ``true`` - Automatically search for color of nick aliases. For example, if nick is - set to red, _nick, nick\_, _nick_, nick\__ etc. will have the same color. - Aliases colors are checked first, so that it is still possible to have - different colors for nick\_ and nick. + Automatically search for color of nick aliases. For example, if nick is + set to red, _nick, nick\_, _nick_, nick\__ etc. will have the same color. + Aliases colors are checked first, so that it is still possible to have + different colors for nick\_ and nick. vertical_tab_list_size @@ -593,7 +539,7 @@ or the way messages are displayed. **Default value:** ``[empty]`` A list of words or sentences separated by colons (":"). All the - informational mesages (described above) containing at least one of those + informational messages (described above) containing at least one of those values will not be shown. hide_exit_join @@ -647,7 +593,7 @@ or the way messages are displayed. Some informational messages (error, a contact getting connected, etc) are sometimes added to the information buffer. These settings can make - that buffer grow temporarly so you can read these information when they + that buffer grow temporarily so you can read these information when they appear. A list of message types that should make the information buffer grow @@ -671,6 +617,14 @@ or the way messages are displayed. If set to true, the color of the nick will be used in chatroom information messages, instead of the default color from the theme. + autocolor_tab_names + + **Default value:** ``false`` + + If ``true``, uses deterministic coloration for tab names or tab + numbers in the activity bar, using Consistent Color Generation + (XEP-0392). + enable_vertical_tab_list **Default value:** ``true`` @@ -769,7 +723,7 @@ or the way messages are displayed. show_roster_subscriptions - **Defalt value:** ``[empty]`` + **Default value:** ``[empty]`` Select the level of display of subscriptions with a char in the contact list. @@ -784,6 +738,17 @@ or the way messages are displayed. If you want to show the tab name in the bottom Tab bar, set this to ``true``. + unique_prefix_tab_names + + **Default value:** ``false`` + + If this and :term:`show_tab_names` is set to true, only the shortest + unique prefix of each tab name is shown instead of the full name. This + can declutter the interface in an instance with many tabs shown in the + interface, while not having to use numbers (which may change completely due to reordering). + + Takes precedence over `use_tab_nicks`. + show_tab_numbers **Default value:** ``true`` @@ -883,14 +848,6 @@ Options related to logging. .. glossary:: :sorted: - load_log - - **Default value:** ``10`` - - The number of line to preload in a chat buffer when it opens. The lines are - loaded from the log files. - ``0`` or a negative value here disable that option. - log_dir **Default value:** ``[empty]`` @@ -903,7 +860,7 @@ Options related to logging. **Default value:** ``true`` - Logs all the tracebacks and erors of poezio/slixmpp in + Logs all the tracebacks and errors of poezio/slixmpp in :term:`log_dir`/errors.log by default. ``false`` disables this option. use_log @@ -912,6 +869,21 @@ Options related to logging. Set to ``false`` if you don’t want to write any message to the disk. + mam_sync + + **Default value:** ``true`` + + If ``true``, will try to fill local logs with missing MAM history + when opening a tab or joining a room. + + mam_sync_limit + + **Default value:** ``2000`` + + Maximum number of messages to fetch on a MAM sync. Will affect + performance when joining rooms with a huge backlog for the first time + or after a long period. + Plugins ~~~~~~~ @@ -1115,7 +1087,7 @@ found. display_user_color_in_join_part - **Default value:** ``false`` + **Default value:** ``true`` If set to ``true``, the color of the nick will be used in chatroom information messages, instead of the default color from the theme. @@ -1168,16 +1140,6 @@ found. Ignore private messages sent from this room. - load_log - - **Default value:** ``10`` - - The number of line to preload in a chat buffer when it opens. The lines are - loaded from the log files. - ``0`` or a negative value here disable that option. - - No value makes poezio fall back to the global value. - password **Default value:** ``[empty]`` diff --git a/doc/source/dev/contributing.rst b/doc/source/dev/contributing.rst index ca7de049..4c2d8161 100644 --- a/doc/source/dev/contributing.rst +++ b/doc/source/dev/contributing.rst @@ -5,7 +5,7 @@ Conventions ----------- We don’t have a strict set of conventions, but you should respect PEP8 mostly -(e.g. 4 spaces, class names in CamelCase and methods lowercased with +(e.g. 4 spaces, class names in CamelCase and methods lowercase with underscores) except if it means less-readable code (80 chars is often a hassle, and if you look inside poezio you’ll see lots of long lines, mostly because of strings). @@ -18,7 +18,7 @@ for the application as a whole. Commit guidelines ----------------- -Commits **should** have a meaninful title (first line), and *may* have a detailed +Commits **should** have a meaningful title (first line), and *may* have a detailed description below. There are of course exceptions (for example, a single-line commit that takes care of a typo right behind a big commit does not need to say ``fix a typo ("azre" → "are") in toto.py line 45454``, since the metainfos @@ -38,8 +38,8 @@ useless merges (and polluting the commit history) when none is needed. .. code-block:: bash git fetch origin - git rebase origin/master - git push origin master + git rebase origin/main + git push origin main If your commit is related to an issue on our tracker_ (or fixes such an issue), you can use ``Fix #BUGID`` or ``References #BUGID`` to help with the @@ -64,4 +64,4 @@ account and submit it again. If you have already submitted some code and plan to do more, you can ask us direct commit access on the main repo. -.. _tracker: https://dev.louiz.org/project/poezio/bugs +.. _tracker: https://lab.louiz.org/poezio/poezio/-/issues diff --git a/doc/source/dev/e2ee.rst b/doc/source/dev/e2ee.rst new file mode 100644 index 00000000..23304512 --- /dev/null +++ b/doc/source/dev/e2ee.rst @@ -0,0 +1,52 @@ +End-to-end Encryption API documentation +======================================= + +E2EEPlugin +---------- + +.. module:: poezio.plugin_e2ee + + +.. autoclass:: E2EEPlugin + :members: decrypt, encrypt, encryption_name, encryption_short_name, eme_ns, replace_body_with_eme, stanza_encryption, tag_whitelist + + +Please refer to :py:class:`~BasePlugin` for more information on how to +write plugins. + +Example plugins +--------------- + +**Example 1:** Base64 plugin + +.. code-block:: python + + from base64 import b64decode, b64encode + from poezio.plugin_e2ee import E2EEPlugin + from slixmpp import Message + + + class Plugin(E2EEPlugin): + """Base64 Plugin""" + + encryption_name = 'base64' + encryption_short_name = 'b64' + eme_ns = 'urn:xmpps:base64:0' + + # This encryption mechanism is using <body/> as a container + replace_body_with_eme = False + + def decrypt(self, message: Message, _tab) -> None: + """ + Decrypt base64 + """ + body = message['body'] + message['body'] = b64decode(body.encode()).decode() + + def encrypt(self, message: Message, _tab) -> None: + """ + Encrypt to base64 + """ + # TODO: Stop using <body/> for this. Put the encoded payload in another element. + body = message['body'] + message['body'] = b64encode(body.encode()).decode() diff --git a/doc/source/dev/events.rst b/doc/source/dev/events.rst index a2e6ad9d..6dd2e65e 100644 --- a/doc/source/dev/events.rst +++ b/doc/source/dev/events.rst @@ -121,7 +121,7 @@ The following events are poezio-only events, for Slixmpp events, check out changing_nick - **presence:** :py:class:`~~slixmpp.Presence` to be sent - Triggered when the user changes his/her nickname on a MUC. The + Triggered when the user changes their nickname on a MUC. The presence can thus be modified before being sent. send_normal_presence diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst index 21ea6253..630abfad 100644 --- a/doc/source/dev/index.rst +++ b/doc/source/dev/index.rst @@ -14,6 +14,7 @@ About plugins :maxdepth: 2 plugin + e2ee events slix xep diff --git a/doc/source/dev/overview.rst b/doc/source/dev/overview.rst index fcf5ff22..96d4435b 100644 --- a/doc/source/dev/overview.rst +++ b/doc/source/dev/overview.rst @@ -40,7 +40,7 @@ method (inherited empty from the Tab class), call a scrolling method from the appropriate **window**. All tabs types inherit from the class **Tab**, and the tabs featuring -chat functionnality will inherit from **ChatTab** (which inherits from **Tab**). +chat functionality will inherit from **ChatTab** (which inherits from **Tab**). Examples of **tabs**: MUCTab, XMLTab, RosterTab, MUCListTab, etc… @@ -80,9 +80,9 @@ or /command "arg1 with spaces" arg2 -However, when creating a command, you wil deal with _one_ str, no matter what. +However, when creating a command, you will deal with _one_ str, no matter what. There are utilities to deal with it (common.shell_split), but it is not always -necessary. Commands are registered in the **commands** dictionnary of a tab +necessary. Commands are registered in the **commands** dictionary of a tab structured as key (command name) -> tuple(command function, help string, completion). Completions are a bit tricky, but it’s easy once you get used to it: diff --git a/doc/source/dev/plugin.rst b/doc/source/dev/plugin.rst index 7a63ed8f..4614c761 100644 --- a/doc/source/dev/plugin.rst +++ b/doc/source/dev/plugin.rst @@ -1,13 +1,32 @@ Plugin API documentation ======================== +External plugins +---------------- + +It is possible to create external plugins easily using `setuptools' +entry_point +<https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins>`_ +feature. You can register your plugin against the ``poezio_plugins`` entry +group with the following snippet in your project ``setup.py``: + +.. code-block:: python + + setup( + .. + packages=['yourmodule'], + entry_points={'poezio_plugins': 'yourplugin = yourmodule'}, + .. + ) + +The plugin will then be available as ``yourplugin`` at runtime. + BasePlugin ---------- .. module:: poezio.plugin .. autoclass:: BasePlugin - :members: init, cleanup, api, core .. method:: init(self) @@ -29,6 +48,16 @@ BasePlugin The :py:class:`~PluginAPI` instance for this plugin. + .. attribute:: dependencies + + Dependencies on other plugins, as a set of strings. A reference + to each dependency will be added in ``refs``. + + .. attribute:: refs + + This attribute is not to be edited by the user. It will be + populated when the plugin is initialized with references on each + plugin specified in the ``dependencies`` attribute. Each plugin inheriting :py:class:`~BasePlugin` has an ``api`` member variable, which refers to a :py:class:`~PluginAPI` object. diff --git a/doc/source/dev/slix.rst b/doc/source/dev/slix.rst index 3c06e349..50f9dd07 100644 --- a/doc/source/dev/slix.rst +++ b/doc/source/dev/slix.rst @@ -1,5 +1,5 @@ -SleekXMPP classes -================= +Slixmpp classes +=============== .. module:: slixmpp diff --git a/doc/source/dev/xep.rst b/doc/source/dev/xep.rst index 339553ff..7feca4cf 100644 --- a/doc/source/dev/xep.rst +++ b/doc/source/dev/xep.rst @@ -91,7 +91,7 @@ Table of all XEPs implemented in poezio. +----------+-------------------------+---------------------+ |0270 |Compliance Suites 2010 |Advanced Client | +----------+-------------------------+---------------------+ -|0280 |Messsage Carbons |100% | +|0280 |Message Carbons |100% | +----------+-------------------------+---------------------+ |0296 |Best Practices for |0% | | |Resource Locking | | diff --git a/doc/source/install.rst b/doc/source/install.rst index 3146958c..31dc332d 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -3,7 +3,7 @@ Installing poezio ================= -.. warning:: Python 3.5 or above is **required**. +.. warning:: Python 3.7 or above is **required**. To install it on a distribution that doesn't provide it, see :ref:`pyenv <pyenv-install>`. poezio in the GNU/Linux distributions @@ -15,16 +15,18 @@ using one of these. - **Archlinux**: poezio_ and poezio-git_ packages are in the AUR (use your favourite AUR wrapper to install them) -- **Gentoo**: It’s uncertain, but the bgo-overlay_ appears to contain poezio - and slixmpp packages. -- **Fedora**: The stable poezio package was out of date for a long time in - Fedora, but now thanks to Casper, there is an `up-to-date package`_ in - the repos since F19. +- **Gentoo**: `net-im/poezio`_ +- **Fedora**: There is an `up-to-date package`_ in the repos since F19. +- **CentOS**: Poezio is available in EPEL repositories since CentOS 8. +- **Flatpak**: A stable package is provided on flathub_. - **Debian**: A stable package is provided since buster_ thanks to debacle. - **Nix** (and **NixOS**): The last stable version of poezio is availalble in the unstable branch of `nixpkgs`. Use ``nix-env -f "<nixpkgs>" -iA poezio`` to install poezio for the current user. - **OpenBSD**: a poezio port_ is available +- **Guix**: Poezio can be obtained with Guix on any GNU/Linux distribution. + To install poezio in default user-profile: ``guix install poezio``. + To try poezio without installation: ``guix environment --pure --ad-hoc poezio``. (If another distribution provides a poezio package, please tell us and we will add it to the list) @@ -54,14 +56,14 @@ support. Therefore, you might want to use the git version. .. code-block:: bash - git clone git://git.poez.io/poezio + git clone https://lab.louiz.org/poezio/poezio cd poezio """"""" General """"""" -Poezio is a python3.5 (and above)-only application, so you will first need that. +Poezio is a python3.7 (and above)-only application, so you will first need that. Packages required for building poezio and deps: @@ -70,6 +72,18 @@ Packages required for building poezio and deps: - libidn and libidn-dev, only if you want to use cython_ (see below) - python3-devel (or equivalent) - python3-setuptools +- python3-pip +- python3-venv +- libffi-dev (for pycares, needed by slixmpp) +- pyasn1 and pyasn1-modules (needed by slixmpp) + +On Debian, you can install the dependencies as follows: + +.. code-block:: bash + + apt install python3-dev make gcc python3-setuptools python3-pip python3-venv libffi-dev + pip3 install --user pyasn1 pyasn1-modules + Then you can run ``make`` to build it the poezio C extension module. If you downloaded the standalone stable package, you are finished here and can skip @@ -102,7 +116,7 @@ Poezio depends on slixmpp, a non-threaded fork of the SleekXMPP library. .. code-block:: bash - git clone git://git.poez.io/slixmpp + git clone https://lab.louiz.org/poezio/slixmpp python3 setup.py install --user @@ -115,7 +129,7 @@ The aiodns library is required in order to properly resolve XMPP domains (with S .. code-block:: bash - pip install --user aiodns + pip3 install --user aiodns This will also install pycares, which aiodns uses. @@ -230,8 +244,7 @@ that should be created beforehand: If you don’t trust images distributed on the docker hub, you can rebuild the image from the Dockerfile at the root of the git repository. -.. _stable sources: https://dev.louiz.org/project/poezio/download -.. _slixmpp: https://dev.louiz.org/projects/slixmpp +.. _slixmpp: https://lab.louiz.org/poezio/slixmpp .. _aiodns: https://github.com/saghul/aiodns .. _poezio: https://aur.archlinux.org/packages/poezio/ .. _poezio-git: https://aur.archlinux.org/packages/poezio-git/ @@ -242,3 +255,5 @@ image from the Dockerfile at the root of the git repository. .. _port: http://ports.su/net/poezio .. _poezio/poezio: https://hub.docker.com/r/poezio/poezio/ .. _buster: https://packages.debian.org/buster/poezio +.. _net-im/poezio: https://packages.gentoo.org/packages/net-im/poezio +.. _flathub: https://flathub.org/apps/details/io.poez.Poezio diff --git a/doc/source/keys.rst b/doc/source/keys.rst index ae641c26..03ab2071 100644 --- a/doc/source/keys.rst +++ b/doc/source/keys.rst @@ -1,7 +1,7 @@ .. _keys-page: -Keys -==== +Keyboard Shortcuts +================== This file describes the default keys of poezio and explains how to configure them. @@ -374,6 +374,15 @@ Actions list Similar to F4. +**_go_to_room_name**: Jump to a tab by unique prefix. + + Similar to :term:`/wup` and the default *Alt-j*. This action will take + input as long as there is at least one tab name starting with the input + given so far. If there is exactly one tab matching, the action completes + and the current tab is switched over to the tab matching the input. If + no tab matches, the action completes without any change. This means that + you can typically abort the action with Escape. + Status actions ~~~~~~~~~~~~~~ diff --git a/doc/source/misc/client_certs.rst b/doc/source/misc/client_certs.rst index df09ea3c..1eacad0f 100644 --- a/doc/source/misc/client_certs.rst +++ b/doc/source/misc/client_certs.rst @@ -1,7 +1,7 @@ Using client certificates to login ================================== -Passwordless authentication is possible in XMPP through the use of mecanisms +Passwordless authentication is possible in XMPP through the use of mechanisms such as `SASL External`_. This mechanism has to be supported by both the client and the server. This page does not cover the server setup, but prosody has a `mod_client_certs`_ module which can perform this kind of authentication, and diff --git a/doc/source/misc/separate.rst b/doc/source/misc/separate.rst index 6c4605d8..66e42cdf 100644 --- a/doc/source/misc/separate.rst +++ b/doc/source/misc/separate.rst @@ -3,7 +3,7 @@ Using several accounts Poezio does not support multi-accounts, and we do not plan to do so in a foreseeable future. However, you can run several poezio instances (e.g. with -tmux or screen) to have similar functionnality. +tmux or screen) to have similar functionality. You can specify a different configuration file than the default with: diff --git a/doc/source/plugins/index.rst b/doc/source/plugins/index.rst index c1d8ded1..c1222c84 100644 --- a/doc/source/plugins/index.rst +++ b/doc/source/plugins/index.rst @@ -145,6 +145,14 @@ Plugin index Sends the current song (and optionally the progress inside the song) to the current (chat) tab. + OMEMO + **Not distributed with Poezio.** See https://lab.louiz.org/poezio/poezio-omemo. + + `Documentation <https://lab.louiz.org/poezio/poezio-omemo>`_ + + Allows for end-to-end encrypted exchanges using the OMEMO + mechanism. + OTR :ref:`Documentation <otr-plugin>` @@ -203,6 +211,11 @@ Plugin index Adds convenient aliases to /status (/away, etc). + Sticker + :ref:`Documentation <sticker-plugin>` + + Opens a graphical sticker picker and sends the selected one. + Tell :ref:`Documentation <tell-plugin>` @@ -304,6 +317,11 @@ Plugin index Add an ``/upload`` command to upload a file. + User Extras + :ref:`Documentation <userextras-plugin>` + + Add /mood, /gaming, /activity + .. toctree:: :hidden: @@ -329,6 +347,7 @@ Plugin index simple_notify spam status + sticker tell time_marker uptime @@ -353,3 +372,4 @@ Plugin index vcard upload contact + userextras diff --git a/doc/source/plugins/sticker.rst b/doc/source/plugins/sticker.rst new file mode 100644 index 00000000..815fb141 --- /dev/null +++ b/doc/source/plugins/sticker.rst @@ -0,0 +1,6 @@ +.. _sticker-plugin: + +Sticker +======= + +.. automodule:: sticker diff --git a/doc/source/plugins/user_extras.rst b/doc/source/plugins/user_extras.rst new file mode 100644 index 00000000..8c63092e --- /dev/null +++ b/doc/source/plugins/user_extras.rst @@ -0,0 +1,6 @@ +.. _userextras-plugin: + +User Extras +=========== + +.. automodule:: user_extras diff --git a/doc/source/themes.rst b/doc/source/themes.rst index f6da6af5..ba4be33b 100644 --- a/doc/source/themes.rst +++ b/doc/source/themes.rst @@ -19,7 +19,7 @@ the text impossible to read). .. note:: The default theme should work properly in any case. If not, that’s a bug. A theme file is a python file (with the .py extension) containing a -class, inheriting the *theming.Theme* class defined into the *theming* +class, inheriting the *poezio.theming.Theme* class defined into the *theming* poezio module. To check how many colors your current terminal/$TERM supports, do: @@ -38,18 +38,18 @@ add: .. code-block:: python - import theming + from poezio.theming import Theme - class FooTheme(theming.Theme): - # Define here colors for that theme + class FooTheme(Theme): + # Define here colors for that theme theme = FooTheme() To define a *color pair* and assign it to the *COLOR_NAME* option, just do .. code-block:: python - class FooTheme(theming.Theme): - COLOR_NAME = (fg_color, bg_color, opt_attr) + class FooTheme(Theme): + COLOR_NAME = (fg_color, bg_color, opt_attr) You do not have to define all the :ref:`available-options`, you can decide that your theme will only change some options, the other diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 86936d03..6caf2728 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -15,20 +15,11 @@ Tab list There are two ways of showing the open tabs: -Horizontal list -^^^^^^^^^^^^^^^ - -This is the default method. - -On all tabs, you get a line showing the the list of all opened tabs. Each tab -has a number, each time you open a new tab, it gets the next available number. - -.. figure:: ./images/tab_bar.png - :alt: Example of 5 opened tabs - Vertical list ^^^^^^^^^^^^^ +This is the default method. + On all tabs, you get a pane on the left side of the screen that shows a list of the opened tabs. As stated above, each tab has a number, and each time you open a new tab, it gets the next available number. @@ -36,10 +27,17 @@ open a new tab, it gets the next available number. .. figure:: ./images/vert_tabs.png :alt: Example of the vertical tab bar +Horizontal list +^^^^^^^^^^^^^^^ + +On all tabs, you get a line showing the the list of all opened tabs. Each tab +has a number, each time you open a new tab, it gets the next available number. + +.. figure:: ./images/tab_bar.png + :alt: Example of 5 opened tabs -This mode is enabled by setting the -:term:`enable_vertical_tab_list` option to ``true`` in the -configuration file. +This mode is enabled by setting the :term:`enable_vertical_tab_list` +option to ``false`` in the configuration file. Options for the tab list ^^^^^^^^^^^^^^^^^^^^^^^^ |