summaryrefslogtreecommitdiff
path: root/doc/en/configure.txt
diff options
context:
space:
mode:
authormathieui <mathieui@mathieui.net>2013-04-08 18:52:35 +0200
committermathieui <mathieui@mathieui.net>2013-04-08 18:52:35 +0200
commitbd8d38d711e15d42ac8e797723af5242e4c3f4fb (patch)
treed3ea6da641be1c7e67a3123071cb816933436502 /doc/en/configure.txt
parente5f219d43edbb4b05c8890f81f2f93b90e215a10 (diff)
downloadpoezio-bd8d38d711e15d42ac8e797723af5242e4c3f4fb.tar.gz
poezio-bd8d38d711e15d42ac8e797723af5242e4c3f4fb.tar.bz2
poezio-bd8d38d711e15d42ac8e797723af5242e4c3f4fb.tar.xz
poezio-bd8d38d711e15d42ac8e797723af5242e4c3f4fb.zip
Beginning of the migration to reST documentation
Diffstat (limited to 'doc/en/configure.txt')
-rw-r--r--doc/en/configure.txt671
1 files changed, 0 insertions, 671 deletions
diff --git a/doc/en/configure.txt b/doc/en/configure.txt
deleted file mode 100644
index def86e7f..00000000
--- a/doc/en/configure.txt
+++ /dev/null
@@ -1,671 +0,0 @@
-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 */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 link:keys.html[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 with the form
-======================
-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.
-
-[horizontal]
-
-*add_space_after_completion*:: 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*:: ,
-
- 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*:: [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*:: false
-
- Set to true if you want to automatically rejoin the room when you're kicked.
-
-*autorejoin_delay*:: 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*:: false
-
- Auto-reconnects you when you get disconnected. Should not be necessary, so
- the default is false.
-
-*beep_on*:: 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*:: [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 “certificate” option.
- This option is not affected by “ignore_certificate“ and boths checks
- may be active at the same time.
-
-*certificate*:: [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*:: [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*:: [empty]
-
- 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.
-
-*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
-
-*display_gaming_notifications*:: 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*:: 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*:: 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*:: 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*:: 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*:: true
-
- Set this to false if you don’t want to receive the activity of your contacts
- anymore.
-
-*enable_user_gaming*:: true
-
- Set this to false if you don’t want to receive the gaming activity of your contacts
- anymore.
-
-*enable_user_mood*:: true
-
- Set this to false if you don’t want to receive the mood of your contacts
- anymore.
-
-*enable_user_nick*:: true
-
- Set to false if you don’t want your contacts to hint you their identity.
-
-*enable_user_tune*:: true
-
- If this is set to false, you will no longer be subscribed to tune events,
- and the display_tune_notifications option will be ignored.
-
-*enable_vertical_tab_list*:: false
-
- If true, a vertical list of tabs, with their name, is displayed on the left of
- the screen.
-
-*enable_xhtml_im*:: 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*:: 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 /link documentation for details.
-
-*filter_info_messages*:: [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*:: -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*:: 120
-
- Set a number for this setting.
- The join OR 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 :
- - status changes won't be displayed unless
- the user talked in the last 2 minutes
-
-*hide_user_list*:: 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*:: [empty]
-
- a list of words (separated by a colon (:)) that will be
- highlighted if said by someone on a room
-
-*ignore_certificate*:: 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*:: 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*:: [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 'server' option will be ignored if you specify a JID (Jabber id)
- It should be in the form nickname@server.tld
-
-*lang*:: en
-
- The lang some automated entities will use when replying to you.
-
-*lazy_resize*:: 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*:: 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*:: [empty]
-
- 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
-
-*max_lines_in_memory*:: 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*:: 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*:: 25
-
- The maximum length of the nickname that will be displayed in the
- conversation window.
-
-*muc_history_length*:: 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*:: [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
-
-*plugins_autoload*:: [empty]
-
- Colon-separated list of plugins to load on startup.
-
-*plugins_conf_dir*:: [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*:: [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*:: 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*:: ./poezio.fifo
-
- The path of the FIFO used to send the commands (see the exec_remote option).
-
-*resource*:: [empty]
-
- 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.
-
-*rooms*:: 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 default_nick option will be used if "/nickname" is not specified.
-
-*roster_group_sort*:: name
-
- How to sort the roster groups. The principles are the same as _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*:: false
-
- Set this to true if you want to display the offline contacts too.
-
-*roster_sort*:: 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*:: true
-
- Save the status automatically in the status and status_message options.
-
-*send_chat_states*:: 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*:: true
-
- 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.
-
-*send_os_info*:: 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 information
- Note that this information will not be sent if send_poezio_info is False
-
-*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
-
-*send_time*:: 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*:: false
-
- If true, the history of inputs of the same nature won’t be shared
- between tabs (as in weechat).
-
-*server*:: 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*:: 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*:: 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 use_tab_nicks is set to true.
-
-*show_roster_jids*:: 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*:: true
-
- Show s2s errors in the roster or not.
-
-*show_tab_names*:: false
-
- If you want to show the tab name in the bottom Tab bar, set this to true.
-
-*show_tab_numbers*:: true
-
- 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
-
- Whether or not to display a timestamp before each message.
-
-*status*:: [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*:: [empty]
-
- The status message poezio will send when connecting.
-
-*use_bookmark_method*:: [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*:: true
-
- Set to 'false' if you don’t want to save logs of all the messages
- in files.
-
-*use_pep_nick*:: true
-
- Use the nickname broadcasted by the user if set to true, and if none
- has already been set manually.
-
-*use_remote_bookmarks*:: true
-
- Use this option to force the use of local bookmarks if needed.
- Anything but "false" will be counted as true.
-
-*use_tab_nicks*:: 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*:: [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*:: [empty]
-
- 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
-
-*user_list_sort*:: 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*:: 20
-
- Size of the vertical tab list.
-
-*vertical_tab_list_sort*:: 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*:: 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*:: [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.
-
-.foo is _true_ for *user@example.com* but is _false_ for everyone else
-============================================
-[source,conf]
--------------
-[Poezio]
-foo = false
-[user@example.com]
-foo = true
-[@example.com]
-bar = false
--------------
-============================================
-
-[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.
-
-*display_activity_notifications*:: 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*:: 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*:: 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*:: 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*:: 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*:: -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*:: 120
-
- Set a number for this setting.
- The join OR 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 :
- - status changes won't be displayed unless
- the user talked in the last 2 minutes
-
-*highlight_on*:: [empty]
-
- a list of words (separated by a colon (:)) that will be
- highlighted if said by someone on a room
-
-*ignore_private*:: false
-
- Ignore private messages sent from this room.
-
-*load_log*:: 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*:: [empty]
-
- The password needed to join the room.
-
-*private_auto_response*:: "Not in private, please."
-
- The message you want to be sent when someone tries to message you.
-
-*send_chat_states*:: true
-
- Lets you disable/enable chatstates per-JID. Works in MucTab, PrivateTab
- and ConversationTab.
-
-*show_useless_separator*:: false
-
- If true, show the separator in a chat room, even if no one spoke.
-
-*use_log*:: [empty]
-
- Use logs for this JID or not. No value will make poezio fall back to the
- global value.
-
-*notify_messages*:: 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.