From 10f3d330414d211449ffbc2ca4186d2df8ccd003 Mon Sep 17 00:00:00 2001 From: Chris Mayo Date: Tue, 23 Aug 2022 19:21:53 +0100 Subject: [PATCH] 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 | 2 +- doc/examples/check_failures.sh | 2 +- doc/examples/check_urls.sh | 4 ++-- doc/src/conf.py | 2 +- doc/src/man/linkchecker.rst | 10 +++++----- doc/src/man/linkcheckerrc.rst | 7 ++++--- linkcheck/command/arg_parser.py | 10 +++++----- linkcheck/configuration/__init__.py | 12 +++++++----- linkcheck/data/linkcheckerrc | 2 +- 9 files changed, 27 insertions(+), 24 deletions(-) diff --git a/Dockerfile b/Dockerfile index 4108c3ae..90a2a259 100644 --- a/Dockerfile +++ b/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 diff --git a/doc/examples/check_failures.sh b/doc/examples/check_failures.sh index c59eb192..2b65f146 100755 --- a/doc/examples/check_failures.sh +++ b/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 diff --git a/doc/examples/check_urls.sh b/doc/examples/check_urls.sh index d1f58af6..43e38a64 100755 --- a/doc/examples/check_urls.sh +++ b/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" diff --git a/doc/src/conf.py b/doc/src/conf.py index 733dcf2b..0476dcdb 100644 --- a/doc/src/conf.py +++ b/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'} diff --git a/doc/src/man/linkchecker.rst b/doc/src/man/linkchecker.rst index 1c635947..e3fb8a20 100644 --- a/doc/src/man/linkchecker.rst +++ b/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 diff --git a/doc/src/man/linkcheckerrc.rst b/doc/src/man/linkcheckerrc.rst index be8c4f39..d3b311e4 100644 --- a/doc/src/man/linkcheckerrc.rst +++ b/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 diff --git a/linkcheck/command/arg_parser.py b/linkcheck/command/arg_parser.py index 672dd242..0f1fa291 100644 --- a/linkcheck/command/arg_parser.py +++ b/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" diff --git a/linkcheck/configuration/__init__.py b/linkcheck/configuration/__init__.py index 7603a2f4..73041395 100644 --- a/linkcheck/configuration/__init__.py +++ b/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): diff --git a/linkcheck/data/linkcheckerrc b/linkcheck/data/linkcheckerrc index 918d686e..d468f50e 100644 --- a/linkcheck/data/linkcheckerrc +++ b/linkcheck/data/linkcheckerrc @@ -105,7 +105,7 @@ # failures logger [failures] -#filename=~/.linkchecker/failures +#filename=$XDG_DATA_HOME/linkchecker/failures # custom xml logger [xml]