Convert documentation into asciidoc from markdown

29 files changed, 389 insertions, 552 deletions

diff --git a/BUILDING.md b/BUILDING.md
deleted file mode 100644
index 105e7b4..0000000
--- a/BUILDING.md
+++ /dev/null
@@ -1,81 +0,0 @@
-## Requirements
-
-### [Qt](https://www.qt.io/)
- - Version 5.11
-
-Even though most of the browser might work with the last LTS Qt release, always
-use an up-to-date version of QtWebEngine. Security fixes to Blink do _not_ get
-backported. QtWebEngine can be built with older versions of Qt, if upgrading Qt
-is not a possibility.
-
-### [boost](http://www.boost.org/)
- - Version 1.66
- - Components: program_options
-
-### cmake
- - Version 3.10
-
-### Compiler
- - C++17 support
- - gcc 7+;  clang 4+
- - Windows: only MSVC is supported due to QtWebEngine
-
-## Basic Installation
-In short, the generic cmake build loop of 'cmake, make, make install' will
-generate a makefile, build the program and install it.
-
-~~~ sh
-# clone the repository
-git clone https://neueland.iserlohn-fortress.net/gitea/aqua/smolbote.git
-
-# generate makefile
-mkdir build && cd build
-cmake -DCMAKE_BUILD_TYPE=Release ../smolbote
-
-# make && make install
-make -j4
-make install
-~~~
-
-## Configuring
-
-### vendor.cmake
-vendor.cmake contains all settings but the build type. It can be used to easily
-create a build profile.
-
-When changing vendor.cmake, make sure to have all values defined in the preset.
-
-### Compiler flags
-cmake does not set any C++ flags by default, including no optimization flags.
-You need to set these yourself if your build system doesn't set any either.
-
-On gcc/clang, no optimize flags are set by default, resulting in rather bloated
-code being generated. Recommend setting at least -O2. MSVC has optimze flags
-set by default.
-
-You can set the compiler using -DCMAKE_CXX_COMPILER=/path/to/c++. 
-You can set additional compiler flags using -DCMAKE_CXX_FLAGS.
-
-### Build type
-Install paths are only set on Release builds.
-
-~~~sh
--DCMAKE_BUILD_TYPE=Debug|Release
-~~~
-
-### Install prefix
-Sets the install location prefix.
-win32: Binary is written to bin/, and plugins to bin/plugins.
-others: Binary will be written to bin/, and plugins to lib/smolbote/.
-
-~~~sh
--DCMAKE_INSTALL_PREFIX=/usr/local
-~~~
-
-### 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
deleted file mode 100644
index 0f65115..0000000
--- a/QUICKSTART.md
+++ /dev/null
@@ -1,59 +0,0 @@
-## Principles
-
-### Simplicity
-This should be a simple browser that only does its browsing job with as little
-fuss as possible. This is not a platform.
-
-### Customizability
-This browser should be usable with minimal configuration necessary. At the same
-time, all functionality should be user-customizable. It is the user's
-responsibility to ensure a stable working state when changing settings.
-
-This browser should be kept as platform-agnostic as possible, while learning
-from and implementing the UNIX philosophy as applicable.
-
-### Pragmatic Freedom
-Free software should serve the user, not impose unbreakable barriers for
-ideological reasons.
-
-QtWebEngine allows the usage of third-party non-free codecs and non-free
-plugins. This browser does not prevent you from doing so. It's up to you how
-you exercise your freedom.
-
-## 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
-
-## Profiles
-A Profile is a collection of settings, policies, scripts, cookies, cache and
-history. Profiles can be used to isolate pages from each other.
-
-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.
-
-## Configuration files
-Configuration is saved in:
-
-- on Linux, _~/.config/smolbote/_
-
diff --git a/README.md b/README.md
deleted file mode 100644
index ac735d1..0000000
--- a/README.md
+++ /dev/null
@@ -1,31 +0,0 @@
-## *smolbote?*
-_It's yet another no-frills browser, poi!_
-
-### What is this and why should I care?
-smolbote is a [keep-it-simple][kiss-principle] free software web browser based
-on Qt and QtWebEngine.
-
-This program is free software. You can use it as you see fit, study and modify
-it, and share the program with or without modification, but providing the same
-terms.
-
-For more information, and a list of dependancies, see [LICENSE.md][repo-license].
-
-### What's up with the name?!
-It's a small boat. It says poi.
-
-### Sounds dumb, how do I use it?
-You make it yourself.
-
-It's a cmake-based project that depends on Qt and Boost, so cmake && make alone
-should be sufficient to build from source. Some basic package scripts are
-provided in the repository.
-
-Detailed [build instructions](/smolbote/building.html) also included.
-
-### 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/gitea/aqua/smolbote/src/branch/master/LICENSE.md
-
diff --git a/Readme.asciidoc b/Readme.asciidoc
new file mode 100644
index 0000000..2434561
--- /dev/null
+++ b/Readme.asciidoc
@@ -0,0 +1,48 @@
+== *smolbote?*
+_It's yet another no-frills browser, poi!_
+
+=== What is this and why should I care?
+smolbote is a link:https://en.wikipedia.org/wiki/KISS_principle[keep-it-simple]
+free software web browser based on Qt and QtWebEngine.
+
+==== Simplicity
+This should be a simple browser that only does its browsing job with as little
+fuss as possible. This is not a platform.
+
+==== Customizability
+This browser should be usable with minimal configuration necessary. At the same
+time, all functionality should be user-customizable. It is the user's
+responsibility to ensure a stable working state when changing settings.
+
+This browser should be kept as platform-agnostic as possible, while learning
+from and implementing the UNIX philosophy as applicable.
+
+==== Pragmatic Freedom
+Free software should serve the user, not impose unbreakable barriers for
+ideological reasons.
+
+QtWebEngine allows the usage of third-party non-free codecs and non-free
+plugins. This browser does not prevent you from doing so. It's up to you how
+you exercise your freedom.
+
+This program is free software. You can use it as you see fit, study and modify
+it, and share the program with or without modification, but providing the same
+terms.
+
+For more information, and a list of dependancies, see the license information
+included in the repository.
+
+=== What's up with the name?!
+It's a small boat. It says poi.
+
+=== Sounds dumb, how do I use it?
+You make it yourself.
+
+It's a cmake-based project that depends on Qt and Boost, so cmake && make alone
+should be sufficient to build from source. Some basic package scripts are
+provided in the repository.
+
+Detailed link:/smolbote/building.html[build instructions] also included.
+
+=== It doesn't work, what now?
+Drop me an email at _aqua at iserlohn dash fortress dot net_.
diff --git a/doc/Breakpad.md b/doc/Breakpad.md
deleted file mode 100644
index d1056a5..0000000
--- a/doc/Breakpad.md
+++ /dev/null
@@ -1,14 +0,0 @@
-## Producing symbols
-
-~~~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
-
-~~~sh
-processor/minidump_stackwalk minidump.dmp ./symbols
-~~~
diff --git a/BUGS.md b/doc/Bugs.asciidoc
index a3a5153..057fae9 100644
--- a/BUGS.md
+++ b/doc/Bugs.asciidoc
@@ -1,21 +1,21 @@
-## Reporting bugs
+== Reporting bugs
 
-### What to include
+=== What to include
 A bug report should contain these 4 things:
 
-#### Environment
+==== 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
+==== 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
+==== 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
+==== 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.
@@ -24,28 +24,28 @@ Send bug reports to _aqua at iserlohn dash fortress dot net_.
 
 _Adapted from the guide in the texmate repository._
 
-## Known bugs
+== Known bugs
 
-#### databases-incognito in home
+=== databases-incognito in home
 https://bugreports.qt.io/browse/QTBUG-62957
 
-#### loadFinished is not always emitted when loading is finished
+=== 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
+=== 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__.
 
-### Wayland bugs
+=== Wayland bugs
 
-#### mainwindow.maximized doesn't work
+=== mainwindow.maximized doesn't work
 setWindowState(Qt::WindowMaximized) has no effect on KDE/Wayland:
 https://community.kde.org/Plasma/Wayland_Showstoppers
 
-### Windows bugs
+=== Windows bugs
 
-#### stdout and stderr
+=== stdout and stderr
 Starting the application with some command-line options (like --version,
 --help, etc) causes the application to 'stall' on exit.
 
diff --git a/doc/Building.asciidoc b/doc/Building.asciidoc
new file mode 100644
index 0000000..47eb0bb
--- /dev/null
+++ b/doc/Building.asciidoc
@@ -0,0 +1,81 @@
+== 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
+
+| cmake
+| Version 3.10
+| Anything supporting modern cmake
+
+| 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
+In short, the generic cmake build loop of 'cmake, make, make install' will
+generate a makefile, build the program and install it.
+
+[source, sh]
+----
+# clone the repository
+git clone https://neueland.iserlohn-fortress.net/gitea/aqua/smolbote.git smolbote.git
+cd smolbote.git
+git submodule init
+git submodule update 3rd-party/SingleApplication/SingleApplication.git
+
+
+# generate makefile
+mkdir build && cd build
+cmake -DCMAKE_BUILD_TYPE=Release ..
+
+# make && make install
+make -j4
+make install
+----
+
+=== vendor.cmake
+vendor.cmake contains various settings to customize the way in which the program
+functions. The available options and their values may change with revisions.
+When changing vendor.cmake, make sure to have all values defined in the preset.
+
+  -DVENDOR=path/to/custom-vendor.cmake
+
+=== Compiler flags
+cmake does not set any C++ flags by default, including no optimization flags.
+You need to set these yourself if your build system doesn't set any either.
+
+- On gcc/clang, no optimize flags are set by default, setting at least -O2 is
+recommended; check vendor.cmake.
+
+=== Install prefix (`-DCMAKE_INSTALL_PREFIX`)
+Sets the install location prefix. Install targets are only set on Release builds.
+
+- windows: Binary is written to bin/, and plugins to bin/plugins.
+- others: Binary 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.
+
+  -DCMAKE_CXX_COMPILER=/usr/bin/clang++ -DUseLibCpp=On
+
+// Additional items
+
+include::Building/Breakpad.asciidoc[]
+
+include::Building/Windows.asciidoc[]
diff --git a/doc/Building/Breakpad.asciidoc b/doc/Building/Breakpad.asciidoc
new file mode 100644
index 0000000..9cc561e
--- /dev/null
+++ b/doc/Building/Breakpad.asciidoc
@@ -0,0 +1,20 @@
+== Breakpad
+
+=== Enabling breakpad
+Use `-DBreakpad=On` cmake option. This requires either Breakpad be installed as
+a package, or that it is already built. Check 3rd-party/breakpad/CMakeLists.txt.
+
+=== 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/QtWebEngine.md b/doc/Building/QtWebEngine.md
deleted file mode 100644
index 7d72dd6..0000000
--- a/doc/Building/QtWebEngine.md
+++ /dev/null
@@ -1,7 +0,0 @@
-- download qtwebengine
-
-~~~sh
-mkdir build && cd build
-qmake ../qtwebengine-version-source/qtwebengine.pro
-make
-~~~
diff --git a/doc/Building/Windows.asciidoc b/doc/Building/Windows.asciidoc
new file mode 100644
index 0000000..4c1fc20
--- /dev/null
+++ b/doc/Building/Windows.asciidoc
@@ -0,0 +1,26 @@
+== 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/smolbote.md b/doc/Building/smolbote.md
deleted file mode 100644
index e40132c..0000000
--- a/doc/Building/smolbote.md
+++ /dev/null
@@ -1,30 +0,0 @@
-## Customizing
-Set through vendor.cmake.
-
-### Configuration defaults
-
-### Version information
-Building without git metadata requires the version be set in vendor.cmake.
-
-
-## Building on Windows
-
-~~~sh
-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.0\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-hg
-cmake --build . --target poi --config Release
-cmake --build . --target install --config Release
-cd %INSTALL_DIR%
-C:\Qt\5.10.1\msvc2017_64\bin\windeployqt.exe bin\poi.exe
-
-7z a C:\projects\smolbote-hg\smolbote.7z %INSTALL_DIR%
-~~~
-
diff --git a/doc/Development.asciidoc b/doc/Development.asciidoc
new file mode 100644
index 0000000..41c832d
--- /dev/null
+++ b/doc/Development.asciidoc
@@ -0,0 +1,42 @@
+== Guidelines
+
+=== Qt
+* Check pointers with Q_CHECK_PTR before using or returning them.
+* Avoid using connect SIGNAL and SLOT. Instead use &Class::method. This way, connects are checked during the compile, 
+  not at runtime.
+* Where possible, use QVector over QList: http://lists.qt-project.org/pipermail/development/2017-March/029040.html
+
+=== clazy
+You can use [clazy](https://github.com/KDE/clazy) to check Qt semantics. 
+Requires clang.
+
+To set check levels, set the CLAZY_CHECKS environment variable to 'level0,level1', etc.
+
+==== Setting up in QtCreator
+The simplest way to set it up is to use _clazy_ instead of _clang_.
+
+1. Go to Tools » Options » Build & Run » Compilers
+2. Clone the clang compiler of your choice
+3. Set _Compiler path_ to _/usr/bin/clazy_
+
+== Licensing
+Smolbote is licensed under GPLv3 _only_. Your code needs to be compatible with it, and have a license header in the
+style used by the project.
+
+- No self-updating "-or-later" licensing.
+
+=== 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.
+
+== Format patch for email
+
+~~~ sh
+hg export -r startcommit[:endcommit] -o patchname.txt
+~~~
+
+to export the from _startcommit_ until tip or optionally _endcommit_.
+
+Email the patch file to _aqua at iserlohn dash fortress dot net_.
diff --git a/doc/Development/ManPage.asciidoc b/doc/Development/ManPage.asciidoc
new file mode 100644
index 0000000..4d8c015
--- /dev/null
+++ b/doc/Development/ManPage.asciidoc
@@ -0,0 +1,7 @@
+== manpage
+
+=== Generating manpage
+[code, sh]
+----
+a2x --format=manpage doc/smolbote.7.asciidoc
+----
diff --git a/doc/Development/RepositoryCommands.asciidoc b/doc/Development/RepositoryCommands.asciidoc
new file mode 100644
index 0000000..13e2f8e
--- /dev/null
+++ b/doc/Development/RepositoryCommands.asciidoc
@@ -0,0 +1,6 @@
+== 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/Translating.asciidoc b/doc/Development/Translating.asciidoc
new file mode 100644
index 0000000..f79fa56
--- /dev/null
+++ b/doc/Development/Translating.asciidoc
@@ -0,0 +1,16 @@
+== 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/Updater.md b/doc/Development/Updater.asciidoc
index 899240f..a039318 100644
--- a/doc/Updater.md
+++ b/doc/Development/Updater.asciidoc
@@ -1,25 +1,25 @@
-## Updater
+== Updater
 
-### Manifest
-~~~sh
+=== Creating manifest
+[code, sh]
+----
 find windows/ -type f | xargs sha512sum | sed 's/windows\///' > windows-sha512.txt
 find windows/ -type d -exec chmod 755 {} +
-~~~
+----
 
-### Building
+=== Building
 
 You can build for the current system using:
-~~~sh
+[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`.
-~~~sh
+[code, sh]
+----
 GOOS=windows GOARCH=amd64 go build
-~~~
-
-#### Removing debug information
-~~~sh
-strip updater
-~~~
+----
diff --git a/doc/ManPage.md b/doc/ManPage.md
deleted file mode 100644
index d3f7c74..0000000
--- a/doc/ManPage.md
+++ /dev/null
@@ -1,15 +0,0 @@
-The manpage format is ridiculous, so they get generated from markdown (which is more sane in comparison)
-
-### with ronn
-~~~sh
-## install
-gem install --user-install ronn
-## generate
-ronn smolbote.7.ronn
-~~~
-
-### with go-md2man
-~~~sh
-go-md2man -in smolbote.md -out smolbote.7
-~~~
-
diff --git a/doc/RepositoryCommands.md b/doc/RepositoryCommands.md
deleted file mode 100644
index 3725b6e..0000000
--- a/doc/RepositoryCommands.md
+++ /dev/null
@@ -1,16 +0,0 @@
-## git commit template
-You can set the commit template with:
-
-~~~sh
-git config commit.template=.git-commit-template
-~~~
-
-## gitea api
-A full list of the api can be found on https://try.gitea.io/api/swagger.
-
-## Listing branches
-
-~~~sh
-curl --request GET --url https://neueland.iserlohn-fortress.net/gitea/api/v1/repos/aqua/smolbote/branches
-~~~
-
diff --git a/doc/Translating.md b/doc/Translating.md
deleted file mode 100644
index fc7bad3..0000000
--- a/doc/Translating.md
+++ /dev/null
@@ -1,24 +0,0 @@
-## Generating translations
-
-~~~sh
-lupdate src/ lib/ -ts lang/<lang-id>.ts
-~~~
-
-### Updating translations
-~~~sh
-lupdate src/ lib/ -no-obsolete -ts lang/<lang-id>.ts
-~~~
-
-## Baking translation
-This generates lang/<lang-id>.qm
-
-~~~sh
-lrelease lang/<land-id>.ts
-~~~
-
-## Using translations
-
-~~~sh
---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/UrlFilter.md b/doc/UrlFilter.md
deleted file mode 100644
index b521228..0000000
--- a/doc/UrlFilter.md
+++ /dev/null
@@ -1,95 +0,0 @@
-## FilterDomain
-Filter Domains are groups of domains that can point to one or more filter
-rules.
-
-### Types
-There are 4 Filter Domain types:
-- AllowOnDomains - only match specified domains
-- BlockOnDomains - match all but specified domains
-- AllowOnAllDomains - match all domains
-- BlockOnAllDomains - match no domains
-
-### JSON
-    {
-        "type" : "AllowOnDomains",
-        "domains" : [ "example.com", "test.example.com" ],
-        "rules" : []
-    }
-
-## FilterRule
-Filter rules contain information on how a request should be modified.
-
-### Action
-- Whitelist - allow this request
-- Blacklist - block this request
-- Redirect - redirect this request
-- SetHeader - apply a list of headers
-
-### Match Type
-- "regexp"
-- "contains"
-- "endswith"
-- if none is specified, all URLs are matched
-
-### JSON
-Allow all URLs that contain "waifu.png"
-    {
-        "action" : "Whitelist"
-        "contains" : "waifu.png"
-    }
-
-Block specific URL
-    {
-        "action" : "Blacklist"
-        "equals" : "example.com/annoying-ad/masquerade/waifu.png"
-    }
-
-Block all URLs that contain "banner.gif"
-    {
-        "action" : "Blacklist",
-        "contains" : "banner.gif"
-    }
-
-Redirect URLs containing "ads/annoying-spam.gif" to "waifu.tld/waifu.gif"
-    {
-        "action" : "Redirect"
-        "contains" : "ads/annoying-spam.gif"
-        "url" : "waifu.tld/waifu.gif"
-    }
-
-Set some headers
-    {
-        "action" : "SetHeader"
-        "headers" : [ "DNT:1" ]
-    }
-
-## QWebEngineUrlRequestInterceptor
-
-All network requests pass through the request interceptor. It gives the
-following information:
-
-- firstPartyUrl - the page on which the request is made
-- requestUrl - the url of the request
-- requestMethod
-- resourceType
-- navigationType
-
-And provides the following methods:
-
-- block (bool shouldBlock) - can block the request
-- redirect (const QUrl) - can redirect the requestUrl
-- setHttpHeader - can set HTTP headers (such as user agent and do not track)
-
-### Example
-This is a sample request made when loading DuckDuckGo:
-
-    firstPartyUrl=https://duckduckgo.com/
-    requestUrl=https://duckduckgo.com/o1635.css
-
-## How the filter works
-When a requst comes in, the interceptor extracts the host of the request and
-matches it against the list of FilterDomains.
-
-    firstPartyHost=duckduckgo.com
-    requestHost=duckduckgo.com
-
diff --git a/doc/Usage.asciidoc b/doc/Usage.asciidoc
new file mode 100644
index 0000000..ee2cc20
--- /dev/null
+++ b/doc/Usage.asciidoc
@@ -0,0 +1,21 @@
+== 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.md b/doc/Usage/CommandLine.asciidoc
index 1c532ce..a21b7c2 100644
--- a/doc/Usage/CommandLine.md
+++ b/doc/Usage/CommandLine.asciidoc
@@ -1,12 +1,8 @@
-## Command-line options
+== Command-line Options
 
-### General
+=== General
 * `-h`, `--help`: Display this help.
 * `-v`, `--version`: Display version information.
 * `--build`: Display build branch and commit.
 * `-c`, `--config`: Set configuration file.
 * `--no-remote`: Don't check for other instances when starting.
-
-### Tweaking configuration
-You can overwrite options at runtime using the option path as a command line
-parameter.
diff --git a/doc/Usage/Configuration.md b/doc/Usage/Configuration.asciidoc
index 3bf55b9..44e6b92 100644
--- a/doc/Usage/Configuration.md
+++ b/doc/Usage/Configuration.asciidoc
@@ -1,35 +1,38 @@
-## Configuration
+== Configuration
 
-The Configuration is loaded from _~/.config/smolbote/smolbote.cfg_. Most
+The Configuration is loaded from .config/smolbote/smolbote.cfg. Most
 settings are only loaded on launch.
 
-For a full list of settings, check `--help`.
+For a full list of settings, check '--help'.
 
-### Browser (group: browser)
+You can overwrite options at runtime using the option path as a command line
+parameter.
 
-### Main Window (group: mainwindow)
+- Browser (group: browser)
+
+- Main Window (group: mainwindow)
 A main window contains one or more subwindows.
 
-### Subwindow (group: window)
+- Subwindow (group: window)
 A subwindow contains multiple tabs and functions similarly to a tab group.
 
-### Navigation bar (group: navigation)
+- Navigation bar (group: navigation)
 The navigation bar is the toolbar that holds the history, reload and home 
 buttons, as well as the address bar. It can be made movable through the
 navigation.movable option.
 
-### Address bar (group: addressbar)
+- Address bar (group: addressbar)
 
-### Filter (group: filter)
+- Filter (group: filter)
 
-### Plugins (group: plugins)
+- Plugins (group: 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.
 
-### Profiles (group: profile)
+- Profiles (group: profile)
 A Profile is a collection of settings, policies, scripts, cookies, cache and
 history. Profiles can be used to isolate pages from each other.
 
@@ -47,7 +50,7 @@ site would still be using the default off-the-record profile.
 Profile definitions are stored in the profiles.path location. To create a new
 profile, create a profile-id.profile file in that location.
 
-### Bookmarks (group: bookmarks)
+- Bookmarks (group: bookmarks)
 
-### Downloads (group: downloads)
+- Downloads (group: downloads)
 
diff --git a/doc/Usage/Profile.asciidoc b/doc/Usage/Profile.asciidoc
new file mode 100644
index 0000000..9b00dbc
--- /dev/null
+++ b/doc/Usage/Profile.asciidoc
@@ -0,0 +1,31 @@
+== Profiles
+A Profile is a collection of settings, policies, scripts, cookies, cache and
+history. Profiles can be used to isolate pages from each other.
+
+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/Usage/Profile.md b/doc/Usage/Profile.md
deleted file mode 100644
index d205a86..0000000
--- a/doc/Usage/Profile.md
+++ /dev/null
@@ -1,17 +0,0 @@
-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/Usage/Session.md b/doc/Usage/Session.md
deleted file mode 100644
index 3018253..0000000
--- a/doc/Usage/Session.md
+++ /dev/null
@@ -1,30 +0,0 @@
-## Session format
-A session is a single window, which contains a list of subwindows.
-
-Each subwindow has a profile (profile id), and a list of tabs.
-
-Each tab has a profile (profile id) and url.
-
-~~~json
-{
-    "subwindows": [
-        {
-            "profile": "<profile id>",
-            "tabs": [
-                {
-                    "profile": "<profile id>",
-                    "url": "<url>"
-                },
-                {
-                    ...
-                }
-            ]
-        }
-    ]
-}
-
-~~~
-
-## --session
-This command-line option causes the browser to load the specified json file.
-
diff --git a/doc/smolbote.7.asciidoc b/doc/smolbote.7.asciidoc
new file mode 100644
index 0000000..ec1150f
--- /dev/null
+++ b/doc/smolbote.7.asciidoc
@@ -0,0 +1,35 @@
+= smolbote(7)
+:doctype: manpage
+:man source: smolbote
+:man manual: smolbote manpage
+:toc:
+:homepage: https://neueland.iserlohn-fortress.net/smolbote/
+
+== Name
+smolbote - yet another no-frills web browser
+
+== Synopsis
+*poi* ['-OPTION' ['...']] ['COMMAND'] ['URL' ['...']]
+
+== Description
+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[]
+
+== Copyright
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 3 as
+published by the Free Software Foundation.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
diff --git a/linux/makepkg/PKGBUILD b/linux/makepkg/PKGBUILD
index 2e0e755..4bb7571 100644
--- a/linux/makepkg/PKGBUILD
+++ b/linux/makepkg/PKGBUILD
@@ -17,7 +17,7 @@ license=('GPL3')
 
 depends=('qt5-webengine>=5.11.0' 'boost-libs>=1.66.0')
 optdepends=('firejail: launch a sandboxed instance')
-makedepends=('git' 'cmake' 'pkg-config' 'go-md2man')
+makedepends=('git' 'cmake' 'pkg-config' 'asciidoc')
 
 # this is the central repository
 source=("git+https://neueland.iserlohn-fortress.net/gitea/aqua/smolbote.git"
@@ -66,7 +66,6 @@ build() {
             -DVerDescribe=$_describe \
             -DVerCommit=$_commit \
             -DVerBranch=$_branch \
-            -DBreakpad=On \
             $srcdir/smolbote
 
     # Build
@@ -77,16 +76,16 @@ package() {
     # Install
     make install
 
-    # icon and .desktop
-    install -Dm644 "${srcdir}/smolbote/data/poi.svg" "${pkgdir}/usr/share/icons/hicolor/scalable/apps/poi.svg"
-    install -Dm644 "${srcdir}/smolbote/linux/poi.desktop" "${pkgdir}/usr/share/applications/poi.desktop"
+    msg2 "Installing icon and .desktop"
+    install -Dm644 $srcdir/smolbote/data/poi.svg $pkgdir/usr/share/icons/hicolor/scalable/apps/poi.svg
+    install -Dm644 $srcdir/smolbote/linux/poi.desktop $pkgdir/usr/share/applications/poi.desktop
 
-    # firejail profile
-    install -Dm644 "${srcdir}/smolbote/data/poi.profile" "${pkgdir}/usr/local/lib/smolbote/poi.profile"
+    msg2 "Installing firejail profile"
+    install -Dm644 $srcdir/smolbote/data/poi.profile $pkgdir/usr/local/lib/smolbote/poi.profile
 
-    msg2 "Install manpage"
-    go-md2man -in $srcdir/smolbote/linux/man/smolbote.md -out smolbote.7
-    gzip smolbote.7
-    install -Dm644 smolbote.7.gz $pkgdir/usr/local/man/man7/smolbote.7.gz
+    msg2 "Installing manpage"
+    a2x --format=manpage $srcdir/doc/smolbote.7.asciidoc
+    gzip $srcdir/doc/smolbote.7
+    install -Dm644 $srcdir/doc/smolbote.7.gz $pkgdir/usr/local/man/man7/smolbote.7.gz
 }
 
diff --git a/linux/man/smolbote.md b/linux/man/smolbote.md
deleted file mode 100644
index b9ea181..0000000
--- a/linux/man/smolbote.md
+++ /dev/null
@@ -1,75 +0,0 @@
-smolbote(7)
-===
-
-## NAME
-smolbote - yet another no-frills web browser
-
-## SYNOPSIS
-`poi` [<options>...] URL(s)
-
-## DESCRIPTION
-smolbote is a cross-platform keep-it-simple free software web browser based on
-Qt and QtWebEngine.
-
-## COMMAND-LINE OPTIONS
-
-### General
-* `-h`, `--help`: Display this help.
-* `-v`, `--version`: Display version information.
-* `--build`: Display build branch and commit.
-* `-c`, `--config`: Set configuration file.
-* `--no-remote`: Don't check for other instances when starting.
-
-## CONFIGURATION
-
-The Configuration is loaded from _~/.config/smolbote/smolbote.cfg_. Most
-settings are only loaded on launch.
-
-For a full list of settings, check `--help`.
-
-### Browser (group: browser)
-
-### Main Window (group: mainwindow)
-A main window contains one or more subwindows.
-
-### Subwindow (group: window)
-A subwindow contains multiple tabs and functions similarly to a tab group.
-
-### Navigation bar (group: navigation)
-The navigation bar is the toolbar that holds the history, reload and home 
-buttons, as well as the address bar. It can be made movable through the
-navigation.movable option.
-
-### Address bar (group: addressbar)
-
-### Filter (group: filter)
-
-### Plugins (group: 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.
-
-### Profiles (group: profile)
-A Profile is a collection of settings, policies, scripts, cookies, cache and
-history. Profiles can be used to isolate pages from each other.
-
-Each window has a default profile it uses when opening new tabs. This can be
-set by the profile.default option, and can be changed from the window's menu.
-Additionally, tabs can have their profiles individually changed from their page
-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.
-
-Profile definitions are stored in the profiles.path location. To create a new
-profile, create a profile-id.profile file in that location.
-
-### Bookmarks (group: bookmarks)
-
-### Downloads (group: downloads)
-