diff options
Diffstat (limited to 'doc/source/usage.rst')
| -rw-r--r-- | doc/source/usage.rst | 224 |
1 files changed, 224 insertions, 0 deletions
diff --git a/doc/source/usage.rst b/doc/source/usage.rst new file mode 100644 index 00000000..65dae4ff --- /dev/null +++ b/doc/source/usage.rst @@ -0,0 +1,224 @@ +Usage +===== + +This page is the main page of the documentation for poezio, explaining how to +use it and describing its interfaces. + +Poezio is composed of tabs which can be of various types. Each tab type has +a distinct interface, list of commands and list of key shortcuts, in addition +to the global commands and key shortcuts. + +The Tab list +~~~~~~~~~~~~ + +Since Poezio 0.7.5, there are now two ways to show the available tabs: + +The old way: horizontal list +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This is the default method. + +On all tabs, you get a line showing the the list of all opened tabs. Each tab +has a number, each time you open a new tab, it gets the next available number. + +.. figure:: ./images/tab_bar.png + :alt: Example of 5 opened tabs + +The new way: vertical list +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On all tabs, you get a pane on the left side of the screen that shows a list +of the opened tabs. As stated above, each tab has a number, and each time you +open a new tab, it gets the next available number. + +.. figure:: ./images/vert_tabs.png + :alt: Example of the vertical tab bar + + +This mode is enabled by setting the +:term:`enable_vertical_tab_list` option to ``true`` in the +configuration file. + +Options for the tab list +^^^^^^^^^^^^^^^^^^^^^^^^ + +The following options are used to configure the behavior of the tab list: + +- :term:`enable_vertical_tab_list` +- :term:`vertical_tab_list_size` +- :term:`vertical_tab_list_sort` +- :term:`show_tab_names` +- :term:`show_tab_numbers` +- :term:`show_inactive_tabs` +- :term:`use_tab_nicks` + +Generalities +~~~~~~~~~~~~ + +:ref:`global-commands` + +The tab numbered **0** is always the **roster** tab, the other tabs can be of any +type. + +.. figure:: ./images/tab_bar.png + :alt: Example of 5 opened tabs + +The status of a tab is represented by its color: + +* **blue** (tab **0**): an inactive tab of any type, nothing new to see + there. +* **purple** (tab **1**): a :ref:`muctab` with at least one new + unread message. +* **green** (tab **2**): a tab of a private conversation (:ref:`privatetab` or :ref:`conversationtab`) + with a new message to read. +* **Cyan** (tab **3**): the current tab. +* **Red** (tab **4**): a :ref:`muctab` with at least one new highlight + message. + +You can go from one tab to another in many ways: + +* ``Ctrl+n`` and ``Ctrl+p`` +* :term:`/win` command +* :term:`/next` and :term:`/prev` commands +* ``Alt`` + a number +* ``Alt+j`` followed by a two-digits number +* ``Alt+e``, this will jump to the next tab with the highest priority. Priority + applies in this order: private message > highlight message > normal message. + +.. _rostertab: + +Roster tab +~~~~~~~~~~ + +:ref:`Specific commands <rostertab-commands>` + +This is a unique tab, always numbered **0**. It contains the list of your +contacts. You can add/remove/edit/search contacts from there, and you can open +a conversation with them. + +Use the **direction arrows** to browse the list, the ``Space`` key to fold or unfold a group +or a contact. + +.. figure:: ./images/roster.png + :alt: The roster tab + +#. The area where information messages are displayed. +#. The actual list of contacts. The first level is group, the second is the + contacts and the third is the resources of you online contacts. +#. More informations about the selected contact. + +.. _muctab: + +MultiUserChat tab +~~~~~~~~~~~~~~~~~ + +:ref:`Specific commands <muctab-commands>` + +This tab contains a multi-user conversation. + +.. figure:: ./images/muc.png + :alt: The MUC tab + +#. The conversation window, this is where all the messages and events + related to the muc will be displayed. It can be scrolled up and down with + ``PageUp`` and ``PageDown``. +#. The participant list. Participants are listed by their role first, and + then alphabetically. + The status of each participant is symbolized using the **color** of the + character on the left of its nick. + That character also shows the chatstate of each participant: + + - ``|``: inactive + - ``X``: composing + - ``A``: active + - ``p``: paused + + The roles and affiliations of the participants are symbolized by the char + before the nick and its color. + The characters define the affiliations, and they mean: + + - ``~``: Owner + - ``&``: Admin + - ``+``: Member + - ``-``: None + + And their color define their roles, and they mean: + + - **Red** : moderator + - **Blue**: participant + - **Grey**: visitor + + The nicks have a random color given by poezio (which can be changed with :term:`/recolor`) + +#. Your information in that MUC (the name of the room, your nick, your role + and affiliation). +#. The topic of the room. + +You can configure the room (if you have the rights to do it) using the +:term:`/configure` command, open a private conversation with someone using the +:term:`/query` command, change or view the topic using the :term:`/topic` command… + +.. _privatetab: + +Private tab +~~~~~~~~~~~ +:ref:`Specific commands <privatetab-commands>` + +This is the tab opened with the :term:`/query` command in a :ref:`muctab`, letting you talk in private +with a participant of a multi-user chat. + +.. figure:: ./images/private.png + :alt: The private tab + +This is just a simple one to one conversation, with a line showing the status, +name and chatstate of the participant. + +.. _conversationtab: + +Conversation tab +~~~~~~~~~~~~~~~~ + +:ref:`Specific commands <conversationtab-commands>` + +A tab opened from the roster or :term:`/message`, to talk in private with one of your contacts. + +.. figure:: ./images/conversation.png + :alt: The conversation tab + +This is also just a simple one to one conversation, with a line showing the status, +name and chatstate of the participant, as well as a line at the top showing the +status message of the contact. Plugins may add some elements to the status line. + +.. _dataformtab: + +Dataforms tab +~~~~~~~~~~~~~ + +This tab lets you view a form receive from a remote entity, edit the values and +send everything back. It is mostly used to configure MUCs with the :term:`/configure` +command but can actually be used for almost anything. + +.. figure:: ./images/data_forms.png + :alt: The dataform tab + +Use the ``Up`` and ``Down`` keys to go from one field to the other, and edit the +value using the ``Space``, ``Left`` or ``Right`` keys, or by entering text. + +You can then send the completed form using ``Ctrl+y`` or cancel using ``Ctrl+g``. + +.. _listtab: + +List tab +~~~~~~~~ + +This tab lists all public rooms on a MUC service. It is currently very limited +but will be improved in the future. There currently is no way to search a room. + +.. figure:: ./images/list.png + :alt: The list tab + +Use the ``Up`` and ``Down`` or ``PageUp`` and ``PageDown`` keys to browse the list, and +use ``Enter`` or ``j`` to join the selected room. + +You can sort the rooms by moving the direction arrows (``←`` or ``→``) and pressing +``Space`` when you are on the appropriate column. |