diff options
| -rw-r--r-- | doc/source/commands.rst | 11 | ||||
| -rw-r--r-- | doc/source/configuration.rst | 31 | ||||
| -rw-r--r-- | doc/source/index.rst | 5 | ||||
| -rw-r--r-- | doc/source/keys.rst | 424 | ||||
| -rw-r--r-- | doc/source/theme/static/basic.css | 4 | ||||
| -rw-r--r-- | doc/source/theme/templates/layout.html | 57 |
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 %} |