Add keys

6 files changed, 457 insertions, 75 deletions

diff --git a/doc/source/commands.rst b/doc/source/commands.rst
index e14f1c3c..6ef5ea1f 100644
--- a/doc/source/commands.rst
+++ b/doc/source/commands.rst
@@ -57,6 +57,14 @@ These commands work in *any* tab.
     /quit
         Just disconnect from the server and exit poezio.
 
+    /plugin
+        **Usage:** ``/load <plugin name>``
+
+        Load a plugin.
+
+    /plugins
+        List the loaded plugins.
+
     /next
         Go to the next room.
 
@@ -150,6 +158,9 @@ These commands work in *any* tab.
 
         Send a custom XML stanza.
 
+    /xml_tab
+        Open an XML tab.
+
     /list
         **Usage:** ``/list [server.tld]``
 
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index a664abb6..fb03e1aa 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -1,12 +1,12 @@
-Configure
-=========
+Configuration
+=============
 
-The configuration is located in the file *~/.config/poezio/poezio.cfg*
+The configuration is located in the file ``~/.config/poezio/poezio.cfg``
 On its first startup, poezio will create that file (and its containing
 directories) with the default configuration. You can edit that file manually
 or use the :term:`/set` command to edit some of its values directly from poezio.
 This file is also used to configure key bindings, but this is explained
-in the *keys* documentation file.
+in the :ref:`keys-page` documentation file.
 
 That file is read at each startup and the configuration is saved when poezio
 is closed.
@@ -26,11 +26,8 @@ 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
@@ -328,7 +325,8 @@ section of this documentation.
         **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.
+        loaded from the log files.
+        ``0`` or a negative value here disable that option.
 
     log_dir
 
@@ -652,14 +650,14 @@ section of this documentation.
 
         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.
+        ``true`` if you want to have them shown instead of the jid of the contact.
 
     theme
 
         **Default value:** ``[empty]``
 
         The name of the theme file (without the .py extension) that will be used.
-        The file should be located in the theme_dir directory.
+        The file should be located in the :term:`themes_dir` directory.
 
         If the file is not found (or no filename is specified) the default
         theme will be used instead
@@ -713,7 +711,8 @@ section of this documentation.
 
 
 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
@@ -754,7 +753,9 @@ found.
         **Default value:** ``5``
 
         Set to the number of seconds before reconnecting after getting kicked or
-        banned. ``0``, a negative value, or no value means instant reconnection.
+        banned.
+       ``0``, a negative value, or no value means instant reconnection.
+
         This option only works if :term:`autorejoin` is ``true``.
 
     disable_beep
@@ -845,7 +846,8 @@ found.
         **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.
+        loaded from the log files.
+        ``0`` or a negative value here disable that option.
 
         No value makes poezio fall back to the global value.
 
@@ -887,3 +889,4 @@ found.
 
         Only for MUC tabs: if true the tab will change its color to notify you when a new message is received.
         You will still be notified of highlights.  Set to ``false`` if you’re not interested in a room non-highlight notifications.
+
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 450368b6..77742cd1 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -6,23 +6,20 @@
 Poezio documentation
 ====================
 
-Contents:
-
 .. toctree::
     :maxdepth: 2
 
     install
     commands
     configuration
+    keys
     misc/index
     themes
     dev/index
 
 ..
     usage
-    keys
     plugins
-    misc
     xep
     dev
 
diff --git a/doc/source/keys.rst b/doc/source/keys.rst
new file mode 100644
index 00000000..213fe28c
--- /dev/null
+++ b/doc/source/keys.rst
@@ -0,0 +1,424 @@
+.. _keys-page:
+
+Keys
+====
+
+This file describes the default keys of poezio and explains how to
+configure them.
+
+By default, most keys manipulating the input (where you type your
+messages and commands) behave like emacs does.
+
+.. note:: Keys are case sensitive. Ctrl-X is not the same than Ctrl-x
+
+Key bindings listing
+--------------------
+Some key bindings are available only in some tabs, others are global.
+
+Global keys
+~~~~~~~~~~~
+These keys work in **any** tab.
+
+**Ctrl-n**: Go to the next tab.
+
+**Ctrl-p**: Go to the previous tab.
+
+**Alt-number**: Go to the tab with that number.
+
+**Alt-j**: Waits for you to type a two-digits number. Go to tab number xx.
+
+**Alt-e**: Go to the tab with a higher priority (private message >
+highlight > message > non-empty input).
+
+**Alt-z**: Go to the previously selected tab.
+
+**Alt-r**: Go to the roster tab.
+
+**F7**: Shrink the information buffer.
+
+**F8**: Grow the information buffer.
+
+**Ctrl-l**: Refresh the screen.
+
+**Alt-D**: Scroll the information buffer up.
+
+**Alt-C**: Scroll the information buffer down.
+
+Input keys
+~~~~~~~~~~
+These keys concern only the inputs.
+
+NOTE: The clipboard is common to all inputs. This lets you cut a text
+from one input to paste it into an other one.
+
+**Ctrl-a**: Move the cursor to the beginning of line.
+
+**Ctrl-e**: Move the cursor to the end of line.
+
+**Ctrl-u**: Delete the text from the start of the input until the cursor
+and save it to the clipboard.
+
+**Ctrl-k**: Delete the text from the cursor until the end of the input
+and save it to the clipboard.
+
+**Ctrl-y**: Insert the content of the clipboard at the cursor position.
+
+**Ctrl-Enter**: Insert a line break. Since the input is only one line,
+the line break is represented by the character ``|`` in it but will be
+sent as the real ``\n`` character.
+
+
+Chat tab input keys
+~~~~~~~~~~~~~~~~~~~
+These keys work in any conversation tab (MultiUserChat, Private or
+Conversation tabs).
+
+**Key Up**: Use the previous message from the message history.
+
+**Key Down**: Use the next message from the message history.
+
+**Page Up**: Scroll up in the conversation by x lines, where x is the
+height of the conversation window - 1.
+
+**Page Down**: Like Page Up, but down.
+
+**Ctrl-b**: Go one line up in the buffer.
+
+**Ctrl-f**: Go one line down in the buffer.
+
+**Ctrl-s**: Go half a screen up in the buffer.
+
+**Ctrl-x**: Go half a screen down in the buffer.
+
+**Alt-/**: Complete what you’re typing using the "recent" words from the
+current conversation, if any.
+
+**Alt-v**: Move the separator at the bottom of the tab.
+
+**Alt-h**: Scroll to the separator, if there is one.
+
+**Ctrl-c**: Insert xhtml formatting.
+
+    You have to press Ctrl-c then a character listed below:
+        - 1: Red
+        - 2: Green
+        - 3: Yellow/Orange
+        - 4: Blue
+        - 5: Pink
+        - 6: Turquoise
+        - b: Bold
+        - o: Stop formatting
+
+MultiUserChat tab input keys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These keys work only in the MultiUserChat tab.
+
+**Alt-u**: Scroll the user list down.
+
+**Alt-y**: Scroll the user list up.
+
+**Alt-p**: Scroll to the previous highlight.
+
+**Alt-n**: Scroll to the next highlight.
+
+**tabulation**: Complete a nick.
+
+MultiUserChat List tab input keys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+These keys work only in the MultiUserChat List tab (obtained with /list <server>).
+
+**Up**: Go up one row.
+
+**Down**: Go down one row.
+
+**j**: Join the MultiUserChat currently selected.
+
+**J**: Join the MultiUserChat currently selected, without giving focus to iuts tab.
+
+**Ctrl-M**: Join the MultiUserChat currently selected (same as "j").
+
+**PageUp**: Scroll a page of chats up.
+
+**PageDown**: Scroll a page of messages down.
+
+
+Roster tab input keys
+~~~~~~~~~~~~~~~~~~~~~
+
+These keys work only in the Roster tab (the tab number 0).
+
+**/**: Open a prompt for commands.
+
+**s**: Start a search on the contacts.
+
+**S**: Start a (slow) search with approximation on the contacts.
+
+**Alt-u**: Move the cursor to the next group.
+
+**Alt-y**: Move the cursor to the previous group.
+
+**Ctrl-c**: Cancel the input (search or command)
+
+.. note:: The following will not work if you can still write things in the
+                input (meaning you previously typed ``s`` or ``/``)
+
+**Space**: Fold/Unfold the current item.
+
+**Up**: Move the cursor down one contact.
+
+**Down**: Move the cursor up one contact.
+
+**o**: Show the offline contacts.
+
+**PageUp**: Scroll a page of contacts up.
+
+**PageDown**: Scroll a page of contacts down.
+
+Data Forms tab keys
+~~~~~~~~~~~~~~~~~~~
+**Ctrl+y**: Validate the form, send it and close the tab.
+
+**Ctrl+g**: Cancel that form (do not send your changes) and close the
+tab.
+
+**Up**: Select the next field.
+
+**Down**: Select the previous field.
+
+**Right/Left**: Switch between possible values, in a jid-multi,
+ list-multi, list-single or text-multi field.
+
+**Space**: Select that option
+
+
+MultiUserChat List tab input keys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+These keys work only in the MultiUserChat List tab (obtained with :term:`/list`).
+
+**Up**: Go up one row.
+
+**Down**: Go down one row.
+
+**j**: Join the MultiUserChat currently selected.
+
+**J**: Join the MultiUserChat currently selected, without giving focus to
+its tab.
+
+**Ctrl-M**: Join the MultiUserChat currently selected (same as ``j``).
+
+
+XML tab input keys
+~~~~~~~~~~~~~~~~~~
+
+These keys only work in the XML tab (obtained with :term:`/xml_tab`)
+
+**Ctrl+k**: Freeze or un-freeze the display in order to have a clear view of
+ the stanzas.
+
+
+.. _key-conf:
+
+Key configuration
+-----------------
+
+Bindings are keyboard shortcut aliases. You can use them
+to define your own keys to replace the default ones.
+where ``^x`` means *Control + x*
+and ``M-x`` means *Alt + x*
+
+To know exactly what the code of a key is, just run
+
+.. code-block:: bash
+
+    python3 src/keyboard.py
+
+And enter any key.
+
+Turn Alt-i into a tab key (completion, etc):
+
+.. code-block:: ini
+
+    M-i = ^I
+
+Actions
+-------
+
+Mapping actions on keys
+~~~~~~~~~~~~~~~~~~~~~~~
+
+One may want to add keyboard shortcuts on actions that were not mapped already
+in poezio. To this effect, you can map the keys on actions using the
+:ref:`key-conf` seen in the previous section.
+
+
+The actions are pseudo-keystrokes, and have to be treated the same way.
+They all begin with an underscore to prevent any possible collision with things
+already defined.
+
+Actions list
+~~~~~~~~~~~~
+
+.. note:: Even if some of these actions are labelled as similar to other
+        keystrokes, remapping the keystrokes will not remap the actions defined here.
+
+**_bookmark**
+
+    Bookmarks the current room.
+
+    Similar to :term:`/bookmark`.
+
+**_bookmark_local** Bookmarks the current room, locally.
+
+    Similar to :term:`/bookmark_local`
+
+**_close_tab**: Closes the current tab.
+
+    This is the same as :term:`/close`. The first tab (the roster) can not be closed.
+
+**_disconnect**: Disconnects poezio from the server.
+
+**_quit**: Exits poezio.
+
+    Similar to :term:`/quit`.
+
+**_reconnect**: Disconnects then reconnects poezio, if possible.
+
+    This is similar to :term:`/reconnect`.
+
+**_redraw_screen**: Redraws the screen.
+
+    This isn’t normally useful, similar to Ctrl-l.
+
+**_reload_theme**: Reloads the theme.
+
+    Similar to :term:`/theme`.
+
+**_remove_bookmark**: Removes the bookmark on the current room.
+
+    Similar to :term:`/remove_bookmark`.
+
+**_room_left**: Goes to the room on the left.
+
+    Similar to the default Ctrl-p action.
+
+**_room_right**: Goes to the room on the right.
+
+    Similar to the default Ctrl-n action.
+
+**_show_roster**: Goes to the roster.
+
+    Similar to Alt-r action.
+
+**_scroll_down**: Scrolls down in the current buffer.
+
+    Similar to PAGEDOWN.
+
+**_scroll_up**: Scrolls up in the current buffer.
+
+    Similar to PAGEUP.
+
+**_scroll_info_down**: Scrolls down in the info buffer.
+
+    Similar to Alt-c.
+
+**_scroll_info_up**: Scrolls up in the info buffer.
+
+    Similar to Alt-d.
+
+**_server_cycle**: Cycles in the current MUC server.
+
+    Similar to :term:`/server_cycle` in a MUC. If you are not in a MUC, you will get
+    an error.
+
+**_show_bookmarks**: Shows the current bookmarks.
+
+    Similar to :term:`/bookmarks`.
+
+**_show_important_room**: Goes to the most important room.
+
+    Similar to Alt-e.
+
+**_show_invitations**: Shows all the pending MUC invitations.
+
+    Similar to :term:`/invitations`.
+
+**_show_plugins**: Shows the currently loaded plugins.
+
+    Similar to :term:`/plugins`.
+
+**_show_xmltab**: Opens an XML tab.
+
+    Similar to :term:`/xml_tab`.
+
+**_toggle_pane**: Toggles the left pane.
+
+    Similar to F4.
+
+Status actions
+~~~~~~~~~~~~~~
+
+**_available**: Sets the status to *available*.
+
+    Similar to ``/status available``.
+
+**_away**: Sets the status to *away*.
+
+    Similar to ``/status away``.
+
+**_chat**: Sets the status to *chat*.
+
+    Similar to ``/status chat``.
+
+**_dnd**: Sets the status to *dnd*.
+
+    Similar to ``/status dnd``.
+
+**_xa**: Sets the status to *xa*.
+
+    Similar to ``/status xa``.
+
+Command execution
+~~~~~~~~~~~~~~~~~
+
+With that kind of actions, you can also execute arbitrary commands, with the
+``_exc_`` keyword.
+
+
+You only have to prefix your command line with ``_exc_``, and without the  ``/``.
+
+
+**/kick Partauche bound on Ctrl-w**:
+
+.. code-block:: ini
+
+    ^W = _exc_kick Partauche
+
+
+That key binding will only work in the tabs defining the command (here, the
+MUC tab), and will show an error message in the others.
+
+Examples
+~~~~~~~~
+
+**Config with user-defined actions**
+
+.. code-block:: ini
+
+    [bindings]
+    ^W = _close_tab
+    M-x = _show_xmltab
+    M-i = _show_important_room
+    M-p = _toggle_pane
+
+**Config with commands mapped**
+
+.. code-block:: ini
+
+    [bindings]
+    M-c = _exc_configure
+    ^Q = _exc_part RAGE QUIT
+    ^J = _exc_join
+    ^F = _exc_load figlet
+    ^R = _exc_load rainbow
+    ^S = _exc_say llollllllllllll
diff --git a/doc/source/theme/static/basic.css b/doc/source/theme/static/basic.css
index 5708b4da..f572584e 100644
--- a/doc/source/theme/static/basic.css
+++ b/doc/source/theme/static/basic.css
@@ -308,6 +308,10 @@ dt:target, .highlight {
     background-color: #fbe54e;
 }
 
+.highlighted {
+    background-color: #fbe54e;
+}
+
 dl.glossary dt {
     font-weight: bold;
     font-size: 1.1em;
diff --git a/doc/source/theme/templates/layout.html b/doc/source/theme/templates/layout.html
index 4306847d..41e0cf28 100644
--- a/doc/source/theme/templates/layout.html
+++ b/doc/source/theme/templates/layout.html
@@ -11,63 +11,6 @@
     <link rel="shortcut icon" type="image/png" href="{{ pathto('_static/poezio.png', 1) }}" />
     {% if not embedded %}<script type="text/javascript" src="{{ pathto('_static/copybutton.js', 1) }}"></script>{% endif %}
     {% if versionswitcher is defined and not embedded %}<script type="text/javascript" src="{{ pathto('_static/version_switch.js', 1) }}"></script>{% endif %}
-    {% if pagename == 'whatsnew/changelog' %}
-    <script type="text/javascript">
-      $(document).ready(function() {
-          // add the search form and bind the events
-          $('h1').after([
-            '<p>Filter entries by content:',
-            '<input type="text" value="" id="searchbox" style="width: 50%">',
-            '<input type="submit" id="searchbox-submit" value="Filter"></p>'
-          ].join('\n'));
-
-          function dofilter() {
-              try {
-                  var query = new RegExp($('#searchbox').val(), 'i');
-              }
-              catch (e) {
-                  return; // not a valid regex (yet)
-              }
-              // find headers for the versions (What's new in Python X.Y.Z?)
-              $('#changelog h2').each(function(index1, h2) {
-                  var h2_parent = $(h2).parent();
-                  var sections_found = 0;
-                  // find headers for the sections (Core, Library, etc.)
-                  h2_parent.find('h3').each(function(index2, h3) {
-                      var h3_parent = $(h3).parent();
-                      var entries_found = 0;
-                      // find all the entries
-                      h3_parent.find('li').each(function(index3, li) {
-                          var li = $(li);
-                          // check if the query matches the entry
-                          if (query.test(li.text())) {
-                              li.show();
-                              entries_found++;
-                          }
-                          else {
-                              li.hide();
-                          }
-                      });
-                      // if there are entries, show the section, otherwise hide it
-                      if (entries_found > 0) {
-                          h3_parent.show();
-                          sections_found++;
-                      }
-                      else {
-                          h3_parent.hide();
-                      }
-                  });
-                  if (sections_found > 0)
-                      h2_parent.show();
-                  else
-                      h2_parent.hide();
-              });
-          }
-          $('#searchbox').keyup(dofilter);
-          $('#searchbox-submit').click(dofilter);
-      });
-    </script>
-    {% endif %}
 {{ super() }}
 {% endblock %}
 {% block footer %}