usage.rst 7.77 KB
Newer Older
mathieui's avatar
mathieui committed
1
2
3
4
5
6
7
8
9
10
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
11
12
Tab list
~~~~~~~~
mathieui's avatar
mathieui committed
13

mathieui's avatar
mathieui committed
14
There are two ways of showing the open tabs:
mathieui's avatar
mathieui committed
15

mathieui's avatar
mathieui committed
16
17
Horizontal list
^^^^^^^^^^^^^^^
mathieui's avatar
mathieui committed
18
19
20
21
22
23
24
25
26

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

mathieui's avatar
mathieui committed
27
28
Vertical list
^^^^^^^^^^^^^
mathieui's avatar
mathieui committed
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

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`

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

mathieui's avatar
mathieui committed
62
63
64
65
66
67
68
69
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:

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
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
  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>`

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

mathieui's avatar
mathieui committed
99
This is a unique tab, always numbered **0**. It contains the list of your
mathieui's avatar
mathieui committed
100
101
102
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
103

mathieui's avatar
mathieui committed
104
105
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
106
107
108
109

.. figure:: ./images/roster.png
    :alt: The roster tab

mathieui's avatar
mathieui committed
110
111
112
#. 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.
mathieui's avatar
mathieui committed
113
114
115
116
117
118
119
120
121
#. More informations about the selected contact.

.. _muctab:

MultiUserChat tab
~~~~~~~~~~~~~~~~~

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

mathieui's avatar
mathieui committed
122
123
124
125
:ref:`Specific shortcuts <muctab-keys>`

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

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

mathieui's avatar
mathieui committed
176
177
:ref:`Chat shortcuts <chattab-keys>`

mathieui's avatar
mathieui committed
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
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
194
195
:ref:`Chat shortcuts <chattab-keys>`

mathieui's avatar
mathieui committed
196
197
198
199
200
201
202
203
204
205
206
207
208
209
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
~~~~~~~~~~~~~

mathieui's avatar
mathieui committed
210
:ref:`Specific shortcuts <forms-keys>`
mathieui's avatar
mathieui committed
211

mathieui's avatar
mathieui committed
212
213
214
This tab lets you view a form received 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.
mathieui's avatar
mathieui committed
215
216
217
218
219
220
221
222
223
224
225
226
227
228

.. 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
229
230
:ref:`Specific shortcuts <muclisttab-keys>`

mathieui's avatar
mathieui committed
231
232
233
This tab lists all public rooms on a MUC service (with the :term:`/list` command).
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
234
235
236
237
238
239
240
241
242

.. 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
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257

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
258
.. _bookmarks tab:
mathieui's avatar
mathieui committed
259
260
261
262
263
264
265
266
267
268
269
270

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
271
.. _XEP-0070: https://xmpp.org/extensions/xep-0070.html