summaryrefslogtreecommitdiff
path: root/doc/source
diff options
context:
space:
mode:
Diffstat (limited to 'doc/source')
-rw-r--r--doc/source/commands.rst11
-rw-r--r--doc/source/configuration.rst31
-rw-r--r--doc/source/index.rst5
-rw-r--r--doc/source/keys.rst424
-rw-r--r--doc/source/theme/static/basic.css4
-rw-r--r--doc/source/theme/templates/layout.html57
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 %}