usage.rst 8.14 KB
Newer Older
mathieui's avatar
mathieui committed
1 2
.. _usage:

mathieui's avatar
mathieui committed
3 4 5 6 7 8 9 10 11 12
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.

mathieui's avatar
mathieui committed
13 14
Tab list
~~~~~~~~
mathieui's avatar
mathieui committed
15

mathieui's avatar
mathieui committed
16
There are two ways of showing the open tabs:
mathieui's avatar
mathieui committed
17

mathieui's avatar
mathieui committed
18 19
Vertical list
^^^^^^^^^^^^^
mathieui's avatar
mathieui committed
20

21 22
This is the default method.

mathieui's avatar
mathieui committed
23 24 25 26 27 28 29
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

30 31 32 33 34 35 36 37
Horizontal list
^^^^^^^^^^^^^^^

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
mathieui's avatar
mathieui committed
38

39 40
This mode is enabled by setting the :term:`enable_vertical_tab_list`
option to ``false`` in the configuration file.
mathieui's avatar
mathieui committed
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59

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`

mathieui's avatar
mathieui committed
60 61
:ref:`Global shortcuts <global-keys>`

mathieui's avatar
mathieui committed
62
The tab numbered **0** is always the **Contact list** tab, the other tabs can be of any
mathieui's avatar
mathieui committed
63 64 65 66 67 68 69
type.

.. figure:: ./images/tab_bar.png
    :alt: Example of 5 opened tabs

The status of a tab is represented by its color:

mathieui's avatar
mathieui committed
70
* **Blue** (tab **0**): an inactive tab of any type, nothing new to see
mathieui's avatar
mathieui committed
71
  there.
mathieui's avatar
mathieui committed
72
* **Purple** (tab **1**): a :ref:`muctab` with at least one new
mathieui's avatar
mathieui committed
73
  unread message.
mathieui's avatar
mathieui committed
74
* **Green** (tab **2**): a tab of a private conversation (:ref:`privatetab` or :ref:`conversationtab`)
mathieui's avatar
mathieui committed
75 76 77 78 79 80 81
  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:

mathieui's avatar
mathieui committed
82
* ``Ctrl+n`` (next tab) and ``Ctrl+p`` (previous tab)
mathieui's avatar
mathieui committed
83 84
* :term:`/win` command
* :term:`/next` and :term:`/prev` commands
mathieui's avatar
mathieui committed
85 86
* ``Alt`` + a number (to go to the tab with that number)
* ``Alt+j`` followed by a two-digits number (same)
mathieui's avatar
mathieui committed
87 88
* ``Alt+e``, this will jump to the next tab with the highest priority. Priority
  applies in this order: private message > highlight message > normal message.
mathieui's avatar
mathieui committed
89
* :term:`/close` command to close a tab and go back to the previous one
mathieui's avatar
mathieui committed
90 91 92

.. _rostertab:

mathieui's avatar
mathieui committed
93 94
Contact list tab
~~~~~~~~~~~~~~~~
mathieui's avatar
mathieui committed
95 96 97

:ref:`Specific commands <rostertab-commands>`

mathieui's avatar
mathieui committed
98 99
:ref:`Specific shortcuts <rostertab-keys>`

mathieui's avatar
mathieui committed
100 101
.. note:: The contact list also called a roster in XMPP terms.

mathieui's avatar
mathieui committed
102
This is a unique tab, always numbered **0**. It contains the list of your
mathieui's avatar
mathieui committed
103 104 105
contacts. You can add (:term:`/add`, :term:`/accept`), remove
(:term:`/remove`) and search contacts from there, and you can open
a conversation with them (``Enter`` key).
mathieui's avatar
mathieui committed
106

mathieui's avatar
mathieui committed
107 108
Use the **direction arrows** (↑↓) to browse the list, the ``Space`` key to
fold or unfold a group or a contact.
mathieui's avatar
mathieui committed
109 110

.. figure:: ./images/roster.png
mathieui's avatar
mathieui committed
111
    :alt: The contact list tab
mathieui's avatar
mathieui committed
112

mathieui's avatar
mathieui committed
113 114 115
#. Area where information messages are displayed.
#. Actual list of contacts. The first level is group, the second is the
   contacts and the third is the resources of your online contacts.
116
#. More information about the selected contact.
mathieui's avatar
mathieui committed
117 118 119

.. _muctab:

120 121
Chatroom tab
~~~~~~~~~~~~
mathieui's avatar
mathieui committed
122 123 124

:ref:`Specific commands <muctab-commands>`

mathieui's avatar
mathieui committed
125 126 127 128
:ref:`Specific shortcuts <muctab-keys>`

:ref:`Chat shortcuts <chattab-keys>`

129 130
.. note:: A chatroom is also called a MUC (for Multi-User-Chat) in XMPP terms.

mathieui's avatar
mathieui committed
131 132 133
This tab contains a multi-user conversation.

.. figure:: ./images/muc.png
134
    :alt: The chatroom tab
mathieui's avatar
mathieui committed
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

#. 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

mathieui's avatar
mathieui committed
165
   The nicks have a fixed color assigned using XEP-0392_.
mathieui's avatar
mathieui committed
166

167
#. Your information in that chatroom (the name of the room, your nick, your role
mathieui's avatar
mathieui committed
168 169 170 171 172 173 174 175 176 177 178 179 180
   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>`

mathieui's avatar
mathieui committed
181 182
:ref:`Chat shortcuts <chattab-keys>`

mathieui's avatar
mathieui committed
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198
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>`

mathieui's avatar
mathieui committed
199 200
:ref:`Chat shortcuts <chattab-keys>`

mathieui's avatar
mathieui committed
201 202
A tab opened by interacting with the contact list or :term:`/message`,
to talk in private with one of your contacts.
mathieui's avatar
mathieui committed
203 204 205 206 207 208 209 210 211 212 213 214 215

.. 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
~~~~~~~~~~~~~

mathieui's avatar
mathieui committed
216
:ref:`Specific shortcuts <forms-keys>`
mathieui's avatar
mathieui committed
217

mathieui's avatar
mathieui committed
218
This tab lets you view a form received from a remote entity, edit the values and
219
send everything back. It is mostly used to configure chatrooms with the
mathieui's avatar
mathieui committed
220
:term:`/configure` command but can actually be used for almost anything.
mathieui's avatar
mathieui committed
221 222 223 224 225 226 227 228 229 230 231 232 233 234

.. 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
~~~~~~~~

mathieui's avatar
mathieui committed
235 236
:ref:`Specific shortcuts <muclisttab-keys>`

237
This tab lists all public rooms on a chatroom service (with the :term:`/list` command).
mathieui's avatar
mathieui committed
238 239
It is currently very limited but will be improved in the future. There currently
is no way to search a room.
mathieui's avatar
mathieui committed
240 241 242 243 244 245 246 247 248

.. 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.
mathieui's avatar
mathieui committed
249

mathieui's avatar
mathieui committed
250 251
.. _confirmtab:

mathieui's avatar
mathieui committed
252 253 254 255 256 257 258 259 260 261 262 263 264 265
Confirm tab
~~~~~~~~~~~

This kind of tab is used to prompt a binary choice to the user due to external
events, such as a certificate change:

.. figure:: ./images/cert_warning.png
    :alt: Certificate warning prompt tab

Or a XEP-0070_ validation:

.. figure:: ./images/xep_0070.png
    :alt: XEP-0070 validation tab

mathieui's avatar
mathieui committed
266
.. _bookmarks tab:
mathieui's avatar
mathieui committed
267 268 269 270 271 272 273 274 275 276 277 278

Bookmarks tab
~~~~~~~~~~~~~

This tab can be obtained using :term:`/bookmarks`, it is a graphical interface
for managing bookmarks. You can edit the bookmark address itself, its password,
the storage backend, and the autojoin status. Note that local bookmarks always
have autojoin set to True.

.. figure:: images/bookmark_tab.png
    :alt: Bookmarks tab screenshot

mathieui's avatar
mathieui committed
279
.. _XEP-0070: https://xmpp.org/extensions/xep-0070.html
mathieui's avatar
mathieui committed
280
.. _XEP-0392: https://xmpp.org/extensions/xep-0392.html