Import wiki documentation from upstream

Imported from: commit 2484d45a8abcb55e900de8538de6ec646992d682 (HEAD) Author: Marvin W <git@larma.de> Date: Fri Aug 19 14:41:11 2022 +0200 Destroyed _Footer (markdown)
2023-09-29 10:53:41 +02:00 · 2023-09-29 10:53:41 +02:00 · d1f04bf33e
parent f25bfb0096
commit d1f04bf33e
7 changed files with 298 additions and 0 deletions
--- a/doc/BUILD.md
+++ b/doc/BUILD.md
@ -0,0 +1,63 @@
+# Dependency package names
+
+### Debian / Ubuntu
+```
+sudo apt install cmake ninja-build valac gettext libgee-0.8-dev libsqlite3-dev libgtk-3-dev libgpgme-dev libsoup2.4-dev libgcrypt20-dev libqrencode-dev libgspell-1-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libwebrtc-audio-processing-dev libsrtp2-dev libnice-dev glib-networking gstreamer1.0-plugins-good gstreamer1.0-gtk3 libsignal-protocol-c-dev
+```
+
+### Fedora
+```
+sudo dnf install cmake gcc-c++ gpgme-devel libnotify-devel libgcrypt-devel pkgconfig vala libsignal-protocol-c-devel "pkgconfig(gee-0.8)" "pkgconfig(gio-2.0)" "pkgconfig(glib-2.0)" "pkgconfig(gthread-2.0)" "pkgconfig(gtk+-3.0)" "pkgconfig(libsoup-2.4)" "pkgconfig(sqlite3)" "pkgconfig(libqrencode)" "pkgconfig(gspell-1)" "pkgconfig(gstreamer-1.0)" "pkgconfig(gstreamer-app-1.0)" "pkgconfig(gstreamer-audio-1.0)" "pkgconfig(gstreamer-rtp-1.0)" "pkgconfig(gstreamer-video-1.0)" "pkgconfig(nice)" "pkgconfig(libsrtp2)" "pkgconfig(webrtc-audio-processing)"
+```
+
+### OpenSUSE Tumbleweed
+```
+sudo zypper install cmake gcc-c++ gpgme-devel libnotify-devel libgcrypt-devel pkgconfig vala "pkgconfig(gee-0.8)" "pkgconfig(gio-2.0)" "pkgconfig(glib-2.0)" "pkgconfig(gthread-2.0)" "pkgconfig(gtk+-3.0)" "pkgconfig(libsoup-2.4)" "pkgconfig(sqlite3)" "pkgconfig(libqrencode)" "pkgconfig(gspell-1)" "pkgconfig(gstreamer-1.0)" "pkgconfig(gstreamer-app-1.0)" "pkgconfig(gstreamer-audio-1.0)" "pkgconfig(gstreamer-rtp-1.0)" "pkgconfig(gstreamer-video-1.0)" "pkgconfig(nice)" "pkgconfig(libsrtp2)" "pkgconfig(webrtc-audio-processing)" openssl-devel libsignal-protocol-c-devel
+```
+
+### Arch Linux
+```
+sudo pacman -S cmake vala ninja glib2 glib-networking gtk3 gpgme libgee>=0.10 libgcrypt libsoup sqlite qrencode gspell gstreamer gst-plugins-base gst-plugins-good gst-plugin-gtk webrtc-audio-processing libnice libsrtp libsignal-protocol-c
+```
+
+# libsignal-protocol-c
+If build complains about missing or incompatible libsignal-protocol-c and it is not provided by your distribution, you can fetch and build it in tree by using `./configure --with-libsignal-in-tree`.
+
+# Dependencies
+
+Basics
+* C compiler
+* CMake
+* Emoji font (recommend)
+* gettext
+* GLib (≥ 2.38)
+* GTK (≥ 3.22)
+* libgee-0.8 (≥ 0.10)
+* libgspell
+* libqrencode3 (For the OMEMO plugin)
+* ninja(-build) (recommend)
+* SQLite3 (≥ 3.24)
+* valac (≥ 0.34)
+
+Encryption
+* GPGME (For the OpenPGP plugin)
+* libgcrypt (For the OMEMO plugin)
+* libsignal-protocol-c (≥ 2.3.2, for the OMEMO plugin)
+* libsrtp2 (For calls)
+
+Connection establishment
+* glib-networking
+* libnice (≥ 0.1.15)
+* libsoup (For the HTTP files plugin)
+
+Audio/video processing
+* GStreamer
+* webrtc-audio-processing
+
+***
+
+### Basic instructions:
+* `./configure`
+* `make`
+* `sudo make install`
+* `sudo ldconfig`
--- a/doc/DEBUGGING.md
+++ b/doc/DEBUGGING.md
@ -0,0 +1,31 @@
+# Stack trace
+If Dino crashes, a stack trace can be obtained by executing Dino within gdb. Make sure you have debug symbols installed.
+```
+gdb dino
+> r // Starts dino
+[Do whatever makes Dino crash]
+> bt // To obtain the stack trace
+```
+To get traces of runtime criticals, use `gdb --args dino --g-fatal-warnings`.
+
+# Debug output
+Additional output will be printed when setting the environment variable `G_MESSAGES_DEBUG`. Setting it to `all` will also print output from non-Dino components (Gtk, Glib, ...).
+
+`env G_MESSAGES_DEBUG=all dino`
+
+You can filter for which components debug output should be printed by replacing `all` with `libdino` and/or `OMEMO`
+
+`env G_MESSAGES_DEBUG=libdino,OMEMO dino`
+
+
+# View XML stanzas
+Starting `dino` with `--print-xmpp=[filter]` results in stanzas being printed to stdout. You can create complex filters to specify which stanzas should be printed.
+
+|`--print-xmpp=`                | Result      |
+|------------------------------ | ----------- |
+| `all`                         | All stanzas |
+| `message`                     | Message stanzas |
+| `message.body`                | Message stanzas with a `body` child node |
+| `message[to=jid@example.com]` | Message stanzas with the `to` attribute set to `jid@example.com` |
+| `presence.{jabber:x:signed}:x` | Presence stanzas having a child node `x` with namespace `jabber:x:signed`|
+| `message\|iq`                  | Message and Iq stanzas |
--- a/doc/FAQ.md
+++ b/doc/FAQ.md
@ -0,0 +1,66 @@
+# How to create a group chat?
+
+*We plan to introduce dialogs to conveniently create channels and groups. The new UI will obsolete the following (more involved) steps.*
+
+Click on the _+_ button on the top left and select _Join channel_. After clicking on the _+_ button below the channel list, the room address has to be provided in the _JID_ field. It has the form "_[room identifier]_@_[domain name]_".
+
+The room identifier can be freely chosen, but it must not exist yet and must not contain spaces (hyphens or underscores are fine). The domain name that is used for rooms (also called <abbr title="Multi-User Chat">MUC</abbr>) depends on your server provider. Often, it can be found on the provider's website.
+
+Once created, the room can be configured via the ☰ / ⚙ button on the top right. You can configure it to be a private group or a public channel by setting the following values:
+
+| Setting name | Private Group | Public Channel |
+|--------------|---------------|----------------|
+| Persistent   | Yes           | Yes            |
+| Publicly searchable | No | Yes |
+| Members only | Yes | No |
+| Permission to view JIDs | Anyone | Moderators only |
+
+# How to add someone to my contact list?
+
+Click on the _+_ button on the top left and select _Start conversation_. The list of contacts you see in the appearing dialog is also sometimes referred to as your roster. You can add someone to your contact list with the _+_ button at the bottom of the list and remove someone with the _-_ button.
+
+# How to change the font size in Dino?
+
+Dino adheres to the font size defined in the global GTK settings, so it could be changed there.
+
+To scale the fonts only for Dino, the `GDK_DPI_SCALE` environment variable can be set before launching. For example, the terminal command for a larger font size is as follows on Ubuntu:
+```shell
+GDK_DPI_SCALE=1.5 dino
+```
+
+# How to use Dino over Tor?
+
+See the [related wiki page](https://github.com/dino/dino/wiki/Tor).
+
+# How to run another separate Dino instance?
+
+```shell
+env DBUS_SESSION_BUS_ADDRESS=  XDG_DATA_HOME="${dino_folder_path_for_this_instance}" dino
+```
+
+# How to move the data and configuration?
+
+**Warning: Wrongly copying Dino's data around leads to OMEMO not working anymore**
+
+Dino's data contains Dino's OMEMO keys. An OMEMO key can only be used by *one* client. The per-client key changes with every exchanged message. That means
+- You can't use the same OMEMO key on multiple devices. The protocol doesn't work that way. It *will* break.
+- You shouldn't backup and restore an old state of the OMEMO keys, since the keys continuously change. It won't work.
+
+What you can do is to **move** Dino from installation A to installation B. Dino's data and configuration is contained in the `~/.local/share/dino` folder. Quit Dino before moving the folder.
+
+# Is it possible to hide Dino and show an icon in the system tray?
+
+No, but it's planned. It will be probably realised by directly implementing the StatusNotifierItem D-Bus interface. Pull requests are welcome!
+
+# Is it possible to enable OMEMO by default?
+
+No, but we understand that improvements in that area are needed.
+
+# How to set a dark theme?
+
+Add the following entry to `~/.config/gtk-3.0/settings.ini`:
+
+```ini
+[Settings]
+gtk-application-prefer-dark-theme = true
+```
--- a/doc/MACOS.md
+++ b/doc/MACOS.md
@ -0,0 +1,45 @@
+**macOS is currently not officially supported**. This should change in the future. Until then, this page provides the information you need to get Dino running. Problems are to be expected.
+
+## Compiling with Homebrew
+The following instructions expect you to use a Terminal emulator, for example the Terminal.app included with macOS. Open it and type in the commands as described.
+
+1. If you don't have XCode tools installed, install them using
+   ```sh
+   $ xcode-select --install
+   ```
+2. If you don't already have homebrew installed, install it using
+   ```sh
+   $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
+   ```
+   See https://brew.sh for updated installation instructions of homebrew.
+3. Make sure all the required dependencies are installed by running
+   ```sh
+   $ brew install adwaita-icon-theme glib glib-networking gpgme icu4c libgpg-error libgcrypt gtk+3 libsignal-protocol-c libgee libsoup sqlite cmake gettext ninja vala qrencode libxml2 gspell gst-plugins-base srtp libnice
+   ```
+4. Download the source code from the git in a directory of your choice (use `cd` to change the current working directory)
+   ```sh
+   $ git clone https://github.com/dino/dino.git
+   $ cd dino
+   ```
+5. Configure and compile the dino in a brew shell
+   ```sh
+   $ brew sh
+   $ ./configure
+   $ make
+   $ exit
+   ```
+6. Fix the filename of plugins
+   ```sh
+   $ zsh -e -x -c 'for plugin in build/plugins/*.dylib;
+         do mv ${plugin} ${plugin%.dylib}.so;
+       done'
+   ```
+
+You are done. Start dino by typing `./build/dino`. If you want to update to the latest version, run `git pull` and redo steps 5 and 6.
+
+TODO: Package dino in a bundle for nice installation.
+
+## Developer notes
+Guides to run virtualized macOS:
+- VirtualBox: https://github.com/myspaghetti/macos-guest-virtualbox
+- KVM/QEMU/libvirt: https://github.com/foxlet/macOS-Simple-KVM
--- a/doc/TOR.md
+++ b/doc/TOR.md
@ -0,0 +1,20 @@
+# Run
+If you configured a system-wide SOCKS proxy, Dino will honor that setting.
+
+Otherwise, you can specifically set Dino to use Tor by starting it with
+```
+$ torsocks dino
+```
+
+# DNS
+
+You can have your system route DNS requests through Tor by writing `nameserver 127.0.0.1` into your `/etc/resolv.conf`.
+
+XMPP uses `SRV` records by default, which cannot be queried through Tor. As a fallback, XMPP uses `A` records, which **can** be queried through Tor. Thus, make sure the domain of your server has an `A` record set to the IP of the XMPP server. Public servers are very frequently set up accordingly.
+
+# Anonymity and privacy distributions
+
+## Tails
+* Download and install the Dino Debian package from [OBS](https://software.opensuse.org/download.html?project=network:messaging:xmpp:dino&package=dino).
+* Start Dino from the console with `torsocks dino`.
+* Don't worry about DNS - Tails forces all traffic through Tor.
--- a/doc/TRANSLATIONS.md
+++ b/doc/TRANSLATIONS.md
@ -0,0 +1,14 @@
+### Weblate
+Translations are managed on [weblate](https://hosted.weblate.org/engage/dino/).
+
+### User addressing
+Some strings address the user ("you", "your", ...). How to address the user differs by language, but should be done consistently within a language:
+
+- French: vous, votre
+- German: du, dein
+- Swedish: du, din
+- Polish: ty, twój
+
+### Translation overview
+
+[![Translation status](https://hosted.weblate.org/widgets/dino/-/multi-auto.svg)](https://hosted.weblate.org/engage/dino/?utm_source=widget)
--- a/doc/XEPS.md
+++ b/doc/XEPS.md
@ -0,0 +1,59 @@
+|                                                   | XEP                          | Status | Note |
+| ------------------------------------------------- | ---------------------------- | ------ |------|
+[0004](https://xmpp.org/extensions/xep-0004.html)|Data Forms|complete||
+[0027](https://xmpp.org/extensions/xep-0027.html)|Current Jabber OpenPGP Usage|complete||
+[0030](https://xmpp.org/extensions/xep-0030.html)|Service Discovery|complete||
+[0045](https://xmpp.org/extensions/xep-0045.html)|Multi-User Chat|partial||
+[0047](https://xmpp.org/extensions/xep-0047.html)|In-Band Bytestreams|complete|For use with XEP-0261|
+[0048](https://xmpp.org/extensions/xep-0048.html)|Bookmarks|deprecated|Migrating to XEP-0402 if supported by server|
+[0049](https://xmpp.org/extensions/xep-0049.html)|Private XML Storage|complete||
+[0054](https://xmpp.org/extensions/xep-0054.html)|vcard-temp|partial|Only for viewing avatars|
+[0059](https://xmpp.org/extensions/xep-0059.html)|Result Set Management|partial|For use with XEP-0313|
+[0060](https://xmpp.org/extensions/xep-0060.html)|Publish-Subscribe|partial||
+[0065](https://xmpp.org/extensions/xep-0065.html)|SOCKS5 Bytestreams|partial|For use with XEP-0260|
+[0066](https://xmpp.org/extensions/xep-0066.html)|Out of Band Data|complete|For file transfers using XEP-0363|
+[0077](https://xmpp.org/extensions/xep-0077.html)|In-Band Registration|complete||
+[0082](https://xmpp.org/extensions/xep-0082.html)|XMPP Date and Time Profiles|complete||
+[0084](https://xmpp.org/extensions/xep-0084.html)|User Avatar|complete||
+[0085](https://xmpp.org/extensions/xep-0085.html)|Chat State Notifications|complete||
+[0115](https://xmpp.org/extensions/xep-0115.html)|Entity Capabilities|complete||
+[0153](https://xmpp.org/extensions/xep-0153.html)|vCard-Based Avatars|deprecated|Only to fetch Avatars from other users|
+[0163](https://xmpp.org/extensions/xep-0163.html)|Personal Eventing Protocol|complete||
+[0166](https://xmpp.org/extensions/xep-0166.html)|Jingle|partial||
+[0167](https://xmpp.org/extensions/xep-0167.html)|Jingle RTP Sessions|partial||
+[0176](https://xmpp.org/extensions/xep-0176.html)|Jingle ICE-UDP Transport Method|partial||
+[0184](https://xmpp.org/extensions/xep-0184.html)|Message Delivery Receipts|complete||
+[0191](https://xmpp.org/extensions/xep-0191.html)|Blocking Command|complete||
+[0198](https://xmpp.org/extensions/xep-0198.html)|Stream Management|complete||
+[0199](https://xmpp.org/extensions/xep-0199.html)|XMPP Ping|complete||
+[0203](https://xmpp.org/extensions/xep-0203.html)|Delayed Delivery|complete||
+[0215](https://xmpp.org/extensions/xep-0215.html)|External Service Discovery|partial||
+[0222](https://xmpp.org/extensions/xep-0222.html)|Persistent Storage of Public Data via PubSub|complete||
+[0223](https://xmpp.org/extensions/xep-0223.html)|Persistent Storage of Private Data via PubSub|complete||
+[0234](https://xmpp.org/extensions/xep-0234.html)|Jingle File Transfer|partial||
+[0245](https://xmpp.org/extensions/xep-0245.html)|The /me Command|complete||
+[0249](https://xmpp.org/extensions/xep-0249.html)|Direct MUC Invitations|partial|No support for sending|
+[0260](https://xmpp.org/extensions/xep-0260.html)|Jingle SOCKS5 Bytestreams Transport Method|complete||
+[0261](https://xmpp.org/extensions/xep-0261.html)|Jingle In-Band Bytestreams Transport Method|complete||
+[0280](https://xmpp.org/extensions/xep-0280.html)|Message Carbons|complete||
+[0293](https://xmpp.org/extensions/xep-0293.html)|Jingle RTP Feedback Negotiation|partial||
+[0294](https://xmpp.org/extensions/xep-0294.html)|Jingle RTP Header Extensions Negotiation|partial||
+[0297](https://xmpp.org/extensions/xep-0297.html)|Stanza Forwarding|complete|For use with XEP-0280|
+[0308](https://xmpp.org/extensions/xep-0308.html)|Last Message Correction|complete||
+[0313](https://xmpp.org/extensions/xep-0313.html)|Message Archive Management|partial|Not for MUCs|
+[0320](https://xmpp.org/extensions/xep-0320.html)|Use of DTLS-SRTP in Jingle Sessions|complete||
+[0333](https://xmpp.org/extensions/xep-0333.html)|Chat Markers|complete||
+[0334](https://xmpp.org/extensions/xep-0334.html)|Message Processing Hints|partial||
+[0353](https://xmpp.org/extensions/xep-0353.html)|Jingle Message Initiation|complete||
+[0359](https://xmpp.org/extensions/xep-0359.html)|Unique and Stable Stanza IDs|complete||
+[0363](https://xmpp.org/extensions/xep-0363.html)|HTTP File Upload|complete||
+[0368](https://xmpp.org/extensions/xep-0368.html)|SRV records for XMPP over TLS|complete||
+[0380](https://xmpp.org/extensions/xep-0380.html)|Explicit Message Encryption|partial|Only for outgoing messages|
+[0384](https://xmpp.org/extensions/xep-0384.html)|OMEMO Encryption|complete||
+[0391](https://xmpp.org/extensions/xep-0391.html)|Jingle Encrypted Transports|partial||
+[0393](https://xmpp.org/extensions/xep-0393.html)|Message Styling|partial||
+[0396](https://xmpp.org/extensions/xep-0396.html)|Jingle Encrypted Transports - OMEMO|complete||
+[0398](https://xmpp.org/extensions/xep-0398.html)|User Avatar to vCard-Based Avatars Conversion|complete||
+[0402](https://xmpp.org/extensions/xep-0402.html)|PEP Native Bookmarks|complete||
+[0410](https://xmpp.org/extensions/xep-0410.html)|MUC Self-Ping (Schrödinger's Chat)|complete||
+[0454](https://xmpp.org/extensions/xep-0454.html)|OMEMO Media sharing|partial|No support for embedded thumbnails|