diff --git a/README.md b/README.md
index dbc002af8..dfa1c9ace 100644
--- a/README.md
+++ b/README.md
@@ -1,347 +1,80 @@
[![KOReader](https://raw.githubusercontent.com/koreader/koreader.github.io/master/koreader-logo.png)](https://koreader.rocks)
-[Download](https://github.com/koreader/koreader/releases) •
-[Wiki](https://github.com/koreader/koreader/wiki) •
-[Developer docs](http://koreader.rocks/doc/) •
-[Forum](http://www.mobileread.com/forums/forumdisplay.php?f=276) •
-[Gitter **Chat**][gitter-link]
-
-[![Build Status][circleci-badge]][circleci-link]
-[![Coverage Status][coverage-badge]][coverage-link]
-[![AGPL Licence][licence-badge]](COPYING)
-[![Latest release][release-badge]](https://github.com/koreader/koreader/releases/)
-
-
-KOReader is a document viewer primarily targeting e-ink readers.
-It runs on Cervantes, Kindle, Kobo, PocketBook and Android devices.
-Developers can also run a KOReader emulator on desktop PCs with Linux or Mac OS X.
-
-
-
-
-
-Main features for users
------------------------
-
-* supports multi-format documents including:
- * fixed page formats: PDF, DjVu, CBT, and CBZ
- * reflowable e-book formats: ePub, fb2, mobi, doc, chm and plain text
- * scanned PDF/DjVu documents can also be reflowed with built-in K2pdfopt
-* use StarDict dictionaries / Wikipedia to lookup words
-* highlights can be exported to Evernote cloud account
-* highly customizable reader view and typesetting
- * setting arbitrary page margins / line space
- * choosing external fonts and styles
- * built-in multi-lingual hyphenation dictionaries
-* supports adding custom online OPDS catalogs
-* calibre integration
- * search calibre metadata on your koreader device
- * send ebooks from calibre library to your koreader device wirelessly
- * browser calibre library and download ebooks via calibre OPDS server
-* can share ebooks with other koreader devices wirelessly
-* various optimizations for e-ink devices
- * paginated menus without animation
- * adjustable text contrast
-* multi-lingual user interface
-* online Over-The-Air software update
-
-Highlights for developers
---------------------------
-
-* frontend written in Lua scripting language
- * multi-platform support through a single code-base
- * you can help develop KOReader in any editor without compilation
- * high runtime efficiency through LuaJIT acceleration
- * light-weight self-contained widget toolkit with small memory footprint
- * extensible with plugin system
-* interfaced backends for documents parsing and rendering
- * high quality document backend libraries like MuPDF, DjvuLibre and CREngine
- * frontend interaction via LuaJIT FFI for best performance
-* in active development
- * with contributions from developers around the world
- * continuous integration with CircleCI
- * with unit tests (busted), static code analysis (luacheck) and code coverage test (luacov/coveralls)
- * automated nightly builds available at http://build.koreader.rocks/download/nightly/
-* free as in free speech
- * licensed under Affero GPL v3
- * all dependencies are free software
-
-Check out the [KOReader wiki](https://github.com/koreader/koreader/wiki) to learn
-more about this project.
-
-Building Prerequisites
-======================
-
-These instructions for how to get and compile the source are intended for a Linux
-OS. Windows users are suggested to develop in a [Linux VM][linux-vm] or use Wubi.
-
-If you only want to work with Lua frontend stuff, you can grab the AppImage and
-run it with `--appimage-extract`.
-
-To get and compile the source you must have `patch`, `wget`, `unzip`, `git`,
-`cmake` and `luarocks` installed, as well as a version of `autoconf`
-greater than 2.64. You also need `nasm` and of course a compiler like `gcc`
-or `clang`. If you want to cross-compile for other architectures, you need a proper
-cross-compile toolchain. Your GCC should be at least version 4.8.
-
-Users of Debian and Ubuntu can install the required packages using:
-```
-sudo apt-get install build-essential git patch wget unzip \
-gettext autoconf automake cmake libtool nasm luarocks \
-libssl-dev libffi-dev libsdl2-dev libc6-dev-i386 xutils-dev linux-libc-dev:i386 zlib1g:i386
-```
-
-If you are running Fedora, be sure to install the package `libstdc++-static`.
-
-That's all you need to get the emulator up and running with `./kodev build` and `./kodev run`.
-
-Cross compile toolchains are available for Ubuntu users through these commands:
-```
-# for Kindle
-sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi
-# for Kobo and Ubuntu touch
-sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
-# for Win32
-sudo apt-get install gcc-mingw-w64-i686 g++-mingw-w64-i686
-```
-
-The packages `pkg-config-arm-linux-gnueabihf` and `pkg-config-arm-linux-gnueabi` may
-block you from building for Kobo or Kindle. Remove them if you get an ld error,
-`/usr/lib/gcc-cross/arm-linux-gnueabihf/4.8/../../../../arm-linux-gnueabihf/bin/
-ld: cannot find -lglib-2.0`
-
-**NOTE:** In the specific case of Kindle & Kobo targets, while we make some effort to support these Linaro/Ubuntu TCs,
-they do *not* exactly target the proper devices. While your build will go fine, this may lead to runtime failure.
-As time goes by, and/or the more bleeding-edge your distro is, the greater the risk for mismatch gets.
-Thankfully, we have a distribution-agnostic solution for you: [koxtoolchain](https://github.com/koreader/koxtoolchain)!
-This will allow you to build the *exact* same TCs used to build the nightlies, thanks to the magic of [crosstool-ng](https://github.com/crosstool-ng/crosstool-ng).
+#### KOReader is a document viewer primarily aimed at e-ink readers.
-On Mac OS X you may need to install the following tools using [Homebrew](https://brew.sh/):
-```
-brew install nasm binutils libtool autoconf automake cmake makedepend sdl2 lua@5.1 luarocks gettext pkg-config wget md5sha1sum
-echo 'export PATH="/usr/local/opt/gettext/bin:$PATH"' >> "$HOME"/.bash_profile
-```
+[![AGPL Licence][badge-license]](COPYING)
+[![Latest release][badge-release]][link-gh-releases]
+[![Gitter][badge-gitter]][link-gitter]
+[![Mobileread][badge-mobileread]][link-forum]
+[![Build Status][badge-circleci]][link-circleci]
+[![Coverage Status][badge-coverage]][link-coverage]
-If you run into a gettext error while building glib, try `brew link --force gettext` to override the built-in Mac OS BSD gettext with GNU GetText.
-
-*Note:* in Mojave (10.14) you need to set a minimum deployment version higher than 10.04. Otherwise you'll get the error `ld: library not found for -lgcc_s.10.4`.
-```
-export MACOSX_DEPLOYMENT_TARGET=10.09
-```
-
-The KOReader Android build requires `ant`, `openjdk-8-jdk` and `p7zip-full`. A compatible version of the Android NDK and SDK will be downloaded automatically by `./kodev build android` if no NDK or SDK is provided in environment variables. For that purpose you can use `NDK=/ndk/location SDK=/sdk/location ./kodev build android`.
-
-Users of Debian Jessie first need to configure the `backports` repository:
-```
-sudo echo "deb http://ftp.debian.org/debian jessie-backports main" > /etc/apt/sources.list.d/backports.list
-sudo apt-get update
-```
-For both Ubuntu and Debian, install the packages:
-```
-sudo apt-get install ant openjdk-8-jdk
-```
-Users on Debian finally need to remove JRE version 7:
-```
-sudo apt-get remove openjdk-7-jre-headless
-```
-
-In order to build KOReader package for Ubuntu Touch, the `click` package management
-tool is needed, Ubuntu users can install it with:
-```
-sudo apt-get install click
-```
-
-You might also need SDL library packages if you want to compile and run
-KOReader on Linux PC. Fedora users can install `SDL` and `SDL-devel` package.
-Ubuntu users probably need to install the `libsdl2-dev` package:
-
-Getting the source
-==================
-
-```
-git clone https://github.com/koreader/koreader.git
-cd koreader && ./kodev fetch-thirdparty
-```
-
-Building, Running and Testing
-=============================
-
-For emulating KOReader on Linux, Windows and Mac OSX
--------------
-
-To build an emulator on your current Linux or OSX machine:
-```
-./kodev build
-```
-
-If you want to compile the emulator for Windows run:
-```
-./kodev build win32
-```
-
-To run KOReader on your development machine:
-```
-./kodev run
-```
-
-To automatically set up a number of primarily luarocks-related environment variables:
-```
-./kodev activate
-```
-
-To run unit tests:
-```
-./kodev test base
-./kodev test front
-```
-
-To run a specific unit test (for test development):
-```
-./kodev test front readerbookmark_spec.lua
-```
-
-NOTE: Extra dependencies for tests: `busted` and `ansicolors` from luarocks.
-
-To run Lua static analysis:
-```
-make static-check
-```
+[Download](https://github.com/koreader/koreader/releases) •
+[Wiki](https://github.com/koreader/koreader/wiki) •
+[Developer docs](http://koreader.rocks/doc/)
-NOTE: Extra dependencies for tests: `luacheck` from luarocks
+## Main features
-You may need to checkout the [circleci config file][circleci-conf] to setup up
-a proper testing environment. Briefly, you need to install `luarocks` and
-then install `busted` with `luarocks`. The "eng" language data file for
-tesseract-ocr is also need to test OCR functionality. Finally, make sure
-that `luajit` in your system is at least of version 2.0.2.
+* **portable**: runs on embedded devices (Cervantes, Kindle, Kobo, PocketBook), Android and Linux computers. Developers can run a KOReader emulator in Linux and MacOS.
-You can also specify the size and DPI of the emulator's screen using
-`-w=X` (width), `-h=X` (height), and `-d=X` (DPI). There is also a convenience
-`-s` (simulate) flag with some presets like `kobo-aura-one`, `kindle3`, and
-`hidpi`. The latter is a fictional device with `--screen_width=1500`,
-`--screen_height=2000` and `--screen_dpi=600` to help ensure DPI scaling works correctly.
-Sample usage:
-```
-./kodev run -s=kobo-aura-one
-```
+* **multi-format documents**: supports fixed page formats (PDF, DjVu, CBT, CBZ) and reflowable e-book formats (EPUB, FB2, Mobi, DOC, CHM, TXT). Scanned PDF/DjVu documents can also be reflowed with the built-in K2pdfopt library.
-To use your own koreader-base repo instead of the default one change the `KOR_BASE`
-environment variable:
-```
-make KOR_BASE=../koreader-base
-```
+* **full-featured reading**: multi-lingual user interface with a highly customizable reader view and many typesetting options. You can set arbitrary page margins, override line spacing and choose external fonts and styles. It has multi-lingual hyphenation dictionaries bundled into the application.
-This will be handy if you are developing `koreader-base` and you want to test your
-modifications with the KOReader frontend. NOTE: this only supports relative path for now.
+* **integrated** with *calibre* (search metadata, receive ebooks wirelessly, browse library via OPDS), *Evernote* (export hightlights), *Wallabag*, *Wikipedia*, *Google Translate* and other content providers.
-For EReader devices (kindle, kobo, pocketbook, ubuntu-touch)
----------------------
+* **optimized for e-ink devices**: custom UI without animation, with paginated menus, adjustable text contrast, and easy zoom to fit content or page in paged media.
-To build an installable package for Kindle:
-```
-./kodev release kindle
-```
+* **extensible**: via plugins
-To build an installable package for Kobo:
-```
-./kodev release kobo
-```
+* **and much more**: look up words with StarDict dictionaries / Wikipedia, add your own online OPDS catalogs and RSS feeds, share ebooks with other KOReader devices wirelessly, online over-the-air software updates, an FTP client, an SSH server, …
-To build an installable package for PocketBook:
-```
-./kodev release pocketbook
-```
+Please check the [wiki][link-wiki] to discover more features and to help us document them.
-To build an installable package for Ubuntu Touch
-```
-./kodev release ubuntu-touch
-```
+## Screenshots
-You may checkout our [nightlybuild script][nb-script] to see how to build a
-package from scratch.
+
+
+
-For Android devices
--------------------
+## Installation
-A compatible version of the Android NDK and SDK will be downloaded automatically by the
-`kodev` command. If you already have an Android NDK and SDK installed that you would like
-to use instead, make sure that the `android` and `ndk-build` tools can be found in your
-`PATH` environment variable. Additionally, the `NDK` and `SDK` variables should point
-to the root directory of the Android NDK and SDK respectively.
+Please follow the model specific steps for your device:
-Then, run this command to build an installable package for Android:
-```
-./kodev release android
-```
+[Android](https://github.com/koreader/koreader/wiki/Installation-on-Android-devices) •
+[Cervantes](https://github.com/koreader/koreader/wiki/Installation-on-BQ-devices) •
+[Kindle](https://github.com/koreader/koreader/wiki/Installation-on-Kindle-devices) •
+[Kobo](https://github.com/koreader/koreader/wiki/Installation-on-Kobo-devices) •
+[Linux](https://github.com/koreader/koreader/wiki/Installation-on-desktop-linux) •
+[Pocketbook](https://github.com/koreader/koreader/wiki/Installation-on-PocketBook-devices)
-Translation
-===========
-Please refer to [l10n's README][l10n-readme] to grab the latest translations
-from [the KOReader project on Transifex][koreader-transifex] with this command:
-```
-make po
-```
-If your language is not listed on the Transifex project, please don't hesitate
-to send a language request [here][koreader-transifex].
-Variables in translation
--------
+## Development
-Some strings contain variables that should remain unaltered in translation.
-For example:
+[Setting a build environment](doc/Building.md) •
+[Collaborating with Git](doc/Collaborating_with_Git.md) •
+[Building targets](doc/Building_targets.md) •
+[Porting](doc/Porting.md) •
+[Developer docs](http://koreader.rocks/doc/)
-```lua
-The title of the book is %1 and its author is %2.
-```
-This might be displayed as:
-```lua
-The title of the book is The Republic and its author is Plato.
-```
-To aid localization the variables may be freely positioned:
-```lua
-De auteur van het boek is %2 en de titel is %1.
-```
-That would result in:
-```lua
-De auteur van het boek is Plato en de titel is The Republic.
-```
+## Support
-Use ccache
-==========
+KOReader is developed and supported by volunteers all around the world. There are many ways you can help:
-Ccache can speed up recompilation by caching previous compilations and detecting
-when the same compilation is being repeated. In other words, it will decrease
-build time when the sources have been built before. Ccache support has been added to
-KOReader's build system. To install ccache:
+- [fix bugs][link-issues-bugs] and [implement new features][link-issues-features]
+- [translate the program into your language][link-translations-transifex] or improve an existing translation
+- document lesser known features on the [wiki][link-wiki]
+- help others with your knowledge on the [forum][link-forum]
-* in Ubuntu use:`sudo apt-get install ccache`
-* in Fedora use:`sudo yum install ccache`
-* from source:
- * download the latest ccache source from http://ccache.samba.org/download.html
- * extract the source package in a directory
- * `cd` to that directory and use:`./configure && make && sudo make install`
-* to disable ccache, use `export USE_NO_CCACHE=1` before make.
-* for more information about ccache, visit: https://ccache.samba.org/
+At this moment we don't support any form of money donation, but you can create a [bounty][link-bountysource] for the specific bug or feature request you want and motivate others to do the work.
+Also if you have and old Pocketbook device you don't want, we might find it useful to tinker a bit with that platform. Please contact us through the forum or GitHub.
-[base-readme]:https://github.com/koreader/koreader-base/blob/master/README.md
-[nb-script]:https://gitlab.com/koreader/nightly-builds/blob/master/build_release.sh
-[circleci-badge]:https://circleci.com/gh/koreader/koreader.svg?style=shield
-[circleci-link]:https://circleci.com/gh/koreader/koreader
-[circleci-conf]:https://github.com/koreader/koreader/blob/master/.circleci/config.yml
-[linux-vm]:http://www.howtogeek.com/howto/11287/how-to-run-ubuntu-in-windows-7-with-vmware-player/
-[l10n-readme]:https://github.com/koreader/koreader/blob/master/l10n/README.md
-[koreader-transifex]:https://www.transifex.com/projects/p/koreader/
-[coverage-badge]:https://codecov.io/gh/koreader/koreader/branch/master/graph/badge.svg
-[coverage-link]:https://codecov.io/gh/koreader/koreader
-[licence-badge]:http://img.shields.io/badge/licence-AGPL-brightgreen.svg
-[release-badge]:https://img.shields.io/github/release/koreader/koreader.svg
-[gitter-badge]:https://badges.gitter.im/Join%20Chat.svg
-[gitter-link]:https://gitter.im/koreader/koreader?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
+## Contributors
-Contributors
-============
+[![Last commit][badge-last-commit]][link-gh-commits]
+[![Commit activity][badge-commit-activity]][link-gh-insights]
[![0](https://sourcerer.io/fame/Frenzie/koreader/koreader/images/0)](https://sourcerer.io/fame/Frenzie/koreader/koreader/links/0)
[![1](https://sourcerer.io/fame/Frenzie/koreader/koreader/images/1)](https://sourcerer.io/fame/Frenzie/koreader/koreader/links/1)
@@ -351,3 +84,26 @@ Contributors
[![5](https://sourcerer.io/fame/Frenzie/koreader/koreader/images/5)](https://sourcerer.io/fame/Frenzie/koreader/koreader/links/5)
[![6](https://sourcerer.io/fame/Frenzie/koreader/koreader/images/6)](https://sourcerer.io/fame/Frenzie/koreader/koreader/links/6)
[![7](https://sourcerer.io/fame/Frenzie/koreader/koreader/images/7)](https://sourcerer.io/fame/Frenzie/koreader/koreader/links/7)
+
+[badge-bountysource]:https://img.shields.io/bountysource/team/koreader/activity?color=red
+[badge-circleci]:https://circleci.com/gh/koreader/koreader.svg?style=shield
+[badge-coverage]:https://codecov.io/gh/koreader/koreader/branch/master/graph/badge.svg
+[badge-commit-activity]:https://img.shields.io/github/commit-activity/m/koreader/koreader
+[badge-gitter]:https://img.shields.io/gitter/room/koreader/koreader?color=red
+[badge-last-commit]:https://img.shields.io/github/last-commit/koreader/koreader?color=orange
+[badge-license]:https://img.shields.io/github/license/koreader/koreader
+[badge-release]:https://img.shields.io/github/release/koreader/koreader.svg
+[badge-mobileread]:https://img.shields.io/badge/forum-on_mobileread-lightgrey
+
+[link-bountysource]:https://www.bountysource.com/teams/koreader
+[link-circleci]:https://circleci.com/gh/koreader/koreader
+[link-coverage]:https://codecov.io/gh/koreader/koreader
+[link-forum]:http://www.mobileread.com/forums/forumdisplay.php?f=276
+[link-gh-commits]:https://github.com/koreader/koreader/commits/master
+[link-gh-insights]:https://github.com/koreader/koreader/pulse
+[link-gh-releases]:https://github.com/koreader/koreader/releases
+[link-gitter]:https://gitter.im/koreader/koreader
+[link-issues-bugs]:https://github.com/koreader/koreader/issues?q=is%3Aopen+is%3Aissue+label%3Abug
+[link-issues-features]:https://github.com/koreader/koreader/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement
+[link-translations-transifex]:https://www.transifex.com/projects/p/koreader/
+[link-wiki]:https://github.com/koreader/koreader/wiki
diff --git a/doc/Building.md b/doc/Building.md
new file mode 100644
index 000000000..487784323
--- /dev/null
+++ b/doc/Building.md
@@ -0,0 +1,199 @@
+# Setting up a build environment for KOReader
+
+These instructions are intended to build the emulator in Linux and MacOS. Windows users are suggested to develop in a [Linux VM](https://www.howtogeek.com/howto/11287/how-to-run-ubuntu-in-windows-7-with-vmware-player/) or using the [Windows Subsystem for Linux](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux).
+
+If you only want to work with Lua frontend stuff, you can grab the AppImage and
+run it with `--appimage-extract`.
+
+You can skip most of the following instructions if desired, and use our premade Docker image instead. In that case the only requirements are Git and Docker. See [the virtual development environment README](https://github.com/koreader/virdevenv) for more information.
+
+## Prerequisites
+
+To get and compile the source you must have `patch`, `wget`, `unzip`, `git`,
+`cmake` and `luarocks` installed, as well as a version of `autoconf`
+greater than 2.64. You also need `nasm` and of course a compiler like `gcc`
+or `clang`.
+
+### Debian/Ubuntu and derivates
+
+Install the prerequisites using APT:
+
+```
+sudo apt-get install build-essential git patch wget unzip \
+gettext autoconf automake cmake libtool nasm luarocks libsdl2-dev \
+libssl-dev libffi-dev libsdl2-dev libc6-dev-i386 xutils-dev linux-libc-dev:i386 zlib1g:i386
+```
+
+
+### Fedora/Red Hat
+
+Install the `libstdc++-static`, `SDL` and `SDL-devel` packages using DNF:
+
+```
+sudo dnf install libstdc++-static SDL SDL-devel
+```
+
+### MacOS
+
+Install the prerequisites using [Homebrew](https://brew.sh/):
+
+```
+brew install nasm binutils libtool autoconf automake cmake makedepend \
+sdl2 lua@5.1 luarocks gettext pkg-config wget md5sha1sum
+echo 'export PATH="/usr/local/opt/gettext/bin:$PATH"' >> "$HOME"/.bash_profile
+```
+
+If you run into a gettext error while building glib, try `brew link --force gettext` to override the built-in Mac OS BSD gettext with GNU GetText.
+
+*Note:* in Mojave (10.14) you need to set a minimum deployment version higher than 10.04. Otherwise you'll get the error `ld: library not found for -lgcc_s.10.4`.
+```
+export MACOSX_DEPLOYMENT_TARGET=10.09
+```
+
+
+## Getting the source
+
+
+```
+git clone https://github.com/koreader/koreader.git
+cd koreader && ./kodev fetch-thirdparty
+```
+
+Building the emulator
+
+## Building and running the emulator
+
+To build an emulator on your Linux or MacOS machine:
+
+```
+./kodev build
+```
+
+To run KOReader on your development machine:
+
+```
+./kodev run
+```
+
+
+You can specify the size and DPI of the emulator's screen using
+`-w=X` (width), `-h=X` (height), and `-d=X` (DPI).
+
+ There is also a convenience
+`-s` (simulate) flag with some presets like `kobo-aura-one`, `kindle3`, and
+`hidpi`. The latter is a fictional device with `--screen_width=1500`,
+`--screen_height=2000` and `--screen_dpi=600` to help ensure DPI scaling works correctly.
+
+Sample usage:
+
+```
+./kodev run -s=kobo-aura-one
+```
+
+To use your own koreader-base repo instead of the default one change the `KOR_BASE`
+environment variable:
+
+```
+make KOR_BASE=../koreader-base
+```
+
+This will be handy if you are developing `koreader-base` and you want to test your
+modifications with the KOReader frontend. NOTE: this only supports relative path for now.
+
+## Building for other platforms
+
+Once you have the emulator ready to rock you can [build for other platforms too](Building_targets.md).
+
+## Testing
+
+You may need to check out the [circleci config file][circleci-conf] to setup up
+a proper testing environment.
+
+Briefly, you need to install `luarocks` and then install `busted` and `ansicolors` with `luarocks`. The "eng" language data file for tesseract-ocr is also need to test OCR functionality. Finally, make sure that `luajit` in your system is at least of version 2.0.2.
+
+To automatically set up a number of primarily luarocks-related environment variables:
+
+```
+./kodev activate
+```
+
+To run unit tests:
+
+```
+./kodev test base
+./kodev test front
+```
+
+To run a specific unit test (for test development):
+
+```
+./kodev test front readerbookmark_spec.lua
+```
+
+To run Lua static analysis:
+
+```
+make static-check
+```
+
+NOTE: Extra dependencies for tests: `luacheck` from luarocks.
+
+## Translations
+
+Please refer to [l10n's README][l10n-readme] to grab the latest translations
+from [the KOReader project on Transifex][koreader-transifex] with this command:
+
+```
+make po
+```
+
+If your language is not listed on the Transifex project, please don't hesitate
+to send a language request [here][koreader-transifex].
+
+### Variables in translation
+
+Some strings contain variables that should remain unaltered in translation. These take the form of a `%` followed by a number from `1-99`, although you'll seldom see more than about 5 in practice. Please don't put any spaces between the `%` and its number. `%1` should always remain `%1`.
+For example:
+
+```lua
+The title of the book is %1 and its author is %2.
+```
+
+This might be displayed as:
+
+```lua
+The title of the book is The Republic and its author is Plato.
+```
+
+To aid localization the variables may be freely positioned:
+
+```lua
+De auteur van het boek is %2 en de titel is %1.
+```
+
+That would result in:
+
+```lua
+De auteur van het boek is Plato en de titel is The Republic.
+```
+
+## Use ccache
+
+Ccache can speed up recompilation by caching previous compilations and detecting
+when the same compilation is being repeated. In other words, it will decrease
+build time when the sources have been built before. Ccache support has been added to
+KOReader's build system. To install ccache:
+
+* in Ubuntu use:`sudo apt-get install ccache`
+* in Fedora use:`sudo dnf install ccache`
+* from source:
+ * download the latest ccache source from http://ccache.samba.org/download.html
+ * extract the source package in a directory
+ * `cd` to that directory and use:`./configure && make && sudo make install`
+* to disable ccache, use `export USE_NO_CCACHE=1` before make.
+* for more information about ccache, visit: https://ccache.samba.org/
+
+[circleci-conf]:https://github.com/koreader/koreader/blob/master/.circleci/config.yml
+[koreader-transifex]:https://www.transifex.com/projects/p/koreader/
+[base-readme]:https://github.com/koreader/koreader-base/blob/master/README.md
+[l10n-readme]:https://github.com/koreader/koreader/blob/master/l10n/README.md
diff --git a/doc/Building_targets.md b/doc/Building_targets.md
new file mode 100644
index 000000000..80a33fcaa
--- /dev/null
+++ b/doc/Building_targets.md
@@ -0,0 +1,170 @@
+# Building targets
+
+KOReader is available for multiple platforms. Here are instructions to build installable packages for all these platforms.
+
+These instructions are intended for a Linux OS. MacOS and Windows users are suggested to develop in a Linux VM.
+
+
+## Prerequisites
+
+This instructions asume that you [have a development environment ready to run](Building.md) KOReader. If not then please install common prerequisites first.
+
+### A toolchain for your target.
+
+Each target has its own architecture and you'll need to setup a proper cross-compile toolchain. Your GCC should be at least version 4.9.
+
+#### for Android
+
+A compatible version of the Android NDK and SDK will be downloaded automatically by `./kodev release android` if no NDK or SDK is provided in environment variables. For that purpose you can use:
+
+```
+NDK=/ndk/location SDK=/sdk/location ./kodev release android
+```
+
+If you want to use your own installed tools please make sure that you have the **NDKr15c** and the SDK for Android 9 (**API level 28**) already installed.
+
+#### for embedded linux devices
+
+Cross compile toolchains are available for Ubuntu users through these commands:
+
+##### Kindle and Cervantes
+
+```
+sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi
+```
+
+##### Kobo and Ubuntu Touch
+
+```
+sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
+```
+
+**NOTE 1:** The packages `pkg-config-arm-linux-gnueabihf` and `pkg-config-arm-linux-gnueabi` may
+block you from building. Remove them if you get the following ld error
+
+```
+/usr/lib/gcc-cross/arm-linux-gnueabihf/4.8/../../../../arm-linux-gnueabihf/bin/ld: cannot find -lglib-2.0
+```
+
+**NOTE 2:** In the specific case of Cervantes, Kindle & Kobo targets, while we make some effort to support these Linaro/Ubuntu TCs,
+they do *not* exactly target the proper devices. While your build will go fine, this may lead to runtime failure.
+As time goes by, and/or the more bleeding-edge your distro is, the greater the risk for mismatch gets.
+Thankfully, we have a distribution-agnostic solution for you: [koxtoolchain](https://github.com/koreader/koxtoolchain)!
+This will allow you to build the *exact* same TCs used to build the nightlies, thanks to the magic of [crosstool-ng](https://github.com/crosstool-ng/crosstool-ng). These are also included precompiled in the Docker images for the respective targets.
+
+**NOTE 3:** The vendor toolchain will be downloaded automatically by `./kodev release pocketbook`
+
+### Additional packages
+
+Some platforms will require additional packages:
+
+#### for Android
+
+Building for Android requires `openjdk-8-jdk` and `p7zip-full`.
+
+
+For both Ubuntu and Debian, install the packages:
+
+```
+sudo apt-get install openjdk-8-jdk p7zip-full
+```
+
+#### for Debian
+
+Building a debian package requires the `dpkg-deb` tool. It should be already installed if you're on a Debian/Ubuntu based distribution.
+
+#### for Ubuntu Touch
+
+Building for Ubuntu Touch requires the `click` package management tool.
+
+Ubuntu users can install it with:
+
+```
+sudo apt-get install click
+```
+
+**NOTE**: The Ubuntu Touch build won't start anymore, and none of the currently active developers have any physical devices. Please visit [#4960](
+https://github.com/koreader/koreader/issues/4960) if you want to help.
+
+The Ubuntu Touch builds are therefore no longer published under releases on GitHub, but they are still available from [the nightly build server](http://build.koreader.rocks/download/nightly/).
+
+## Building
+
+You can check out our [nightlybuild script][nb-script] to see how to build a
+package from scratch.
+
+### Android
+
+```
+./kodev release android
+```
+
+### Android (x86)
+
+```
+ANDROID_ARCH=x86 ./kodev release android
+```
+
+### Cervantes
+
+```
+./kodev release cervantes
+```
+
+### Desktop Linux
+
+#### AppImage (x86_64)
+
+```
+./kodev release appimage
+```
+
+#### Debian (x86_64)
+
+```
+./kodev release debian
+```
+
+#### Debian (armel)
+
+```
+./kodev release debian-armel
+```
+
+#### Debian (armhf)
+
+```
+./kodev release debian-armhf
+```
+
+### Kindle
+
+```
+./kodev release kindle
+```
+
+### Kobo
+
+```
+./kodev release kobo
+```
+
+### Pocketbook
+
+```
+./kodev release pocketbook
+```
+
+### Ubuntu Touch
+
+```
+./kodev release ubuntu-touch
+```
+
+
+## Porting to a new target.
+
+See [Porting.md](Porting.md)
+
+
+[nb-script]:https://gitlab.com/koreader/nightly-builds/blob/master/build_release.sh
diff --git a/doc/Collaborating with Git.md b/doc/Collaborating_with_Git.md
similarity index 100%
rename from doc/Collaborating with Git.md
rename to doc/Collaborating_with_Git.md
diff --git a/doc/Development guide.md b/doc/Development_guide.md
similarity index 100%
rename from doc/Development guide.md
rename to doc/Development_guide.md
diff --git a/doc/Unit tests.md b/doc/Unit_tests.md
similarity index 100%
rename from doc/Unit tests.md
rename to doc/Unit_tests.md