Improve function documentation with text from XDG BDS spec

* lisp/xdg.el (xdg-config-home, xdg-cache-home, xdg-data-home)
(xdg-runtime-dir, xdg-config-dirs, xdg-data-dirs): Copy in the
text from the XDG Base Directory Specification to better explain
what these functions return.
This commit is contained in:
Stefan Kangas 2021-10-26 23:17:29 +02:00
parent 284c77eeb6
commit e45b3fc521

View file

@ -50,30 +50,84 @@
,env))))
(defun xdg-config-home ()
"Return the base directory for user specific configuration files."
"Return the base directory for user specific configuration files.
According to the XDG Base Directory Specification version
0.8 (8th May 2021):
\"$XDG_CONFIG_HOME defines the base directory relative to
which user-specific configuration files should be stored.
If $XDG_CONFIG_HOME is either not set or empty, a default
equal to $HOME/.config should be used.\""
(xdg--dir-home "XDG_CONFIG_HOME" "~/.config"))
(defun xdg-cache-home ()
"Return the base directory for user specific cache files."
"Return the base directory for user specific cache files.
According to the XDG Base Directory Specification version
0.8 (8th May 2021):
\"$XDG_CACHE_HOME defines the base directory relative to
which user-specific non-essential data files should be
stored. If $XDG_CACHE_HOME is either not set or empty, a
default equal to $HOME/.cache should be used.\""
(xdg--dir-home "XDG_CACHE_HOME" "~/.cache"))
(defun xdg-data-home ()
"Return the base directory for user specific data files."
"Return the base directory for user specific data files.
According to the XDG Base Directory Specification version
0.8 (8th May 2021):
\"$XDG_DATA_HOME defines the base directory relative to which
user-specific data files should be stored. If $XDG_DATA_HOME is
either not set or empty, a default equal to $HOME/.local/share
should be used.\""
(xdg--dir-home "XDG_DATA_HOME" "~/.local/share"))
(defun xdg-runtime-dir ()
"Return the value of $XDG_RUNTIME_DIR."
"Return the value of $XDG_RUNTIME_DIR.
According to the XDG Base Directory Specification version
0.8 (8th May 2021):
\"$XDG_RUNTIME_DIR defines the base directory relative to
which user-specific non-essential runtime files and other
file objects (such as sockets, named pipes, ...) should be
stored.\""
(getenv "XDG_RUNTIME_DIR"))
(defun xdg-config-dirs ()
"Return the config directory search path as a list."
"Return the config directory search path as a list.
According to the XDG Base Directory Specification version
0.8 (8th May 2021):
\"$XDG_CONFIG_DIRS defines the preference-ordered set of base
directories to search for configuration files in addition to
the $XDG_CONFIG_HOME base directory. The directories in
$XDG_CONFIG_DIRS should be seperated with a colon ':'.
\"If $XDG_CONFIG_DIRS is either not set or empty, a value equal to
/etc/xdg should be used.\""
(let ((env (getenv "XDG_CONFIG_DIRS")))
(if (or (null env) (string= env ""))
'("/etc/xdg")
(parse-colon-path env))))
(defun xdg-data-dirs ()
"Return the data directory search path as a list."
"Return the data directory search path as a list.
According to the XDG Base Directory Specification version
0.8 (8th May 2021):
\"$XDG_DATA_DIRS defines the preference-ordered set of base
directories to search for data files in addition to the
$XDG_DATA_HOME base directory. The directories in
$XDG_DATA_DIRS should be seperated with a colon ':'.
\"If $XDG_DATA_DIRS is either not set or empty, a value equal
to /usr/local/share/:/usr/share/ should be used.\""
(let ((env (getenv "XDG_DATA_DIRS")))
(if (or (null env) (string= env ""))
'("/usr/local/share/" "/usr/share/")