Finish documenting the use of XDG_CONFIG_HOME and XDG_DATA_HOME

Introduced by:
a03e2e4a ("use xdg dirs for config & data", 2017-10-17)

Dockerfile

@@ -1,7 +1,7 @@
 # Use the maximum Python version tested
 FROM python:3.10-slim
 
-# linkchecker creates ~/.linkchecker/ (700) containing linkcheckerrc et al
+# linkchecker creates $XDG_CONFIG_HOME/linkchecker/ (700) containing linkcheckerrc et al
 ENV HOME /tmp
 
 # Enables access to local files when run with -v "$PWD":/mnt

doc/examples/check_failures.sh

@@ -17,7 +17,7 @@
 #
 # This script is intended to be run daily from cron. It complains when
 # URLs fail for at least a number of script runs.
-LOGFILE="$HOME/.linkchecker/failures"
+LOGFILE="$XDG_DATA_HOME/linkchecker/failures"
 linkchecker -Ffailures "$@"
 # this awk script complains if urls fail for at least two script runs
 [ -r $LOGFILE ] && awk '/^[[:digit:]]+/ {if ($1 > 1) printf "URL %s failed for %d days.", $2, $1; }' $LOGFILE

doc/examples/check_urls.sh

@@ -25,7 +25,7 @@
 #    10 4 * * * $HOME/bin/check_urls.sh --cron http://mysite.com/
 #
 # To only get a mail when errors are encountered, you have to disable
-# the intro and outro output in a config file $HOME/.linkchecker/cron:
+# the intro and outro output in a config file $XDG_CONFIG_HOME/linkchecker/cron:
 #
 #    [text]
 #    parts=realurl,result,extern,base,name,parenturl,info,warning,url
@@ -39,7 +39,7 @@ else
     echo "linkchecker binary not found"
     exit 1
 fi
-LCOPTS="-f$HOME/.linkchecker/cron"
+LCOPTS="-f$XDG_CONFIG_HOME/linkchecker/cron"
 if [ "$1" = "--cron" ]; then
     shift
     LCOPTS="$LCOPTS --no-status"

doc/src/conf.py

@@ -93,4 +93,4 @@ sitemap_url_scheme = "{link}"
 
 import linkcheck.logger
 linkcheck.logger.failures.FailuresLogger.LoggerArgs = {
-    'filename': '~/.linkchecker/failures'}
+    'filename': '$XDG_DATA_HOME/linkchecker/failures'}

doc/src/man/linkchecker.rst

@@ -86,7 +86,7 @@ General options
 .. option:: -f FILENAME, --config=FILENAME
 
     Use FILENAME as configuration file. By default LinkChecker uses
-    ~/.linkchecker/linkcheckerrc.
+    $XDG_CONFIG_HOME/linkchecker/linkcheckerrc.
 
 .. option:: -h, --help
 
@@ -118,7 +118,7 @@ URL checking results
 .. option:: -F TYPE[/ENCODING][/FILENAME], --file-output=TYPE[/ENCODING][/FILENAME]
 
     Output to a file linkchecker-out.TYPE,
-    $HOME/.linkchecker/failures for the failures output type, or
+    $XDG_DATA_HOME/linkchecker/failures for the failures output type, or
     FILENAME if specified. The ENCODING specifies the output
     encoding, the default is that of your locale. Valid encodings are
     listed at
@@ -279,7 +279,7 @@ outputting a sitemap graph format.
     script to create the initial SQL table is included as create.sql.
 **failures**
     Suitable for cron jobs. Logs the check result into a file
-    **~/.linkchecker/failures** which only contains entries with
+    **$XDG_DATA_HOME/linkchecker/failures** which only contains entries with
     invalid URLs and the number of times they have failed.
 **none**
     Logs nothing. Suitable for debugging or checking the exit code.
@@ -527,9 +527,9 @@ This might slow down the program or even the whole system.
 FILES
 -----
 
-**~/.linkchecker/linkcheckerrc** - default configuration file
+**$XDG_CONFIG_HOME/linkchecker/linkcheckerrc** - default configuration file
 
-**~/.linkchecker/failures** - default failures logger output filename
+**$XDG_DATA_HOME/linkchecker/failures** - default failures logger output filename
 
 **linkchecker-out.**\ *TYPE* - default logger file output name
 

doc/src/man/linkcheckerrc.rst

@@ -8,8 +8,9 @@ DESCRIPTION
 
 **linkcheckerrc** is the configuration file for LinkChecker. The file is
 written in an INI-style format.
-The default file location is **~/.linkchecker/linkcheckerrc** on Unix,
-**%HOMEPATH%\\.linkchecker\\linkcheckerrc** on Windows systems.
+The default file location is **$XDG_CONFIG_HOME/linkchecker/linkcheckerrc**
+or else **~/.config/linkchecker/linkcheckerrc** on Unix,
+**%HOMEPATH%\\.config\\linkchecker\\linkcheckerrc** on Windows systems.
 
 SETTINGS
 --------
@@ -166,7 +167,7 @@ URL checking results
 
 **fileoutput=**\ *TYPE*\ [**,**\ *TYPE*...]
     Output to a file **linkchecker-out.**\ *TYPE*, or
-    **$HOME/.linkchecker/failures** for the **failures** output type.
+    **$XDG_DATA_HOME/linkchecker/failures** for the **failures** output type.
     Valid file output types are **text**, **html**, **sql**, **csv**,
     **gml**, **dot**, **xml**, **none** or **failures**. Default is no
     file output. The various output types are documented below. Note

linkcheck/command/arg_parser.py

@@ -165,8 +165,8 @@ sql     Log check result as SQL script with INSERT commands. An example
         script to create the initial SQL table is included as create.sql.
 failures
         Suitable for cron jobs. Logs the check result into a file
-        ~/.linkchecker/failures which only contains entries with invalid
-        URLs and the number of times they have failed.
+        $XDG_DATA_HOME/linkchecker/failures which only contains entries with
+        invalid URLs and the number of times they have failed.
 none    Logs nothing. Suitable for debugging or checking the exit code.
 """
 )
@@ -219,8 +219,8 @@ class ArgParser(LCArgumentParser):
             metavar="FILENAME",
             help=_(
                 "Use FILENAME as configuration file. Per default LinkChecker uses\n"
-                "~/.linkchecker/linkcheckerrc (under Windows\n"
-                "%%HOMEPATH%%\\.linkchecker\\linkcheckerrc)."
+                "$XDG_CONFIG_HOME/linkchecker/linkcheckerrc (under Windows\n"
+                "%%HOMEPATH%%\\.config\\linkchecker\\linkcheckerrc)."
             ),
         )
         group.add_argument(
@@ -273,7 +273,7 @@ class ArgParser(LCArgumentParser):
             dest="fileoutput",
             metavar="TYPE[/ENCODING[/FILENAME]]",
             help=_(
-                "Output to a file linkchecker-out.TYPE, $HOME/.linkchecker/failures for\n"
+                "Output to a file linkchecker-out.TYPE, $XDG_DATA_HOME/linkchecker/failures for\n"
                 "'failures' output, or FILENAME if specified.\n"
                 "The ENCODING specifies the output encoding, the default is that of your\n"
                 "locale.\n"

linkcheck/configuration/__init__.py

@@ -324,8 +324,9 @@ class Configuration(dict):
 
 def get_user_data():
     """Get the user data folder.
-    Returns "~/.linkchecker/" if this folder exists, \
-    "$XDG_DATA_HOME/linkchecker" if it does not.
+    Returns "~/.linkchecker/" if this folder exists,
+    "$XDG_DATA_HOME/linkchecker" if $XDG_DATA_HOME is set,
+    else "~/.local/share/linkchecker".
     @rtype string
     """
     homedotdir = normpath("~/.linkchecker/")
@@ -339,9 +340,10 @@ def get_user_data():
 
 def get_plugin_folders():
     """Get linkchecker plugin folders. Default is
-    "$XDG_DATA_HOME/linkchecker/plugins/". "~/.linkchecker/plugins/" is also
-    supported for backwards compatibility, and is used if both directories
-    exist."""
+    "$XDG_DATA_HOME/linkchecker/plugins/" if $XDG_DATA_HOME is set, else
+    "~/.local/share/linkchecker/plugins/".
+    "~/.linkchecker/plugins/" is also
+    supported for backwards compatibility, and is used if it exists."""
     folders = []
     defaultfolder = os.path.join(get_user_data(), "plugins")
     if not os.path.exists(defaultfolder):

linkcheck/data/linkcheckerrc

@@ -105,7 +105,7 @@
 
 # failures logger
 [failures]
-#filename=~/.linkchecker/failures
+#filename=$XDG_DATA_HOME/linkchecker/failures
 
 # custom xml logger
 [xml]