diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/commands.rst | 14 | ||||
| -rw-r--r-- | doc/source/configuration.rst | 889 | ||||
| -rw-r--r-- | doc/source/index.rst | 10 |
3 files changed, 900 insertions, 13 deletions
diff --git a/doc/source/commands.rst b/doc/source/commands.rst index 6b8e58b9..e14f1c3c 100644 --- a/doc/source/commands.rst +++ b/doc/source/commands.rst @@ -309,7 +309,7 @@ MultiUserChat tab commands Display some information about the user in the room: his/her role, affiliation, status, and status message. - /version [MUC tab version] + /version **Usage:** ``/version <nickname or jid>`` Get the software version of the given nick in @@ -328,13 +328,13 @@ Private tab commands .. glossary:: :sorted: - /info [Private tab version] + /info Display some info about this user in the MultiUserChat. - /unquery [Private tab version] + /unquery Close the tab. - /version [Private tab version] + /version Get the software version of the current interlocutor (usually its XMPP client and Operating System). @@ -344,13 +344,13 @@ Normal Conversation tab commands .. glossary:: :sorted: - /info [Conversation tab version] + /info Display the status of this contact. - /unquery [Conversation tab version] + /unquery Close the tab. - /version [Conversation tab version] + /version Get the software version of the current interlocutor (usually its XMPP client and Operating System). diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst new file mode 100644 index 00000000..a664abb6 --- /dev/null +++ b/doc/source/configuration.rst @@ -0,0 +1,889 @@ +Configure +========= + +The configuration is located in the file *~/.config/poezio/poezio.cfg* +On its first startup, poezio will create that file (and its containing +directories) with the default configuration. You can edit that file manually +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 *keys* documentation file. + +That file is read at each startup and the configuration is saved when poezio +is closed. + +This configuration file **requires** all global options to be in a section +named [Poezio]. Some other options can be in optional sections and will +apply only to tabs having the option’s name. + +An option is formatted like this: + +``option = value`` + +An empty value *doesn’t* mean that the default value will be used. That’s +just an empty value. To use the default value, just comment or remove the +option entirely. + +Here is a list of all the available configuration options, their meaning +and their default value. + +Configuration options +--------------------- + +Global section options +~~~~~~~~~~~~~~~~~~~~~~ + +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:** ``,`` + + 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`` + + 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) + + ca_cert_path + + **Default value:** ``[empty]`` + + Path to the certificate of the Certification Authority. + As some services may keep different certificates, it is an alternative to + the Trust On First Use model provided by the :term:`certificate` option. + This option is not affected by :term:`ignore_certificate` and boths checks + may be active at the same time. + + certificate + + **Default value:** ``[empty]`` + + The fingerprint of the SSL certificate as a hexadecimal string, you should + not touch it, except if know what you are doing. + + custom_host + + **Default value:** ``[empty]`` + + A custom host that will be used instead of the DNS records for the server + (anonymous or the jid’s) defined above. + You should not need this in a "normal" use case. + + custom_port + + **Default value:** ``[empty]`` + + A custom port to use instead of the ``5222``. + This option can be combined with :term:`custom_host`. + You should not need this in a "normal" use case. + + default_nick + + **Default value:** ``[empty]`` + + 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 + + **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. + + display_user_color_in_join_part + + **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. + + 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. + + enable_vertical_tab_list + + **Default value:** ``false`` + + If ``true``, a vertical list of tabs, with their name, is displayed on the left of + the screen. + + 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. + Set to ``true`` if you want to see colored (and otherwise formatted) messages. + + exec_remote + + **Default value:** ``false`` + + 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. + + filter_info_messages + + **Default value:** ``[empty]`` + + 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. + + hide_exit_join + + **Default value:** ``-1`` + + 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``. + + Default setting means: + - all quit and join notices will be displayed + + hide_status_change + + **Default value:** ``120`` + + Set a number for this setting. + The join AND status-change notices will be + displayed according to this number. + + ``-1``: the notices will ALWAYS be displayed + + ``0``: the notices will NEVER be displayed + + ``n``: On any other number, the notices will only be displayed + if the user involved has talked since the last n seconds + + if the value is incorrect, ``-1`` is assumed + + Default setting means that status changes won't be displayed + unless the user talked in the last 2 minutes + + hide_user_list + + **Default value:** ``false`` + + 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 + + highlight_on + + **Default value:** ``[empty]`` + + a list of words (separated by a colon (:)) that will be + highlighted if said by someone on a room + + ignore_certificate + + **Default value:** ``false`` + + 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. + + information_buffer_popup_on + + **Default value:** ``error roster warning help info`` + + 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. + + A list of message types that should make the information buffer grow + Possible values: ``error``, ``roster``, ``warning``, ``info``, ``help`` + + jid + + **Default value:** ``[empty]`` + + 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 + + lang + + **Default value:** ``en`` + + The lang some automated entities will use when replying to you. + + 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 + + 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]`` + + 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 + + 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 + + max_nick_length + + **Default value:** ``25`` + + 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. + + muc_history_length + + **Default value:** ``50`` + + Limit the number of messages you want to receive when the + multiuserchat rooms send you recent history + + ``0``: You won't receive any + + ``-1``: You will receive the maximum + + ``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. + + 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. + + plugins_autoload + + **Default value:** ``[empty]`` + + Colon-separated list of plugins to load on startup. + + plugins_conf_dir + + **Default value:** ``[empty]`` + + 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. + + plugins_dir + + **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 + + **Default value:** ``4`` + + 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. + + remote_fifo_path + + **Default value:** ``./poezio.fifo`` + + The path of the FIFO used to send the commands (see the :term:`exec_remote` option). + + resource + + **Default value:** ``[empty]`` + + 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. + + rooms + + **Default value:** ``poezio@muc.poezio.eu`` + + 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. + + roster_group_sort + + **Default value:** ``name`` + + How to sort the roster groups. The principles are the same as :term:`roster_sort` + (see below). + + Available methods are: + * ``reverse``: reverse the current sorting + * ``name``: sort by group name (alphabetical order) + * ``fold``: sort by unfolded/folded + * ``connected``: sort by number of connected contacts + * ``size``: sort by group size + * ``none``: put the "none" group (if any) at the end of the list + + roster_show_offline + + **Default value:** ``false`` + + Set this to true if you want to display the offline contacts too. + + roster_sort + + **Default value:** ``jid:show`` + + How you want the contacts to be sorted inside the roster groups. The given + methods are used sequentially (from left to right), so the last one is the + one on the far right. + + Available methods are : + + * ``reverse``: reverse the current sorting + * ``jid``: sort by JID (alphabetical order) + * ``show``: sort by show (available/away/xa/…) + * ``name``: sort by roster name (if no name, then the bare jid is used) + * ``resource``: sort by resource number + * ``online``: sort by online presence (online or not) + + Those methods can be arranged however you like, and they have to be + 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`` + + If you want to show all the tabs in the Tab bar, even those + with no activity, set to ``true``. Else, set to ``false``. + + show_muc_jid + + **Default value:** ``true`` + + Set this to ``false`` if you want to display only the “user” part of the MUC + jid. E.g. if you have **poezio@muc.poezio.eu**, it will be displayed as + **poezio**. This will be used only if :term:`use_tab_nicks` is set to ``true``. + + show_roster_jids + + **Default value:** ``true`` + + Set this to ``false`` if you want to hide the JIDs in the roster (and keep only + the contact names). If there is no contact name, the JID will still be + displayed. + + show_s2s_errors + + **Default value:** ``true`` + + Show s2s errors in the roster or not. + + show_tab_names + + **Default value:** ``false`` + + If you want to show the tab name in the bottom Tab bar, set this to ``true``. + + show_tab_numbers + + **Default value:** ``true`` + + If you want to disable the numbers in the bottom Tab bar, set this to ``false``. + Note that if both :term:`show_tab_names` and :term:`show_tab_numbers` are set to ``false``, the + numbers will still be displayed. + + show_timestamps + + **Default value:** ``true`` + + Whether or not to display a timestamp before each message. + + 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. + + use_bookmark_method + + **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. + + use_log + + **Default value:** ``true`` + + Set to ``false`` if you don’t want to save logs of all the messages + in files. + + use_pep_nick + + **Default value:** ``true`` + + Use the nickname broadcasted by the user if set to ``true``, and if none + has already been set manually. + + use_remote_bookmarks + + **Default value:** ``true`` + + Use this option to force the use of local bookmarks if needed. + Anything but "false" will be counted as true. + + use_tab_nicks + + **Default value:** ``true`` + + 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. + + theme + + **Default value:** ``[empty]`` + + The name of the theme file (without the .py extension) that will be used. + The file should be located in the theme_dir directory. + + 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:`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. + + This directory will be created at startup if it doesn't exist + + user_list_sort + + **Default value:** ``desc`` + + 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 + + **Default value:** ``20`` + + Size of the vertical tab list. + + vertical_tab_list_sort + + **Default value:** ``desc`` + + 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. + + 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. + + 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 +~~~~~~~~~~~~~~~~~~~~~~~~ +These option can appear in optional sections. These section are named +after a JID. These option will apply only for the given JID. For example +if an option appears in a section named [user@example.com], it will +apply only for the conversations with user@example.com. + +If an option appears in a section named [@example.com], it will apply +for all the conversations with people @example.com, except when the option +is already defined in a [user@example.com] section. + +The priority of settings is thus like this: +user@example.com > @example.com > Poezio (more specific to less specific) + +Note that some of these options can also appear in the global section, +they will be used as a fallback value when no JID-specific option is +found. + +.. code-block:: ini + + [Poezio] + foo = false + [user@example.com] + foo = true + [@example.com] + bar = false + +.. glossary:: + :sorted: + + autorejoin + + **Default value:** ``false`` + + Set to ``true`` if you want to automatically rejoin the + room when you're kicked or banned. + + autorejoin_delay + + **Default value:** ``5`` + + Set to the number of seconds before reconnecting after getting kicked or + banned. ``0``, a negative value, or no value means instant reconnection. + This option only works if :term:`autorejoin` is ``true``. + + disable_beep + + **Default value:** ``false`` + + Disable the beeps triggered by this conversation. Works in MucTab, + PrivateTab and ConversationTab. + + 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. + + display_gaming_notifications + + **Default value:** ``false`` + + If set to ``true``, notifications about the game your are playing + will be displayed in the info buffer as 'Gaming' 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_user_color_in_join_part + + **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. + + 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. + + hide_exit_join + + **Default value:** ``-1`` + + Exact same thing than hide_status_change, except that it concerns + the quit message, and that it will be hidden only if the value is 0. + Default setting means: + - all quit and join notices will be displayed + + hide_status_change + + **Default value:** ``120`` + + Set a number for this setting. + The join AND status-change notices will be + displayed according to this number. + + ``-1``: the notices will ALWAYS be displayed + + ``0``: the notices will NEVER be displayed + + ``n``: On any other number, the notices will only be displayed + if the user involved has talked since the last n seconds + + if the value is incorrect, ``-1`` is assumed + Default setting means that status changes won't be displayed unless + the user talked in the last 2 minutes + + highlight_on + + **Default value:** ``[empty]`` + + A list of words (separated by a colon (:)) that will be + highlighted if said by someone on a room. + + ignore_private + + **Default value:** ``false`` + + 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]`` + + The password needed to join the room. + + private_auto_response + + **Default value:** ``Not in private, please.`` + + The message you want to be sent when someone tries to message you. + + send_chat_states + + **Default value:** ``true`` + + Lets you disable/enable chatstates per-JID. Works in MucTab, PrivateTab + and ConversationTab. + + show_useless_separator + + **Default value:** ``false`` + + If ``true``, show the separator at the bottom of a chat room, even if no one spoke. + + use_log + + **Default value:** ``[empty]`` + + Use logs for this JID or not. No value will make poezio fall back to the + global :term:`use_log` value. + + notify_messages + + **Default value:** ``true`` + + Only for MUC tabs: if true the tab will change its color to notify you when a new message is received. + You will still be notified of highlights. Set to ``false`` if you’re not interested in a room non-highlight notifications. diff --git a/doc/source/index.rst b/doc/source/index.rst index ea744b26..450368b6 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -9,19 +9,17 @@ Poezio documentation Contents: .. toctree:: - :maxdepth: 1 + :maxdepth: 2 install - themes commands - dev/index + configuration misc/index + themes + dev/index .. - configure - ssl usage - themes keys plugins misc |