summaryrefslogtreecommitdiff
path: root/doc/en
diff options
context:
space:
mode:
Diffstat (limited to 'doc/en')
-rw-r--r--doc/en/install.txt40
-rw-r--r--doc/en/keys.txt161
-rw-r--r--doc/en/usage.txt343
3 files changed, 523 insertions, 21 deletions
diff --git a/doc/en/install.txt b/doc/en/install.txt
index 75cc0ea8..4338afef 100644
--- a/doc/en/install.txt
+++ b/doc/en/install.txt
@@ -5,31 +5,44 @@ Install
Poezio in the GNU/Linux distributions
-------------------------------------
-As far as I know, Poezio is available in the following distributions, you just have to install it by using the package manager of the distribution, if you're using one of these.
-
-* *Archlinux*: A poezio and poezio-git packages are in AUR (use your favourite AUR wrapper to install them)
-* *Frugalware*: Just use pacmang-g2 to install the poezio package. (Thanks to its maintainer, Kooda)
+As far as I know, Poezio is available in the following distributions, you just
+ have to install it by using the package manager of the distribution, if you're
+ using one of these.
+
+* *Archlinux*: A poezio and poezio-git packages are in AUR (use your favourite
+ AUR wrapper to install them)
+* *Frugalware*: Just use pacmang-g2 to install the poezio package. (Thanks to
+ its maintainer, Kooda)
* *Debian*: Use an other distro.
-(If an other distribution provides a poezio package, please tell us and we will add it to the list)
+(If an other distribution provides a poezio package, please tell us and we will
+ add it to the list)
Install poezio from the sources
-------------------------------
-You can download poezio's https://dev.louiz.org/project/poezio/download[stable sources] or fetch the development version (trunk), using git:
+You can download poezio's https://dev.louiz.org/project/poezio/download[stable
+ sources] or fetch the development version (trunk), using git:
============================
git clone https://git.louiz.org/poezio
============================
-In order for poezio to correctly work, you need the libs SleekXMPP and dnspython. You can install them by downloading it from the https://github.com/fritzy/SleekXMPP/[SleekXMPP] page and the http://www.dnspython.org/[dnspython] page , but you'll need the development versions. Alternatively, you can download poezio's sources including SleekXMPP and dnspython, that's the easier way.
+In order for poezio to correctly work, you need the libs SleekXMPP and
+ dnspython. You can install them by downloading it from the
+ https://github.com/fritzy/SleekXMPP/[SleekXMPP] page and the
+ http://www.dnspython.org/[dnspython] page , but you'll need the development
+ versions. Alternatively, you can download poezio's sources including SleekXMPP
+ and dnspython, that's the easier way.
-As for dnspython, you will have to use our python3 fork, or poke them to accept patches.
+As for dnspython, you will have to use our python3 fork, or poke them to accept
+ patches.
=== Dependencies ===
-If you want to install SleekXMPP and dnspython yourself, follow these instructions. Else, go to the next section.
+If you want to install SleekXMPP and dnspython yourself, follow these
+ instructions. Else, go to the next section.
Download SleekXMPP
@@ -51,7 +64,8 @@ python3 setup.py build
su -c "python3 setup.py install"
============================
-Clone the repository at http://hg.louiz.org/dnspython (this is a fork, because upstream is unresponsive and didn’t fix an important bug).
+Clone the repository at http://hg.louiz.org/dnspython (this is a fork, because
+ upstream is unresponsive and didn’t fix an important bug).
============================
hg clone http://hg.louiz.org/dnspython
@@ -68,12 +82,14 @@ su -c "python3 setup.py install"
=== Poezio installation ===
-If you skipped the installation of the dependencies and you only want to test poezio without a system-wide install, do, in the _poezio_ directory:
+If you skipped the installation of the dependencies and you only want to test
+ poezio without a system-wide install, do, in the _poezio_ directory:
============================
sh update.sh
============================
-If you have git and hg installed, it will download and update locally the libraries for you.
+If you have git and hg installed, it will download and update locally the
+ libraries for you.
If you don't want to install poezio but just test it, do:
diff --git a/doc/en/keys.txt b/doc/en/keys.txt
index eaae961d..109e5df5 100644
--- a/doc/en/keys.txt
+++ b/doc/en/keys.txt
@@ -7,12 +7,14 @@ configure them.
By default, most keys manipulating the input (where you type your
messages and commands) behave like emacs does.
-Note that keys are case sensitive. Ctrl-X is not the same than Ctrl-x
+NOTE: keys are case sensitive. Ctrl-X is not the same than Ctrl-x
+
Key bindings listing
--------------------
Some key bindings are available only in some tabs, others are global.
+
Global keys
~~~~~~~~~~~
These keys work in *any* tab.
@@ -21,44 +23,185 @@ These keys work in *any* tab.
*Ctrl-p*:: Go to the previous tab.
-*Alt-number*:: Go to tab number x.
+*Alt-number*:: Go to the tab with that number.
*Alt-j*:: Waits for you to type a two-digits number. Go to tab number xx.
+*Alt-e*:: Go to the tab with a higher priority (private message >
+ highlight > message > non-empty input).
+
+*Alt-z*:: Go to the previously selected tab.
+
+*Alt-r*:: Go to the roster tab.
+
+*F7*:: Shrink the information buffer.
+
+*F8*:: Grow the information buffer.
+
+*Ctrl-l*:: Refresh the screen.
+
+
Input keys
~~~~~~~~~~
These keys concern only the inputs.
+NOTE: The clipboard is common to all inputs. This lets you cut a text
+from one input to paste it into an other one.
+
*Ctrl-a*:: Move the cursor to the beginning of line.
*Ctrl-e*:: Move the cursor to the end of line.
+*Ctrl-u*:: Delete the text from the start of the input until the cursor
+ and save it to the clipboard.
+
+*Ctrl-k*:: Delete the text from the cursor until the end of the input
+ and save it to the clipboard.
+
+*Ctrl-y*:: Insert the content of the clipboard at the cursor position.
+
+
Chat tab input keys
~~~~~~~~~~~~~~~~~~~~~
-These keys work in any conversation tab (MultiUserChat, Private or Conversation tabs)
+These keys work in any conversation tab (MultiUserChat, Private or
+Conversation tabs).
*Key Up*:: Use the previous message from the message history.
*Key Down*:: Use the next message from the message history.
-*Page Up*:: Scroll up in the conversation by x lines, where x is the height of the conversation window - 1.
+*Page Up*:: Scroll up in the conversation by x lines, where x is the
+height of the conversation window - 1.
+
+*Page Down*:: Like Page Up, but down.
+
+*Alt-/*:: Complete what you’re typing using the "recent" words from the
+ current conversation, if any.
+
+*Alt-v*:: Move the separator at the bottom of the tab.
+
+
+MultiUserChat tab input keys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These keys work only in the MultiUserChat tab.
+
+*Alt-u*:: Scroll the user list down.
+
+*Alt-y*:: Scroll the user list up.
+
+*tabulation*:: Complete a nick.
+
+*Ctrl-c*:: Insert xhtml formatting. You have to press Ctrl-c then a character
+ listed below:
+- 1: Red
+- 2: Green
+- 3: Yellow/Orange
+- 4: Blue
+- 5: Pink
+- 6: Turquoise
+- b: Bold
+- o: Stop formatting
+
+
+MultiUserChat List tab input keys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+These keys work only in the MultiUserChat List tab (obtained with /list <server>).
+
+*Up*:: Go up one row.
+
+*Down*:: Go down one row.
+
+*j*:: Join the MultiUserChat currently selected.
+
+*J*:: Join the MultiUserChat currently selected, without giving focus to iuts tab.
+
+*Ctrl-M*:: Join the MultiUserChat currently selected (same as "j").
+
+*PageUp*:: Scroll a page of chats up.
+
+*PageDown*:: Scroll a page of messages down.
+
+
+Roster tab input keys
+~~~~~~~~~~~~~~~~~~~~~
+
+These keys work only in the Roster tab (the tab number 0).
+
+*/*:: Open a prompt for commands.
+
+*s*:: Start a search on the contacts.
+
+*S*:: Start a (slow) search with approximation on the contacts.
+
+*Alt-u*:: Move the cursor to the next group.
+
+*Alt-y*:: Move the cursor to the previous group.
+
+*Ctrl-c*:: Cancel the input (search or command)
+
+NOTE: The following will not work if you can still write things in the
+input (meaning you previously typed _s_ or _/_):
+
+*Space*:: Fold/Unfold the current item.
+
+*Up*:: Move the cursor down one contact.
+
+*Down*:: Move the cursor up one contact.
+
+*o*:: Show the offline contacts.
+
+*PageUp*:: Scroll a page of contacts up.
+
+*PageDown*:: Scroll a page of contacts down.
+
+
+Data Forms tab keys
+~~~~~~~~~~~~~~~~~~~
+*Ctrl+y*:: Validate the form, send it and close the tab.
+
+*Ctrl+g*:: Cancel that form (do not send your changes) and close the
+ tab.
+
+*Up*:: Select the next field.
+
+*Down*:: Select the previous field.
+
+*Right/Left*:: Switch between possible values, in a jid-multi,
+ list-multi, list-single or text-multi field.
+
+*Space*:: Select that option
+
+
+MultiUserChat List tab input keys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+These keys work only in the MultiUserChat List tab (obtained with /list
+<server>).
+
+*Up*:: Go up one row.
+
+*Down*:: Go down one row.
+
+*j*:: Join the MultiUserChat currently selected.
+
+*J*:: Join the MultiUserChat currently selected, without giving focus to
+ iuts tab.
-*Page Down*:: Likfe Page Up, but down.
+*Ctrl-M*:: Join the MultiUserChat currently selected (same as _j_).
-*Alt-/*:: Complete what you’re typing using the "recent" words from the current conversation, if any.
Key configuration
-----------------
Bindings are keyboard shortcut aliases. You can use them
to define your own keys to replace the default ones.
-where ^x means Control + x
-and M-x means Alt + x
+where _^x_ means _Control + x_
+and _M-x_ means _Alt + x_
To know exactly what the code of a key is, just run
==================
python3 src/keyboard.py
==================
-And enter any keys
+And enter any key.
.Turn Alt-i into a tab key (completion, etc)
==================
diff --git a/doc/en/usage.txt b/doc/en/usage.txt
new file mode 100644
index 00000000..f11ab5ed
--- /dev/null
+++ b/doc/en/usage.txt
@@ -0,0 +1,343 @@
+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.
+
+Tabs
+----
+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.
+
+
+image::../images/tab_bar.png[title="Example of 5 opened tabs"]
+
+The tab numbered _0_ is always the _roster_ tab, the other tabs can be of any
+type.
+
+
+The status of a tab is represented by its color:
+
+* *[navy]#blue#* (tab _0_): an inactive tab of any type, nothing new to see
+ there.
+* *[purple]#purple#* (tab _1_): a MultiUserChat tab with at least one new
+ unread message.
+* *[green]#green#* (tab _2_): a tab of a private conversation with a new
+ message to read.
+* *[teal]#cyan#* (tab _3_): the current tab.
+* *[red]#red#* (tab _4_): a MultiUserChat tab with at least one new hightlight
+ message.
+
+You can go from one tab to another in many ways:
+
+* Ctrl+n and Ctrl+p
+* <<command-win, win>> command
+* <<command-next, next>> and <<command-prev, 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.
+
+Roster tab
+~~~~~~~~~~
+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 one of them.
+
+Use the _arrows_ to browse the list, the _space_ key to fold or unfold a group
+or a contact.
+
+image::../images/roster.png["The roster tab", title="The roster tab"]
+
+* _1_: The area where information messages are displayed.
+* _2_: 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.
+* _3_: More informations about the selected contact.
+
+MultiUserChat tab
+~~~~~~~~~~~~~~~~~
+
+This tab contains a multi-users conversation.
+
+image::../images/muc.png["The MUC tab", title="The MUC tab"]
+
+* _1_: 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.
+* _2_: The participant list. Participants are listed by their role first, and
+ then alphabetically.
+ In the default theme, The nick colors mean:
+ - Red: moderator
+ - Blue: participant
+ - gray: visitor +
+ +
+ 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
+* _3_: Your information in that MUC (the name of the room, your nick, your role
+ and affiliation).
+* _4_: The topic of the room.
+
+You can configure the room (if you have the rights to do it) using the
+_/configure_ command, open a private conversation with someone using the
+_/query_ command, change or view the topic using the _/topic_ command…
+
+Private tab
+~~~~~~~~~~~
+This is the tab opened with the _/query_ command, letting you talk in private
+with a participant of a multi-users chat.
+
+image::../images/private.png["The private tab", title="The private tab"]
+
+This is just a simple one to one conversation, with a line showing the status,
+name and chatstate of the participant.
+
+Conversation tab
+~~~~~~~~~~~~~~~~
+A tab opened from the roster, to talk in private with one of your contacts.
+
+image::../images/conversation.png["The conversation tab", title="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.
+
+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 _/configure_
+command but can actually be used for almost anything.
+
+image::../images/data_forms.png["The dataform tab", title="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_.
+
+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
+or even to sort them.
+
+image::../images/list.png["The list tab", title="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.
+
+Commands
+--------
+
+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.
+
+The commands described in this page are shown like this:
+
+===========================================================
+/command <mandatory argument> [optional argument]
+===========================================================
+
+You can get the same help as below with the _/help_ command.
+
+
+Global commands
+~~~~~~~~~~~~~~~
+
+These commands work in *any* tab.
+
+*/help [command]*:: If called without an argument, this command will list the
+ available commands. If it has a valid command as an argument, this command
+ will show the usage and the help for the given command.
+
+*/join [room_name][@server][/nick] [password]*:: Join the specified room. You
+ can specify a nickname after a slash (/). If no nickname is specified, you
+ will use the default_nick in the configuration file. You can omit the room
+ name: you will then join the room you're looking at (useful if you were
+ kicked). You can also provide a room_name without specifying a server, the
+ server of the room you're currently in will be used. You can also provide a
+ password to join the room.
+
+- Examples:
+* /join room@server.tld
+* /join room@server.tld/John
+* /join room2
+* /join /me_again
+* /join
+* /join room@server.tld/my_nick password
+* /join / password
+
+*/exit*:: Just disconnect from the server and exit poezio.
+
+*/quit*:: Like /exit.
+
+[[command-next]]
+*/next*:: Go to the next room.
+
+[[command-prev]]
+*/prev*:: Go to the previous room.
+
+[[command-win]]
+*/win <number>*:: Go to the specified room.
+
+*/w <number>*:: Like /win.
+
+*/status <availability> [status message]*:: Set your availability and
+ (optionaly) your status message. The <availability> argument is one of
+ "available, chat, away, afk, dnd, busy, xa" and the optional [status] argument
+ will be your status message.'
+
+*/bookmark [roomname][/nick]*:: Bookmark the specified room (you will then
+ auto-join it on each poezio start). This commands uses almost the same syntax
+ as /join. Type /help join for syntax examples. Note that when typing /bookmark
+ on its own, the room will be bookmarked with the nickname you're currently
+ using in this room (instead of default_nick).
+
+*/set <option> [value]*:: Sets the value to the option in your configuration
+ file. You can, for example, change your default nickname by doing "/set
+ default_nick toto" or your resource with "/set resource blabla". You can also
+ set an empty value (nothing) by providing no [value] after <option>.
+
+*/theme*:: Reload the theme defined in the config file.
+
+*/list [server.tld]*:: Get the list of public chatrooms in the specified server
+.
+
+*/message <jid> [optional message]*:: Open a conversation with the specified
+ JID (event if it is not in our roster), and send a message to him, if
+ specified.
+
+*/version <jid>*:: Get the software version of the given JID (usually its XMPP
+ client and Operating System).
+
+*/server_cycle [server.tld] [message]*:: Disconnect and reconnect in all the
+ rooms of server.tld.
+
+*/bind <key> <eq>*:: Bind a key to another key or to a "command". For example,
+ "/bind ^H KEY_UP" makes Control + h behave the same way as the Up key. See the
+ link:keys.html[key bindings documentation page] for more details.
+
+NOTE: The following command will work everywhere, except in the Roster tab.
+
+*/close*:: Close the tab.
+
+Chat tab commands
+~~~~~~~~~~~~~~~~~
+
+These commands will work in any conversation tab (MultiUserChat, Private, or
+ Conversation tabs).
+
+*/say <message>*:: Just send the message (only useful it you want your message
+ to begin with a _/_). Note that you can also send message starting with a _/_
+ by starting it with _//_.
+
+MultiUserChat tab commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*/ignore <nickname>*:: Ignore a specified nickname.
+
+*/unignore <nickname>*:: Remove the specified nickname from the ignore list.
+
+*/kick <nick> [reason]*:: Kick the user with the specified nickname. You can
+ also give an optional reason.
+
+*/topic <subject>*:: Change the subject of the room. You might want to knwow
+ that entering "/topic [tab]" will autocomplete the topic.
+
+*/query <nick> [message]*:: Open a private conversation 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.
+
+*/part [message]*:: Disconnect you from a room. You can specify an optional
+ message.
+
+*/close [message]*:: Disconnect you from a room (if you are connected) and
+ close the tab. You can specify an optional message if you are still connected.
+
+*/nick <nickname>*:: Change your nickname in the current room.
+
+*/recolor*:: Re-assign a color to all the participants in the current room,
+ based on the last time they talked. Use this if the participants currently
+ talking have too many identical colors.
+
+*/cycle [message]*:: Leave the current room an rejoint it immediatly. You can
+ specify an optional quit message.
+
+*/info <nickname>*:: Display some information about the user in the room:
+ his/her role, affiliation, status, and status message.
+
+*/version <nickname or jid>*:: Get the software version of the given nick in
+ room or the given jid (usually its XMPP client and Operating System).
+
+*/configure*:: Configure the current room through a form.
+
+*/names*:: Get the list of the users in the room, their number, and the list
+ of the people assuming different roles.
+
+*/clear*:: Clear the current buffer.
+
+Private tab commands
+~~~~~~~~~~~~~~~~~~~~
+
+*/info*:: Display some info about this user in the MultiUserChat.
+
+*/unquery*:: Close the tab.
+
+*/version*:: Get the software version of the current interlocutor (usually its
+ XMPP client and Operating System).
+
+Normal Conversation tab commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*/info*:: Display the status of this contact.
+
+*/unquery*:: Close the tab.
+
+*/version*:: Get the software version of the current interlocutor (usually its
+ XMPP client and Operating System).
+
+Roster tab commands
+~~~~~~~~~~~~~~~~~~~
+
+*/accept [jid]*:: Authorize the provided JID (or the selected contact in the
+ roster) to see your presence.
+
+*/deny [jid]*:: Prevent the provided JID (or the selected contact in the
+ roster) from seeing your presence.
+
+*/add <jid>*:: Add the specified JID to your roster and authorize him to see
+ your presence. If he accepts you, the subscription will be mutual (and if he
+ doesn’t, you can still /deny him).
+
+*/name <jid> <name>*:: Set the given JID’s name.
+
+*/groupadd <jid> <group>*:: Add the given JID to the given group (if the group
+ does not exist, it will be created).
+
+*/groupremove <jid> <group>*:: Remove the given JID from the given group (if
+ the group is empty after that, it will get deleted).
+
+*/remove [jid]*:: Remove the specified JID from your roster. This will
+ unsubscribe you from its presence, cancel its subscription to yours, and
+ remove the item from your roster.
+
+NOTE: The following commands do not comply with any XEP or whatever, but they
+ can still prove useful when you are migrating to an other JID.
+
+*/export [/path/to/file]*:: Export your contacts into /path/to/file if
+ specified, or $HOME/poezio_contacts if not.
+
+*/import [/path/to/file]*:: Import your contacts from /path/to/file if
+ specified, or $HOME/poezio_contacts if not.
+