diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/commands.rst | 34 | ||||
| -rw-r--r-- | doc/source/conf.py | 2 | ||||
| -rw-r--r-- | doc/source/index.rst | 4 | ||||
| -rw-r--r-- | doc/source/usage.rst | 224 |
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. |