Documentation update

sort the configurations options by theme
make the sidebar fixed

5 files changed, 470 insertions, 366 deletions

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