summaryrefslogtreecommitdiff
path: root/doc/source/configuration.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/source/configuration.rst')
-rw-r--r--doc/source/configuration.rst827
1 files changed, 462 insertions, 365 deletions
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index b584359b..8929f45b 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -33,66 +33,18 @@ These options have a sense when they are in the global section. Some of
them can also be in an optional configuration section, see the next
section of this documentation.
-.. glossary::
- :sorted:
-
- add_space_after_completion
-
- **Default value:** ``true``
-
- Whether or not to add a space after a completion in the middle of the
- input (not at the start of it)
-
- after_completion
-
- **Default value:** ``,``
+The options here are separated thematically for convenience but they all
+go into the main config section.
- What will be put after the name, when using autocompletion at the
- beginning of the input. A space will always be added after that
-
- alternative_nickname
-
- **Default value:** ``[empty]``
-
- If you want poezio to join the room with an alternative nickname when
- your nickname is already in use in the room you wanted to join, put
- a non-empty value. If you don’t, poezio won't join the room
- This value will be added to your nickname to create the alternative nickname.
- For example, if you set "\_", and wanted to use the nickname "john",
- your alternative nickname will be "john\_".
- autorejoin
-
- **Default value:** ``false``
-
- Set to true if you want to automatically rejoin the room when you're kicked.
-
- autorejoin_delay
-
- **Default value:** ``5``
-
- Set to the number of seconds before reconnecting after getting kicked.
- 0, a negative value, or no value means you reconnect instantly.
- This option only works if autorejoin is enabled.
-
- auto_reconnect
-
- **Default value:** ``false``
-
- Auto-reconnects you when you get disconnected. Should not be necessary, so
- the default is false.
-
- beep_on
-
- **Default value:** ``highlight private``
+Security
+~~~~~~~~
- The terminal can beep on various event. Put the event you want in a list
- (separated by spaces).
+Options pertaining to security, such as :ref:`TLS encryption <security settings>`
+and certificate validation.
- The events can be
- - ``highlight`` (when you are highlighted in a MUC)
- - ``private`` (when a new private message is received, from your contacts or someone from a MUC)
- - ``message`` (any message from a MUC)
+.. glossary::
+ :sorted:
ca_cert_path
@@ -119,24 +71,41 @@ section of this documentation.
you know what you are doing, see the :ref:`ciphers` dedicated section
for more details.
- connection_check_interval
+ force_encryption
- **Default value:** ``60``
+ **Default value:** ``true``
- A ping is sent to the server every N seconds, N being the value of
- that option. Change this to a low value if you want to know quickly
- when you are disconnected, and to a very high value if bandwidth
- matters so much that you can’t afford 100 bytes/minute, or if you
- don’t want to waste your battery by waking up the TCP connection too
- often. Disable this ping altogether by setting this value to 0.
+ If set to true, all connections will use TLS by default. Only turn this to
+ false if you cannot connect to your server, and do not care about your password
+ or the pricacy of your communications.
- connection_timeout_delay
+ ignore_certificate
- **Default value:** ``10``
+ **Default value:** ``false``
- The timeout delay of the ping referenced above, 10 should really be fine, but
- if your network is really unstable, it can be set higher or lower, depending
- of your preference.
+ Skip certificate validation on connection when ``true``. Useful when you are in
+ anonymous mode and changing servers often. Dangerous in other cases, from a
+ security perspective.
+
+
+
+Account
+~~~~~~~
+
+Options related to account configuration, nickname…
+
+.. glossary::
+ :sorted:
+
+ jid
+
+ **Default value:** ``[empty]``
+
+ Jabber identifier. Specify it only if you want to connect using an existing
+ account on a server. This is optional and useful only for some features,
+ like room administration or nickname registration.
+ The :term:`server` option will be ignored if you specify a JID (Jabber id)
+ It should be in the form nickname@server.tld
custom_host
@@ -161,48 +130,141 @@ section of this documentation.
the nick you will use when joining a room with no associated nick
If this is empty, the $USER environnement variable will be used
- display_gaming_notifications
+ server
- **Default value:** ``false``
+ **Default value:** ``anon.jeproteste.info``
- If set to true, notifications about the games your are playing
- will be displayed in the info buffer as 'Gaming' messages.
+ The server to use for anonymous authentication;
+ make sure it supports anonymous authentification.
- display_tune_notifications
+ Note that this option doesn’t do anything at all if you’re using your own JID.
- **Default value:** ``false``
+ alternative_nickname
- If set to true, notifications about the music your contacts listen to
- will be displayed in the info buffer as 'Tune' messages.
+ **Default value:** ``[empty]``
- force_encryption
+ If you want poezio to join the room with an alternative nickname when
+ your nickname is already in use in the room you wanted to join, put
+ a non-empty value. If you don’t, poezio won't join the room
+ This value will be added to your nickname to create the alternative nickname.
+ For example, if you set "_", and wanted to use the nickname "john",
+ your alternative nickname will be "john\_".
- **Default value:** ``true``
- If set to true, all connections will use TLS by default. Only turn this to
- false if you cannot connect to your server, and do not care about your password
- or the pricacy of your communications.
+ resource
- display_mood_notifications
+ **Default value:** ``[empty]``
- **Default value:** ``false``
+ The resource you will use. If it's empty, your resource will be chosen
+ (most likely randomly) by the server. It is not recommended to use a
+ resource that is easy to guess, because it can lead to presence leak.
- If set to true, notifications about the mood of your contacts
- will be displayed in the info buffer as 'Mood' messages.
+ rooms
- display_activity_notifications
+ **Default value:** ``[empty]``
+
+ The rooms you will join automatically on startup, with associated
+ nickname or not.
+
+ Format : ``room@server.tld/nickname:room2@server.tld/nickname2``.
+
+ The :term:`default_nick` option will be used if "/nickname" is not specified.
+
+ password
+
+ **Default value:** ``[empty]``
+
+ A password is needed only if you specified a :term:`jid`. It will be ignored otherwise
+ If you leave this empty, the password will be asked at each startup, which is recommended.
+
+ status
+
+ **Default value:** ``[empty]``
+
+ The status (show) poezio will send when connecting. It can be available,
+ ``dnd``, ``chat``, ``xa`` or ``away``.
+
+ Nothing or an invalid value will mean available.
+
+ status_message
+
+ **Default value:** ``[empty]``
+
+ The status message poezio will send when connecting.
+
+
+
+
+Connectivity
+
+~~~~~~~~~~~~
+
+Options about general or chatroom connectivity. Reconnecting does not work very
+well, but you will at least want to know when you get disconnected.
+
+
+.. glossary::
+ :sorted:
+
+ auto_reconnect
**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.
+ Auto-reconnects you when you get disconnected. Should not be necessary, so
+ the default is false.
- display_user_color_in_join_part
+ connection_check_interval
+
+ **Default value:** ``60``
+
+ A ping is sent to the server every N seconds, N being the value of
+ that option. Change this to a low value if you want to know quickly
+ when you are disconnected, and to a very high value if bandwidth
+ matters so much that you can’t afford 100 bytes/minute, or if you
+ don’t want to waste your battery by waking up the TCP connection too
+ often. Disable this ping altogether by setting this value to 0.
+
+ connection_timeout_delay
+
+ **Default value:** ``10``
+
+ The timeout delay of the ping referenced above, 10 should really be fine, but
+ if your network is really unstable, it can be set higher or lower, depending
+ of your preference.
+
+ whitespace_interval
+
+ **Default value:** ``300``
+
+ Interval of the whitespace keepalive sending to the server.
+ ``300`` should be fine, but change it if some services have a stricter policy
+ on client inactivity.
+
+ autorejoin
**Default value:** ``false``
- If set to true, the color of the nick will be used in MUCs information
- messages, instead of the default color from the theme.
+ Set to true if you want to automatically rejoin the room when you're kicked.
+
+ autorejoin_delay
+
+ **Default value:** ``5``
+
+ Set to the number of seconds before reconnecting after getting kicked.
+ 0, a negative value, or no value means you reconnect instantly.
+ This option only works if autorejoin is enabled.
+
+
+XMPP features
+~~~~~~~~~~~~~
+
+These options enable, disable, or allow to configure the behavior
+of some non-essential XMPP features. There is a dedicated page
+to understand what is :ref:`carbons <carbons-details>` or
+:ref:`user activity/gaming/mood/tune <pep-details>`.
+
+.. glossary::
+ :sorted:
enable_carbons
@@ -242,254 +304,247 @@ section of this documentation.
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.
- enable_vertical_tab_list
+ use_bookmark_method
- **Default value:** ``false``
+ **Default value:** ``[empty]``
- If ``true``, a vertical list of tabs, with their name, is displayed on the left of
- the screen.
+ The method that poezio will use to store your bookmarks online.
+ Possible values are: ``privatexml``, ``pep``.
+ You should not have to edit this in a normal use case.
- enable_xhtml_im
+ use_pep_nick
**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.
- Set to ``true`` if you want to see colored (and otherwise formatted) messages.
+ Use the nickname broadcasted by the user if set to ``true``, and if none
+ has already been set manually.
- exec_remote
+ use_remote_bookmarks
- **Default value:** ``false``
+ **Default value:** ``true``
- If this is set to ``true``, poezio will try to send the commands to a FIFO
- instead of executing them locally. This is to be used in conjunction with
- ssh and the daemon.py file. See the :term:`/link` documentation for details.
+ Use this option to force the use of local bookmarks if needed.
+ Anything but "false" will be counted as true.
- filter_info_messages
+ display_gaming_notifications
- **Default value:** ``[empty]``
+ **Default value:** ``false``
- A list of words or sentences separated by colons (":"). All the
- informational mesages (described above) containing at least one of those
- values will not be shown.
+ If set to true, notifications about the games your are playing
+ will be displayed in the info buffer as 'Gaming' messages.
- hide_exit_join
+ display_tune_notifications
- **Default value:** ``-1``
+ **Default value:** ``false``
- Exact same thing than :term:`hide_status_change`, except that it concerns
- the quit message, and that it will be hidden only if the value is ``0``.
+ If set to true, notifications about the music your contacts listen to
+ will be displayed in the info buffer as 'Tune' messages.
- Default setting means:
- - all quit and join notices will be displayed
+ display_mood_notifications
- hide_status_change
+ **Default value:** ``false``
- **Default value:** ``120``
+ If set to true, notifications about the mood of your contacts
+ will be displayed in the info buffer as 'Mood' messages.
- Set a number for this setting.
- The join AND status-change notices will be
- displayed according to this number.
+ display_activity_notifications
- ``-1``: the notices will ALWAYS be displayed
+ **Default value:** ``false``
- ``0``: the notices will NEVER be displayed
+ If set to true, notifications about the current activity of your contacts
+ will be displayed in the info buffer as 'Activity' messages.
- ``n``: On any other number, the notices will only be displayed
- if the user involved has talked since the last n seconds
+ enable_xhtml_im
- if the value is incorrect, ``-1`` is assumed
+ **Default value:** ``true``
- Default setting means that status changes won't be displayed
- unless the user talked in the last 2 minutes
+ 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.
+ Set to ``true`` if you want to see colored (and otherwise formatted) messages.
- hide_user_list
+ send_chat_states
- **Default value:** ``false``
+ **Default value:** ``true``
- Whether to hide the list of user in the MultiUserChat tabs or not. Useful
- for example if you want to copy/paste the content of the buffer, or if you
- want to gain space
+ if ``true``, chat states will be sent to the people you are talking to.
+ Chat states are, for example, messages informing that you are composing
+ a message or that you closed the tab, etc.
- highlight_on
+ Set to ``false`` if you don't want people to know these information
+ Note that you won’t receive the chat states of your contacts
+ if you don't send yours.
- **Default value:** ``[empty]``
- a list of words (separated by a colon (:)) that will be
- highlighted if said by someone on a room
+ send_os_info
- ignore_certificate
+ **Default value:** ``true``
- **Default value:** ``false``
+ If ``true``, information about the Operation System you're using
+ will be sent when requested by anyone
+ Set to ``false`` if you don't want people to know these informations.
- Skip certificate validation on connection when ``true``. Useful when you are in
- anonymous mode and changing servers often. Dangerous in other cases, from a
- security perspective.
+ Note that this information will not be sent if :term:`send_poezio_info` is False
- information_buffer_popup_on
+ send_poezio_info
- **Default value:** ``error roster warning help info``
+ **Default value:** ``true``
- 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
- appear.
+ if true, information about the software (name and version)
+ will be sent if requested by anyone
+ Set to false if you don't want people to know these information
- A list of message types that should make the information buffer grow
- Possible values: ``error``, ``roster``, ``warning``, ``info``, ``help``
+ send_time
- jid
+ **Default value:** ``true``
- **Default value:** ``[empty]``
+ If ``true``, your current time will be sent if asked
+ Set to ``false`` if you don't want people to know that information
- Jabber identifiant. Specify it only if you want to connect using an existing
- account on a server. This is optional and useful only for some features,
- like room administration or nickname registration.
- The :term:`server` option will be ignored if you specify a JID (Jabber id)
- It should be in the form nickname@server.tld
+Visual interface
+~~~~~~~~~~~~~~~~
- lang
+All these options will change how poezio looks, either by removing
+parts of the interface, adding them, changing the ordering of stuff,
+or the way messages are displayed.
- **Default value:** ``en``
- The lang some automated entities will use when replying to you.
+.. glossary::
+ :sorted:
- lazy_resize
+ use_tab_nicks
**Default value:** ``true``
- Defines if all tabs are resized at the same time (if set to ``false``)
- or if they are really resized only when needed (if set to ``true``).
- ``true`` should be the most comfortable value
+ The tabs have a name, and a nick, which is, for a contact, its name in the
+ roster, or for a private conversation, the nickname in the MUC. Set this to
+ ``true`` if you want to have them shown instead of the jid of the contact.
- load_log
+ theme
- **Default value:** ``10``
+ **Default value:** ``[empty]``
- 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.
+ The name of the theme file (without the .py extension) that will be used.
+ The file should be located in the :term:`themes_dir` directory.
- log_dir
+ If the file is not found (or no filename is specified) the default
+ theme will be used instead
+
+ themes_dir
**Default value:** ``[empty]``
- If :term:`log_dir` is not set, logs will be saved in ``$XDG_DATA_HOME/poezio/logs``,
- i.e. in ``~/.local/share/poezio/logs/``. So, you should specify the directory
- you want to use instead. This directory will be created if it doesn't exist
+ If :term:`themes_dir` is not set, themes will searched for in
+ ``$XDG_DATA_HOME/poezio/themes``, i.e. in ``~/.local/share/poezio/themes/``.
+ So you should specify the directory you want to use instead.
- log_errors
+ This directory will be created at startup if it doesn't exist
- **Default value:** ``true``
+ user_list_sort
- Logs all the tracebacks or poezio/sleekxmpp in :term:`log_dir`/errors.log by
- default. ``false`` disables this option.
+ **Default value:** ``desc``
- max_lines_in_memory
+ If set to ``desc``, the MUC users will be displayed from top to bottom in the list,
+ if set to ``asc``, they will be displayed from bottom to top.
- **Default value:** ``2048``
+ vertical_tab_list_size
- Configure the number of maximum lines (for each tab) that
- can be kept in memory. If poezio consumes too much memory, lower these
- values
+ **Default value:** ``20``
- max_messages_in_memory
+ Size of the vertical tab list.
- **Default value:** ``2048``
+ vertical_tab_list_sort
- Configure the number of maximum messages (for each tab) that
- can be kept in memory. If poezio consumes too much memory, lower these
- values
+ **Default value:** ``desc``
- max_nick_length
+ If set to ``desc``, the tabs will be displayed from top to bottom in the list,
+ if set to ``asc``, they will be displayed from bottom to top.
- **Default value:** ``25``
+ filter_info_messages
- The maximum length of the nickname that will be displayed in the
- conversation window. Nicks that are too long will be truncated and have
- a ``…`` appened to them.
+ **Default value:** ``[empty]``
- muc_history_length
+ A list of words or sentences separated by colons (":"). All the
+ informational mesages (described above) containing at least one of those
+ values will not be shown.
- **Default value:** ``50``
+ hide_exit_join
- Limit the number of messages you want to receive when the
- multiuserchat rooms send you recent history
+ **Default value:** ``-1``
- ``0``: You won't receive any
+ Exact same thing than :term:`hide_status_change`, except that it concerns
+ the quit message, and that it will be hidden only if the value is ``0``.
- ``-1``: You will receive the maximum
+ Default setting means:
+ - all quit and join notices will be displayed
- ``n``: You will receive at most n messages
+ hide_status_change
- Note that if you set a huge number (like the default value), you
- may not receive that much messages. The server has its own
- maximum too.
+ **Default value:** ``120``
- password
+ Set a number for this setting.
+ The join AND status-change notices will be
+ displayed according to this number.
- **Default value:** ``[empty]``
+ ``-1``: the notices will ALWAYS be displayed
- A password is needed only if you specified a :term:`jid`. It will be ignored otherwise
- If you leave this empty, the password will be asked at each startup, which is recommended.
+ ``0``: the notices will NEVER be displayed
- plugins_autoload
+ ``n``: On any other number, the notices will only be displayed
+ if the user involved has talked since the last n seconds
- **Default value:** ``[empty]``
+ if the value is incorrect, ``-1`` is assumed
- Colon-separated list of plugins to load on startup.
+ Default setting means that status changes won't be displayed
+ unless the user talked in the last 2 minutes
- plugins_conf_dir
+ hide_user_list
- **Default value:** ``[empty]``
+ **Default value:** ``false``
- If plugins_conf_dir is not set, plugin configs will be loaded from
- ``$XDG_CONFIG_HOME/poezio/plugins``.
- You can specify another directory to use, it will be created if it
- does not exist.
+ Whether to hide the list of user in the MultiUserChat tabs or not. Useful
+ for example if you want to copy/paste the content of the buffer, or if you
+ want to gain space
- plugins_dir
+ highlight_on
**Default value:** ``[empty]``
- If plugins_dir is not set, plugins will be loaded from
- ``$XDG_DATA_HOME/poezio/plugins``.
- You can specify another directory to use. It will be created if it
- does not exist.
-
- popup_time
+ a list of words (separated by a colon (:)) that will be
+ highlighted if said by someone on a room
- **Default value:** ``4``
+ information_buffer_popup_on
- The time the message will be visible in the information buffer when it
- pops up.
- If the message takes more than one line, the popup will stay visible
- two more second per additional lines.
+ **Default value:** ``error roster warning help info``
- remote_fifo_path
+ 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
+ appear.
- **Default value:** ``./poezio.fifo``
+ A list of message types that should make the information buffer grow
+ Possible values: ``error``, ``roster``, ``warning``, ``info``, ``help``
- The path of the FIFO used to send the commands (see the :term:`exec_remote` option).
+ display_user_color_in_join_part
- resource
+ **Default value:** ``false``
- **Default value:** ``[empty]``
+ If set to true, the color of the nick will be used in MUCs information
+ messages, instead of the default color from the theme.
- The resource you will use. If it's empty, your resource will be chosen
- (most likely randomly) by the server. It is not recommended to use a
- resource that is easy to guess, because it can lead to presence leak.
+ enable_vertical_tab_list
- rooms
+ **Default value:** ``false``
- **Default value:** ``[empty]``
+ If ``true``, a vertical list of tabs, with their name, is displayed on the left of
+ the screen.
- The rooms you will join automatically on startup, with associated
- nickname or not.
+ max_nick_length
- Format : ``room@server.tld/nickname:room2@server.tld/nickname2``.
+ **Default value:** ``25``
- The :term:`default_nick` option will be used if "/nickname" is not specified.
+ The maximum length of the nickname that will be displayed in the
+ conversation window. Nicks that are too long will be truncated and have
+ a ``…`` appened to them.
roster_group_sort
@@ -533,73 +588,6 @@ section of this documentation.
separated by colons (":"). If there are more than 3 or 4 chained
sorting methods, your sorting is most likely inefficient.
- save_status
-
- **Default value:** ``true``
-
- Save the status automatically in the :term:`status` and :term:`status_message` options.
-
- send_chat_states
-
- **Default value:** ``true``
-
- if ``true``, chat states will be sent to the people you are talking to.
- Chat states are, for example, messages informing that you are composing
- a message or that you closed the tab, etc.
-
- Set to ``false`` if you don't want people to know these information
- Note that you won’t receive the chat states of your contacts
- if you don't send yours.
-
- send_initial_presence
-
- **Default value:** ``true``
-
- Send initial presence (normal behaviour). If ``false``, you will not send nor
- receive any presence that is not directed (through :term:`/presence`) or sent by a
- MUC.
-
- send_os_info
-
- **Default value:** ``true``
-
- If ``true``, information about the Operation System you're using
- will be sent when requested by anyone
- Set to ``false`` if you don't want people to know these informations.
-
- Note that this information will not be sent if :term:`send_poezio_info` is False
-
- send_poezio_info
-
- **Default value:** ``true``
-
- if true, information about the software (name and version)
- will be sent if requested by anyone
- Set to false if you don't want people to know these information
-
- send_time
-
- **Default value:** ``true``
-
- If ``true``, your current time will be sent if asked
- Set to ``false`` if you don't want people to know that information
-
- separate_history
-
- **Default value:** ``false``
-
- If true, the history of inputs of the same nature won’t be shared
- between tabs (as in weechat).
-
- server
-
- **Default value:** ``anon.jeproteste.info``
-
- The server to use for anonymous authentication;
- make sure it supports anonymous authentification.
-
- Note that this option doesn’t do anything at all if you’re using your own JID.
-
show_inactive_tabs
**Default value:** ``true``
@@ -660,28 +648,96 @@ section of this documentation.
Whether or not to display a timestamp before each message.
- status
+ popup_time
- **Default value:** ``[empty]``
+ **Default value:** ``4``
- The status (show) poezio will send when connecting. It can be available,
- ``dnd``, ``chat``, ``xa`` or ``away``.
+ The time the message will be visible in the information buffer when it
+ pops up.
+ If the message takes more than one line, the popup will stay visible
+ two more second per additional lines.
- Nothing or an invalid value will mean available.
+User Interaction
+~~~~~~~~~~~~~~~~
- status_message
+Options that change the behavior of poezio in a non-visual manner.
+
+.. glossary::
+ :sorted:
+
+ add_space_after_completion
+
+ **Default value:** ``true``
+
+ Whether or not to add a space after a completion in the middle of the
+ input (not at the start of it)
+
+ after_completion
+
+ **Default value:** ``,``
+
+ What will be put after the name, when using autocompletion at the
+ beginning of the input. A space will always be added after that
+
+
+ beep_on
+
+ **Default value:** ``highlight private``
+
+ The terminal can beep on various event. Put the event you want in a list
+ (separated by spaces).
+
+ The events can be
+ - ``highlight`` (when you are highlighted in a MUC)
+ - ``private`` (when a new private message is received, from your contacts or someone from a MUC)
+ - ``message`` (any message from a MUC)
+
+ separate_history
+
+ **Default value:** ``false``
+
+ If true, the history of inputs of the same nature won’t be shared
+ between tabs (as in weechat).
+
+ words
**Default value:** ``[empty]``
- The status message poezio will send when connecting.
+ Personal dictionary of the words you use often, that you want to complete
+ through recent words completion. They must be separated bu a colon (:). That
+ completion will work in chatrooms, private conversations, and direct
+ conversations.
- use_bookmark_method
+Logging
+~~~~~~~
+
+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]``
- The method that poezio will use to store your bookmarks online.
- Possible values are: ``privatexml``, ``pep``.
- You should not have to edit this in a normal use case.
+ If :term:`log_dir` is not set, logs will be saved in ``$XDG_DATA_HOME/poezio/logs``,
+ i.e. in ``~/.local/share/poezio/logs/``. So, you should specify the directory
+ you want to use instead. This directory will be created if it doesn't exist.
+
+ log_errors
+
+ **Default value:** ``true``
+
+ Logs all the tracebacks and erors of poezio/sleekxmpp in
+ :term:`log_dir`/errors.log by default. ``false`` disables this option.
use_log
@@ -690,84 +746,125 @@ section of this documentation.
Set to ``false`` if you don’t want to save logs of all the messages
in files.
- use_pep_nick
+Plugins
+~~~~~~~
- **Default value:** ``true``
+This sections references the configuration of the plugin system; for
+more details, go to the :ref:`dedicated page<plugins-doc>`.
- Use the nickname broadcasted by the user if set to ``true``, and if none
- has already been set manually.
+.. glossary::
+ :sorted:
- use_remote_bookmarks
+ plugins_autoload
- **Default value:** ``true``
+ **Default value:** ``[empty]``
- Use this option to force the use of local bookmarks if needed.
- Anything but "false" will be counted as true.
+ Colon-separated list of plugins to load on startup.
- use_tab_nicks
+ plugins_conf_dir
- **Default value:** ``true``
+ **Default value:** ``[empty]``
- The tabs have a name, and a nick, which is, for a contact, its name in the
- roster, or for a private conversation, the nickname in the MUC. Set this to
- ``true`` if you want to have them shown instead of the jid of the contact.
+ If plugins_conf_dir is not set, plugin configs will be loaded from
+ :file:`$XDG_CONFIG_HOME/poezio/plugins`.
+ You can specify another directory to use, it will be created if it
+ does not exist.
- theme
+ plugins_dir
**Default value:** ``[empty]``
- The name of the theme file (without the .py extension) that will be used.
- The file should be located in the :term:`themes_dir` directory.
+ If plugins_dir is not set, plugins will be loaded from
+ ``$XDG_DATA_HOME/poezio/plugins``.
+ You can specify another directory to use. It will be created if it
+ does not exist.
- If the file is not found (or no filename is specified) the default
- theme will be used instead
- themes_dir
- **Default value:** ``[empty]``
+Other
+~~~~~
- If :term:`themes_dir` is not set, themes will searched for in
- ``$XDG_DATA_HOME/poezio/themes``, i.e. in ``~/.local/share/poezio/themes/``.
- So you should specify the directory you want to use instead.
+.. glossary::
+ :sorted:
- This directory will be created at startup if it doesn't exist
+ exec_remote
- user_list_sort
+ **Default value:** ``false``
- **Default value:** ``desc``
+ If this is set to ``true``, poezio will try to send the commands to a FIFO
+ instead of executing them locally. This is to be used in conjunction with
+ ssh and the daemon.py file. See the :term:`/link` documentation for details.
- If set to ``desc``, the MUC users will be displayed from top to bottom in the list,
- if set to ``asc``, they will be displayed from bottom to top.
- vertical_tab_list_size
+ lang
- **Default value:** ``20``
+ **Default value:** ``en``
- Size of the vertical tab list.
+ The lang some automated entities will use when replying to you.
- vertical_tab_list_sort
+ muc_history_length
- **Default value:** ``desc``
+ **Default value:** ``50``
- If set to ``desc``, the tabs will be displayed from top to bottom in the list,
- if set to ``asc``, they will be displayed from bottom to top.
+ Limit the number of messages you want to receive when the
+ multiuserchat rooms send you recent history
- whitespace_interval
+ ``0``: You won't receive any
- **Default value:** ``300``
+ ``-1``: You will receive the maximum
- Interval of the whitespace keepalive sending to the server.
- ``300`` should be fine, but change it if some services have a stricter policy
- on client inactivity.
+ ``n``: You will receive at most n messages
+
+ Note that if you set a huge number (like the default value), you
+ may not receive that much messages. The server has its own
+ maximum too.
+
+ remote_fifo_path
+
+ **Default value:** ``./poezio.fifo``
+
+ The path of the FIFO used to send the commands (see the :term:`exec_remote` option).
+
+ save_status
+
+ **Default value:** ``true``
+
+ Save the status automatically in the :term:`status` and :term:`status_message` options.
+
+ send_initial_presence
+
+ **Default value:** ``true``
+
+ Send initial presence (normal behaviour). If ``false``, you will not send nor
+ receive any presence that is not directed (through :term:`/presence`) or sent by a
+ MUC.
+
+ lazy_resize
+
+ **Default value:** ``true``
+
+ Defines if all tabs are resized at the same time (if set to ``false``)
+ or if they are really resized only when needed (if set to ``true``).
+ ``true`` should be the most comfortable value
+
+ max_lines_in_memory
+
+ **Default value:** ``2048``
+
+ Configure the number of maximum lines (for each tab) that
+ can be kept in memory. If poezio consumes too much memory, lower these
+ values
+
+ max_messages_in_memory
+
+ **Default value:** ``2048``
+
+ Configure the number of maximum messages (for each tab) that
+ can be kept in memory. If poezio consumes too much memory, lower these
+ values
- words
- **Default value:** ``[empty]``
- Personal dictionary of the words you use often, that you want to complete
- through recent words completion. They must be separated bu a colon (:). That
- completion will work in chatrooms, private conversations, and direct
- conversations.
Optional section options