summaryrefslogtreecommitdiff
path: root/doc/source
diff options
context:
space:
mode:
Diffstat (limited to 'doc/source')
-rw-r--r--doc/source/commands.rst34
-rw-r--r--doc/source/conf.py2
-rw-r--r--doc/source/index.rst4
-rw-r--r--doc/source/usage.rst224
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.