diff options
Diffstat (limited to 'doc/en')
| -rw-r--r-- | doc/en/configure.txt | 526 |
1 files changed, 260 insertions, 266 deletions
diff --git a/doc/en/configure.txt b/doc/en/configure.txt index b5639c1d..2bc66573 100644 --- a/doc/en/configure.txt +++ b/doc/en/configure.txt @@ -6,7 +6,7 @@ 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 */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. +in the link:keys.html[Keys] documentation file. That file is read at each startup and the configuration is saved when poezio is closed. @@ -24,7 +24,7 @@ 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 avalaible configuration options, their meaning +Here is a list of all the available configuration options, their meaning and their default value. Configuration options @@ -33,128 +33,120 @@ Configuration options Global section options ~~~~~~~~~~~~~~~~~~~~~~ -These option have a sense when they are in the global section. Some of +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. [horizontal] -*server*:: anon.louiz.org - - The server to use for *anonymous* authentication. - Make sure it accepts anonymous authentification - Note that this option doesn’t do anything at all if you’re using your own JID. -*certificate*:: [empty] - - The fingerprint of the SSL certificate as a hexadecimal string, you should - not touch it, except if know what you are doing. +*add_space_after_completion*:: true -*ignore_certificate*:: false + Whether or not to add a space after a completion in the middle of the + input (not at the start of it) - 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. +*after_completion*:: , -*ca_cert_path*:: [empty] + What will be put after the name, when using autocompletion at the + beginning of the input. A space will always be added after that - 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 _certificate_. This option is not - affected by _ignore_certificate_ and boths checks may be active at the same - time. +*alternative_nickname*:: [empty] -*whitespace_interval*:: 300 + 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*:: false - 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. + Set to true if you want to automatically rejoin the room when you're kicked. -*resource*:: [empty] +*autorejoin_delay*:: 5 - 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. + 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*:: false Auto-reconnects you when you get disconnected. Should not be necessary, so the default is false. +*beep_on*:: highlight private -*default_nick*:: [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 - - -*jid*:: [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, nickname registration. - The 'server' option will be ignored if you specify a JID (Jabber identifiant) - It should be in the form nickname@server.tld + 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) -*password*:: [empty] +*ca_cert_path*:: [empty] - A password is needed only if you specified a jid. It will be ignored otherwise - If you leave this empty, the password will be asked at each startup + 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 “certificate” option. + This option is not affected by “ignore_certificate“ and boths checks + may be active at the same time. -*rooms*:: poezio@muc.poezio.eu +*certificate*:: [empty] - the rooms you will join automatically on startup, with associated nickname or not - format : room@server.tld/nickname:room2@server.tld/nickname2 - default_nick will be used if "/nickname" is not specified + The fingerprint of the SSL certificate as a hexadecimal string, you should + not touch it, except if know what you are doing. -*use_bookmark_method*:: [empty] +*custom_host*:: [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. + 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. -*use_remote_bookmarks*:: true +*custom_port*:: [empty] - use this option to force the use of local bookmarks if needed. - Anything but "false" will be counted as true. + A custom port to use instead of the 5222. + This option can be combined with custom_host. + You should not need this in a "normal" use case. -*after_completion*:: , +*default_nick*:: [empty] - What will be put after the name, when using autocompletion at the - beginning of the input. A space will always be added after that + the nick you will use when joining a room with no associated nick + If this is empty, the $USER environnement variable will be used -*add_space_after_completion*:: true +*display_user_color_in_join_part*:: false - Whether or not to add a space after a completion in the middle of the - input (not at the start of it) + If set to true, the color of the nick will be used in MUCs information + messages, instead of the default color from the theme. -*max_nick_length*:: 25 +*enable_vertical_tab_list*:: false - The maximum length of the nickname that will be displayed in the - conversation window. + If true, a vertical list of tabs, with their name, is displayed on the left of + the screen. -*show_timestamps*:: true +*enable_xhtml_im*:: true - Whether or not to display a timestamp before each message. + 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. -*words*:: [empty] +*exec_remote*:: false - 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. + 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 /link documentation for details. -*highlight_on*:: [empty] +*filter_info_messages*:: [empty] - a list of words (separated by a colon (:)) that will be - highlighted if said by someone on a room + 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. -*enable_xhtml_im*:: true +*hide_exit_join*:: -1 - 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. + 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*:: 120 @@ -170,23 +162,22 @@ section of this documentation. - status changes won't be displayed unless the user talked in the last 2 minutes -*hide_exit_join*:: -1 +*hide_user_list*:: false - 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 + 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 -*send_initial_presence*:: true +*highlight_on*:: [empty] - Send initial presence (normal behaviour). If false, you will not send nor - receive any presence that is not directed (through /presence) or sent by a - MUC. + a list of words (separated by a colon (:)) that will be + highlighted if said by someone on a room -*display_user_color_in_join_part*:: false +*ignore_certificate*:: 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. + 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*:: error roster warning help info @@ -196,50 +187,49 @@ section of this documentation. appear. A list of message types that should make the information buffer grow - Possible values; error, roster, warning, info, help + Possible values: error, roster, warning, info, help -*popup_time*:: 4 +*jid*:: [empty] - 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 + 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 'server' option will be ignored if you specify a JID (Jabber id) + It should be in the form nickname@server.tld -*hide_user_list*:: false +*lazy_resize*:: 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 + 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 -*filter_info_messages*:: [empty] +*load_log*:: 10 - 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. + 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. -*autorejoin*:: false +*log_dir*:: [empty] - set to 'true' if you want to automatically rejoin the - room when you're kicked. + If 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 -*autorejoin_delay*:: 5 +*max_lines_in_memory*:: 2048 - Set to the number of seconds before reconnecting after getting kicked. - 0, a negative value, or no value means you instant reconnection. - This option only works if autorejoin is enabled. + Configure the number of maximum lines (for each tab) that + can be kept in memory. If poezio consumes too much memory, lower these + values -*alternative_nickname*:: [empty] +*max_messages_in_memory*:: 2048 - 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. - Else, 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_" + 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*:: 25 + + The maximum length of the nickname that will be displayed in the + conversation window. *muc_history_length*:: 50 @@ -250,56 +240,60 @@ section of this documentation. 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 - -*use_log*:: true + maximum too. - set to 'false' if you don’t want to save logs of all the messages - in files. +*password*:: [empty] -*load_log*:: 200 + A password is needed only if you specified a jid. It will be ignored otherwise + If you leave this empty, the password will be asked at each startup - 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. +*plugins_autoload*:: [empty] -*log_dir*:: [empty] + Space separated list of plugins to load on startup. - If 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 +*plugins_dir*:: [empty] -*show_inactive_tabs*:: true + 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 you want to show all the tabs in the Tab bar, even those - with no activity, set to true. Else, set to false +*popup_time*:: 4 -*show_tab_names*:: false + 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. - If you want to show the tab name in the bottom Tab bar, set this to true. +*remote_fifo_path*:: ./poezio.fifo -*show_tab_numbers*:: true + The path of the FIFO used to send the commands (see the exec_remote option). - If you want to disable the numbers in the bottom Tab bar, set this to false. - Note that if both show_tab_names and show_tab_numbers are set to false, the - numbers will still be displayed. +*resource*:: [empty] -*use_tab_nicks*:: true + The resource you will use. If it's empty, your resource will be chosen + (most likely randomly) by the server. t is not recommended to use a + resource that is easy to guess, because it can lead to presence leak. - 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. +*rooms*:: poezio@muc.poezio.eu -*show_muc_jid*:: true + the rooms you will join automatically on startup, with associated + nickname or not. + Format : room@server.tld/nickname:room2@server.tld/nickname2 + The default_nick option will be used if "/nickname" is not specified. - 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 use_tab_nicks is set to true. +*roster_group_sort*:: name -*show_roster_jids*:: true + How to sort the roster groups. The principles are the same as _roster_sort_ + (see below). - 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. + 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*:: false @@ -323,140 +317,138 @@ section of this documentation. separated by colons (":"). If there are more than 3 or 4 chained sorting methods, your sorting is most likely inefficient. -*roster_group_sort*:: name +*send_chat_states*:: true - How to sort the roster groups. The principles are the same as _roster_sort_ - (see above). + 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. - 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 +*send_initial_presence*:: true -*beep_on*:: highlight private + Send initial presence (normal behaviour). If false, you will not send nor + receive any presence that is not directed (through /presence) or sent by a + MUC. - 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) +*send_os_info*:: true -*themes_dir*:: [empty] + 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 information + Note that this information will not be sent if send_poezio_info is False - If 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 +*send_poezio_info*:: 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 -*theme*:: [empty] +*send_time*:: true - 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 + if true, your current time will be sent if asked + Set to false if you don't want people to know that information -*enable_vertical_tab_list*:: false +*server*:: anon.louiz.org - If true, a vertical list of tabs, with their name, is displayed on the left of - the screen. + 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. -*vertical_tab_list_size*:: 20 +*show_inactive_tabs*:: true -*vertical_tab_list_sort*:: desc + If you want to show all the tabs in the Tab bar, even those + with no activity, set to true. Else, set to false - 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. +*show_muc_jid*:: true -*user_list_sort*:: desc + 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 use_tab_nicks is set to true. - 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. +*show_roster_jids*:: true -*send_chat_states*:: 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. - 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. +*show_tab_names*:: false + If you want to show the tab name in the bottom Tab bar, set this to true. -*send_poezio_info*:: true +*show_tab_numbers*:: 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 + If you want to disable the numbers in the bottom Tab bar, set this to false. + Note that if both show_tab_names and show_tab_numbers are set to false, the + numbers will still be displayed. +*show_timestamps*:: true -*send_os_info*:: true + Whether or not to display a timestamp before each message. - 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 information - Note that this information will not be sent if send_poezio_info is False +*use_bookmark_method*:: [empty] -*send_time*:: true + 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 true, your current time will be sent if asked - Set to false if you don't want people to know that information +*use_log*:: true + Set to 'false' if you don’t want to save logs of all the messages + in files. -*max_messages_in_memory*:: 2048 +*use_remote_bookmarks*:: true - Configure the number of maximum messages (for each tab) that - can be kept in memory. If poezio consumes too much memory, lower these - values + Use this option to force the use of local bookmarks if needed. + Anything but "false" will be counted as true. -*max_lines_in_memory*:: 2048 +*use_tab_nicks*:: true - Configure the number of maximum lines (for each tab) that - can be kept in memory. If poezio consumes too much memory, lower these - values + 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. -*lazy_resize*:: true +*theme*:: [empty] - 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 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 -*custom_host*:: [empty] +*themes_dir*:: [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. + If 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 -*custom_port*:: [empty] +*user_list_sort*:: desc - A custom port to use instead of the 5222. - This option can be combined with custom_host. - You should not need this in a "normal" use case. + 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. -*plugins_autoload*:: [empty] +*vertical_tab_list_size*:: 20 - Space separated list of plugins to load on startup. + Size of the vertical tab list. -*plugins_dir*:: [empty] +*vertical_tab_list_sort*:: desc - 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 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. -*exec_remote*:: false +*whitespace_interval*:: 300 - 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 /link documentation for details. + 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. -*remote_fifo_path*:: ./poezio.fifo +*words*:: [empty] - The path of the FIFO used to send the commands (see the exec_remote option). + 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 @@ -481,24 +473,28 @@ foo = true ------------- ============================================ +[horizontal] +*autorejoin*:: false + + Set to 'true' if you want to automatically rejoin the + room when you're kicked or banned. + +*autorejoin_delay*:: 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 autorejoin is enabled. + *disable_beep*:: false Disable the beeps triggered by this conversation. Works in MucTab, PrivateTab and ConversationTab. -*send_chat_states*:: true - - Lets you disable/enable chatstates per-JID. Works in MucTab, PrivateTab and ConversationTab. - *display_user_color_in_join_part*:: 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. -*show_useless_separator*:: false - - If true, show the separator in a chat room, even if no one spoke. - *hide_exit_join*:: -1 Exact same thing than hide_status_change, except that it concerns @@ -533,19 +529,17 @@ foo = true The message you want to be sent when someone tries to message you. -*use_log*:: [empty] +*send_chat_states*:: true - Use logs for this JID or not. No value will make poezio fall back to the - global value. + Lets you disable/enable chatstates per-JID. Works in MucTab, PrivateTab + and ConversationTab. -*autorejoin*:: false +*show_useless_separator*:: false - Set to 'true' if you want to automatically rejoin the - room when you're kicked or banned. + If true, show the separator in a chat room, even if no one spoke. -*autorejoin_delay*:: 5 +*use_log*:: [empty] - 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 autorejoin is enabled. + Use logs for this JID or not. No value will make poezio fall back to the + global value. |