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

5 files changed, 118 insertions, 77 deletions

diff --git a/doc/pl/includes/cmdline_options.pl.adoc b/doc/pl/includes/cmdline_options.pl.adoc
index de8c8fca6..f124174de 100644
--- a/doc/pl/includes/cmdline_options.pl.adoc
+++ b/doc/pl/includes/cmdline_options.pl.adoc
@@ -14,21 +14,22 @@
     (works only with the command *weechat-headless*, not compatible with option
     "--daemon").
 
+// TRANSLATION MISSING
 *-d*, *--dir* _<ścieżka>_::
-    Ustawia ścieżkę jako katalog domowy WeeChat (używany dla plików
-    konfiguracyjnych, logów, wtyczek użytkownika i skryptów), domyślna wartość
-    to "~/.weechat" (katalog zostanie utworzony jeśli nie istnieje).
+    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).
     Jeśli ta opcja nie zostanie podada, użyta zostanie zawartość zmiennej
     WEECHAT_HOME (jeśli została ustawiona).
 
 *-t*, *--temp-dir*::
     Tworzy tymczasowy katalog dla ustawień WeeChat, który jest kasowany po wyłączeniu
     aplikacji (nie kompatybilne z opcją "-d"). +
-    Nazwa katalogu jest automatyczne tworzona według wzoru: "weechat_temp_XXXXXX" 
+    Nazwa katalogu jest automatyczne tworzona według wzoru: "weechat_temp_XXXXXX"
     (gdzie "XXXXXX" jest losowe). Katalog jest tworzony w pierwszym dostępnym miejscu
-    według tej listy: zmienna środowiskowa "TMPDIR", "/tmp" (może być inaczej na 
+    według tej listy: zmienna środowiskowa "TMPDIR", "/tmp" (może być inaczej na
     niektórych systemach operacyjnych), zmienna środowiskowa "HOME", obecny katalog. +
-    Utworony katalog ma uprawnienia 0700 (tylko właściciel może czytać, pisać i 
+    Utworony katalog ma uprawnienia 0700 (tylko właściciel może czytać, pisać i
     wykonywać).
 
 *-h*, *--help*::
diff --git a/doc/pl/includes/man.pl.adoc b/doc/pl/includes/man.pl.adoc
index 9cce69657..cf4bbb724 100644
--- a/doc/pl/includes/man.pl.adoc
+++ b/doc/pl/includes/man.pl.adoc
@@ -18,79 +18,79 @@ numeru potyu po adresie, na przykład:
 // end::plugin_options[]
 
 // tag::files[]
-$HOME/.weechat/weechat.conf::
+$HOME/.config/weechat/weechat.conf::
     główny plik konfiguracyjny WeeChat
 
-$HOME/.weechat/plugins.conf::
+$HOME/.config/weechat/plugins.conf::
     plik konfiguracyjny wtyczek
 
-$HOME/.weechat/sec.conf::
+$HOME/.config/weechat/sec.conf::
     plik konfiguracyjny z zabezpieczonymi danymi
 
-$HOME/.weechat/alias.conf::
+$HOME/.config/weechat/alias.conf::
     plik konfiguracyjny wtyczki _alias_
 
-$HOME/.weechat/buflist.conf::
+$HOME/.config/weechat/buflist.conf::
     plik konfiguracyjny wtyczki _buflist_
 
-$HOME/.weechat/charset.conf::
+$HOME/.config/weechat/charset.conf::
     plik konfiguracyjny wtyczki _charset_
 
-$HOME/.weechat/exec.conf::
+$HOME/.config/weechat/exec.conf::
     plik konfiguracyjny wtyczki _exec_
 
-$HOME/.weechat/fifo.conf::
+$HOME/.config/weechat/fifo.conf::
     plik konfiguracyjny wtyczki _fifo_
 
-$HOME/.weechat/fset.conf::
+$HOME/.config/weechat/fset.conf::
     plik konfiguracyjny wtyczki _fset_
 
-$HOME/.weechat/guile.conf::
+$HOME/.config/weechat/guile.conf::
     plik konfiguracyjny wtyczki _guile_
 
-$HOME/.weechat/irc.conf::
+$HOME/.config/weechat/irc.conf::
     plik konfiguracyjny wtyczki _irc_
 
-$HOME/.weechat/javascript.conf::
+$HOME/.config/weechat/javascript.conf::
     plik konfiguracyjny wtyczki _javascript_
 
-$HOME/.weechat/logger.conf::
+$HOME/.config/weechat/logger.conf::
     plik konfiguracyjny wtyczki _logger_
 
-$HOME/.weechat/lua.conf::
+$HOME/.config/weechat/lua.conf::
     plik konfiguracyjny wtyczki _lua_
 
-$HOME/.weechat/perl.conf::
+$HOME/.config/weechat/perl.conf::
     plik konfiguracyjny wtyczki _perl_
 
-$HOME/.weechat/php.conf::
+$HOME/.config/weechat/php.conf::
     plik konfiguracyjny wtyczki _php_
 
-$HOME/.weechat/python.conf::
+$HOME/.config/weechat/python.conf::
     plik konfiguracyjny wtyczki _python_
 
-$HOME/.weechat/relay.conf::
+$HOME/.config/weechat/relay.conf::
     plik konfiguracyjny wtyczki _relay_
 
-$HOME/.weechat/ruby.conf::
+$HOME/.config/weechat/ruby.conf::
     plik konfiguracyjny wtyczki _ruby_
 
-$HOME/.weechat/script.conf::
+$HOME/.config/weechat/script.conf::
     plik konfiguracyjny wtyczki _script_
 
-$HOME/.weechat/spell.conf::
+$HOME/.config/weechat/spell.conf::
     plik konfiguracyjny wtyczki _spell_
 
-$HOME/.weechat/tcl.conf::
+$HOME/.config/weechat/tcl.conf::
     plik konfiguracyjny wtyczki _tcl_
 
-$HOME/.weechat/trigger.conf::
+$HOME/.config/weechat/trigger.conf::
     plik konfiguracyjny wtyczki _trigger_
 
-$HOME/.weechat/xfer.conf::
+$HOME/.config/weechat/xfer.conf::
     plik konfiguracyjny wtyczki _xfer_
 
-$HOME/.weechat/weechat.log::
+$HOME/.local/share/weechat/weechat.log::
     plik z logami WeeChat
 // end::files[]
 
diff --git a/doc/pl/weechat_faq.pl.adoc b/doc/pl/weechat_faq.pl.adoc
index e25e99302..87f861987 100644
--- a/doc/pl/weechat_faq.pl.adoc
+++ b/doc/pl/weechat_faq.pl.adoc
@@ -1058,9 +1058,13 @@ w tym dokumencie (zwłaszcza opcji _weechat.network.gnutls_ca_file_).
 Jeśli to nie pomoże spróuj ręcznie usunąć plik z listą skryptów (z poziomu powłoki):
 
 ----
-$ 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_.
+
 Następnie ponownie zaktualizuj listę sktyptów w WeeChat:
 
 ----
@@ -1080,7 +1084,7 @@ have to update manually the file yourself to get updates):
 * w powłoce, z zainstalowanym programem curl:
 
 ----
-$ cd ~/.weechat/script
+$ cd ~/.cache/weechat/script
 $ curl -O https://weechat.org/files/plugins.xml.gz
 ----
 
@@ -1196,8 +1200,9 @@ Na przykład:
 [[sharing_config_files]]
 === Chcę się podzielić moją konfiguracją WeeChat, które pliki powinienem pokazać, a które nie?
 
-Możesz pokazywać pliki z _~/.weechat/*.conf_ poza plikiem _sec.conf_, który
-zawiera Twoje hasla zaszywrowane Twoim kluczem.
+// TRANSLATION MISSING
+You can share configuration files _*.conf_ except the file _sec.conf_ which
+contains your passwords ciphered with your passphrase.
 
 Niektóre inne pliki mogą zawierać poufne informacje jak hasła (jeśli nie są przetrzymywane
 w _sec.conf_ za pomocą komendy `/secure`).
diff --git a/doc/pl/weechat_scripting.pl.adoc b/doc/pl/weechat_scripting.pl.adoc
index fe542fe53..8d9a9b665 100644
--- a/doc/pl/weechat_scripting.pl.adoc
+++ b/doc/pl/weechat_scripting.pl.adoc
@@ -342,7 +342,7 @@ Możesz zrobić dowiązanie w katalogu _język/autoload_ jeśli chcesz automatyc
 Na przykład dla Pythona:
 
 ----
-$ cd ~/.weechat/python/autoload
+$ cd ~/.local/share/weechat/python/autoload
 $ ln -s ../skrypt.py
 ----
 
@@ -1375,10 +1375,11 @@ weechat.prnt("", "Version %s" % weechat.info_get("version", ""))
 [[infos_other]]
 ==== Inne informacje
 
+// TRANSLATION MISSING
 [source,python]
 ----
-# katalog domowy WeeChat, na przykład: "/home/xxxx/.weechat"
-weechat.prnt("", "Katalog domowy WeeChat: %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", ""))
 
 # nieaktywność klawiatury
 weechat.prnt("", "Nieaktywny od %s sekund" % weechat.info_get("inactivity", ""))
diff --git a/doc/pl/weechat_user.pl.adoc b/doc/pl/weechat_user.pl.adoc
index 578bb5f43..1d79767d2 100644
--- a/doc/pl/weechat_user.pl.adoc
+++ b/doc/pl/weechat_user.pl.adoc
@@ -473,10 +473,10 @@ _/var/lib/systemd/coredump_ and you must use the command `coredumpctl` to read i
 For more information, see this wiki page: https://wiki.archlinux.org/index.php/Core_dump
 
 Na przykład jeśli _weechat_ jest zainstalowany w _/usr/bin/_ i plik _core_
-znajduje się w _/home/xxx/_, uruchom gdb za pomocą tej komendy:
+znajduje się w _/home/user/_, uruchom gdb za pomocą tej komendy:
 
 ----
-gdb /usr/bin/weechat /home/xxx/core
+gdb /usr/bin/weechat /home/user/core
 ----
 
 Następnie pod gdb użyj komendy `bt full`, aby wyświetlić log.
@@ -563,8 +563,8 @@ to upgrade the kernel or to move your WeeChat to another machine:
 ----
 
 This saves the current state in `*.upgrade` files. You can then either reboot
-or move the whole directory `~/.weechat` to another machine, and restart
-WeeChat later with this command:
+or move the whole WeeChat directories (config, data, cache) to another machine,
+and restart WeeChat later with this command:
 
 ----
 $ weechat --upgrade
@@ -597,7 +597,7 @@ WeeChat has an automatic upgrade of configuration files (`*.conf`):
 Example of warning when an option has been removed:
 
 ----
-=!= Ostrzeżenie: /home/xxx/.weechat/sec.conf, linia 15: nieznana opcja dla sekcji "crypt": passphrase_file = ""
+=!= Ostrzeżenie: /home/user/.config/weechat/sec.conf, linia 15: nieznana opcja dla sekcji "crypt": passphrase_file = ""
 ----
 
 That means the option `sec.crypt.passphrase_file` has been removed, and you
@@ -617,7 +617,7 @@ $ weechat
 ----
 
 Podczas pierwszego uruchomienia WeeChat tworzone są domyślne pliki konfiguracyjne
-w  _~/.weechat_ z domyślnymi opcjami i wartościami
+w  _~/.config/weechat_ z domyślnymi opcjami i wartościami
 (zobacz <<files_and_directories,Pliki i foldery>>).
 
 ==== Argumenty linii poleceń
@@ -648,8 +648,28 @@ Niektóre zmienne śwodowiskowe są używane przez WeeChat o ile zostały zdefin
 [[files_and_directories]]
 === Pliki i foldery
 
-WeeChat zapisuje pliki konfiguracyjne i inne rzeczy domyślnie w folderze `~/.weechat`. +
-Pliki te są tworzone z domyślnymi wartościami przy pierwszym uruchomieniu WeeChat.
+// 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]]
 ==== Katalogi WeeChat
@@ -658,29 +678,39 @@ Katalogi używane przez WeeChat to:
 
 [width="100%",cols="1m,3",options="header"]
 |===
-| Ścieżka/plik      | Opis
-| ~/.weechat/       | Katalog domowy WeeChat (można go zmienić, zobacz <<running_weechat,Uruchamianie WeeChat>>).
-|    logs/          | Pliki z logami (jeden na bufor).
-|    python/        | Skrypty pythonowe.
-|       autoload/   | Skrypty pythonowe automatycznie ładowane przy starcie ^(1)^.
-|    perl/          | Skrypty perlowe.
-|       autoload/   | Skrypty perlowe automatycznie ładowane przy starcie ^(1)^.
-|    ruby/          | Skrypty ruby.
-|       autoload/   | Skrypty ruby automatycznie ładowane przy starcie ^(1)^.
-|    lua/           | Skrypty lua.
-|       autoload/   | Skrypty lua automatycznie ładowane przy starcie ^(1)^.
-|    tcl/           | Skrypty tcl.
-|       autoload/   | Skrypty tcl automatycznie ładowane przy starcie ^(1)^.
-|    guile/         | Skrypty guile.
-|       autoload/   | skrypry guile automatycznie ładowane przy starcie ^(1)^.
-|    javascript/    | Skrypty JavaScript.
-|       autoload/   | Skrypty JavaScript automatycznie ładowane przy starcie ^(1)^.
-|    php/           | Skrypty PHP.
-|       autoload/   | Skrypty PHP automatycznie ładowane przy starcie ^(1)^.
+// TRANSLATION MISSING
+| Path ^(1)^              | Opis
+// 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/                | Pliki z logami (jeden na bufor).
+|    python/              | Skrypty pythonowe.
+|       autoload/         | Skrypty pythonowe automatycznie ładowane przy starcie ^(2)^.
+|    perl/                | Skrypty perlowe.
+|       autoload/         | Skrypty perlowe automatycznie ładowane przy starcie ^(2)^.
+|    ruby/                | Skrypty ruby.
+|       autoload/         | Skrypty ruby automatycznie ładowane przy starcie ^(2)^.
+|    lua/                 | Skrypty lua.
+|       autoload/         | Skrypty lua automatycznie ładowane przy starcie ^(2)^.
+|    tcl/                 | Skrypty tcl.
+|       autoload/         | Skrypty tcl automatycznie ładowane przy starcie ^(2)^.
+|    guile/               | Skrypty guile.
+|       autoload/         | Skrypry guile automatycznie ładowane przy starcie ^(2)^.
+|    javascript/          | Skrypty JavaScript.
+|       autoload/         | Skrypty JavaScript automatycznie ładowane przy starcie ^(2)^.
+|    php/                 | Skrypty PHP.
+|       autoload/         | Skrypty PHP automatycznie ładowane przy starcie ^(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)^ Ten folder zawiera przewazine linki symboliczne do plików w folderze nadrzędnym.
+^(1)^ XDG directories may be different according to your environment variables `XDG_*`. +
+^(2)^ Ten folder zawiera przewazine linki symboliczne do plików w folderze nadrzędnym.
 
 [[weechat_files]]
 ==== Pliki WeeChat
@@ -2738,7 +2768,9 @@ Możesz zdalnie kontrolować WeeChat, poprzez wysyłanie komend lub tekstu do
 kolejki FIFO (jeśli opcja "fifo.file.enabled" jest włączona, domyślnie jest
 włączona).
 
-Kolejka FIFO znajduje się w katalogu _~/.weechat/_ i domyślnie nazywa się _weechat_fifo_.
+// TRANSLATION MISSING
+The FIFO pipe is located in WeeChat runtime directory and is called
+_weechat_fifo_ by default.
 
 Składnia dla komend/tekstu przekazywanego do kolejki FIFO wygląda następująco:
 
@@ -2752,26 +2784,26 @@ Kilka przykładów:
 * Zmiana nicka na serwerze IRC freenode na "newnick":
 
 ----
-$ echo 'irc.server.freenode */nick newnick' >~/.weechat/weechat_fifo
+$ echo 'irc.server.freenode */nick newnick' >/run/user/1000/weechat/weechat_fifo
 ----
 
 * Wysłanie wiadomości na kanał IRC #weechat:
 
 ----
-$ echo 'irc.freenode.#weechat *hello!' >~/.weechat/weechat_fifo
+$ echo 'irc.freenode.#weechat *hello!' >/run/user/1000/weechat/weechat_fifo
 ----
 
 * Wysłanie wiadomości do obecnego bufora:
 
 ----
-$ echo '*hello!' >~/.weechat/weechat_fifo
+$ echo '*hello!' >/run/user/1000/weechat/weechat_fifo
 ----
 
 * Wysłanie dwóch komend do wyładowania/przeładowania skryptów Python (należy
   oddzielić je za pomocą "\n"):
 
 ----
-$ 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]]
@@ -3416,7 +3448,7 @@ na przykład:
 Spowoduje powstanie następującej struktury:
 
 ....
-~/.weechat
+~/.local/share/weechat
 └── logs
     ├── 2010
     │   ├── 11
@@ -3446,7 +3478,7 @@ każdego kanału:
 Spowoduje powstanie następującej struktury:
 
 ....
-~/.weechat
+~/.local/share/weechat
 └── logs
     └── irc
         ├── freenode
@@ -3652,16 +3684,18 @@ Adres URL musi się zawsze kończyć "/weechat" (dla protokołów _irc_ i _weech
 [[relay_unix_socket]]
 ==== Sockety UNIXowe
 
-Używając opcji protokołu "unix" razem z komendą `/relay`, można nasłuchiwać dowolnego 
+Używając opcji protokołu "unix" razem z komendą `/relay`, można nasłuchiwać dowolnego
 protokołu za pomocą socketu UNIXowego w podanej ścieżce. Na przykład:
 
 ----
-/relay add unix.weechat %h/relay_socket
+/relay add unix.weechat ${weechat_runtime_dir}/relay_socket
 ----
 
 Pozwala to na połączenia od klientów za pomocą protokołu weechat do
-_~/.weechat/relay_socket_. Jest to przydatne zwłaszcza jeśli chcemy tunelować klienty 
-przez SSH, w przypadku, kiedy inne porty nie moga być otwierane. Za pomocą OpenSSH:
+_/run/user/1000/weechat/relay_socket_. Jest to przydatne zwłaszcza jeśli chcemy
+tunelować klienty przez SSH, w przypadku, kiedy inne porty nie moga być otwierane.
+
+Za pomocą OpenSSH:
 
 ----
 $ ssh -L 9000:.weechat/relay_socket user@hostname