Merge branch 'doc'

7 files changed, 519 insertions, 4 deletions

diff --git a/Makefile b/Makefile
index e055d203..7e71edb1 100644
--- a/Makefile
+++ b/Makefile
@@ -34,5 +34,9 @@ uninstall:
 	rm -rf $(DESTDIR)$(DATADIR)/poezio
 	rm -rf $(DESTDIR)$(MANDIR)/man1/poezio.1
 
+doc:
+	find doc -name \*.txt -exec asciidoc {} \;
 pot:
 	xgettext src/*.py --from-code=utf-8 --keyword=_ -o locale/poezio.pot
+
+.PHONY : doc
\ No newline at end of file
diff --git a/README b/README
index 5bfbe17a..6729fb0a 100644
--- a/README
+++ b/README
@@ -28,6 +28,9 @@ You need python 3.0 (and the associated devel package, to build C modules)
 or higher, and the SleekXMPP python library.
 In the developpement version, you’ll need this fork of SleekXMPP
 http://github.com/louiz/SleekXMPP.
+Additionally, you’ll need asciidoc to build the html documentation pages.
+You can read the documentation using the .txt files, as well, if you don’t
+have asciidoc, or read it on the web.
 
 The simplest way to have up-to-date dependencies and to be able to test
 this developpement version is to use the update.sh script that downloads
diff --git a/data/default_config.cfg b/data/default_config.cfg
index afedfc38..279f902d 100644
--- a/data/default_config.cfg
+++ b/data/default_config.cfg
@@ -112,9 +112,9 @@ alternative_nickname =
 # Limit the number of messages you want to receive when the
 # multiuserchat rooms send you recent history
 # 0: You won't receive any
-# -1: You will receive the maximum (default)
+# -1: You will receive the maximum
 # n: You will receive at most n messages
-muc_history_length = -1
+muc_history_length = 50
 
 # set to 'true' if you want to save logs of all the messages
 # in files.
@@ -149,7 +149,7 @@ beep_on = highlight private
 # Theme
 
 # If themes_dir is not set, logs will searched for in $XDG_DATA_HOME/poezio/themes,
-# i.e. in ~/.local/share/poezio/themes/. Si you should specify the directory you
+# i.e. in ~/.local/share/poezio/themes/. So you should specify the directory you
 # want to use instead. This directory will be created at startup if it doesn't
 # exist
 themes_dir =
@@ -158,7 +158,7 @@ themes_dir =
 # in the theme_dir directory.
 # If the file is not found (or no filename is specified) the default
 # theme will be used instead
-theme = poezio
+theme =
 
 # The nick of people who join, part, change their status, etc. in a MUC will
 # be displayed using their nick color if true.
diff --git a/doc/en/configure.txt b/doc/en/configure.txt
new file mode 100644
index 00000000..94f8e121
--- /dev/null
+++ b/doc/en/configure.txt
@@ -0,0 +1,265 @@
+Configure
+=========
+
+The configuration is located in the file *~/.config/poezio/poezio.cfg*
+On its first startup, poezio will create that file (and its containing
+directories) with the default configuration. You can edit that file manually
+or use the */set* command to edit some of its values directly from poezio.
+This file is also used to configure key bindings, but this is explained
+in the _keys_ documentation file.
+
+That file is read at each startup and the configuration is saved when poezio
+is closed.
+
+This configuration file *requires* all the options to be in a section
+named [Poezio].
+
+An option is formatted with the form
+======================
+option = value
+======================
+
+An empty value *doesn’t* mean that the default value will be used. That’s
+just an empty value. To use the default value, just comment or remove the
+option entirely.
+
+Here is a list of all the avalaible configuration options, their meaning
+and their default value.
+
+Configuration options
+---------------------
+
+[horizontal]
+*server*:: anon.louiz.org
+
+  The server to use for *anonymous* authentication.
+  Make sure it accepts anonymous authentification
+  Note that this option doesn’t do anything at all if you’re using your own JID.
+
+*port*:: 5222
+
+ The port you’ll use to connect.
+
+*resource*:: [empty]
+
+  the resource you will use
+  If it's empty, your resource will be chosen (most likely randomly) by the server
+  It is not recommended to use a resource that is easy to guess, because it can lead
+  to presence leak.
+
+
+*default_nick*:: [empty]
+
+  the nick you will use when joining a room with no associated nick
+  If this is empty, the $USER environnement variable will be used
+
+
+*jid*:: [empty]
+
+  Jabber identifiant. Specify it only if you want to connect using an existing
+  account on a server. This is optional and useful only for some features,
+  like room administration, nickname registration.
+  The 'server' option will be ignored if you specify a JID (Jabber identifiant)
+  It should be in the form nickname@server.tld
+
+*password*:: [empty]
+
+  A password is needed only if you specified a jid. It will be ignored otherwise
+  If you leave this empty, the password will be asked at each startup
+
+
+
+*rooms*:: poezio@muc.poezio.eu
+
+  the rooms you will join automatically on startup, with associated nickname or not
+  format : room@server.tld/nickname:room2@server.tld/nickname2
+  default_nick will be used if "/nickname" is not specified
+
+*completion*:: normal
+
+  the completion type you will use to complete nicknames
+  if "normal", complete the entire name to the first available completion
+  and then cycle through the possible completion with the next TABs
+  if "shell", if there's more than one nick for this completion, complete
+  only the part that all then nicks have in common (like in a shell)
+
+
+*after_completion*:: ,
+
+  what will be put after the name, when using autocompletion
+  a SPACE will always be added after that
+
+*highlight_on*:: [empty]
+
+  a list of words (separated by a colon (:)) that will be
+  highlighted if said by someone on a room
+
+*enable_xhtml_im*:: true
+
+  XHTML-IM is an XMPP extension letting users send messages
+  containing XHTML and CSS formating. We can use this to make
+  colored text for example.
+  It is disabled by default because this is only in an experimental
+  state: you could miss some part of a message (mainly the URL)
+  but you can still send colored messages. You just won’t be able te see
+  the colors, though
+  Set to true if you want to see colored messages
+
+*hide_status_change*:: 120
+
+  Set a number for this setting.
+  The join OR status-change notices will be
+  displayed according to this number.
+  -1: the notices will ALWAYS be displayed
+   0: the notices will NEVER be displayed
+   n: On any other number, the notices will only be displayed
+      if the user involved has talked since the last n seconds
+  if the value is incorrect, -1 is assumed
+  Default setting means :
+   - status changes won't be displayed unless
+     the user talked in the last 2 minutes
+
+*hide_exit_join*:: -1
+
+  Exact same thing than hide_status_change, except that it concerns
+  the quit message, and that it will be hidden only if the value is 0.
+  Default setting means:
+   - all quit and join notices will be displayed
+
+
+*information_buffer_popup_on*:: error roster warning help info
+
+  Some informational messages (error, a contact getting connected, etc)
+  are sometimes added to the information buffer. These settings can make
+  that buffer grow temporarly so you can read these information when they
+  appear.
+
+  A list of message types that should make the information buffer grow
+  Possible values; error, roster, warning, info, help
+
+*popup_time*:: 4
+
+  The time the message will be visible in the information buffer when it
+  pops up.
+  If the message takes more than one line, the popup will stay visible
+  two more second per additional lines
+
+*autorejoin*:: false
+
+  set to 'true' if you want to automatically rejoin the
+  room when you're kicked
+
+*alternative_nickname*:: [empty]
+
+  If you want poezio to join
+  the room with an alternative nickname when
+  your nickname is already in use in the room you
+  wanted to join, put a non-empty value.
+  Else, poezio won't join the room
+  This value will be added to your nickname to
+  create the alternative nickname.
+  For example, if you set "\_", and wanted to use
+  the nickname "john", your alternative nickname
+  will be "john_"
+
+*muc_history_length*:: 50
+
+  Limit the number of messages you want to receive when the
+  multiuserchat rooms send you recent history
+  0: You won't receive any
+  -1: You will receive the maximum
+  n: You will receive at most n messages
+  Note that if you set a huge number (like the default value), you
+  may not receive that much messages. The server has its own
+  maximum too
+
+*use_log*:: true
+
+  set to 'false' if you don’t want to save logs of all the messages
+  in files.
+
+
+*log_dir*:: [empty]
+
+  If log_dir is not set, logs will be saved in $XDG_DATA_HOME/poezio/logs,
+  i.e. in ~/.local/share/poezio/logs/. So, you should specify the directory
+  you want to use instead. This directory will be created if it doesn't exist
+
+*show_inactive_tabs*:: true
+
+  If you want to show all the tabs in the Tab bar, even those
+  with no activity, set to true. Else, set to false
+
+
+*beep_on*:: highlight private
+
+  The terminal can beep on various event. Put the event you want in a list
+  (separated by spaces).
+  The events can be
+  - highlight (when you are highlighted in a MUC)
+  - private (when a new private message is received, from your contacts or
+             someone from a MUC)
+  - message (any message from a MUC)
+
+*themes_dir*:: [empty]
+
+  If themes_dir is not set, themes will searched for in $XDG_DATA_HOME/poezio/themes,
+  i.e. in ~/.local/share/poezio/themes/. So you should specify the directory you
+  want to use instead. This directory will be created at startup if it doesn't
+  exist
+
+
+*theme*:: [empty]
+
+  The name of the theme file (without the .py extension) that will be used.
+  The file should be located in the theme_dir directory.
+  If the file is not found (or no filename is specified) the default
+  theme will be used instead
+
+*send_chat_states*:: true
+
+  if true, chat states will be sent to the people you are talking to.
+  Chat states are, for example, messages informing that you are composing
+  a message or that you closed the tab, etc
+  Set to false if you don't want people to know these information
+  Note that you won’t receive the chat states of your contacts
+  if you don't send yours.
+
+
+*send_poezio_info*:: true
+
+  if true, information about the software (name and version)
+  will be sent if requested by anyone
+  Set to false if you don't want people to know these information
+
+
+*send_os_info*:: true
+
+  if true, information about the Operation System you're using
+  will be sent when requested by anyone
+  Set to false if you don't want people to know these information
+  Note that this information will not be sent if send_poezio_info is False
+
+*send_time*:: true
+
+  if true, your current time will be sent if asked
+  Set to false if you don't want people to know that information
+
+
+*max_messages_in_memory*:: 2048
+
+  Configure the number of maximum messages (for each tab) that
+  can be kept in memory. If poezio consumes too much memory, lower these
+  values
+
+*max_lines_in_memory*:: 2048
+
+  Configure the number of maximum lines (for each tab) that
+  can be kept in memory. If poezio consumes too much memory, lower these
+  values
+
+*lazy_resize*:: true
+
+  Defines if all tabs are resized at the same time (if set to false)
+  or if they are really resized only when needed (if set to true).
+  “true” should be the most comfortable value
diff --git a/doc/en/install.txt b/doc/en/install.txt
new file mode 100644
index 00000000..75cc0ea8
--- /dev/null
+++ b/doc/en/install.txt
@@ -0,0 +1,94 @@
+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)
+* *Debian*: Use an other distro.
+
+(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:
+============================
+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.
+
+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.
+
+
+Download SleekXMPP
+============================
+git clone git://github.com/louiz/SleekXMPP.git
+============================
+
+Make sure you're using the develop branch by typing
+============================
+cd SleekXMPP
+
+git checkout develop
+============================
+
+Install SleekXMPP with
+============================
+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).
+============================
+hg clone http://hg.louiz.org/dnspython
+
+cd dnspython
+============================
+
+And do the same again:
+============================
+python3 setup.py build
+
+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:
+============================
+sh update.sh
+============================
+
+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:
+============================
+ ./launch.sh
+============================
+
+
+To install poezio, do, as root (or sudo with ubuntu or whatever):
+============================
+make install
+============================
+
+And then start it with:
+============================
+poezio
+============================
+
diff --git a/doc/en/keys.txt b/doc/en/keys.txt
new file mode 100644
index 00000000..eaae961d
--- /dev/null
+++ b/doc/en/keys.txt
@@ -0,0 +1,66 @@
+Keys
+====
+
+This file describes the default keys of poezio and explains how to
+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
+
+Key bindings listing
+--------------------
+Some key bindings are available only in some tabs, others are global.
+
+Global keys
+~~~~~~~~~~~
+These keys work in *any* tab.
+
+*Ctrl-n*:: Go to the next tab.
+
+*Ctrl-p*:: Go to the previous tab.
+
+*Alt-number*:: Go to tab number x.
+
+*Alt-j*:: Waits for you to type a two-digits number. Go to tab number xx.
+
+Input keys
+~~~~~~~~~~
+These keys concern only the inputs.
+
+*Ctrl-a*:: Move the cursor to the beginning of line.
+
+*Ctrl-e*:: Move the cursor to the end of line.
+
+Chat tab input keys
+~~~~~~~~~~~~~~~~~~~~~
+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 Down*:: Likfe Page Up, but down.
+
+*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
+
+To know exactly what the code of a key is, just run
+==================
+python3 src/keyboard.py
+==================
+And enter any keys
+
+.Turn Alt-i into a tab key (completion, etc)
+==================
+M-i = ^I
+==================
diff --git a/doc/poezio.txt b/doc/poezio.txt
new file mode 100644
index 00000000..47497434
--- /dev/null
+++ b/doc/poezio.txt
@@ -0,0 +1,83 @@
+Poezio documentation
+====================
+
+This page is the documentation for poezio.
+
+Poezio is an XMPP console client mostly written in python and a little
+bit in C.
+
+It uses curses to draw its user interface.
+
+It has been written to create an XMPP client that could very easily be used by
+any IRC user. Its interface tries to be like the ones of famous clients such
+as irssi or weechat.
+
+:numbered:
+== Usage ==
+
+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.
+
+
+=== 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 command nick with only one argument
+==========================================
+/nick "my new nick"
+==========================================
+
+.The command status with two arguments
+==========================================
+/status away "on vacation"
+==========================================
+
+.Note
+The character *'* cannot be used instead of *"*.
+
+
+To know the list of all available commands, use the *help* command with no
+argument. To know more about the command (what it does and how to use it),
+use the *help* command and pass the command name as its first argument.
+
+The list of all global commands is as follow:
+
+[horizontal]
+*help*:: [command_name] + 
+  Displays the list of all available commands in the current tab, or displays
+  the usage of the given command.
+*message*:: <jid> [message] + 
+  Open a conversation with the specified JID, and send a message to it,
+  if specified.
+
+
+
+
+
+.Get information on the status command
+==========================================
+/help status
+==========================================
+
+
+=== Tabs ===
+This section lists and describes all the tab types.
+
+
+==== Roster Tab ====
+This is the first tab that you will see when starting poezio.
+
+It contains your roster
+
+[glossary]
+== Glossary ==
+
+This glossary explains some terms that are used in this documentation.
+
+[glossary]
+Roster::
+  The list of contacts, sorted by groups, status, or anything the client wishes.