Refresh README.md and BUILDING.md

Author: KitsuneRal

BUILDING.md

@@ -41,8 +41,8 @@ Depending on your case, either option can be preferrable. For instance, Option 2
 is more convenient if you're actively hacking on Quaternion and libQMatrixClient
 at the same time. On the other hand, packagers should make a separate package
 for libQMatrixClient so should use Option 1. 0.0.9.3 is the only version using
-Option 1 as default; due to popular demand, Option 2 is used by default (but
-with a fallback to Option 1) from 0.0.9.4 beta.
+Option 1 as default; due to popular demand, Option 2 is used by default
+(with a fallback to Option 1) from 0.0.9.4 beta.
 
 ### Pre-requisites
 - a Linux, macOS or Windows system (desktop versions tried; mobile Linux/Windows
@@ -82,32 +82,32 @@ dnf install git cmake qt5-qtdeclarative-devel qt5-qtquickcontrols qt5-qtquickcon
 ```
 
 #### macOS
-`brew install qt5` should get you Qt5. You have to point CMake at the Qt5
-installation location, with something like:
+`brew install qt5` should get you Qt5. If you want to build with QtKeychain,
+call `brew install qtkeychain`.
+
+You have to point CMake at the Qt5 installation location, with something like:
 
 ```bash
 # if using in-tree libqmatrixclient:
-cmake .. -DUSE_INTREE_LIBQMC=1 -DUSE_QQUICKWIDGET=ON -DCMAKE_PREFIX_PATH=$(brew --prefix qt5)
+cmake .. -DUSE_QQUICKWIDGET=ON -DCMAKE_PREFIX_PATH=$(brew --prefix qt5)
 # or otherwise...
-cmake .. -DCMAKE_PREFIX_PATH=../../libqmatrixclient -DUSE_QQUICKWIDGET=ON -DCMAKE_PREFIX_PATH=$(brew --prefix qt5)
+cmake .. -DCMAKE_PREFIX_PATH=/path/to/libqmatrixclient -DUSE_QQUICKWIDGET=ON -DCMAKE_PREFIX_PATH=$(brew --prefix qt5)
 ```
 (read on to find out about `USE_QQUICKWIDGET`).
 
 #### Windows
 1. Install CMake. The commands in further sections imply that cmake is in your
    PATH - otherwise you have to prepend them with actual paths.
 1. Install Qt5, using their official installer.
+1. Optionally, get the QtKeychain sources and make them available to CMake
+   (TODO: elaborate the steps).
 1. Make sure CMake knows about Qt and the toolchain - the easiest way is to run
    `qtenv2.bat` script that can be found in `C:\Qt\<Qt version>\<toolchain>\bin`
    (assuming you installed Qt to `C:\Qt`). The only thing it does is adding
    necessary paths to `PATH` - you might not want to run it on system startup
    but it's very handy to setup environment before building.
    Setting `CMAKE_PREFIX_PATH`, the same way as for macOS (see above), also helps.
 
-Be prepared that a VS 64-bit build won't give you a working Quaternion -
-the last time checked Quaternion ran but could not get anything from the network.
-PRs are welcome. MinGW-based 64-bit builds (with Qt 5.12) run fine.
-
 ### Build
 In the root directory of the project sources:
 ```bash

README.md

@@ -59,14 +59,26 @@ brew cask install quaternion
 ```
 
 ## Running
-Just start the executable in your most preferred way - either from build directory or from the installed location.
+Just start the executable in your most preferred way - either from the build
+directory or from the installed location. If you're interested in tweaking
+configuration beyond what's available in the UI, read the "Configuration"
+section further below.
 
-### Configuration and cache files
+## Translation
+Quaternion uses [Lokalise.co](https://lokalise.co) for the translation effort.
+It's easy to participate:
+[join the project at Lokalise.co](https://lokalise.co/public/730769035bbc328c31e863.62506391/),
+ask to add your language (either in #qmatrixclient:matrix.org or in
+the Lokalise project chat) and start translating! Many languages are still
+longing for contributors.
+
+## Configuration
 The only non-trivial command-line option available so far is `--locale` - it
 allows you to override the locale Quaternion uses (an equivalent of setting
 `LC_ALL` variable on UNIX-based systems). As of version 0.0.9.3, Quaternion has
 no translations to other languages, so you will hardly notice the difference in
-messages; number and date formats will be following the setting though.
+messages; number and date formats will be following the setting though. Version
+0.0.9.4 gains German, Polish, and Russian translations.
 
 Quaternion stores its configuration in a way standard for Qt applications. It will read and write the configuration in the user-specific location (creating it if non-existent) and will only read the system-wide location with reasonable defaults if the configuration is nowhere to be found.
 - Linux:
@@ -146,7 +158,7 @@ Settings not exposed in UI:
   the beginning and end of the quote. By default it's `(.+)(?:\n|$)`.
 
 Since version 0.0.9.4, AppImage binaries for Linux and .dmg files for macOS
-are compiled with Qt Keychain support. That means that Quaternion will try
+are compiled with Qt Keychain support. It means that Quaternion will try
 to store your access token(s) in the secure storage configured for your
 platform. If the storage or Qt Keychain are not available (Qt Keychain is off
 by default on Windows - you have to rebuild Quaternion to enable it),
@@ -168,7 +180,16 @@ Quaternion caches the rooms state and user/room avatars on the file system in a
 - macOS: `$HOME/Library/Cache/QMatrixClient/quaternion`
 - Windows: `%LOCALAPPDATA%/QMatrixClient/quaternion/cache`
 
-Cache files are safe to delete at any time but Quaternion only looks for them when starting up and overwrites them regularly while running; so it only makes sense to delete cache files when Quaternion is not running. If Quaternion doesn't find cache files at startup it downloads the whole state from Matrix servers, which can take much time (up to a minute and even more, depending on the number of rooms and the number of users in them). Deleting cache files may help with problems such as missing avatars, rooms stuck in a wrong state etc.
+Cache files are safe to delete at any time but Quaternion only looks for them
+when starting up and overwrites them regularly while running; so it only
+makes sense to delete cache files when Quaternion is not running. If Quaternion
+doesn't find or cannot fully load cache files at startup it downloads
+the whole state from Matrix servers. It tries to optimise this process by
+lazy-loading if the server supports it; in an unlucky case when the server
+cannot do lazy-loading, initial sync can take much time (up to a minute and
+even more, depending on the number of rooms and the number of users in them).
+Deleting cache files may help with problems such as missing avatars,
+rooms stuck in a wrong state etc.
 
 ## Troubleshooting
 
@@ -201,15 +222,13 @@ Especially on Windows, if Quaternion starts up but upon an attempt to connect re
 If you have troubles with dynamic libraries on Windows, [the Dependencies Walker tool aka depends.exe](http://www.dependencywalker.com/) helps a lot in navigating the DLL hell - especially when you have a mixed 32/64-bit environment or have different versions of the same library scattered around. OpenSSL, in particular, is notoriously often dragged along by all kinds of software; and you may have other copies of Qt around which you didn't even know about - e.g., with CMake GUI.
 
 #### Logging
-If you run Quaternion from a console on Windows, you should set `QT_LOGGING_TO_CONSOLE=1` in order for the debug output be redirected to the console.
+If you run Quaternion from a console on Windows and want to see log messages,
+set `QT_LOGGING_TO_CONSOLE=1` so that the output is redirected to the console.
 
 When chasing bugs and investigating crashes, it helps to increase the debug level. Thanks to [@eang:matrix.org](https://matrix.to/#/@eang:matrix.org]), libqmatrixclient uses Qt logging categories - the "Troubleshooting" section of the library's `README.md` elaborates on how to setup logging. Note that Quaternion itself doesn't use Qt logging categories yet, only the library does.
 
 You may also want to set `QT_MESSAGE_PATTERN` to make logs slightly more informative (see https://doc.qt.io/qt-5/qtglobal.html#qSetMessagePattern for the format description). My (@kitsune's) `QT_MESSAGE_PATTERN` looks as follows:
 `%{time h:mm:ss.zzz}|%{category}|%{if-debug}D%{endif}%{if-info}I%{endif}%{if-warning}W%{endif}%{if-critical}C%{endif}%{if-fatal}F%{endif}|%{message}` (the scary `%{if}`s are just encoding the logging level into its initial letter).
 
-## Translation
-Quaternion uses [Lokalise.co](https://lokalise.co) for the translation effort. It's easy to participate: [join the project at Lokalise.co](https://lokalise.co/public/730769035bbc328c31e863.62506391/), ask to add your language (either in #qmatrixclient:matrix.org or in the Lokalise project chat) and start translating!
-
 ## Screenshot
 ![Screenshot](quaternion.png)