update client docs

This are the most important pages in the bitmask documentation.

I have converted .rst files using pandoc, since the .rst
does not seem to be supported like the README says.

I have added @nav_title and @title headers.

10 files changed, 546 insertions, 391 deletions

diff --git a/docs/client/bleeding-edge.md b/docs/client/bleeding-edge.md
deleted file mode 100644
index 6a926f1..0000000
--- a/docs/client/bleeding-edge.md
+++ /dev/null
@@ -1,104 +0,0 @@
-@title = "HOWTO for running latest develop branch"
-@nav_title = "Running Latest"
-
-This document covers a how-to guide to:
-
-1. Quickly fetching latest development code, and
-2. Reporting bugs.
-
-Let's go!
-
-Fetching latest development code
-=========================================
-
-To allow rapid testing in different platforms, we have put together a quick script that is able to fetch latest development code. It more or less does all the steps covered in the [Setting up a Work Enviroment](client/dev-guide) section, only that in a more compact way suitable (ahem) also for non developers.
-
-Install dependencies
--------------------------------
-
-First, install all the base dependencies plus git, virtualenv and development files needed to compile several extensions:
-
-    apt-get install openvpn git-core python-dev python-qt4 python-setuptools python-virtualenv
-
-
-Bootstrap script
----------------------------------
-
-> note: This will fetch the *develop* branch. If you want to test another branch, just change it in the line starting with *pip install...*. Alternatively, bug kali so she add an option branch to a decent script.
-
-> note: This script could make use of the after_install hook. Read http://pypi.python.org/pypi/virtualenv/
-
-Download and source the following script in the parent folder where you want your testing build to be downloaded. For instance, to `/tmp/`:
-
-
-    cd /tmp
-    wget https://raw.github.com/leapcode/bitmask_client/develop/pkg/scripts/bitmask_bootstrap.sh
-    source leap_client_bootstrap.sh
-
-Tada! If everything went well, you should be able to run the client by typing:
-
-    bin/leap-client
-
-Noticed that your prompt changed? That was *virtualenv*. Keep reading...
-
-Activating the virtualenv
---------------------------------
-
-The above bootstrap script has fetched latest code inside a virtualenv, which is an isolated, *virtual* python local environment that avoids messing with your global paths. You will notice you are *inside* a virtualenv because you will see a modified prompt reminding it to you (*leap-client-testbuild* in this case).
-
-Thus, if you forget to *activate your virtualenv*, the client will not run from the local path, and it will be looking for something else in your global path. So, **you have to remember to activate your virtualenv** each time that you open a new shell and want to execute the code you are testing. You can do this by typing:
-
-    $ source bin/activate
-
-from the directory where you *sourced* the bootstrap script.
-
-Refer to [Working with virtualenv](client/dev-guide) to learn more about virtualenv.
-
-Copying config files
-----------------------------
-
-If you have never installed the `leap-client` globally, **you need to copy some files to its proper path before running it for the first time** (you only need to do this once). This, unless the virtualenv-based operations, will need root permissions. See [copy script files](client/dev-guide) and [running openvpn without root privileges](client/dev-guide) sections for more info on this. In short:
-
-    $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/
-    $ sudo mkdir -p /etc/leap
-    $ sudo cp pkg/linux/resolv-update /etc/leap
-
-Local config files
---------------------------
-
-If you want to start fresh without config files, just move them. In linux:
-
-    mv ~/.config/leap ~/.config/leap.old
-
-Pulling latest changes
-------------------------------
-
-You should be able to cd into the downloaded repo and pull latest changes:
-
-    (leap-client-testbuild)$ cd src/leap-client
-    (leap-client-testbuild)$ git pull origin develop
-
-However, as a tester you are encouraged to run the whole bootstrap process from time to time to help us catching install and versioniing bugs too.
-
-Testing the packages
--------------------------------
-
-When we have a release candidate for the supported platforms (Debian stable, Ubuntu 12.04 by now), we will announce also the URI where you can download the rc for testing in your system. Stay tuned!
-
-Testing the status of translations
-==================================================
-
-We need translators! You can go to [transifex](https://www.transifex.com/projects/p/bitmask/), get an account and start contributing.
-
-If you want to check the current status of the client localization in a language other than the one set in your machine, you can do it with a simple trick (under linux). For instance, do:
-
-    $ lang=es_ES leap-client
-
-for running  LEAP Client with the spanish locales.
-
-Reporting bugs
-=======================
-
-We use the [LEAP Client Bug Tracker](https://leap.se/code/projects/eip-client), although you can also use [Github issues](https://github.com/leapcode/bitmask_client/issues).
-
-> There is a great text on the art of bug reporting, that can be found at http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
diff --git a/docs/client/client-index.rst b/docs/client/client-index.rst
deleted file mode 100644
index d0b0ff2..0000000
--- a/docs/client/client-index.rst
+++ /dev/null
@@ -1,95 +0,0 @@
-.. Bitmask documentation master file, created by
-   sphinx-quickstart on Sun Jul 22 18:32:05 2012.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Bitmask
-=====================================
-
-Release v \ |version|. (`Impatient? jump to the` :ref:`Installation <install>` `section!`)
-
-.. if you change this paragraph, change it in user/intro too
-**Bitmask** is the multiplatform desktop client for the services offered by :ref:`the LEAP Platform <leapplatform>`.
-It is written in python using `PySide`_ and :ref:`licensed under the GPL3 <gpl3>`.
-Currently we distribute pre-compiled bundles for Linux and OSX, with Windows
-bundles following soon.
-
-.. _`PySide`: http://qt-project.org/wiki/PySide
-
-User Guide
-----------
-
-.. toctree::
-   :maxdepth: 2
-
-   user/intro
-   user/install
-   user/running
-
-Tester Guide
-------------
-
-This part of the documentation details how to fetch the last development version and how to report bugs.
-
-.. toctree::
-   :maxdepth: 1
-
-   testers/howto
-
-Hackers Guide
----------------
-
-If you want to contribute to the project, we wrote this for you.
-
-.. toctree::
-   :maxdepth: 1
-
-   dev/environment
-   dev/tests
-   dev/workflow
-   dev/resources
-   dev/internationalization
-
-.. dev/internals
-   dev/authors
-   dev/todo
-
-Packager Guide
----------------
-
-Docs related to the process of building and releasing a version of the client.
-
-.. toctree::
-   :maxdepth: 1
-
-   pkg/debian
-   pkg/osx
-   pkg/win
-
-
-Directories and Files
----------------------
-
-Different directories and files used for the configuration of the client.
-
-.. toctree::
-   :maxdepth: 1
-
-   config/files
-
-
-API Documentation
------------------
-
-If you are looking for a reference to specific classes or functions, you are likely to find it here.
-
-.. I should investigate a bit more how to skip some things, and how to give nice format
-   to the docstrings.
-   Maybe we should not have sphinx-apidocs building everything, but a minimal index of our own.
-
-.. toctree::
-   :maxdepth: 2
-
-   api/leap
-
-
diff --git a/docs/client/dev-environment.md b/docs/client/dev-environment.md
new file mode 100644
index 0000000..c788251
--- /dev/null
+++ b/docs/client/dev-environment.md
@@ -0,0 +1,144 @@
+@nav_title = 'Hacking'
+@title = 'Setting up a development environment'
+
+Setting up a development environment
+====================================
+
+This document covers how to get an enviroment ready to contribute code
+to Bitmask.
+
+Cloning the repo
+----------------
+
+> **note**
+>
+> Stable releases are in *master* branch. Development code lives in
+> *develop* branch.
+
+    git clone git://leap.se/bitmask_client
+    git checkout develop
+
+Base Dependencies
+-----------------
+
+Bitmask depends on these libraries:
+
+-   python 2.6 or 2.7
+-   qt4 libraries (see also
+    Troubleshooting PySide install \<pysidevirtualenv\> about how to
+    install inside your virtualenv)
+-   openssl
+-   [openvpn](http://openvpn.net/index.php/open-source/345-openvpn-project.html)
+
+### Debian
+
+In debian-based systems:
+
+    $ apt-get install openvpn python-pyside python-openssl
+
+To install the software from sources:
+
+    $ apt-get install python-pip python-dev
+
+Working with virtualenv
+-----------------------
+
+### Intro
+
+*Virtualenv* is the *Virtual Python Environment builder*.
+
+It is a tool to create isolated Python environments.
+
+The basic problem being addressed is one of dependencies and versions,
+and indirectly permissions. Imagine you have an application that needs
+version 1 of LibFoo, but another application requires version 2. How can
+you use both these applications? If you install everything into
+/usr/lib/python2.7/site-packages (or whatever your platform's standard
+location is), it's easy to end up in a situation where you
+unintentionally upgrade an application that shouldn't be upgraded.
+
+Read more about it in the [project documentation
+page](http://pypi.python.org/pypi/virtualenv/).
+
+> **note**
+>
+> this section could be completed with useful options that can be passed
+> to the virtualenv command (e.g., to make portable paths,
+> site-packages, ...). We also should document how to use
+> virtualenvwrapper.
+
+### Create and activate your dev environment
+
+    $ virtualenv </path/to/new/environment>
+    $ source </path/to/new/environment>/bin/activate
+
+### Avoid compiling PySide inside a virtualenv
+
+If you attempt to install PySide inside a virtualenv as part of the rest
+of the dependencies using pip, basically it will take ages to compile.
+
+As a workaround, you can run the following script after creating your
+virtualenv. It will symlink to your global PySide installation (*this is
+the recommended way if you are running a debian-based system*):
+
+    $ pkg/postmkvenv.sh
+
+A second option if that does not work for you would be to install PySide
+globally and pass the `--site-packages` option when you are creating
+your virtualenv:
+
+    $ apt-get install python-pyside
+    $ virtualenv --site-packages .
+
+After that, you must export `LEAP_VENV_SKIP_PYSIDE` to skip the
+isntallation:
+
+    $ export LEAP_VENV_SKIP_PYSIDE=1
+
+And now you are ready to proceed with the next section.
+
+### Install python dependencies
+
+You can install python dependencies with `pip`. If you do it inside your
+working environment, they will be installed avoiding the need for
+administrative permissions:
+
+    $ pip install -r pkg/requirements.pip
+
+Copy script files
+-----------------
+
+The openvpn invocation expects some files to be in place. If you have
+not installed bitmask from a debian package, you must copy these files
+manually by now:
+
+    $ sudo mkdir -p /etc/leap
+    $ sudo cp pkg/linux/resolv-update /etc/leap
+
+Running openvpn without root privileges
+---------------------------------------
+
+In linux, we are using `policykit` to be able to run openvpn without
+root privileges, and a policy file is needed to be installed for that to
+be possible. The setup script tries to install the policy file when
+installing bitmask system-wide, so if you have installed bitmask in your
+global site-packages at least once it should have copied this file for
+you.
+
+If you *only* are running bitmask from inside a virtualenv, you will
+need to copy this file by hand:
+
+    $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/
+
+### Missing Authentication agent
+
+If you are using linux and running a desktop other than unity or gnome,
+you might get an error saying that you are not running the
+authentication agent. For systems with gnome libraries installed you can
+launch it like this:
+
+    /usr/lib/policykit-1-gnome/polkit-gnome-authentication-agent-1 &
+
+or if you are a kde user:
+
+    /usr/lib/kde4/libexec/polkit-kde-authentication-agent-1 &
diff --git a/docs/client/dev-guide.md b/docs/client/dev-guide.md
deleted file mode 100644
index fb7f0ba..0000000
--- a/docs/client/dev-guide.md
+++ /dev/null
@@ -1,107 +0,0 @@
-@nav_title = 'Development Guide'
-@title = 'Setting up a development environment'
-
-This document covers how to get an enviroment ready to contribute code to the LEAP Client.
-
-Cloning the repo
-==========================
-
-> Stable releases will be in *master* branch (nothing there yet, move on!). Development code lives in *develop* branch.
-
-    git clone https://leap.se/git/bitmask_client
-
-Base Dependencies
-=========================
-
-Leap client depends on these libraries:
-
-* `python 2.6 or 2.7`
-* `qt4` libraries (see below for how to install under virtualenv)
-* `openssl`
-* [openvpn](http://openvpn.net/index.php/open-source/345-openvpn-project.html)
-
-Debian
--------------
-
-In debian-based systems:
-
-    $ apt-get install openvpn python-qt4 python-crypto python-openssl
-
-To install the software from sources:
-
-    $ apt-get install python-pip python-dev
-
-Working with virtualenv
-===================================
-
-Intro
--------------------
-
-*Virtualenv* is the *Virtual Python Environment builder*.
-
-It is a tool to create isolated Python environments.
-
-The basic problem being addressed is one of dependencies and versions, and indirectly permissions. Imagine you have an application that needs version 1 of LibFoo, but another application requires version 2. How can you use both these applications? If you install everything into /usr/lib/python2.7/site-packages (or whatever your platform's standard location is), it's easy to end up in a situation where you unintentionally upgrade an application that shouldn't be upgraded.
-
-Read more about it in the [project documentation page](http://pypi.python.org/pypi/virtualenv/).
-
-Create and activate your dev environment
--------------------------------------------------
-
-    $ virtualenv </path/to/new/environment>
-    $ source </path/to/new/environment>/bin/activate
-
-Install python dependencies
------------------------------------------
-
-You can install python dependencies with pip. If you do it inside your working environment, they will be installed avoiding the need for administrative permissions:
-
-    $ pip install -r pkg/requirements.pip
-
-Troubleshooting PyQt install inside a virtualenv
----------------------------------------------------------------
-
-If you attempt to install PyQt inside a virtualenv using pip, it will fail because PyQt4 does not use the standard setup.py mechanism.
-
-As a workaround, you can run the following script after creating your virtualenv. It will symlink to your global PyQt installation (*this is the recommended way if you are running a debian-based system*):
-
-    $ pkg/postmkvenv.sh
-
-A second option if that does not work for you would be to install PyQt globally and pass the `--site-packages` option when you are creating your virtualenv:
-
-    $ apt-get install python-qt4
-    $ virtualenv --site-packages .
-
-Or, if you prefer, you can also `download the official PyQt tarball http://www.riverbankcomputing.com/software/pyqt/download and execute `configure.py` in the root folder of their distribution, which generates a `Makefile`:
-
-    $ python configure.py
-    $ make && make install
-
-> this section could be completed with useful options that can be passed to the virtualenv command (e.g., to make portable paths, site-packages, ...).
-
-
-Copy script files
-==========================
-
-The openvpn invocation expects some files to be in place. If you have not installed `leap-client` from a debian package, you must copy these files manually:
-
-    $ sudo mkdir -p /etc/leap
-    $ sudo cp pkg/linux/resolv-update /etc/leap
-
-Running openvpn without root privileges
-============================================
-
-In linux, we are using `policykit` to be able to run openvpn without root privileges, and a policy file is needed to be installed for that to be possible.
-The setup script tries to install the policy file when installing the client system-wide, so if you have installed the client in your global site-packages at least once it should have copied this file for you.
-
-If you *only* are running the client from inside a virtualenv, you will need to copy this file by hand:
-
-    $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/
-
-
-Missing Authentication agent
---------------------------------------
-
-If you are running a desktop other than gnome or unity, you might get an error saying that you are not running the authentication agent. You can launch it like this:
-
-    /usr/lib/policykit-1-gnome/polkit-gnome-authentication-agent-1 &
diff --git a/docs/client/en.md b/docs/client/en.md
index accd7ad..3bfe3f1 100644
--- a/docs/client/en.md
+++ b/docs/client/en.md
@@ -1,12 +1,40 @@
+@nav_title = "Bitmask"
 @title = 'Bitmask'
 @summary = "The Internet Encryption Toolkit: Encrypted Internet Proxy and Encrypted Mail"
 
-**Bitmask** is the multiplatform desktop client for the services offered by the [the LEAP Platform](platform). It is written in python using PySide and licensed under the GPL3. Currently we distribute pre-compiled bundles for Linux and OSX, with Windows bundles following soon.
+Bitmask
+=======
 
-You can find the complete up-to-date documentation [at the python package documentation site.](http://pythonhosted.org/leap.bitmask "Bitmask documentation")
+**Bitmask** is the multiplatform desktop client for the services offered by
+[the LEAP Platform](platform).  It is written in python using
+[PySide](http://qt-project.org/wiki/PySide) and licensed under the GPL3. Currently we distribute pre-compiled bundles for Linux and OSX, with Windows bundles following soon.
+
+You can find the complete up-to-date documentation [at the python package documentation
+site.](http://pythonhosted.org/leap.bitmask "Bitmask documentation")
+
+We include below some sections of the user guide and the development documentation so
+you can get started.
+
+User Guide
+----------
+* [Installing Bitmask](client/user-install)
+* [Running Bitmask](client/user-running)
+ 
+Tester Guide
+------------
+
+This part of the documentation details how to fetch the last development
+version and how to report bugs.
+
+* [Howto for testers](client/testers-howto)
+ 
+Hackers Guide
+-------------
+
+If you want to contribute to the project, we wrote this for you.
+
+* [Setting up a development environment](client/dev-environment)
 
-* [Bitmask Documentation index](client/client-index)
-* [User guide](client/user-guide)
  
 <!--
 * [Running latest code](client/bleeding-edge)
diff --git a/docs/client/packaging.md b/docs/client/packaging.md
deleted file mode 100644
index f767c9f..0000000
--- a/docs/client/packaging.md
+++ /dev/null
@@ -1,25 +0,0 @@
-@title = 'Packaging'
-
-Debian
-======
-
-This section documents all related to the debian package.
-
-Dependencies
-------------
-
-* `openvpn`
-* `python-qt4`
-* `python-crypto`
-* `python setuptools`
-* `python-requests`
-* `python-openssl`
-
-These need a version that is not found in the current debian stable or in ubuntu 12.04. They will be packaged... soon.
-
-* `python-keyring`
-
-For tests
------------------------
-
-* `python-nose`, `python-mock`, `python-coverage`
diff --git a/docs/client/testers-howto.md b/docs/client/testers-howto.md
new file mode 100644
index 0000000..7c92dd5
--- /dev/null
+++ b/docs/client/testers-howto.md
@@ -0,0 +1,215 @@
+@nav_title = "Testers Guide"
+@title = "Howto for Testers"
+
+Howto for Testers
+=================
+
+This document covers a how-to guide to:
+
+1.  Where and how report bugs for Bitmask \<reporting\_bugs\>, and
+2.  Quickly fetching latest development code \<fetchinglatest\>.
+
+Let's go!
+
+Reporting bugs
+--------------
+
+Report all the bugs you can find to us! If something is not quite
+working yet, we really want to know. Reporting a bug to us is the best
+way to get it fixed quickly, and get our unconditional gratitude.
+
+It is quick, easy, and probably the best way to contribute to Bitmask
+development, other than submitting patches.
+
+> **Reporting better bugs**
+>
+> New to bug reporting? Here you have a [great document about this noble
+> art](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html).
+
+### Where to report bugs
+
+We use the [Bitmask Bug
+Tracker](https://leap.se/code/projects/eip-client), although you can
+also use [Github
+issues](https://github.com/leapcode/bitmask_client/issues). But we
+reaaaally prefer if you sign up in the former to send your bugs our way.
+
+### What to include in your bug report
+
+-   The symptoms of the bug itself: what went wrong? What items appear
+    broken, or do not work as expected? Maybe an UI element that appears
+    to freeze?
+-   The Bitmask version you are running. You can get it by doing bitmask
+    --version, or you can go to Help -\> About Bitmask menu.
+-   The installation method you used: bundle? from source code? debian
+    package?
+-   Your platform version and other details: Ubuntu 12.04? Debian
+    unstable? Windows 8? OSX 10.8.4? If relevant, your desktop system
+    also (gnome, kde...)
+-   When does the bug appear? What actions trigger it? Does it always
+    happen, or is it sporadic?
+-   The exact error message, if any.
+-   Attachments of the log files, if possible (see section below).
+
+Also, try not to mix several issues in your bug report. If you are
+finding several problems, it's better to issue a separate bug report for
+each one of them.
+
+### Attaching log files
+
+If you can spend a little time getting them, please add some logs to the
+bug report. They are **really** useful when it comes to debug a problem.
+To do it:
+
+Launch Bitmask in debug mode. Logs are way more verbose that way:
+
+    bitmask --debug
+
+Get your hand on the logs. You can achieve that either by clicking on
+the "Show log" button, and saving to file, or directly by specifying the
+path to the logfile in the command line invocation:
+
+    bitmask --debug --logfile /tmp/bitmask.log
+
+Attach the logfile to your bug report.
+
+### Need human interaction?
+
+You can also find us in the `#leap-dev` channel on the [freenode
+network](https://freenode.net). If you do not have a IRC client at hand,
+you can [enter the channel via
+web](http://webchat.freenode.net/?nick=leaper....&channels=%23leap-dev&uio=d4).
+
+Fetching latest development code
+--------------------------------
+
+Normally, testing the latest client bundles \<standalone-bundle\> should
+be enough. We are engaged in a two-week release cycle with minor
+releases that are as stable as possible.
+
+However, if you want to test that some issue has *really* been fixed
+before the next release is out (if you are testing a new provider, for
+instance), you are encouraged to try out the latest in the development
+branch. If you do not know how to do that, or you prefer an automated
+script, keep reading for a way to painlessly fetch the latest
+development code.
+
+We have put together a script to allow rapid testing in different
+platforms for the brave souls like you. It more or less does all the
+steps covered in the Setting up a Work Enviroment \<environment\>
+section, only that in a more compact way suitable (ahem) also for non
+developers.
+
+> **note**
+>
+> At some point in the near future, we will be using standalone bundles
+> \<standalone-bundle\> with the ability to self-update.
+
+### Install dependencies
+
+First, install all the base dependencies plus git, virtualenv and
+development files needed to compile several extensions:
+
+    apt-get install openvpn git-core python-dev python-pyside python-setuptools python-virtualenv
+
+### Bootstrap script
+
+> **note**
+>
+> This will fetch the *develop* branch. If you want to test another
+> branch, just change it in the line starting with *pip install...*.
+> Alternatively, bug kali so she add an option branch to an improved
+> script.
+
+> **note**
+>
+> This script could make use of the after\_install hook. Read
+> <http://pypi.python.org/pypi/virtualenv/>
+
+Download and source the following script in the parent folder where you
+want your testing build to be downloaded. For instance, to \`/tmp/:
+
+.. code-block:: bash
+
+   cd /tmp
+   wget https://raw.github.com/leapcode/bitmask\_client/develop/pkg/scripts/bitmask\_bootstrap.sh
+   source bitmask\_bootstrap.sh
+
+Tada! If everything went well, you should be able to run bitmask by typing::
+
+    bitmask --debug
+
+Noticed that your prompt changed? That was \*virtualenv\*. Keep reading...
+
+Activating the virtualenv
+\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^
+The above bootstrap script has fetched latest code inside a virtualenv, which is
+an isolated, \*virtual\* python local environment that avoids messing with your
+global paths. You will notice you are \*inside\* a virtualenv because you will see
+a modified prompt reminding it to you (\*bitmask-testbuild\* in this case).  
+
+Thus, if you forget to \*activate your virtualenv\*, bitmask will not run from the
+local path, and it will be looking for something else in your global path. So,
+\*\*you have to remember to activate your virtualenv\*\* each time that you open a
+new shell and want to execute the code you are testing. You can do this by
+typing::
+
+    \$ source bin/activate
+
+from the directory where you \*sourced\* the bootstrap script.
+
+Refer to :ref:Working with virtualenv \<virtualenv\>\` to learn more
+about virtualenv.
+
+### Copying config files
+
+If you have never installed `bitmask` globally, **you need to copy some
+files to its proper path before running it for the first time** (you
+only need to do this once). This, unless the virtualenv-based
+operations, will need root permissions. See
+copy script files \<copyscriptfiles\> and
+running openvpn without root privileges \<policykit\> sections for more
+info on this. In short:
+
+    $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/
+    $ sudo mkdir -p /etc/leap
+    $ sudo cp pkg/linux/resolv-update /etc/leap
+
+### Local config files
+
+If you want to start fresh without config files, just move them. In
+linux:
+
+    mv ~/.config/leap ~/.config/leap.old
+
+### Pulling latest changes
+
+You should be able to cd into the downloaded repo and pull latest
+changes:
+
+    (bitmask-testbuild)$ cd src/bitmask
+    (bitmask-testbuild)$ git pull origin develop
+
+However, you are encouraged to run the whole bootstrapping process from
+time to time to help us catching install and versioning bugs too.
+
+### Testing the packages
+
+When we have a release candidate for the supported platforms, we will
+announce also the URI where you can download the rc for testing in your
+system. Stay tuned!
+
+Testing the status of translations
+----------------------------------
+
+We need translators! You can go to
+[transifex](https://www.transifex.com/projects/p/bitmask/), get an
+account and start contributing.
+
+If you want to check the current status of bitmask localization in a
+language other than the one set in your machine, you can do it with a
+simple trick (under linux). For instance, do:
+
+    $ lang=es_ES bitmask
+
+for running Bitmask with the spanish locales.
diff --git a/docs/client/user-guide.md b/docs/client/user-guide.md
deleted file mode 100644
index a6a5e58..0000000
--- a/docs/client/user-guide.md
+++ /dev/null
@@ -1,56 +0,0 @@
-@nav_title = "User Guide"
-@title = "Client User Guide"
-
-Installation
-==================
-
-Note: currently, this does not completely work. See [testing](testing)
-
-You can get the code from LEAP public git repository
-
-    git clone https://leap.se/git/bitmask_client
-
-Or from the github mirror
-
-    git clone https://github.com/leapcode/bitmask_client.git
-
-Once you have grabbed a copy of the sources, you can install it into your site-packages easily
-
-    $ python setup.py install
-
-
-Running
-==================
-
-This document covers how to launch the LEAP Client.
-
-Launching the client
---------------------
-
-After a successful installation, there should be a launcher called leap-client somewhere in your path:
-
-    $ leap-client
-
-Debug mode
-----------
-
-If you are happy having lots of output in your terminal, you will like to know that you can run the client in debug mode:
-
-    $ leap-client --debug
-
-If you ask for it, you can also have all that debug info in a beautiful file ready to be attached to your bug reports:
-
-    $ leap-client --debug --logfile /tmp/leap.log
-
-> the following is broken since it will clutter your stdout with all the commands sent to the management interface. See bug #1232
-
-If you want to increment the level of verbosity passed to openvpn, you can do:
-
-    $ leap-client --openvpn-verbosity 4
-
-Options
-------------
-
-To see all the available command line options:
-
-    $ leap-client --help
diff --git a/docs/client/user-install.md b/docs/client/user-install.md
new file mode 100644
index 0000000..122bc6a
--- /dev/null
+++ b/docs/client/user-install.md
@@ -0,0 +1,110 @@
+@nav_title = 'Installing'
+@title = 'Installing Bitmask'
+
+Installation
+============
+
+This part of the documentation covers the installation of Bitmask. We
+assume that you want to get it properly installed before being able to
+use it. But we can we wrong.
+
+Standalone bundle
+-----------------
+
+Maybe the quickest way of running Bitmask in your machine is using the
+standalone bundle. That is the recommended way to use Bitmask for the
+time being.
+
+You can get the latest bundles, and their matching signatures at [the
+downloads page](https://downloads.leap.se/client/).
+
+### Linux
+
+-   [Linux 32 bits
+    bundle](https://downloads.leap.se/client/linux/Bitmask-linux32-latest.tar.bz2)
+    ([signature](https://downloads.leap.se/client/linux/Bitmask-linux32-latest.tar.bz2.asc))
+-   [Linux 64 bits
+    bundle](https://downloads.leap.se/client/linux/Bitmask-linux64-latest.tar.bz2)
+    ([signature](https://downloads.leap.se/client/linux/Bitmask-linux64-latest.tar.bz2.asc))
+
+### OSX
+
+-   [OSX
+    bundle](https://downloads.leap.se/client/osx/Bitmask-OSX-latest.dmg)
+    ([signature](https://downloads.leap.se/client/osx/Bitmask-OSX-latest.dmg.asc))
+
+### Windows
+
+> **note**
+>
+> The release of the bundles for Windows is delayed right now. We should
+> resume producing them shortly, keep tuned.
+
+### Signature verification
+
+For the signature verification you can use :
+
+    $ gpg --verify Bitmask-linux64-latest.tar.bz2.asc
+
+Asuming that you downloaded the linux 64 bits bundle.
+
+Debian package
+--------------
+
+> **warning**
+>
+> The debian package that you can currently find in the leap
+> repositories is from the stable, 0.2.0 release, which is now outdated.
+> You are encouraged to install the development version or the
+> standalone bundles while we upload the newest packages.
+
+First, you need to bootstrap your apt-key:
+
+    # gpg --recv-key 0x1E34A1828E207901 0x485B12FA218E81EB
+    # gpg --list-sigs 0x1E34A1828E207901
+    # gpg --list-sigs 0x485B12FA218E81EB
+    # gpg -a --export 0x1E34A1828E207901  | sudo apt-key add - 
+
+Add the archive to your sources.list:
+
+    # echo "deb http://deb.leap.se/debian unstable main" >> /etc/apt/sources.list
+    # apt-get update
+    # apt-get install leap-keyring
+
+And then you can happily install bitmask:
+
+    apt-get install bitmask
+
+Distribute & Pip
+----------------
+
+> **note**
+>
+> The rest of the methods described below in this page assume you are
+> familiar with python code, and you can find your way through the
+> process of dependencies install. For more insight, you can also refer
+> to the sections setting up a working environment \<environment\> or
+> fetching latest code for testing \<fetchinglatest\>.
+
+![image](https://pypip.in/v/leap.bitmask/badge.png%0A%20%20%20%20%20:target:%20https://crate.io/packages/leap.bitmask)
+
+Installing Bitmask is as simple as using
+[pip](http://www.pip-installer.org/) for the already released versions :
+
+    $ pip install leap.bitmask
+
+Show me the code!
+-----------------
+
+You can get the code from LEAP public git repository :
+
+    $ git clone git://leap.se/bitmask_client
+
+Or from the github mirror :
+
+    $ git clone git://github.com/leapcode/bitmask_client.git
+
+Once you have grabbed a copy of the sources, you can install it into
+your site-packages easily :
+
+    $ pyton setup.py install
diff --git a/docs/client/user-running.md b/docs/client/user-running.md
new file mode 100644
index 0000000..79fd58f
--- /dev/null
+++ b/docs/client/user-running.md
@@ -0,0 +1,45 @@
+@nav_title = 'Running'
+@title = 'Running Bitmask'
+
+Running
+=======
+
+This document covers how to launch Bitmask. Also know as, where the
+magic happens.
+
+Launching Bitmask
+-----------------
+
+After a successful installation, there should be a launcher called
+bitmask somewhere in your path:
+
+    % bitmask
+
+The first time you launch it, it should launch the first run wizard that
+will guide you through the mostly automatic configuration of the LEAP
+Services.
+
+> **note**
+>
+> You will need to enter a valid test provider running the LEAP
+> Platform. You can use the LEAP test service, *<https://bitmask.net>*
+
+Debug mode
+----------
+
+If you are happy having lots of output in your terminal, you will like
+to know that you can run bitmask in debug mode:
+
+    $ bitmask --debug
+
+If you ask for it, you can also have all that debug info in a beautiful
+file ready to be attached to your bug reports:
+
+    $ bitmask --debug --logfile /tmp/leap.log
+
+I want all the options!
+-----------------------
+
+To see all the available command line options:
+
+    $ bitmask --help