Add real README.md and INSTALL.md

INSTALL.md

@@ -0,0 +1,240 @@
+# Installation
+
+Instructions and releases are currently only available for Linux,
+but compiling on Windows and macOS should be possible with the right tools.
+
+- [Releases](#releases)
+  - [Linux](#linux)
+- [Manual installation](#manual-installation)
+  - [Environment variables](#environment-variables)
+  - [Package manager dependencies](#package-manager-dependencies)
+    - [Alpine Linux 3.9+ / apk](#alpine-linux-39--apk)
+    - [Arch Linux / pacman & AUR](#arch-linux--pacman--aur)
+    - [Fedora 30+ / dnf](#fedora-30--dnf)
+    - [Ubuntu 19.04 / apt](#ubuntu-1904--apt)
+    - [Ubuntu 19.10+, Debian bullseye / apt](#ubuntu-1910-debian-bullseye--apt)
+    - [Void Linux / xbps](#void-linux--xbps)
+  - [Installing PyOtherSide manually](#installing-pyotherside-manually)
+  - [Installing libolm manually](#installing-libolm-manually)
+  - [Installing Mirage](#installing-mirage)
+- [Common issues](#common-issues)
+  - [cffi version mismatch](#cffi-version-mismatch)
+  - [Component is not ready](#component-is-not-ready)
+
+
+## Releases
+
+### Linux
+
+For **x86 64bit glibc-based systems**, Mirage is available as an **AppImage**
+on the [release page](releases).  
+For other architectures and musl-based distros, see the 
+[manual installation section](#manual-installation).
+
+AppImages are single executable files that contain the app and all 
+its dependencies.  
+Mirage images are built in Ubuntu 16.04, and should therefore run on any distro
+released in 2016 or later.
+
+To run from a terminal:
+
+```sh
+chmod +x Mirage-x86_64.AppImage
+./Mirage-x86_64.AppImage
+```
+
+To run from a file manager, give executable permission in the file's
+properties and double-click to launch.  
+[More detailed instructions](https://docs.appimage.org/introduction/quickstart.html#ref-quickstart)
+
+
+## Manual installation
+
+Qt 5.12+, Python 3.6+ (with development headers and pip),
+PyOtherSide 1.5+ and libolm 3+ are required.
+
+### Environment variables
+
+To ensure Qt **5** will be used by default, compile using all CPU cores and 
+optimize the build for your machine:
+
+```sh
+export QT_SELECT=5
+export MAKEFLAGS="-j$(nproc)"
+export CFLAGS="-march=native -O2 -pipe"
+```
+
+### Package manager dependencies
+
+#### Alpine Linux 3.9+ / apk
+
+[PyOtherSide](#installing-pyotherside-manually) and 
+[libolm](#installing-libolm-manually) must be manually installed.
+
+```sh
+sudo apk add qt5-qtquickcontrols2-dev qt5-qtsvg-dev qt5-qtimageformats \
+             python3-dev py3-setuptools \
+             build-base git cmake \
+             libjpeg-turbo-dev zlib-dev tiff-dev libwebp-dev openjpeg-dev \
+             libmediainfo-dev
+export PATH="/usr/lib/qt5/bin:$PATH"
+```
+
+#### Arch Linux / pacman & AUR
+
+**libolm** is from the AUR, this example uses
+[yay](https://github.com/Jguer/yay) to install it like other packages.  
+Alternatively, you can just use `pacman` and
+[install libolm manually](#installing-libolm-manually).
+
+```sh
+yay -Syu qt5-base qt5-declarative qt5-quickcontrols2 qt5-svg \
+         qt5-graphicaleffects qt5-imageformats \
+         python python-pip \
+         python-pyotherside \
+         libolm \
+         base-devel git cmake \
+         libjpeg-turbo zlib libtiff libwebp openjpeg2 libmediainfo
+```
+
+#### Fedora 30+ / dnf
+
+[PyOtherSide](#installing-pyotherside-manually) and 
+[libolm](#installing-libolm-manually) must be manually installed.
+
+```sh
+sudo dnf groupinstall 'Development Tools'
+sudo dnf install qt5-devel qt5-qtbase qt5-qtdeclarative qt5-qtquickcontrols2 \
+                 qt5-qtsvg qt5-qtgraphicaleffects qt5-qtimageformats \
+                 python3-devel python3-pip \
+                 git cmake \
+                 libjpeg-turbo-devel zlib-devel libtiff-devel libwebp-devel	\
+                 openjpeg2-devel libmediainfo-devel
+sudo ln -s /usr/bin/qmake-qt5 /usr/bin/qmake
+```
+
+#### Ubuntu 19.04 / apt
+
+[libolm](#installing-libolm-manually) must be manually installed.
+
+
+```sh
+sudo apt update
+sudo apt install qt5-default qt5-qmake qt5-image-formats-plugins \
+                 qml-module-qtquick2 qml-module-qtquick-window2 \
+                 qml-module-qtquick-layouts qml-module-qtquick-dialogs \
+                 qml-module-qt-labs-platform \
+                 qtdeclarative5-dev \
+                 qtquickcontrols2-5-dev \
+                 python3-dev python3-pip \
+                 qml-module:io-thp-pyotherside \
+                 build-essential git cmake \
+                 libjpeg-turbo8-dev zlib1g-dev libtiff5-dev libwebp-dev \
+                 libopenjp2-7-dev libmediainfo-dev
+```
+
+#### Ubuntu 19.10+, Debian bullseye / apt
+
+Follow the steps for [Ubuntu 19.04](#ubuntu-1904--apt), but instead of
+installing libolm manually:
+
+```sh
+sudo apt install libolm-dev
+```
+
+#### Void Linux / xbps
+
+[PyOtherSide](#installing-pyotherside-manually) must be manually installed.
+
+```sh
+sudo xbps-install -Su qt5-devel qt5-declarative-devel \
+                      qt5-quickcontrols2-devel \
+                      qt5-svg-devel qt5-graphicaleffects qt5-imageformats \
+                      python3-devel python3-pip \
+                      olm-devel \
+                      base-devel git cmake \
+                      libjpeg-turbo-devel zlib-devel tiff-devel libwebp-devel \
+                      libopenjpeg2-devel libmediainfo-devel
+```
+
+### Installing PyOtherSide manually
+
+Skip this section if you already installed it from your
+distro's package manager.
+
+```sh
+git clone https://github.com/thp/pyotherside
+cd pyotherside
+make clean
+qmake
+make
+sudo make install
+```
+
+### Installing libolm manually
+
+Skip this section if you already installed it from your
+distro's package manager.
+
+```sh
+git clone https://gitlab.matrix.org/matrix-org/olm/
+cd olm
+cmake . -Bbuild
+cmake --build build
+sudo make install
+```
+
+
+## Installing Mirage
+
+After following the above sections instructions depending on your system,
+clone the repository, install the python dependencies, compile and install:
+
+```sh
+git clone --recursive https://github.com/mirukan/mirage
+cd mirage
+pip3 install --user -Ur requirements.txt
+pip3 install --user -U uvloop==0.14.0
+
+qmake mirage.pro
+make
+sudo make install
+```
+
+`uvloop` brings performance improvements, but can be skipped 
+if you have trouble installing it.
+
+If everything went fine, run `mirage` to start.
+
+
+## Common issues
+
+### cffi version mismatch
+
+When installing the python dependencies, if you get a version mismatch error
+related to `cffi`, try:
+
+```sh
+pip3 install --user --upgrade --force-reinstall cffi
+```
+
+### Component is not ready
+
+If the application doesn't start when you run `mirage` and shows a 
+`QQmlComponent: Component is not ready` message in the terminal,
+a QML component failed to import due to either missing dependencies
+or a programming error.
+
+If PyOtherSide is correctly installed, you should see a similar message:
+
+    Got library name:  "/usr/lib/qt5/qml/io/thp/pyotherside/libpyothersideplugin.so"
+
+If not, verify the installed files and their permissions. 
+To ensure the correct permissions are set for the PyOtherSide plugin files:
+
+    sudo chmod -R 755 /usr/lib/qt5/qml/io
+    sudo chmod 644 /usr/lib/qt5/qml/io/thp/pyotherside/*
+    sudo chmod 755 /usr/lib/qt5/qml/io/thp/pyotherside/*.so
+
+Note that the Qt lib path might be `/usr/lib/qt/` instead of `/usr/lib/qt5/`,
+depending on the distro.

README.md

@@ -1,60 +1,121 @@
-# Mirage
+# Mirage ![Latest release](https://img.shields.io//github/v/release/mirukan/mirage)
+
+[Features](#currently-implemented-features) ⬥
+[Installation](INSTALL.MD) ⬥
+[Configuration & theming](#configuration-and-theming) ⬥
+[More screenshots](#more-screenshots)
+
+A fancy [matrix](https://matrix.org/) chat client for secure,
+decentralized communication with an emphasis on user experience
+and customization. **Currently in alpha**.
+
+![Chat screenshot](extra/general/screenshots/01-chat.png?raw=true)
+
+## Currently implemented features
+
+### Client
+
+- **Fluid interface** that adapts to any window size
+- Customizable **keyboard shortcuts** for (almost) everything, including
+  filtering and switching rooms, scrolling, sending files...
+- Versatile **theming system**, properties can refer to each others and have 
+  any valid ECMAScript 7 expression as value
+  - Comes by default with **dark and transparent themes**
+- **Multiple accounts** in one client
+
+### Profile
+
+- Set your display name and profile picture
+- Import/export **E2E** key files
+
+### Rooms
+
+- Create, join, leave and forget rooms
+- Send, accept and refuse invites
+
+### Messages
+
+- Send and receive **E2E encrypted messages**
+- Send and receive emote messages (e.g. `/me reads attentively`)
+- Receive notice (bot) messages
+- Send **markdown** formatted messages
+  - Additional syntax for **coloring** text, e.g. `<red>(Some text...)` - 
+    [SVG/CSS color names](https://www.december.com/html/spec/colorsvg.html),
+    and `#hex` codes can be used
+- Send and receive normal or **E2E encrypted files**
+- Client-side Matrix & HTTP URL **image previews**, including animated GIF 
+
+### Presence
+
+- Typing notifications
+
+## Installation
+
+See [INSTALL.MD](INSTALL.MD).
+
+## Configuration and theming
+
+The config file can be found at *$XDG_CONFIG_HOME/mirage/settings.json*, 
+or *~/.config/mirage/settings.json*.
+
+The `theme` setting can be:
+
+- The name of a built-in theme (`Midnight` or `Glass`)
+- The filename without extension of a custom theme at 
+  *$XDG_DATA_HOME/mirage/themes*, or *~/.local/share/mirage/themes*
+
+A default theme from this repository can be copied to use as a base and edit,
+for example:
+
+```sh
+    cp mirage/src/themes/Midnight.qpl \
+       "${XDG_DATA_HOME:-$HOME/.local/share}/mirage/themes/MyTheme.qpl"
+```
+
+The config setting `theme` would need to be set to `MyTheme` in this case.
+
+Theme files are nested-by-indentations sections of properties and values.  
+Properties are declared as `<type> <name>: <value>`.  
+Values can be any JavaScript (ECMAScript 7) expressions.
+
+Most of the properties are of type `color`.
+Their values, if not just refering to another property,
+can be expressed with a:
+- [SVG/CSS color name](https://www.december.com/html/spec/colorsvg.html)
+  string, e.g. `"blue"`
+- hexadecimal code string, e.g. `"#fff"` or `"#cc0000"`
+- RGBA value, using the `Qt.rgba(0-1, 0-1, 0-1, 0-1)` function
+- HSLA value, using the `Qt.hsla(0-1, 0-1, 0-1, 0-1)` function
+- HSVA value, using the `Qt.hsva(0-1, 0-1, 0-1, 0-1)` function
+- [HSLUV](https://www.hsluv.org/) value, using the
+  `hsluv(0-360, 0-100, 0-100, 0-1)` function. This is the prefered method 
+  used throughout the default theme files
+  (why? see [this](https://www.hsluv.org/comparison/#rainbow-hsluv) and
+  [that](https://www.boronine.com/2012/03/26/Color-Spaces-for-Human-Beings/#hsl-is-a-lemon))
+
+If you just want to change the background picture,
+or use a gradient/simple color instead, search for the `ui:` section in your
+text editor.
 
 
-## Dependencies setup
+With `Alt+Shift+R` by default, the config and theme can be reloaded without 
+restarting the app.
 
-From your distribution's package manager, install:
+**Warnings**: 
 
-Qt 5.12+, including:
+- API currently unstable: theme properties are often renamed, added or deleted.
-- qt5-declarative-devel
+- The file format for both config and themes will soon change
-- qt5-quickcontrols2-devel
+- The current file format currently forces all theme to have all properties
-- qt5-svg-devel
+  defined, instead of being able to only specify the ones to override from the
-- qt5-graphicaleffects
+  default theme.
-- qt5-qmake
-- qt5-devel
 
-- python3
+GUI settings will also be implemented in the future.
-- python3-devel
-- olm-python3 >= 3.1
 
-Make sure that the right version of Qt is selected and compiler flags are
+## More screenshots
-correctly set:
 
-    export QT_SELECT=5
+![Sign-in](extra/general/screenshots/02-sign-in.png)
-    export CFLAGS="-march=native -O2 -pipe"
+![Account settings](extra/general/screenshots/03-account-settings.png)
-    export CXXFLAGS="$CFLAGS"
+![Room creation](extra/general/screenshots/04-create-room.png)
-    export MAKEFLAGS="$(nproc)"
+![Main pane in small window](extra/general/screenshots/05-main-pane-small.png)
+![Chat in small window](extra/general/screenshots/06-chat-small.png)
 
-Install [pyotherside](https://github.com/thp/pyotherside):
-
-    git clone https://github.com/thp/pyotherside
-    cd pyotherside
-    make clean; qmake && make && sudo make install
-
-After this, verify the permissions of the installed plugin files.
-To ensure that they're correctly set:
-
-    sudo chmod -R 755 /usr/lib/qt5/qml/io
-    sudo chmod 644 /usr/lib/qt5/qml/io/thp/pyotherside/*
-    sudo chmod 755 /usr/lib/qt5/qml/io/thp/pyotherside/*.so
-
-Install the Python 3 dependencies:
-
-    pip3 install --user -Ur requirements.txt
-
-Optional dependency for performance improvements:
-
-    pip3 install --user -U uvloop==0.13.0
-
-
-## Building
-
-    git clone --recursive <TODO>
-    cd mirage
-    qmake mirage.pro && make && sudo make install
-
-After this if no errors happened, run `mirage`.
-
-If you get a version mismatch error related to cffi, try:
-
-    pip3 install --user --upgrade --force-reinstall cffi

TODO.md

@@ -4,7 +4,6 @@
 
 - page back buttons
 - Add Gentoo instructions
-- Finish the README.md
 - Build final AppImage and test media opening
 
 ## Refactoring