summaryrefslogtreecommitdiff
path: root/doc/en
diff options
context:
space:
mode:
Diffstat (limited to 'doc/en')
-rw-r--r--doc/en/configure.txt526
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.