Merge branch 'master' of ssh://code.leap.se/leap_doc

4 files changed, 122 insertions, 238 deletions

diff --git a/docs/client/dev-environment.md b/docs/client/dev-environment.md
index 37aefa6..eb78b3b 100644
--- a/docs/client/dev-environment.md
+++ b/docs/client/dev-environment.md
@@ -4,7 +4,7 @@
 Setting up a development environment
 ====================================
 
-This document covers how to get an enviroment ready to contribute code
+This document covers how to get an environment ready to contribute code
 to Bitmask.
 
 Cloning the repo
@@ -18,27 +18,22 @@ Cloning the repo
     git clone https://leap.se/git/bitmask_client
     git checkout develop
 
-Base Dependencies
------------------
+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)
+- python 2.6 or 2.7
+- qt4 libraries
+- openssl
+- [openvpn](http://openvpn.net/index.php/open-source/345-openvpn-project.html)
 
-### Debian
+### Install dependencies in a Debian based distro
 
 In debian-based systems:
 
-    $ apt-get install openvpn python-pyside python-openssl
-
-To install the software from sources:
+    $ sudo apt-get install git python-dev python-setuptools python-virtualenv python-pip libssl-dev python-openssl libsqlite3-dev g++ openvpn pyside-tools python-pyside libffi-dev
 
-    $ apt-get install python-pip python-dev
 
 Working with virtualenv
 -----------------------
@@ -49,28 +44,27 @@ Working with virtualenv
 
 It is a tool to create isolated Python environments.
 
-The basic problem being addressed is one of dependencies and versions,
+> 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
+`/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.
+page](http://www.virtualenv.org/en/latest/virtualenv.html).
 
 ### Create and activate your dev environment
 
-    $ virtualenv </path/to/new/environment>
-    $ source </path/to/new/environment>/bin/activate
+You first create a virtualenv in any directory that you like:
+
+    $ mkdir ~/Virtualenvs
+    $ virtualenv ~/Virtualenvs/bitmask
+    $ source ~/Virtualenvs/bitmask/bin/activate
+    (bitmask)$
+
+Note the change in the prompt.
 
 ### Avoid compiling PySide inside a virtualenv
 
@@ -84,14 +78,14 @@ 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
+globally and pass the `--system-site-packages` option when you are creating
 your virtualenv:
 
     $ apt-get install python-pyside
-    $ virtualenv --site-packages .
+    $ virtualenv --system-site-packages .
 
 After that, you must export `LEAP_VENV_SKIP_PYSIDE` to skip the
-isntallation:
+installation:
 
     $ export LEAP_VENV_SKIP_PYSIDE=1
 
@@ -105,40 +99,90 @@ administrative permissions:
 
     $ pip install -r pkg/requirements.pip
 
+This step is not strictly needed, since the `setup.py develop` in the next
+paragraph with also fetch the needed dependencies. But you need to know abou it:
+when you or any person in the development team will be adding a new dependency,
+you will have to repeat this command so that the new dependencies are installed
+inside your virtualenv.
+
+Install Bitmask
+---------------
+
+Normally we would install the `leap.bitmask` package as any other package
+inside the virtualenv.
+But, instead, we will be using setuptools **development mode**. The difference
+is that, instead of installing the package in a permanent location in your
+regular installed packages path, it will create a link from the local
+site-packages to your working directory. In this way, your changes will always
+be in the installation path without need to install the package you are working
+on.::
+
+    (bitmask)$ python2 setup.py develop
+
+After this step, your Bitmask launcher will be located at
+`~/Virtualenvs/bitmask/bin/bitmask`, and it will be in the path as long as you
+have sourced your virtualenv.
+
+Make resources
+--------------
+
+We also need to compile the resource files::
+
+    (bitmask)$ make resources
+
+You need to repeat this step each time you change a `.ui` file.
+
 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:
+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.
+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:
+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:
+Running!
+--------
+
+If everything went well, you should be able to run your client by invoking
+`bitmask`. If it does not get launched, or you just want to see more verbose
+output, try the debug mode:
+
+   (bitmask)$ bitmask --debug
+
+
+Using automagic helper script
+-----------------------------
+
+You can use a helper script that will get you started with bitmask and all the related repos.
+
+1. install system dependencies
+2. download automagic script
+3. run it :)
 
-    /usr/lib/policykit-1-gnome/polkit-gnome-authentication-agent-1 &
+Commands so you can copy/paste:
 
-or if you are a kde user:
+    $ mkdir bitmask && cd bitmask
+    $ wget https://raw.githubusercontent.com/leapcode/bitmask_client/develop/pkg/scripts/bootstrap_develop.sh
+    $ chmod +x bootstrap_develop.sh
+    $ ./bootstrap_develop.sh init  # use help parameter for more information
 
-    /usr/lib/kde4/libexec/polkit-kde-authentication-agent-1 &
+This script allows you to get started, update and run the bitmask app with all its repositories.
diff --git a/docs/client/en.md b/docs/client/en.md
index 0436ec2..4dd6953 100644
--- a/docs/client/en.md
+++ b/docs/client/en.md
@@ -5,15 +5,11 @@
 Bitmask
 =======
 
-**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.
+**Bitmask** is the multiplatform desktop client for the services offered by [the LEAP Platform](platform).
 
-You can find the complete up-to-date documentation [at the python package documentation
-site.](http://pythonhosted.org/leap.bitmask "Bitmask documentation")
+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.
 
-We include below some sections of the user guide and the development documentation so
-you can get started.
+We include below some sections of the user guide and the development documentation so you can get started.
 
 User Guide
 ----------
@@ -23,8 +19,7 @@ User Guide
 Tester Guide
 ------------
 
-This part of the documentation details how to fetch the last development
-version and how to report bugs.
+This part of the documentation details how to fetch the last development version and how to report bugs.
 
 * [Howto for testers](client/testers-howto)
 
@@ -46,12 +41,19 @@ If you want to contribute to the project, we wrote this for you.
 Supported OSs
 -------------
 
-Currently supported OSs (32 and 64 bits) are:
+We currently support:
 
-* Debian 7 (32bits lxde and 64 bits gnome3)
-* Ubuntu 12.04 (LTS, unity)
-* Ubuntu 13.10 (latest, unity)
+### Through the bundle
+
+* Debian 7
+* Ubuntu 12.04 (LTS)
+* Ubuntu 13.10 (latest)
 * Mac OSX >= 10.8
-* Windows 7 (32 bits only)
-* Windows 8 (planned)
+* Note: It *should* work in other Debian based distros
+
+### Through the debian package
 
+* Ubuntu 13.04 (Raring Ringtail)
+* Ubuntu 13.10 (Saucy Salamander)
+* Debian 7.0 (Wheezy)
+* Debian 8.0 (Jessie)
diff --git a/docs/client/testers-howto.md b/docs/client/testers-howto.md
index 10a436d..8311b95 100644
--- a/docs/client/testers-howto.md
+++ b/docs/client/testers-howto.md
@@ -75,16 +75,16 @@ Attach the logfile to your bug report.
 
 ### Need human interaction?
 
-You can also find us in the `#leap-dev` channel on the [freenode
+You can also find us in the `#leap` 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).
+web](http://webchat.freenode.net/?nick=leaper....&channels=%23leap&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
+be enough. We are engaged in a three-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
@@ -95,86 +95,16 @@ 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.
+platforms for the brave souls like you. Check it out in the
+*Using automagic helper script* section of the
+[Hacking](client/dev-environment) page 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
@@ -182,17 +112,6 @@ 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
diff --git a/docs/client/user-install.md b/docs/client/user-install.md
index e29d63e..2a99d66 100644
--- a/docs/client/user-install.md
+++ b/docs/client/user-install.md
@@ -4,86 +4,16 @@
 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
-
--   [Windows 32 bits
-    bundle](https://downloads.leap.se/client/windows/Bitmask-win32-latest.zip)
-    ([signature](https://downloads.leap.se/client/windows/Bitmask-win32-latest.zip.asc))
-
-### 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 / Ubuntu 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, replace <suite> below with your Debian or
-Ubuntu suite, which you can find by typing 'lsb_release -c' in a terminal.
-Currently the following are available: sid, jessie, trusty, saucy, raring, quantal
-
-    # echo "deb http://deb.leap.se/debian <suite> main" >> /etc/apt/sources.list
-    # apt-get update
-    # apt-get install leap-keyring
-
-And then you can happily install bitmask:
-
-    apt-get install bitmask
+For download links and installation instructions go to https://dl.bitmask.net/
 
 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 or
-> fetching latest code for testing.
-
-![image](https://pypip.in/v/leap.bitmask/badge.png%0A%20%20%20%20%20:target:%20https://crate.io/packages/leap.bitmask)
+**Note**
 
-Installing Bitmask is as simple as using
-[pip](http://www.pip-installer.org/) for the already released versions :
+If you are familiar with python code and you can find your way through the
+process of dependencies install, you can installing Bitmask using [pip](http://www.pip-installer.org/)
+for the already released versions :
 
     $ pip install leap.bitmask
 
@@ -99,16 +29,5 @@ Or from the github mirror :
 
     $ git clone https://github.com/leapcode/bitmask_client.git
 
-Once you have grabbed a copy of the sources, and installed all the base
-dependencies, the recommended way to proceed is to install things in a virtualenv.
-
-    $ virtualenv bitmask && source bitmask/bin/activate
-    $ make  # compile the resources
-    $ python2 setup.py install
-
-Or you can install it into your global site-packages easily :
-
-    $ make  # compile the resources
-    $ sudo python2 setup.py install
+For more information go to the [Hacking](client/dev-environment) section :)
 
-WARNING: installing a package in the global site-packages can be harmful because the dependency installation can overwrite some of the existing packages.