diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/commands.rst | 82 | ||||
| -rw-r--r-- | doc/source/conf.py | 16 | ||||
| -rw-r--r-- | doc/source/configuration.rst | 145 | ||||
| -rw-r--r-- | doc/source/dev/contributing.rst | 6 | ||||
| -rw-r--r-- | doc/source/dev/plugin.rst | 11 | ||||
| -rw-r--r-- | doc/source/install.rst | 17 | ||||
| -rw-r--r-- | doc/source/keys.rst | 9 | ||||
| -rw-r--r-- | doc/source/plugins/index.rst | 14 | ||||
| -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 |
12 files changed, 189 insertions, 161 deletions
diff --git a/doc/source/commands.rst b/doc/source/commands.rst index bea44fe0..d1763084 100644 --- a/doc/source/commands.rst +++ b/doc/source/commands.rst @@ -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,6 +99,15 @@ 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]`` @@ -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]`` @@ -225,28 +245,6 @@ These commands work in *any* tab. .. versionadded:: 0.13 - /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". - - /gaming - **Usage:** ``/gaming [<game name> [server address]]`` - - Send your current gaming activity to your contacts. - - Nothing means "stop broadcasting a gaming activity". - /last_activity **Usage:** ``/activity <jid>`` @@ -331,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>`` @@ -350,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 @@ -411,18 +409,34 @@ 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]`` 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 9619022a..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 @@ -81,15 +81,6 @@ and certificate validation. you know what you are doing, see the :ref:`ciphers` dedicated section for more details. - default_muc_service - - **Default value:** ``[empty]`` - - If specified, will be used instead of the MUC service provided by - the user domain. - - .. versionadded:: 0.13 - force_encryption **Default value:** ``true`` @@ -142,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]`` @@ -324,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`` @@ -371,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 - - **Default value:** ``false`` + synchronise_open_rooms - If ``true``, poezio will bookmark automatically every room that is joined with - a manual ``/join`` command. + **Default value:** ``true`` - force_remote_bookmarks + 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. - **Default value:** ``false`` + If ``true``, ``/join`` will create a bookmark with ``autojoin=true``, + and ``/leave`` will remove said bookmark. - Try to retrieve your remote bookmarks, even when your server doesn’t advertise - support. + This was previously named ``bookmark_on_join``. use_bookmark_method @@ -407,34 +381,6 @@ 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`` @@ -566,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 @@ -680,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`` @@ -793,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`` @@ -913,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 ~~~~~~~ @@ -1116,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. diff --git a/doc/source/dev/contributing.rst b/doc/source/dev/contributing.rst index 8d386c87..4c2d8161 100644 --- a/doc/source/dev/contributing.rst +++ b/doc/source/dev/contributing.rst @@ -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/plugin.rst b/doc/source/dev/plugin.rst index 6a7605b2..4614c761 100644 --- a/doc/source/dev/plugin.rst +++ b/doc/source/dev/plugin.rst @@ -27,7 +27,6 @@ BasePlugin .. module:: poezio.plugin .. autoclass:: BasePlugin - :members: init, cleanup, api, core .. method:: init(self) @@ -49,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/install.rst b/doc/source/install.rst index 3425542c..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 @@ -16,14 +16,17 @@ using one of these. - **Archlinux**: poezio_ and poezio-git_ packages are in the AUR (use your favourite AUR wrapper to install them) - **Gentoo**: `net-im/poezio`_ -- **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. +- **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) @@ -60,7 +63,7 @@ support. Therefore, you might want to use the git version. 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: @@ -241,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/ @@ -254,3 +256,4 @@ image from the Dockerfile at the root of the git repository. .. _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 dc5fa35b..03ab2071 100644 --- a/doc/source/keys.rst +++ b/doc/source/keys.rst @@ -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/plugins/index.rst b/doc/source/plugins/index.rst index 59801784..c1222c84 100644 --- a/doc/source/plugins/index.rst +++ b/doc/source/plugins/index.rst @@ -146,7 +146,7 @@ Plugin index the current (chat) tab. OMEMO - *Not distributed with Poezio.* See https://lab.louiz.org/poezio/poezio-omemo. + **Not distributed with Poezio.** See https://lab.louiz.org/poezio/poezio-omemo. `Documentation <https://lab.louiz.org/poezio/poezio-omemo>`_ @@ -211,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>` @@ -312,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: @@ -337,6 +347,7 @@ Plugin index simple_notify spam status + sticker tell time_marker uptime @@ -361,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 ^^^^^^^^^^^^^^^^^^^^^^^^ |