Updated documentation

4 files changed, 128 insertions, 11 deletions

diff --git a/BUGS.md b/BUGS.md
index df2d942..53d77dd 100644
--- a/BUGS.md
+++ b/BUGS.md
@@ -1,5 +1,25 @@
+## Reporting bugs
+
+Please include the following when reporting bugs:
+
+* Operating system used
+* Version of Qt used, any relevant information if you built it yourself
+* Detailed explanation of the bug: 
+  * what was done
+  * what was expected
+  * what happened
+
+An example of a bad bug report is:
+
+> Something happened, and when I pressed the button it broke.
+
+An exmaple of a good bug report is:
+
+> When I opened xyz menu and pressed abc, nothing happened.
+
+Send bug reports to _aqua at iserlohn dash fortress dot net_.
+
 ## Known bugs
-List of known bugs that can't be fixed atm
 
 ### Search terms in address bar
 QUrl always seems to return true when checking if valid url. Workaround is to
@@ -7,6 +27,3 @@ prepend '#' to the search.
 
 ### databases-incognito in home
 https://bugreports.qt.io/browse/QTBUG-62957
-
-### Shortcuts don't work at times
-A field on a page is probably taking focus.
diff --git a/BUILDING.md b/BUILDING.md
new file mode 100644
index 0000000..f654f8f
--- /dev/null
+++ b/BUILDING.md
@@ -0,0 +1,55 @@
+## Before you start
+
+### [Qt](https://www.qt.io/)
+An up-to-date version of Qt is required, even though the code, with minor
+patches, can work with anything after 5.7.
+
+An up-to-date version of QtWebEngine is highly recommended also due to fixes to
+Blink that do _not_ get backported. QtWebEngine can be built with older versions
+of Qt.
+
+### [boost](http://www.boost.org/)
+Required component: program_options
+
+### cmake
+Minimal version 3.1.0, but please use something up-to-date.
+
+### A working compiler with C++17 support
+ - gcc 7
+ - clang 4 or later
+ - only MSVC is supported on Windows due to QtWebEngine
+
+## Compiling
+smolbote follows the generic cmake build template:
+
+~~~ sh
+# 1. Clone the repository
+hg clone https://neueland.iserlohn-fortress.net/smolbote.hg
+
+# 2. Generate Makefile
+mkdir release && cd release
+cmake -DCMAKE_BUILD_TYPE=Release ../smolbote.hg
+
+# 3. Build
+make -j 4
+
+# 4. Install
+make install
+~~~
+
+### howto --verbose
+
+#### -DCMAKE_BUILD_TYPE
+Controls what flags and optimizations are set. Possible values: Debug, Release,
+RelWithDebInfo, MinSizeRel
+
+#### -DCMAKE_INSTALL_PREFIX
+Sets the install location. Binaries will be written to bin/, and plugins to
+lib/smolbote/.
+
+#### Using libc++
+You can use libc++ over stdlibc++ by setting UseLibCpp to On. Requires clang.
+
+~~~ sh
+-DCMAKE_CXX_COMPILER=/usr/bin/clang++ -DUseLibCpp=On
+~~~
diff --git a/QUICKSTART.md b/QUICKSTART.md
new file mode 100644
index 0000000..8d8d80b
--- /dev/null
+++ b/QUICKSTART.md
@@ -0,0 +1,37 @@
+## Configuration files
+Configuration is saved in:
+
+- on Linux, _~/.config/smolbote/_
+
+## Keyboard shortcuts
+
+### Navigation
+- Ctrl + Left - go back
+- Ctrl + Right - go forward
+
+### Tabs
+- Ctrl + T - new tab
+- Ctrl + O - previous tab
+- Ctrl + P - next tab
+- Ctrl + X - close tab
+
+## Command line
+
+~~~ sh
+Usage: poi [options] URL
+
+Options:
+- h, help             Displays this help.
+- v, version          Displays version information.
+- build               Show build information.
+- c, config           Set configuration file.                 ~/.config/smolbote/smolbote.cfg
+- p, profile          Use this profile.
+- socket              Local server socket                     /tmp/smolbote.socket
+- in-new-window       Open URL in new window
+
+You can also overwrite configuration options using the syntax:
+--browser.setting.path=value
+
+Arguments:
+- URL                 URL(s) to open
+~~~
diff --git a/README.md b/README.md
index 0044991..99e93d4 100644
--- a/README.md
+++ b/README.md
@@ -2,25 +2,33 @@
 _It's yet another no-frills browser, poi!_
 
 ### What is this and why should I care?
-The aim is to create a [KISS][kiss-principle] free-software web browser.
+The aim is to create a [keep-it-simple][kiss-principle] free software web browser.
 
-* small: do one thing and do it well
-* clean: a small codebase of human-readable code
+* do one thing and do it well
+* just work out of the box
 * tweakable: you can change all the things
 
-This is free software. You can use it as you see fit, studay the source code
-and change it to suit your needs, and share the program, with or without
-modification. For more information, see LICENSE.md.
+This program is free software. You can:
+
+* use it as you see fit;
+* study the source code and change it to suit your needs;
+* share the program;
+* share your modifications.
+
+For more information, and a list of free software we depend on, see [LICENSE.md][repo-license].
 
 ### What's up with the name?!
-It's a small boat.
+It's a small boat. It says poi.
 
 ### Sounds dumb, how do I use it?
 You make it yourself. Then you _poi_.
 
 Do you know what makepkg is? Then take a look in linux/makepkg/.
 
+Do you know what a compiler is? Great, glance at the [build instructions](/smolbote/building.html).
+
 ### It doesn't work, what now?
 Drop me an email at _aqua at iserlohn dash fortress dot net_.
 
 [kiss-principle]: https://en.wikipedia.org/wiki/KISS_principle
+[repo-license]: https://neueland.iserlohn-fortress.net/smolbote.hg/file/tip/LICENSE.md