Commit 975dcb4b authored by mathieui's avatar mathieui

Add the usage help

parent fe16bd78
Commands
========
Commands start with the **/** character and can take a list of any number
Commands start with the ``/`` character and can take a list of any number
of arguments, separated by spaces. If an argument should contain a space,
you can use the **"** character to surround this argument.
you can use the ``"`` character to surround this argument.
The commands described in this page are shown like this:
``/command <mandatory argument> [optional argument]``
You can get the same help as below from inside poezio with the **/help** command.
You can get the same help as below from inside poezio with the :term:`/help` command.
.. note:: Use command parameters like this:
......@@ -17,6 +17,8 @@ You can get the same help as below from inside poezio with the **/help** command
- If the command takes several agrguments, you need to put quotes around arguments containing special chars such as backslashes or quotes
- If the command always takes only one argument, then do not use quotes even for words containing special chars
.. _global-commands:
Global commands
~~~~~~~~~~~~~~~
......@@ -164,7 +166,7 @@ These commands work in *any* tab.
/list
**Usage:** ``/list [server.tld]``
Get the list of public chatrooms in the specified server
Get the list of public chatrooms in the specified server (open a :ref:`listtab`)
/message
**Usage:** ``/message <jid> [optional message]``
......@@ -223,6 +225,8 @@ These commands work in *any* tab.
which can’t be closed.
.. _chattab-commands:
Chat tab commands
~~~~~~~~~~~~~~~~~
......@@ -252,6 +256,8 @@ These commands will work in any conversation tab (MultiUserChat, Private, or
/clear
Clear the current buffer.
.. _muctab-commands:
MultiUserChat tab commands
~~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -283,7 +289,7 @@ MultiUserChat tab commands
/query
**Usage:** ``/query <nick> [message]``
Open a private conversation with <nick>. This nick
Open a :ref:`privatetab` with <nick>. This nick
has to be present in the room you’re currently in. If you specified a message
after the nickname, it will be sent to this user.
......@@ -327,12 +333,14 @@ MultiUserChat tab commands
room or the given jid (usually its XMPP client and Operating System).
/configure
Configure the current room through a form.
Configure the current room through a form (Open a :ref:`dataformtab`).
/names
Get the list of the users in the room, their number, and the list
of the people assuming different roles.
.. _privatetab-commands:
Private tab commands
~~~~~~~~~~~~~~~~~~~~
......@@ -349,6 +357,8 @@ Private tab commands
Get the software version of the current interlocutor (usually its
XMPP client and Operating System).
.. _conversationtab-commands:
Normal Conversation tab commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -365,6 +375,8 @@ Normal Conversation tab commands
Get the software version of the current interlocutor (usually its
XMPP client and Operating System).
.. _rostertab-commands:
Roster tab commands
~~~~~~~~~~~~~~~~~~~
.. glossary::
......@@ -455,14 +467,16 @@ Roster tab commands
/export
**Usage:** ``/export [/path/to/file]``
Export your contacts into /path/to/file if
specified, or $HOME/poezio_contacts if not.
Export your contacts into :file:`/path/to/file` if
specified, or :file:`$HOME/poezio_contacts` if not.
/import
**Usage:** ``/import [/path/to/file]``
Import your contacts from /path/to/file if
specified, or $HOME/poezio_contacts if not.
Import your contacts from :file:`/path/to/file` if
specified, or :file:`$HOME/poezio_contacts` if not.
.. _xmltab-commands:
XML tab commands
~~~~~~~~~~~~~~~~
......
......@@ -154,7 +154,7 @@ html_static_path = ['theme/static']
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
html_split_index = True
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
......
......@@ -10,15 +10,15 @@ Poezio documentation
:maxdepth: 2
install
commands
configuration
usage
commands
keys
misc/index
themes
dev/index
..
usage
plugins
xep
dev
......
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.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment