Update doc/ and move various entries to wiki

25 files changed, 96 insertions, 639 deletions

diff --git a/doc/Bugs.asciidoc b/doc/Bugs.asciidoc
deleted file mode 100644
index d4ab1ec..0000000
--- a/doc/Bugs.asciidoc
+++ /dev/null
@@ -1,60 +0,0 @@
-== Reporting bugs
-
-=== What to include
-A bug report should contain these 4 things:
-
-==== Environment
-This includes program version; operating system used; version of Qt or other
-libraries; any relevant information if you built from source.
-
-==== Steps to reproduce
-Give detailed steps on how to reproduce the problem. Start from the beginning,
-mention the actions involved, and be verbose.
-
-==== Expected result
-It's important to include the result you were expecting, as it might differ
-from the way the program was designed to work.
-
-==== Actual result
-It is also important to include a good description of the buggy behaviour
-itself as well, because it's possible that following your steps on a different
-system doesn't reproduce the issue.
-
-Send bug reports to _aqua at iserlohn dash fortress dot net_.
-
-_Adapted from the guide in the texmate repository._
-
-== Known bugs
-
-=== databases-incognito in home
-https://bugreports.qt.io/browse/QTBUG-62957
-
-=== loadFinished is not always emitted when loading is finished
-https://bugreports.qt.io/browse/QTBUG-65223
-
-=== QWebEngineView setUrl()/load() methods in some case divide page in two parts
-https://bugreports.qt.io/browse/QTBUG-68224
-
-Only affects Qt 5.11.0. Set __QTBUG_68224_WORKAROUND__.
-
-=== rcc embeds time in output
-https://bugreports.qt.io/browse/QTBUG-62511
-
-=== QWebEngineUrlRequestInterceptor does not allow to pass the Referer header
-https://bugreports.qt.io/browse/QTBUG-60203
-
-=== Wayland bugs
-
-=== mainwindow.maximized doesn't work
-setWindowState(Qt::WindowMaximized) has no effect on KDE/Wayland:
-https://community.kde.org/Plasma/Wayland_Showstoppers
-
-=== Windows bugs
-
-=== stdout and stderr
-Starting the application with some command-line options (like --version,
---help, etc) causes the application to 'stall' on exit.
-
-Starting the application from the command prompt returns after launch, but
-continues outputting stdout and stderr to it.
-
diff --git a/doc/Building.asciidoc b/doc/Building.asciidoc
deleted file mode 100644
index fc7cc89..0000000
--- a/doc/Building.asciidoc
+++ /dev/null
@@ -1,67 +0,0 @@
-== Requirements
-
-[cols="1,1,3"]
-|===
-|Name |Version |Notes
-
-| link:https://www.qt.io/[Qt]
-| 5.11.1 or later
-| QtWebEngine should be buildable with older versions of Qt. Please use the
-  latest version.
-
-| link:http://www.boost.org/[boost]
-| Version 1.66
-| Components: program_options
-
-| link:https://mesonbuild.com/[meson]
-| Version 0.48
-| Requires python3 and ninja
-
-| link:https://github.com/ulfalizer/Kconfiglib[Kconfiglib]
-| Version 10.22.1
-| Available on PyPI with 'pip install kconfiglib'
-
-| A compiler
-| C++17 support
-| gcc 7+; clang 4+; on Windows only MSVC is supported due to QtWebEngine
-
-| asciidoc
-| 
-| Only for building manpage
-
-|===
-
-== Building from source
-[source, sh]
-----
-# clone the repository
-git clone https://neueland.iserlohn-fortress.net/gitea/aqua/smolbote.git smolbote.git
-cd smolbote.git
-
-# These two submodules are required
-git submodule init
-git submodule update 3rd-party/SingleApplication/SingleApplication.git
-git submodule update tools/Kconfiglib
-
-# generate build.ninja
-mkdir build
-meson build
-
-# make
-ninja
-----
-
-Run `meson configure` in the build directory to list available options.
-For more information on how to use meson, see the meson link:https://mesonbuild.com/Quick-guide.html[quick guide].
-
-=== Configuring smolbote
-smolbote uses Kconfig to store and customize default application settings such
-as keyboard shortcuts and paths. You can edit these settings using 'menuconfig'
-in the repository root.
-
-When building, tools/config.py is used to load `$platform-name/.config` and
-generate a header file.
-
-// Compiling on Windows
-include::Building/Windows.asciidoc[]
-
diff --git a/doc/Building/Breakpad.asciidoc b/doc/Building/Breakpad.asciidoc
deleted file mode 100644
index aa2642e..0000000
--- a/doc/Building/Breakpad.asciidoc
+++ /dev/null
@@ -1,44 +0,0 @@
-== Breakpad
-
-=== Enabling breakpad
-Use the `-DBreakpad=enabled` option. This requires Breakpad be installed as a package.
-
-=== Building breakpad on linux
-[source, sh]
-----
-# Get the missing linux syscall support header
-if [ ! -f breakpad.git/src/third_party/lss/linux_syscall_support.h ]; then
-    mkdir -p breakpad.git/src/third_party/lss
-    curl -L https://chromium.googlesource.com/linux-syscall-support/+/master/linux_syscall_support.h?format=TEXT | base64 --decode > breakpad.git/src/third_party/lss/linux_syscall_support.h
-fi
-
-buildpath=$(pwd)/build
-if [ ! -d $buildpath ]; then
-    mkdir $buildpath
-fi
-
-installpath=$(pwd)/install
-if [ ! -d $installpath ]; then
-    mkdir $installpath
-fi
-
-cd $buildpath
-../breakpad.git/configure --prefix=$installpath
-make
-make install
-----
-
-=== Producing symbols
-[source, sh]
-----
-tools/linux/dump_syms/dump_syms ./poi > poi.sym
-head -n1 poi.sym
-mkdir -p ./symbols/poi/<hex>
-mv poi.sym ./symbols/poi/<hex>
-----
-
-=== Processing minidump
-[source, sh]
-----
-processor/minidump_stackwalk minidump.dmp ./symbols
-----
diff --git a/doc/Building/Windows.asciidoc b/doc/Building/Windows.asciidoc
deleted file mode 100644
index 4c1fc20..0000000
--- a/doc/Building/Windows.asciidoc
+++ /dev/null
@@ -1,26 +0,0 @@
-== Building on Windows
-[source, bat]
-----
-set INSTALL_DIR="C:\projects\smolbote-install"
-mkdir %INSTALL_DIR%
-
-mkdir C:\projects\smolbote-build
-cd C:\projects\smolbote-build
-
-set QT="C:\Qt\5.11\msvc2017_64"
-set BOOST_ROOT="C:\Libraries\boost_1_66_0"
-set BOOST_LIBDIR="C:\Libraries\boost_1_66_0\lib64-msvc-14.1"
-
-cmake  -G "Visual Studio 15 2017 Win64" -DCMAKE_BUILD_TYPE=Release 
-    -DCMAKE_INSTALL_PREFIX=%INSTALL_DIR% 
-    -DCMAKE_PREFIX_PATH=%QT%;%BOOST_ROOT% 
-    -DBOOST_ROOT=%BOOST_ROOT% -DBOOST_LIBRARYDIR=%BOOST_LIBDIR% -DBoost_USE_STATIC_LIBS=On 
-    C:\projects\smolbote
-
-cmake --build . --target poi --config Release
-cmake --build . --target install --config Release
-cd %INSTALL_DIR%
-C:\Qt\5.11\msvc2017_64\bin\windeployqt.exe bin\poi.exe
-
-7z a C:\projects\smolbote\build.7z %INSTALL_DIR%
-----
diff --git a/doc/Building/meson.asciidoc b/doc/Building/meson.asciidoc
deleted file mode 100644
index 255e0ad..0000000
--- a/doc/Building/meson.asciidoc
+++ /dev/null
@@ -1,39 +0,0 @@
-==== Setting compiler
-Compiler can only be set when initially configuring the build, and cannot be
-changed with --reconfigure:
-
-[source, sh]
-----
-export CXX="ccache clang++"
-meson build-path
-----
-
-==== Setting linker
-[source, sh]
-----
-build% meson configure -Dcpp_link_args='-fuse_ld=gold'
-----
-
-==== Listing build options
-[source, sh]
-----
-build% meson configure
-----
-
-==== Changing build options
-[source, sh]
-----
-build% meson configure -D<option-name>=<enabled|disabled>
-# for example:
-build% meson configure -DPlasma=enabled
-----
-
-==== Prevent meson from downloading wraps
-During configure, meson can download missing dependencies on its own using
-wraps. To disable this, pass '--wrap-mode=nodownload' during the configure
-phase:
-[source, sh]
-----
-repo% meson --wrap-mode=nodownload build-path
-----
-
diff --git a/doc/Development.asciidoc b/doc/Development.asciidoc
deleted file mode 100644
index 1ef2ded..0000000
--- a/doc/Development.asciidoc
+++ /dev/null
@@ -1,73 +0,0 @@
-== Guidelines
-
-smolbote is written under the C++17 standard, without any compiler-specific
-extensions. Source code should be kept as platform-agnostic as possible.
-
-=== General
-* All behaviour, where possible, should be configurable.
-* Configuration is stored in plaintext files, and option names should be as
-  self-descriptive as possible.
-* Use sane defaults. Normally, the program should "just work".
-
-=== Qt
-* Check pointers with Q_CHECK_PTR.
-* Use the Qt5 signal/slot syntax (&Class::method) over the old string-based
-  syntax (SIGNAL/SLOT). This enables compile-time connect checks.
-* Prefer QVector over QList: http://lists.qt-project.org/pipermail/development/2017-March/029040.html
-
-=== Setting linker
-Meson has no environment variable to set the linker (link:https://github.com/mesonbuild/meson/issues/3597[issue]).
-
-Instead, this can be done using the cpp_link_args:
-[source, sh]
-----
-build% meson configure -Dcpp_link_args='-fuse-ld=gold'
-----
-
-=== clazy
-You can use https://github.com/KDE/clazy[clazy] to check Qt semantics.
-
-clazy is a drop-in replacement for clang. To set check levels, set the
-CLAZY_CHECKS environment variable to 'level0,level1', etc.
-
-== Licensing
-Smolbote is licensed under GPLv3 _only_, and explicitly does not use any
-self-updating "-or-later" licensing. Your code needs to be compatible with it,
-and have a license header in the style used by the project.
-
-Interfaces (located in include/) should be licensed under MIT. This is to allow
-more license compatibility for plugins.
-
-=== SPDX-License-Identifier
-A full list of license identifiers can be found on https://spdx.org/licenses/[the SPDX website].
-
-== Style
-There is a clang-format style in .clang-format.
-
-== Format patch for email
-
-[source, sh]
-----
-git format-patch $from..$to
-----
-
-This will give you one patch per commit. If you want to merge all of them into
-a single patch, you can merge the commits using rebase:
-
-[source, sh]
-----
-git rebase --interactive
-----
-
-Alternatively, replay all your commits from the commit before $from on a new
-branch:
-
-[source, sh]
-----
-git branch delivery X
-git checkout delivery
-git merge --squash master
-git format-patch HEAD
-----
-
-Email patches to _aqua at iserlohn dash fortress dot net_.
diff --git a/doc/Development/Fuzzing.asciidoc b/doc/Development/Fuzzing.asciidoc
deleted file mode 100644
index 0981f1a..0000000
--- a/doc/Development/Fuzzing.asciidoc
+++ /dev/null
@@ -1,49 +0,0 @@
-=== Setup
-Required packages: afl
-
-==== Compiling Qt
-This will build an instrumented Qt:
-
-[source, sh]
-----
-export CC=$(which afl-gcc)
-export CXX=$(which afl-g++)
-./configure ...
-make
-----
-
-=== Running the fuzzer
-[source, sh]
-----
-cd /sys/devices/system/cpu
-su
-echo performance | tee cpu*/cpufreq/scaling_governor
-exit
-
-cd $testdir
-afl-fuzz -m 512 -t 40 -i $input -o $output -- $testexe @@
-
-# see for available scaling_governor values:
-cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_governors
-
-cd /sys/devices/system/cpu
-su
-echo powersave | tee cpu*/cpufreq/scaling_governor
-exit
-----
-
-The $input directory contains your reference input files, while the findings of the fuzzers will be written in $output.
-
-@@ gets replaced by the name of a file generated by AFL, containing the mutated input.
-
-=== Using ramdisk for tests
-[source, sh]
-----
-$ mkdir afl
-# mount -t tmpfs -o size=1024M tmpfs afl/
-$ cd afl/
-$ afl-fuzz -i inputs -o findings ...
-----
-
-=== Sources
-1. https://www.kdab.com/fuzzing-qt-fun-profit/
diff --git a/doc/Development/Hacking.asciidoc b/doc/Development/Hacking.asciidoc
deleted file mode 100644
index d0332e9..0000000
--- a/doc/Development/Hacking.asciidoc
+++ /dev/null
@@ -1,52 +0,0 @@
-== C++ Performance
-(Adapted from CppCon2016 Practical Performance Practices)
-https://florianjw.de/en/cpp_coding_standard.html
-
-- Prefer std::array, then std::vector
-- Construct and initialize in one step
-- Use const always when possible
-- To enable const with complex initialization, use lambdas
-- Don't recalculate values that only need to be calculated once
-- Don't disable move operations - moving is more efficient than copying
-- Avoid shared_ptr copies unless really needed
-- Prefer returning unique_ptr from factories
-- Use '\n' instead of std::endl
-- Use lambdas - they have no overhead compared to direct functions
-- final can help the compiler optimize virtual function calls
-- Code branches are expensive
-
-=== Smaller code is faster code
-
-=== Do one thing and do it well
-Simple code is easy to understand, easy to maintain, and as such lead to less bugs.
-
-=== Only use text formats
-They can be edited both by humans and by programs. Use generic formats (ini, json, etc.) instead of custom ones.
-
-=== Document your changes
-Don't do this just for others, do it for your future self.
-
-== Useful compiler options
-- -fuse-ld=gold
-- -Wold-style-cast
-
-=== Setting in meson
-Compiler arguments are free-form comma-separated list.
-meson configure -Dcpp_args="-Wold-style-cast"
-meson configure -Dcpp_link_args="-fuse-ld=gold"
-
-== C++ Coding Standard
-
-=== Naming Conventions
-- Naming uses camelCase
-- Private attributes are prefixed with 'm_'.
-- Include guards should be named SMOLBOTE_<class name in caps>_H
-
-=== Compiler
-- Use the highest sane warning level.
-
-=== Resource management
-- Manage your resources with RAII (Resource Acquisition Is Initialization).
-
-=== Functions
-- Try to keep the complexity low and the body short.
diff --git a/doc/Development/Manual.asciidoc b/doc/Development/Manual.asciidoc
deleted file mode 100644
index 6e5a39f..0000000
--- a/doc/Development/Manual.asciidoc
+++ /dev/null
@@ -1,11 +0,0 @@
-== manpage
-
-=== Generating manpage
-[code, sh]
-----
-# with asciidoc
-a2x --format=manpage doc/smolbote.7.asciidoc
-
-# with asciidoctor
-asciidoctor --backend=manpage doc/smolbote.7.asciidoc
-----
diff --git a/doc/Development/RepositoryCommands.asciidoc b/doc/Development/RepositoryCommands.asciidoc
deleted file mode 100644
index 13e2f8e..0000000
--- a/doc/Development/RepositoryCommands.asciidoc
+++ /dev/null
@@ -1,6 +0,0 @@
-== Repository commands
-[code, sh]
-----
-# listing branches
-curl --request GET --url https://neueland.iserlohn-fortress.net/gitea/api/v1/repos/aqua/smolbote/branches
-----
diff --git a/doc/Development/Session.asciidoc b/doc/Development/Session.asciidoc
deleted file mode 100644
index 846d6a3..0000000
--- a/doc/Development/Session.asciidoc
+++ /dev/null
@@ -1,19 +0,0 @@
-== Session
-
-== Session JSON structure
-- windows: list of windows
-
-=== Window
-- subwindows: list of subwindows
-
-=== Subwindow
-- profile: profile ID
-- tabs: list of views
-- current: current tab index
-
-=== View
-- profile: profile ID
-- history: view history
-
-Storing history: compress, toBase64 (to make printable), toQString (to store in json)
-Restoring history: toLatin1 (turn into bytearray), fromBase64, uncompress
diff --git a/doc/Development/Translating.asciidoc b/doc/Development/Translating.asciidoc
deleted file mode 100644
index f79fa56..0000000
--- a/doc/Development/Translating.asciidoc
+++ /dev/null
@@ -1,16 +0,0 @@
-== Translating
-[code, sh]
-----
-# generating translations
-lupdate src/ lib/ -ts lang/<lang-id>.ts
-
-# updating translations
-lupdate src/ lib/ -no-obsolete -ts lang/<lang-id>.ts
-
-# generate lang/<lang-id>.qm
-lrelease lang/<land-id>.ts
-----
-
-=== Using translations
-  --browser.locale        # set Qt translation; ex. de
-  --browser.translation   # set translation file; ex. /home/user/.config/smolbote/lang/custom-translate.qm
diff --git a/doc/Development/Updater.asciidoc b/doc/Development/Updater.asciidoc
deleted file mode 100644
index a039318..0000000
--- a/doc/Development/Updater.asciidoc
+++ /dev/null
@@ -1,25 +0,0 @@
-== Updater
-
-=== Creating manifest
-[code, sh]
-----
-find windows/ -type f | xargs sha512sum | sed 's/windows\///' > windows-sha512.txt
-find windows/ -type d -exec chmod 755 {} +
-----
-
-=== Building
-
-You can build for the current system using:
-[code, sh]
-----
-go build
-# remove debug information
-strip updater
-----
-
-You can also cross-compile for other systems by setting GOOS and GOARCH. For a
-list of supported platforms, use `go tool dist list`.
-[code, sh]
-----
-GOOS=windows GOARCH=amd64 go build
-----
diff --git a/doc/Development/git.asciidoc b/doc/Development/git.asciidoc
deleted file mode 100644
index e9e8b61..0000000
--- a/doc/Development/git.asciidoc
+++ /dev/null
@@ -1,10 +0,0 @@
-== git
-
-=== Updating submodules
-[source, sh]
-----
-git submodule update --remote --merge
-
-# add to commit
-git add 3rd-party/<submodule>
-----
diff --git a/doc/Usage.asciidoc b/doc/Usage.asciidoc
deleted file mode 100644
index ee2cc20..0000000
--- a/doc/Usage.asciidoc
+++ /dev/null
@@ -1,21 +0,0 @@
-== Keyboard shortcuts
-- F4 to focus the address bar and type an address; F2 show its menu
-- Ctrl + Left/Right - go back/forward
-- Ctrl + T - new tab
-- Ctrl + X - close tab
-- Ctrl + O/P - previous tab/next tab
-- Ctrl + Shift + O/P - move tab left/right
-- Ctrl + B - show/hide bookmarks
-- Ctrl + D - show/hide downloads
-
-== Subwindows
-A subwindow is a multiple document interface window that contains a collection
-of tabs and has a default profile. It can be minimized, resized, moved,
-maximized, tiled (F9) and cascaded (F10) within the main window.
-
-- Ctrl + G - new subwindow
-- Ctrl + W - close subwindow
-
-include::Usage/Profile.asciidoc[]
-
-include::Usage/Configuration.asciidoc[]
diff --git a/doc/Usage/CommandLine.asciidoc b/doc/Usage/CommandLine.asciidoc
deleted file mode 100644
index 00a8d6c..0000000
--- a/doc/Usage/CommandLine.asciidoc
+++ /dev/null
@@ -1,14 +0,0 @@
-== Command-line Options
-
-=== General
-* `-h`, `--help`: Display command-line options list..
-* `-v`, `--version`: Display version information.
-* `--build`: Display build commit.
-
-=== Configuration
-* `-c`, `--config`: Set configuration file.
-* `--no-remote`: Don't check for other instances when starting.
-
-=== Sessions
-* `-s, --session`: Open the selected session.
-* `--pick-session`: Open all available sessions and select which one to open.
diff --git a/doc/Usage/Configuration.asciidoc b/doc/Usage/Configuration.asciidoc
deleted file mode 100644
index b1dbec5..0000000
--- a/doc/Usage/Configuration.asciidoc
+++ /dev/null
@@ -1,14 +0,0 @@
-== Configuration
-
-The Configuration is loaded from the path specified by `--config`, by default
-_~/.config/smolbote/smolbote.cfg_.
-
-You can set the value of configuration options using its name in a key=value
-pair, for example:
-[source, ini]
-----
-mainwindow.height=600
-----
-For a full list of options, check `--help`.
-
-You can overwrite options at runtime using the option name as a parameter.
diff --git a/doc/Usage/Filter.asciidoc b/doc/Usage/Filter.asciidoc
deleted file mode 100644
index d23d57a..0000000
--- a/doc/Usage/Filter.asciidoc
+++ /dev/null
@@ -1,12 +0,0 @@
-== Url Request Filter
-smolbote has a singular URL request filter that is installed onto all profiles.
-Any setting applied to it will be applied to all profiles.
-
-=== filter.header
-  A list of header-value pairs, separated by a colon (':').
-
-You can specify multiple headers by using --filter.header multiple times:
-[source, sh]
-----
-poi --filter.header "Dnt:1" --filter.header "Accept:text/html"
-----
diff --git a/doc/Usage/Linux.asciidoc b/doc/Usage/Linux.asciidoc
deleted file mode 100644
index 748ea10..0000000
--- a/doc/Usage/Linux.asciidoc
+++ /dev/null
@@ -1,15 +0,0 @@
-== Linux
-
-=== firejail
-To launch poi by default with firejail, symlink /usr/bin/firejail to the poi
-executable:
-
-[source, sh]
-----
-# poi is installed to /usr/local/bin/poi, and local/sbin is before local/bin.
-ln -s /usr/bin/firejail /usr/local/sbin/poi
-----
-
-To add the poi.profile to firejail, copy or symlink it to '/etc/firejail' or
-'~/.config/firejail'.
-
diff --git a/doc/Usage/Plugins.asciidoc b/doc/Usage/Plugins.asciidoc
deleted file mode 100644
index 1f2d3a0..0000000
--- a/doc/Usage/Plugins.asciidoc
+++ /dev/null
@@ -1,7 +0,0 @@
-== Plugins
-Plugins a way of extending smolbote's functionality using the Qt plugin system.
-They are not to be confused with NPAPI/PPAPI or WebExtension plugins.
-
-To enable a plugin either copy it or symlink it in the plugins.path location,
-or set its absolute path as the plugins.path.
-
diff --git a/doc/Usage/Profile.asciidoc b/doc/Usage/Profile.asciidoc
deleted file mode 100644
index 79506fd..0000000
--- a/doc/Usage/Profile.asciidoc
+++ /dev/null
@@ -1,37 +0,0 @@
-== Profiles
-A Profile is a collection of settings, policies, scripts, cookies, cache and
-history. Profiles can be used to isolate pages from each other.
-
-Off-the-record profiles only use in-memory cache and save no files to disk.
-
-Profiles can be either temporary or permanent. Temporary profiles are expire
-when the application is closed, whereas permanent profiles are kept between
-runs.
-
-Each window has a default profile it uses when opening new tabs. This can be
-changed from the window's menu. Additionally, tabs can have their profiles
-individually changed from their context menu.
-
-Because profiles store all their data separately, you can log in into the same
-site with a different account from each profile. However, links opened into new
-tabs will still use the subwindow's default profile. For example, you can set a
-profile to hold login information for a site, but all new tabs opened from that
-site would still be using the default off-the-record profile.
-
-Profiles are read from profile.path
-
-Settings
-
-- otr (defaults to true) - is this profile off-the-record
-- name (defaults to the configuration file name)
-- search (defaults to profile.search) - search engine url
-- homepage (defaults to profile.homepage)
-- newtab (defaults to profile.newtab)
-
-Properties
-Key is property name; value is property value
-
-Attributes
-see QWebEngineSetting::WebAttribute for list of IDs.
-Key is attribute id; value is attribute value (true/false)
-
diff --git a/doc/building.md b/doc/building.md
new file mode 100644
index 0000000..9ea9344
--- /dev/null
+++ b/doc/building.md
@@ -0,0 +1,59 @@
+## Building from source
+
+### Dependencies
+- [Qt](https://www.qt.io/)
+- [meson](https://mesonbuild.com/) 0.52.0 or later
+- [kconfiglib](https://github.com/ulfalizer/Kconfiglib/)
+- A compiler with C++17 support
+- spdlog: if not found can be downloaded by meson
+
+### Optional dependencies
+- openssl or libressl: for signing plugins
+- breakpad-client
+- gtest
+
+### Steps
+```
+# clone the repository
+git clone https://neueland.iserlohn-fortress.net/gitea/aqua/smolbote.git smolbote.git
+cd smolbote.git
+
+# Get the submodules
+git submodule init
+git submodule update
+
+# configure
+mkdir build
+meson build
+
+# make
+ninja
+```
+
+## Using meson
+
+### Listing build options
+```
+build% meson configure
+```
+
+### Changing build options
+```
+build% meson configure -D<option-name>=<enabled|disabled>
+```
+
+### Prevent meson from downloading wraps
+During configure, meson can download missing dependencies on its own using
+wraps. To disable this, pass '--wrap-mode=nodownload' during the configure
+phase:
+```
+repo% meson --wrap-mode=nodownload build-path
+```
+
+For more information on how to use meson, see the meson [quick quide](https://mesonbuild.com/Quick-guide.html).
+
+## Configuring builds
+smolbote uses Kconfig to store and customize features and default settings such
+as keyboard shortcuts and paths. You can edit these settings using `menuconfig`
+from kconfiglib or similar.
+
diff --git a/doc/contributing.md b/doc/contributing.md
new file mode 100644
index 0000000..a5cd0ae
--- /dev/null
+++ b/doc/contributing.md
@@ -0,0 +1,37 @@
+## Guidelines
+
+smolbote is written under the C++17 standard, without any compiler-specific
+extensions. Source code should be kept as platform-agnostic as possible.
+
+## General
+* All behaviour, where possible, should be configurable.
+* Configuration option names should be as self-descriptive as possible.
+* Use sane defaults: normally the program should "just work".
+
+## Qt
+* Check pointers with `Q_CHECK_PTR`.
+* Use the Qt5 signal/slot syntax (&Class::method) over the old string-based
+  syntax (SIGNAL/SLOT). This enables compile-time connect checks.
+* Prefer QVector over QList: http://lists.qt-project.org/pipermail/development/2017-March/029040.html
+* Use [clazy](https://github.com/KDE/clazy) to check Qt semantics.
+
+## Licensing
+Smolbote is licensed under GPLv3 _only_, and explicitly does not use any
+self-updating "-or-later" licensing. Your code needs to be compatible with it,
+and have a license header in the style used by the project.
+
+Interfaces (located in include/) should be licensed under MIT. This is to allow
+more license compatibility for plugins.
+
+### SPDX-License-Identifier
+A full list of license identifiers can be found on [the SPDX website](https://spdx.org/licenses/).
+
+## Style
+There is a clang-format style in .clang-format.
+
+## How to format patch for email
+```
+git format-patch $from-commit..$to-commit
+```
+Email patches to _aqua at iserlohn dash fortress dot net_.
+
diff --git a/doc/images/browser-for-fun.png b/doc/images/browser-for-fun.png
deleted file mode 100644
index 72d24e6..0000000
--- a/doc/images/browser-for-fun.png
+++ /dev/null
diff --git a/doc/smolbote.asciidoc b/doc/smolbote.asciidoc
deleted file mode 100644
index 101ce77..0000000
--- a/doc/smolbote.asciidoc
+++ /dev/null
@@ -1,22 +0,0 @@
-= smolbote: yet another no-frills web browser
-:doctype: book
-:toc: left
-:data-uri:
-
-[preface]
-image::browser-for-fun.png[World Domination cat, role="thumb right"]
-smolbote is a cross-platform keep-it-simple free software web browser based on
-Qt and QtWebEngine.
-
-'''
-
-include::Usage/CommandLine.asciidoc[]
-
-include::Usage/Configuration.asciidoc[]
-
-include::Usage/Profile.asciidoc[]
-
-include::Usage/Plugins.asciidoc[]
-
-include::Usage/Filter.asciidoc[]
-