doc: add XDG directories support in docs (issue #1285)

5 files changed, 116 insertions, 77 deletions

diff --git a/doc/de/includes/cmdline_options.de.adoc b/doc/de/includes/cmdline_options.de.adoc
index bdbb9f456..04b304241 100644
--- a/doc/de/includes/cmdline_options.de.adoc
+++ b/doc/de/includes/cmdline_options.de.adoc
@@ -15,10 +15,11 @@
     (funktioniert ausschließlich mit *weechat-headless* und ist nicht kompatibel mit Option
     "--daemon").
 
+// TRANSLATION MISSING
 *-d*, *--dir* _<path>_::
-    legt den Konfigurationsordner für WeeChat fest in welchem die Erweiterungen,
-    Skripten, Protokolldateien etc.pp. gesichert werden (Voreinstellung: "~/.weechat").
-    Sollte das Verzeichnis nicht existieren wird es beim Start angelegt.
+    Force a single directory for all WeeChat files (directory is created if not found).
+    Four directories can be given, separated by colons (in this order: config,
+    data, cache, runtime).
     Wird diese Option nicht genutzt, wird die Umgebungsvariable WEECHAT_HOME genutzt
     (sofern diese vorhanden ist).
 
diff --git a/doc/de/includes/man.de.adoc b/doc/de/includes/man.de.adoc
index 8d87d25b2..ae2151989 100644
--- a/doc/de/includes/man.de.adoc
+++ b/doc/de/includes/man.de.adoc
@@ -17,79 +17,79 @@ Um eine IPv6 Adresse zu nutzen, muss diese in eckige Klammern gesetzt werden:
 // end::plugin_options[]
 
 // tag::files[]
-$HOME/.weechat/weechat.conf::
+$HOME/.config/weechat/weechat.conf::
     WeeChats Konfigurationsdatei
 
-$HOME/.weechat/plugins.conf::
+$HOME/.config/weechat/plugins.conf::
     Konfigurationsdatei für Erweiterungen
 
-$HOME/.weechat/sec.conf::
+$HOME/.config/weechat/sec.conf::
     Konfigurationsdatei mit schutzwürdigen Daten
 
-$HOME/.weechat/alias.conf::
+$HOME/.config/weechat/alias.conf::
     Konfigurationsdatei für _alias_ Erweiterung
 
-$HOME/.weechat/buflist.conf::
+$HOME/.config/weechat/buflist.conf::
     Konfigurationsdatei für _buflist_ Erweiterung
 
-$HOME/.weechat/charset.conf::
+$HOME/.config/weechat/charset.conf::
     Konfigurationsdatei für _charset_ Erweiterung
 
-$HOME/.weechat/exec.conf::
+$HOME/.config/weechat/exec.conf::
     Konfigurationsdatei für _exec_ Erweiterung
 
-$HOME/.weechat/fifo.conf::
+$HOME/.config/weechat/fifo.conf::
     Konfigurationsdatei für _fifo_ Erweiterung
 
-$HOME/.weechat/fset.conf::
+$HOME/.config/weechat/fset.conf::
     Konfigurationsdatei für _fset_ Erweiterung
 
-$HOME/.weechat/guile.conf::
+$HOME/.config/weechat/guile.conf::
     Konfigurationsdatei für _guile_ Erweiterung
 
-$HOME/.weechat/irc.conf::
+$HOME/.config/weechat/irc.conf::
     Konfigurationsdatei für _irc_ Erweiterung
 
-$HOME/.weechat/javascript.conf::
+$HOME/.config/weechat/javascript.conf::
     Konfigurationsdatei für _javascript_ Erweiterung
 
-$HOME/.weechat/logger.conf::
+$HOME/.config/weechat/logger.conf::
     Konfigurationsdatei für _logger_ Erweiterung
 
-$HOME/.weechat/lua.conf::
+$HOME/.config/weechat/lua.conf::
     Konfigurationsdatei für _lua_ Erweiterung
 
-$HOME/.weechat/perl.conf::
+$HOME/.config/weechat/perl.conf::
     Konfigurationsdatei für _perl_ Erweiterung
 
-$HOME/.weechat/php.conf::
+$HOME/.config/weechat/php.conf::
     Konfigurationsdatei für _php_ Erweiterung
 
-$HOME/.weechat/python.conf::
+$HOME/.config/weechat/python.conf::
     Konfigurationsdatei für _python_ Erweiterung
 
-$HOME/.weechat/relay.conf::
+$HOME/.config/weechat/relay.conf::
     Konfigurationsdatei für _relay_ Erweiterung
 
-$HOME/.weechat/ruby.conf::
+$HOME/.config/weechat/ruby.conf::
     Konfigurationsdatei für _ruby_ Erweiterung
 
-$HOME/.weechat/script.conf::
+$HOME/.config/weechat/script.conf::
     Konfigurationsdatei für _script_ Erweiterung
 
-$HOME/.weechat/spell.conf::
+$HOME/.config/weechat/spell.conf::
     Konfigurationsdatei für _spell_ Erweiterung
 
-$HOME/.weechat/tcl.conf::
+$HOME/.config/weechat/tcl.conf::
     Konfigurationsdatei für _tcl_ Erweiterung
 
-$HOME/.weechat/trigger.conf::
+$HOME/.config/weechat/trigger.conf::
     Konfigurationsdatei für _trigger_ Erweiterung
 
-$HOME/.weechat/xfer.conf::
+$HOME/.config/weechat/xfer.conf::
     Konfigurationsdatei für _xfer_ Erweiterung
 
-$HOME/.weechat/weechat.log::
+$HOME/.local/share/weechat/weechat.log::
     WeeChat Protokolldatei
 // end::files[]
 
diff --git a/doc/de/weechat_faq.de.adoc b/doc/de/weechat_faq.de.adoc
index 396c02b35..c9e668b1c 100644
--- a/doc/de/weechat_faq.de.adoc
+++ b/doc/de/weechat_faq.de.adoc
@@ -1143,9 +1143,13 @@ Wenn das nicht hilft, sollte die Skriptliste von Hand gelöscht werden. Dazu
 folgenden Befehl in der Shell ausführen:
 
 ----
-$ rm ~/.weechat/script/plugins.xml.gz
+$ rm ~/.cache/weechat/script/plugins.xml.gz
 ----
 
+// TRANSLATION MISSING
+[NOTE]
+With WeeChat ≤ 3.1, the path should be: _~/.weechat/script/plugins.xml.gz_.
+
 Danach sollte man noch einmal versuchen die Datei herunter zu laden:
 
 ----
@@ -1165,7 +1169,7 @@ Das bedeutet aber auch, dass die Skripten von Hand aktuell gehalten werden müss
 * und in der Shell, mit installiertem curl:
 
 ----
-$ cd ~/.weechat/script
+$ cd ~/.cache/weechat/script
 $ curl -O https://weechat.org/files/plugins.xml.gz
 ----
 
@@ -1287,9 +1291,9 @@ Beispiel:
 [[sharing_config_files]]
 === Ich möchte meine WeeChat Konfiguration teilen. Welche Dateien kann ich weitergeben und welche sollte ich behalten?
 
-Es können alle _~/.weechat/*.conf_ Dateien geteilt werden.
-Hiervon ausgenommen ist die Datei _sec.conf_,
-die durch eine Passphrase verschlüsselte, sensible, Daten enthalten kann.
+// TRANSLATION MISSING
+You can share configuration files _*.conf_ except the file _sec.conf_ which
+contains your passwords ciphered with your passphrase.
 
 Einige andere Dateien enthalten möglicherweise vertrauliche Informationen wie
 Kennwörter (sofern sie nicht mit dem Befehl `/secure` in _sec.conf_ gesichert werden).
diff --git a/doc/de/weechat_scripting.de.adoc b/doc/de/weechat_scripting.de.adoc
index b4988eb88..161090634 100644
--- a/doc/de/weechat_scripting.de.adoc
+++ b/doc/de/weechat_scripting.de.adoc
@@ -349,7 +349,7 @@ anlegen, der in das Verzeichnis _Skriptsprache/autoload_ zeigt.
 Ein Beispiel für ein Python-Skript:
 
 ----
-$ cd ~/.weechat/python/autoload
+$ cd ~/.local/share/weechat/python/autoload
 $ ln -s ../script.py
 ----
 
@@ -1394,10 +1394,11 @@ weechat.prnt("", "Version %s" % weechat.info_get("version", ""))
 [[infos_other]]
 ==== andere Informationen
 
+// TRANSLATION MISSING
 [source,python]
 ----
-# WeeChat Hauptverzeichnis, zum Beispiel: "/home/xxxx/.weechat"
-weechat.prnt("", "WeeChat Hauptverzeichnis: %s" % weechat.info_get("weechat_dir", ""))
+# WeeChat config directory, for example: "/home/user/.config/weechat"
+weechat.prnt("", "WeeChat config dir: %s" % weechat.info_get("weechat_config_dir", ""))
 
 # Inaktivität der Tastatur
 weechat.prnt("", "Tastatur ist seit %s Sekunden nicht mehr betätigt worden" % weechat.info_get("inactivity", ""))
diff --git a/doc/de/weechat_user.de.adoc b/doc/de/weechat_user.de.adoc
index 580689ad5..bdeb35819 100644
--- a/doc/de/weechat_user.de.adoc
+++ b/doc/de/weechat_user.de.adoc
@@ -476,10 +476,10 @@ werden um die Datei zu lesen. +
 Weitere Informationen finden Sie auf dieser Wiki-Seite: https://wiki.archlinux.org/index.php/Core_dump
 
 Beispiel: _weechat_ ist in _/usr/bin/_ installiert und die _core_ Datei befindet sich
-in _/home/xxx/_. Nun wird gdb mit folgendem Befehl aufgerufen:
+in _/home/user/_. Nun wird gdb mit folgendem Befehl aufgerufen:
 
 ----
-gdb /usr/bin/weechat /home/xxx/core
+gdb /usr/bin/weechat /home/user/core
 ----
 
 Nun startet man _gdb_ und führt den Befehl `bt full` innerhalb der gdb Umgebung aus, um die
@@ -563,9 +563,10 @@ z.B. um den Kernel zu aktualisieren oder WeeChat auf einen anderen Computer zu v
 /upgrade -quit
 ----
 
-Dies speichert den aktuellen Status in `*.upgrade`-Dateien. Sie können dann entweder das
-gesamte `~/.weechat` Verzeichnis auf einen anderen Computer verschieben oder diesen
-gespeicherten Status neu starten, mit folgendem Befehl:
+// TRANSLATION MISSING
+This saves the current state in `*.upgrade` files. You can then either reboot
+or move the whole WeeChat directories (config, data, cache) to another machine,
+and restart WeeChat later with this command:
 
 ----
 $ weechat --upgrade
@@ -597,7 +598,7 @@ WeeChat hat ein automatisches Upgrade für Konfigurationsdateien (`*.conf`):
 Beispiel für eine Warnung, wenn eine Option entfernt wurde:
 
 ----
-=!= Warnung: /home/xxx/.weechat/sec.conf, Zeile 15: unbekannte Einstellung für Sektion "crypt": passphrase_file = ""
+=!= Warnung: /home/user/.config/weechat/sec.conf, Zeile 15: unbekannte Einstellung für Sektion "crypt": passphrase_file = ""
 ----
 
 Das bedeutet, dass die Option "sec.crypt.passphrase_file" entfernt wurde und der
@@ -617,7 +618,7 @@ $ weechat
 ----
 
 Wird WeeChat das erste mal ausgeführt, wird die Standardkonfiguration und
-die entsprechenden Dateien im Verzeichnis _~/.weechat_ erstellt.
+die entsprechenden Dateien im Verzeichnis _~/.config/weechat_ erstellt.
 (siehe <<files_and_directories,Dateien und Verzeichnisse>>).
 
 ==== Optionen für Befehlszeile
@@ -648,9 +649,28 @@ Einige Umgebungsvariablen werden von WeeChat genutzt, sofern sie definiert wurde
 [[files_and_directories]]
 === Dateien und Verzeichnisse
 
-WeeChat schreibt standardmäßig seine Konfiguration und andere
-Daten in folgendes Verzeichnis: `~/.weechat` +
-Diese Dateien werden, mit Standardwerten, beim ersten Ausführen von WeeChat automatisch erstellt.
+// TRANSLATION MISSING
+[[xdg_directories]]
+==== XDG directories
+
+WeeChat uses XDG directories by default
+(according to the https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG Base Directory Specification]). +
+A single home directory for all files can be forced by CMake option `WEECHAT_HOME`,
+the environment variable `WEECHAT_HOME` or the command-line option `-d` / `--dir`.
+
+When a single WeeChat home directory is not forced, XDG directories are used
+and set like this:
+
+[width="100%",cols="1,2m,5",options="header"]
+|===
+| Directory | Default value            | Fallback value
+| config    | $XDG_CONFIG_HOME/weechat | `$HOME/.config/weechat` if `$XDG_CONFIG_HOME` is not defined or empty.
+| data      | $XDG_DATA_HOME/weechat   | `$HOME/.local/share/weechat` if `$XDG_DATA_HOME` is not defined or empty.
+| cache     | $XDG_CACHE_HOME/weechat  | `$HOME/.cache/weechat` if `$XDG_CACHE_HOME` is not defined or empty.
+| runtime   | $XDG_RUNTIME_DIR/weechat | Same as _cache_ directory if `$XDG_RUNTIME_DIR` is not defined or empty.
+|===
+
+The configuration files are created with default values the first time you run WeeChat.
 
 [[weechat_directories]]
 ==== WeeChat Verzeichnisse
@@ -659,29 +679,38 @@ Es gibt folgende WeeChat Verzeichnisse:
 
 [width="100%",cols="1m,3",options="header"]
 |===
-| Pfad/Datei        | Beschreibung
-| ~/.weechat/       | WeeChat Heimatverzeichnis (kann angepasst werden, siehe <<running_weechat,Running WeeChat>>).
-|    logs/          | Logdateien (eine Datei pro Buffer).
-|    python/        | Python-Skripten.
-|       autoload/   | Python-Skripten die beim Start automatisch ausgeführt werden ^(1)^.
-|    perl/          | Perl-Skripten.
-|       autoload/   | Perl-Skripten die beim Start automatisch ausgeführt werden ^(1)^.
-|    ruby/          | Ruby-Skripten.
-|       autoload/   | Ruby-Skripten die beim Start automatisch ausgeführt werden ^(1)^.
-|    lua/           | Lua-Skripten.
-|       autoload/   | Lua-Skripten die beim Start automatisch ausgeführt werden ^(1)^.
-|    tcl/           | Tcl-Skripten.
-|       autoload/   | Tcl-Skripten die beim Start automatisch ausgeführt werden ^(1)^.
-|    guile/         | Guile-Skripten.
-|       autoload/   | Guile-Skripten die beim Start automatisch ausgeführt werden ^(1)^.
-|    javascript/    | JavaScript-Skripten.
-|       autoload/   | JavaScript-Skripten die beim Start automatisch ausgeführt werden ^(1)^.
-|    php/           | PHP-Skripten.
-|       autoload/   | PHP-Skripten die beim Start automatisch ausgeführt werden ^(1)^.
+| Pfad ^(1)^             | Beschreibung
+// TRANSLATION MISSING
+| ~/.config/weechat/      | WeeChat configuration files: `*.conf`, certificates, etc.
+// TRANSLATION MISSING
+| ~/.local/share/weechat/ | WeeChat data files: logs, scripts, scripts data, xfer files, etc.
+|    logs/                | Logdateien (eine Datei pro Buffer).
+|    python/              | Python-Skripten.
+|       autoload/         | Python-Skripten die beim Start automatisch ausgeführt werden ^(2)^.
+|    perl/                | Perl-Skripten.
+|       autoload/         | Perl-Skripten die beim Start automatisch ausgeführt werden ^(2)^.
+|    ruby/                | Ruby-Skripten.
+|       autoload/         | Ruby-Skripten die beim Start automatisch ausgeführt werden ^(2)^.
+|    lua/                 | Lua-Skripten.
+|       autoload/         | Lua-Skripten die beim Start automatisch ausgeführt werden ^(2)^.
+|    tcl/                 | Tcl-Skripten.
+|       autoload/         | Tcl-Skripten die beim Start automatisch ausgeführt werden ^(2)^.
+|    guile/               | Guile-Skripten.
+|       autoload/         | Guile-Skripten die beim Start automatisch ausgeführt werden ^(2)^.
+|    javascript/          | JavaScript-Skripten.
+|       autoload/         | JavaScript-Skripten die beim Start automatisch ausgeführt werden ^(2)^.
+|    php/                 | PHP-Skripten.
+|       autoload/         | PHP-Skripten die beim Start automatisch ausgeführt werden ^(2)^.
+// TRANSLATION MISSING
+| ~/.cache/weechat/       | WeeChat cache files: scripts cache.
+// TRANSLATION MISSING
+| /run/user/1000/weechat/ | WeeChat runtime files: FIFO pipe, Relay UNIX sockets.
 |===
 
+// TRANSLATION MISSING
 [NOTE]
-^(1)^ Das Verzeichnis besteht meistens aus symbolischen Links welche auf das eigentliche Skript zeigen.
+^(1)^ XDG directories may be different according to your environment variables `XDG_*`. +
+^(2)^ Das Verzeichnis besteht meistens aus symbolischen Links welche auf das eigentliche Skript zeigen.
 
 [[weechat_files]]
 ==== WeeChat Dateien
@@ -2765,7 +2794,9 @@ Sie können WeeChat fern steuern indem Sie Befehle oder einen Text an die FIFO P
 schicken (dazu muss die Option "fifo.file.enabled" aktiviert sein (standardmäßig
 ist diese Option aktiviert).
 
-Die FIFO-Pipe befindet sich standardmäßig im Pfad _~/.weechat/_ und heißt _weechat_fifo_.
+// TRANSLATION MISSING
+The FIFO pipe is located in WeeChat runtime directory and is called
+_weechat_fifo_ by default.
 
 Die Syntax der FIFO Pipe Befehle/Text sieht wie folgt aus:
 
@@ -2779,26 +2810,26 @@ einige Beispiele:
 * Ändert den eigenen Nick auf dem IRC Server freenode in "newnick":
 
 ----
-$ echo 'irc.server.freenode */nick newnick' >~/.weechat/weechat_fifo
+$ echo 'irc.server.freenode */nick newnick' >/run/user/1000/weechat/weechat_fifo
 ----
 
 * Schickt eine Nachrich in den IRC #weechat Channel:
 
 ----
-$ echo 'irc.freenode.#weechat *hello!' >~/.weechat/weechat_fifo
+$ echo 'irc.freenode.#weechat *hello!' >/run/user/1000/weechat/weechat_fifo
 ----
 
 * Schickt eine Nachricht in den aktuellen Buffer:
 
 ----
-$ echo '*hello!' >~/.weechat/weechat_fifo
+$ echo '*hello!' >/run/user/1000/weechat/weechat_fifo
 ----
 
 * Sendet zwei Befehle um alle Python-Skripten zu entfernen und dann neu zu laden (die beiden Befehle müssen
   mit "\n" getrennt werden):
 
 ----
-$ printf '%b' '*/python unload\n*/python autoload\n' >~/.weechat/weechat_fifo
+$ printf '%b' '*/python unload\n*/python autoload\n' >/run/user/1000/weechat/weechat_fifo
 ----
 
 [[fifo_commands]]
@@ -3451,7 +3482,7 @@ Datumsspezifikationen in der Maske genutzt werden (siehe
 Erstellt eine Struktur in folgender Form:
 
 ....
-~/.weechat
+~/.local/share/weechat
 └── logs
     ├── 2010
     │   ├── 11
@@ -3481,7 +3512,7 @@ einer Protokolldatei für jeden Channel:
 Erstellt eine Struktur in folgender Form:
 
 ....
-~/.weechat
+~/.local/share/weechat
 └── logs
     └── irc
         ├── freenode
@@ -3698,13 +3729,15 @@ man jedes Protokoll zum Lauschen an einem UNIX Domain Socket nutzen, indem
 man einen Pfad angibt. Zum Beispiel:
 
 ----
-/relay add unix.weechat %h/relay_socket
+/relay add unix.weechat ${weechat_runtime_dir}/relay_socket
 ----
 
-Das erlaubt es Clients sich mittels dem weechat Protokoll mit 
-_~/.weechat/relay_socket_ zu verbinden. Dies ist besonders zu
+Das erlaubt es Clients sich mittels dem weechat Protokoll mit
+_/run/user/1000/weechat/relay_socket_ zu verbinden. Dies ist besonders zu
 empfehlen um SSH forwarding für relay Clients zu nutzen, falls
-andere Ports nicht geöffnet werden können. OpenSSH nutzen:
+andere Ports nicht geöffnet werden können.
+
+OpenSSH nutzen:
 
 ----
 $ ssh -L 9000:.weechat/relay_socket user@hostname