From 662f9a7621308a21fbed96ca46cbac33848403f0 Mon Sep 17 00:00:00 2001
From: mathieui <mathieui@mathieui.net>
Date: Mon, 8 Apr 2013 19:17:32 +0200
Subject: Start migrating the command index

---
 doc/source/commands.rst    | 306 +++++++++++++++++++++++++++++++++++++++++++++
 doc/source/dev/theming.rst |   8 ++
 doc/source/index.rst       |   1 +
 doc/source/themes.rst      |   4 +-
 4 files changed, 317 insertions(+), 2 deletions(-)
 create mode 100644 doc/source/commands.rst
 create mode 100644 doc/source/dev/theming.rst

(limited to 'doc/source')

diff --git a/doc/source/commands.rst b/doc/source/commands.rst
new file mode 100644
index 00000000..024dc3cc
--- /dev/null
+++ b/doc/source/commands.rst
@@ -0,0 +1,306 @@
+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:
+
+.. code-block::
+
+    /command <mandatory argument> [optional argument]
+
+You can get the same help as below from inside poezio with the **/help** command.
+
+.. note:: Use command parameters like this:
+
+    - Do not use quotes if they are unnecessary (words without special chars or spaces)
+    - 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
+~~~~~~~~~~~~~~~
+
+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 and /quit**
+    Just disconnect from the server and exit poezio.
+
+.. _command-next:
+**/next**
+    Go to the next room.
+
+.. _command-prev:
+**/prev**
+    Go to the previous room.
+
+.. _command-win:
+**/win <number> or /w <number>**
+    Go to the specified room.
+
+.. _command-status:
+**/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.'
+
+.. _command-bookmark:
+**/bookmark [roomname][/nick] [autojoin] [password]**
+    Bookmark the specified
+    room. This command 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). You can specify an optional *autojoin* and *password* if you
+    call it with the full line (/bookmark alone will put the room in autojoin
+    without password). The bookmarks stored with this command are stored on your
+    xmpp server.
+
+.. _command-bookmark-local:
+**/bookmark_local [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). The bookmarks stored
+    with this command will be stored locally. They have priority over the ones
+    stored online.
+
+.. _command-remove-bookmark:
+**/remove_bookmark [room_jid]**
+    Remove the bookmark on *room_jid* or the one on the current tab, if any.
+
+.. _command-bookmarks:
+**/bookmarks**
+    Show the current bookmarks.
+
+.. _command-set:
+**/set [plugin|][section] <option> <value>**
+    Set 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".  Doing so will write in the main config file, and in the main
+    section ([Poezio]). But you can also write to another section, with "/set
+    bindings M-i ^i", to a plugin configuration with "/set mpd_client| host
+    main" (notice the **|**, it is mandatory to write in a plugin), or even to
+    another section in a plugin configuration "/set plugin|other_section option
+    value".  **toggle** can be used as a special value for a boolean option. It
+    just set the option to true if it’s currently false, and to false if it’s
+    currently true.
+
+.. _command-move-tab:
+**/move_tab <source> <destination>**
+    Move tab <source> to <destination>. If
+    the create_gaps option is true, then it will leave a gap at the <source>
+    position, leading to usual behaviour. If create_gaps is not enabled, then the
+    tabs will number from 0 to your actual tab number, without gaps (which means
+    their number will change if you close a tab on the left of the list).
+
+.. _command-theme:
+**/theme [theme_name]**
+    Reload the theme defined in the config file. If
+    _theme_name_ is given, this command will act like /set theme theme_name then
+    /theme.
+
+.. _command-presence:
+**/presence <jid> [type] [status]**
+    Send a directed presence to _jid_ using
+    _type_ and _status_ if provided.
+
+*/rawxml <stanza>*:: Send a custom XML stanza.
+
+*/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).
+
+*/invite <jid> <room> [reason]*:: Invite _jid_ to _room_ wit _reason_ (if
+  provided).
+
+*/invitations*:: Show the pending invitations.
+
+*/activity <jid>*:: Show the last activity of a contact or a server (its
+ uptime, in that case).
+
+*/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.
+
+*/runkey <key>*:: Execute the action defined for _key_. For example,
+ "/runkey KEY_PPAGE" will scroll up, or "/runkey ^N" will go to the next tab.
+
+*/self*:: Reminds you of who you are and what your status is.
+
+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 _//_.
+
+*/xhtml <custom xhtml>*:: Send a custom xhtml message to the current tab.
+
+*/clear*:: Clear the current buffer.
+
+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.
+ *Except for gmail users* because gmail.com sucks and will do weird things
+ if you change your nickname in a MUC.
+
+*/recolor [random]*:: 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. If a random argument is
+ given, the participants will be shuffled before they are assigned a color.
+
+*/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.
+
+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).
+
+*/groupmove <jid> <old_group> <new_group>*:: Move the given JID from one group
+ to another (the JID has to be in the first group, and the new group  may not
+ exist).
+
+*/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.
+
+*/reconnect*:: Disconnect from the remote server (if connected) and then
+ connect to it again.
+
+NOTE: The following commands only exist if your server supports them. If it
+does not, you will be notified when you start poezio.
+
+*/block [jid]*:: Block the following JID using simple blocking. You will not
+ receive any of his messages and won’t be able to send some to him either.
+
+*/unblock [jid]*:: Unblock a previously blocked JID using simple blocking. You
+ will be able to send and receive messages from him again.
+
+*/list_blocks*:: List the blocked JIDs.
+
+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.
+
+XML tab commands
+~~~~~~~~~~~~~~~~
+
+*/clear*:: Clear the current buffer.
diff --git a/doc/source/dev/theming.rst b/doc/source/dev/theming.rst
new file mode 100644
index 00000000..6ad5105d
--- /dev/null
+++ b/doc/source/dev/theming.rst
@@ -0,0 +1,8 @@
+Theming module
+==============
+
+.. automodule:: theming
+
+.. autoclass:: Theme
+
+
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 1b621e5a..8ec26348 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -13,6 +13,7 @@ Contents:
 
     install
     themes
+    commands
     dev/index
 
 ..
diff --git a/doc/source/themes.rst b/doc/source/themes.rst
index 98b5f13e..92b88245 100644
--- a/doc/source/themes.rst
+++ b/doc/source/themes.rst
@@ -51,7 +51,7 @@ To define a *color pair* and assign it to the *COLOR_NAME* option, just do
     class FooTheme(theming.Theme):
           COLOR_NAME = (fg_color, bg_color, opt_attr)
 
-You do not have to define all the :ref:`available options`,
+You do not have to define all the :ref:`available-options`,
 you can decide that your theme will only change some options, the other
 one will just have the default value (from the default theme).
 
@@ -105,4 +105,4 @@ Available options
 .. warning:: This section is not complete.
 
 All available options can be found into the default theme, which is into the
-_theming.py_ file from the poezio’s source code.
+**theming.py** file from the poezio’s source code.
-- 
cgit v1.2.3