Add the usage help

4 files changed, 251 insertions, 13 deletions

diff --git a/doc/source/commands.rst b/doc/source/commands.rst
index 6ef5ea1f..ad8eb7d0 100644
--- a/doc/source/commands.rst
+++ b/doc/source/commands.rst
@@ -1,15 +1,15 @@
 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
 ~~~~~~~~~~~~~~~~
diff --git a/doc/source/conf.py b/doc/source/conf.py
index f49f8015..265d5482 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -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
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 77742cd1..1cb7485b 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -10,15 +10,15 @@ Poezio documentation
     :maxdepth: 2
 
     install
-    commands
     configuration
+    usage
+    commands
     keys
     misc/index
     themes
     dev/index
 
 ..
-    usage
     plugins
     xep
     dev
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.