DOC: Update README and CONTRIBUTING

CONTRIBUTING.md

@@ -9,6 +9,10 @@ Please, add your name in the CONTRIBUTORS file. The format is `First name
 'Pseudal' FAMILY NAME`. The licence is a modified version of the ISC licence
 to include this file (in short, a kind of MIT licence).
 
+## License
+
+See [LICENSE](LICENSE).
+
 ## Building
 
 It is recommended to use the `../configure` method to build while in
@@ -20,6 +24,8 @@ there are no package for your distribution, feel free to add a way to make it.
 
 ## Style and the code
 
+### C code and style
+
 Prefer using `__${name}` names for static variables and functions. Prefix the
 name of the file or folder in function names, e.g. `database_` or `command_`.
 
@@ -31,3 +37,36 @@ You are encouraged to use the `./scripts/tags.bash` script to build the `ctags`
 and `cscope` database files to explore more easelly the project.
 
 The C standard used here is C11, because on debian C18 doesn't compiles.
+
+### Scripts
+
+Scripts goes to the [scripts](scripts) folder. They must be written to be
+launched from the root of the project. Include the language used in the name of
+the script, for example:
+
+- `astyle.bash`: written in bash
+- `magic.rb`: written in ruby
+
+Please, do not write scripts in too many different languages to reduce the
+number of dependencies. If you are using binaries in your scripts (like astyle
+or bc), include them in the binary dependencies in the [README](README.md)
+file.
+
+There is a strong possibility that your script will do similar things to what a
+script already in this repo do. In that case, please work on the existing
+script and enhance it with your changes. No need to duplicate things.
+
+## Merge request titles
+
+Try to be as more descriptive as you can in your Merge Request title. Include
+the issue number and the target OS if possible.
+
+- Branch from the master branch and, if needed, rebase to the current master
+  branch before submitting your merge request. If it doesn't merge cleanly with
+  master you may be asked to rebase your changes
+
+- Commits should be as small as possible, while ensuring that each commit is
+  correct independently (i.e., each commit should compile and pass tests)
+
+- Add tests relevant to the fixed bug or new feature. In general, add a way to
+  test lektor

README.md

@@ -6,9 +6,16 @@
 A Karaoke player made to replace the old bash scripts on Sakura.
 They will enable one to have a database and make requests over the network.
 
+## Table of content
+
+- [Building instructions](#building-the-player)
+- [Preparing karaokes for lektor](#preparing-a-kara-for-lektor)
+- [How to use lektor](#how-to-use-lektor)
+- [Contributing](#contributing)
+
 ## Building the player
 
-Prerequisites:
+### Prerequisites
 
 - [autotools](https://www.gnu.org/software/autoconf/) only if you change the
   configuration (if you only edit existing files you won't need it)
@@ -52,6 +59,13 @@ If you use the configure with the `--with-depends` option (needed on debian
 Note that because of the use of `curl` and `get`, building behind a proxy may
 be challenging.
 
+If you are developping for lektor, you will need:
+
+- the [astyle](http://astyle.sourceforge.net/) command line utility, for a
+  beautifull and uniform coding style.
+
+### Building instructions
+
 The manual way of installing and setting up lektor:
 
 ```sh
@@ -81,14 +95,14 @@ On archlinux, you need only to install the package:
 makepkg -si
 ```
 
-**Important note**: if you are building using WSL, `lektord` will likely not
+> **Important note**: if you are building using WSL, `lektord` will likely not
 launch, because `XDG_RUNTIME_DIR` is not defined here. This folder is
 important, this is where most of your deamons are puttings theirs sockets and
 so. Blame Microsoft for that. A workaround is to export one: `export
 XDG_RUNTIME_DIR=$(mktemp -d)` before launching lektord. Be aware that you will
 have issues with sound and videos becouse you will need to set up a X server...
 
-Currently, supported compilers are: `icc` 19.1.2.254 and above, `gcc` 8.3.0 and
+> Currently, supported compilers are: `icc` 19.1.2.254 and above, `gcc` 8.3.0 and
 above, `clang` 7.0.1 and above. It compiles on debian, thus it must compiles on
 your system (apport from CentOS, because I never tested on it).
 
@@ -109,7 +123,9 @@ written in the `.mkv` file.
 The ideal way of populating lektor is using *Kurisu*. The *update* and *rescan*
 commands are here for that.
 
-## How to launch lektor
+## How to use lektor
+
+### Launch instructions
 
 To run lektor, you can simply run the binary like: `./lektord`.
 
@@ -132,7 +148,7 @@ card with optimus (in almose every laptop), please use `optirun` or `primusrun`:
 optirun ./lektord
 ```
 
-## How to use lektor
+### How to send commands to lektor
 
 Lektor is compatible with mpd, which means that you can use any client (only mpc is
 tested) to interact with lektor. Some functions are not *really* compatible
@@ -140,29 +156,37 @@ tested) to interact with lektor. Some functions are not *really* compatible
 
 The ideal way is to use *lkt*.
 
-## How to configure lektor
+### How to configure lektor
 
 Lektor configuration is done with an INI file. Modules' configuration is also
-done by the same INI file using diferent sections.
-
-Lektor searches for the configuration file in that order:
+done by the same INI file using diferent sections.  Lektor searches for the
+configuration file in that order:
 
-- `$(pwd)/lektor.ini`
-- if `XDG_CONFIG_HOME` defined then `$XDG_CONFIG_HOME/lektor/lektor.ini` else
+1. `$(pwd)/lektor.ini`
+2. if `XDG_CONFIG_HOME` defined then `$XDG_CONFIG_HOME/lektor/lektor.ini` else
    `$HOME/.config/lektor/lektor.ini`
-- `/opt/lektor/lektor.ini`
-- `/usr/local/etc/lektor.ini`
-- `/etc/lektor.ini`
+3. `/opt/lektor/lektor.ini`
+4. `/usr/local/etc/lektor.ini`
+5. `/etc/lektor.ini`
 
 The first one to be found is picked up by lektor. Note that if the environment
 variable `XDG_CONFIG_HOME` is not defined, it is replaced by `HOME/.config`.
 
-To get the default config file, you can use the `lkt adm conf` command.
+To get the default config file, you can use the `lkt adm conf` command. If no
+config file is found, lektord will try to create the
+`$HOME/.config/lektor/lektor.ini` config file with the default content.
+
+Be aware that if the home directory or the `XDG_CONFIG_HOME` are too long they
+will be ignored and truncated. You may then get uncomprehensible errors.
+
+## Contributing
+
+Please, refer to the [CONTRIBUTING](CONTRIBUTING.md) file.
 
-Be aware that if the home directory or the `XDG_CONFIG_HOME` are too long
-they will be ignored and truncated.
+### Modules
 
-## Modules
+Modules are a way of putting modular code in lektor. It enable the user to
+select different types of players and repositories.
 
 Modules are `.so` files (i.e. dynamic libraries) loaded by lektors using a
 function named `module_set_function` which takes a `void *` and a
@@ -187,7 +211,8 @@ structure. The rest is up to you, no checks will be done. All functions must ret
 an `int` in a POSIX way: `0` if everything is ok, an other value if something
 went wrong.
 
-## MPD
+### MPD
 
 Lektor is almost MPD compatible, at least it uses the same protocol, which can
-be gotten [here](https://www.musicpd.org/doc/html/protocol.html#).
+be gotten [here](https://www.musicpd.org/doc/html/protocol.html#). The full
+support for MPD clients (like mpc) is still WIP.