usage.rst 6.69 KB
Newer Older
mathieui's avatar
mathieui committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 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.