summaryrefslogtreecommitdiff
path: root/scripts
diff options
context:
space:
mode:
Diffstat (limited to 'scripts')
-rw-r--r--scripts/Makefile.in7
-rw-r--r--scripts/README.md4
-rw-r--r--scripts/desc/xdg-copy.xml9
-rw-r--r--scripts/desc/xdg-desktop-icon.xml4
-rw-r--r--scripts/desc/xdg-desktop-menu.xml3
-rw-r--r--scripts/desc/xdg-email.xml4
-rw-r--r--scripts/desc/xdg-file-dialog.xml9
-rw-r--r--scripts/desc/xdg-icon-resource.xml11
-rw-r--r--scripts/desc/xdg-mime.xml9
-rw-r--r--scripts/desc/xdg-open.xml21
-rw-r--r--scripts/desc/xdg-realpath.xml7
-rw-r--r--scripts/desc/xdg-screensaver.xml7
-rw-r--r--scripts/desc/xdg-settings.xml3
-rw-r--r--scripts/desc/xdg-su.xml3
-rw-r--r--scripts/desc/xdg-terminal.xml9
-rw-r--r--scripts/desc/xdg-utils-common.xml230
-rw-r--r--scripts/man/.gitignore2
-rw-r--r--scripts/xdg-email.in2
-rw-r--r--scripts/xdg-icon-resource.in34
-rw-r--r--scripts/xdg-mime.in17
-rw-r--r--scripts/xdg-realpath.in14
-rw-r--r--scripts/xdg-screensaver.in11
-rwxr-xr-xscripts/xdg-settings.in65
-rw-r--r--scripts/xdg-utils-common.in79
24 files changed, 494 insertions, 70 deletions
diff --git a/scripts/Makefile.in b/scripts/Makefile.in
index 7939a4e..c1c27ce 100644
--- a/scripts/Makefile.in
+++ b/scripts/Makefile.in
@@ -20,6 +20,7 @@ SCRIPTS = \
xdg-icon-resource \
xdg-open \
xdg-email \
+ xdg-realpath \
xdg-screensaver \
xdg-settings
# xdg-su
@@ -27,7 +28,7 @@ SCRIPTS = \
# xdg-file-dialog
# xdg-terminal
-MANPAGES= $(SCRIPTS:%=man/%.1)
+MANPAGES= $(SCRIPTS:%=man/%.1) man/xdg-utils-common.7
WEBPAGES= $(SCRIPTS:%=html/%.html)
XMLFILES= $(SCRIPTS:%=desc/%.xml)
@@ -91,6 +92,7 @@ xdg-desktop-icon: xdg-desktop-icon.in xdg-utils-common.in
xdg-email: xdg-email.in xdg-utils-common.in
xdg-mime: xdg-mime.in xdg-utils-common.in
xdg-open: xdg-open.in xdg-utils-common.in
+xdg-realpath: xdg-realpath.in xdg-utils-common.in
xdg-screensaver: xdg-screensaver.in xdg-utils-common.in
xdg-settings: xdg-settings.in xdg-utils-common.in
xdg-icon-resource: xdg-icon-resource.in xdg-utils-common.in
@@ -103,6 +105,9 @@ xdg-terminal: xdg-terminal.in xdg-utils-common.in
man/%.1: desc/%.xml
(cd man;$(XMLTO) man ../$<)
+man/%.7: desc/%.xml
+ (cd man;$(XMLTO) man ../$<)
+
html/index.html: $(XMLFILES)
(cat html/index.html.pre; \
xsltproc xsl/refentry2htmlindex.xsl $(XMLFILES); \
diff --git a/scripts/README.md b/scripts/README.md
index eb41e03..24088ab 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -49,3 +49,7 @@ Replace the lines …
]>
```
+For spellchecking one can use the following command:
+```sh
+LANG=en_US aspell --mode=sgml check desc/<file>.xml
+```
diff --git a/scripts/desc/xdg-copy.xml b/scripts/desc/xdg-copy.xml
index e3f5493..1e8e4d0 100644
--- a/scripts/desc/xdg-copy.xml
+++ b/scripts/desc/xdg-copy.xml
@@ -137,6 +137,15 @@
</varlistentry>
</variablelist>
</refsect1>
+
+ <refsect1 id="seealso">
+ <title>See Also</title>
+ <para><citerefentry><refentrytitle>xdg-utils-common</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+
<refsect1 id="examples">
<title>Examples</title>
<para>
diff --git a/scripts/desc/xdg-desktop-icon.xml b/scripts/desc/xdg-desktop-icon.xml
index 273045d..0805cf2 100644
--- a/scripts/desc/xdg-desktop-icon.xml
+++ b/scripts/desc/xdg-desktop-icon.xml
@@ -317,6 +317,10 @@
<manvolnum>1</manvolnum>
</citerefentry>
</para>
+ <para><citerefentry><refentrytitle>xdg-utils-common</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </para>
</refsect1>
<refsect1 id="examples">
<title>Examples</title>
diff --git a/scripts/desc/xdg-desktop-menu.xml b/scripts/desc/xdg-desktop-menu.xml
index 6919ff9..6d86f04 100644
--- a/scripts/desc/xdg-desktop-menu.xml
+++ b/scripts/desc/xdg-desktop-menu.xml
@@ -538,6 +538,9 @@
<citerefentry><refentrytitle>xdg-mime</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
+ <citerefentry><refentrytitle>xdg-utils-common</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>,
<ulink url="http://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/">Desktop entry specification</ulink>,
<ulink url="http://www.freedesktop.org/wiki/Specifications/menu-spec/">Desktop menu specification</ulink>
</para>
diff --git a/scripts/desc/xdg-email.xml b/scripts/desc/xdg-email.xml
index 3abea2a..ac94f1b 100644
--- a/scripts/desc/xdg-email.xml
+++ b/scripts/desc/xdg-email.xml
@@ -257,6 +257,10 @@
<refentrytitle>xdg-mime</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
+ <citerefentry>
+ <refentrytitle>xdg-utils-common</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>,
<ulink url="http://www.freedesktop.org/wiki/Specifications/mime-apps-spec/">MIME applications associations specification</ulink>,
<ulink url="https://tools.ietf.org/html/rfc6068">RFC 6068 - The 'mailto' URI Scheme</ulink>
</para>
diff --git a/scripts/desc/xdg-file-dialog.xml b/scripts/desc/xdg-file-dialog.xml
index 3ca5cdd..bf4ac56 100644
--- a/scripts/desc/xdg-file-dialog.xml
+++ b/scripts/desc/xdg-file-dialog.xml
@@ -204,6 +204,15 @@
</varlistentry>
</variablelist>
</refsect1>
+
+ <refsect1 id="seealso">
+ <title>See Also</title>
+ <para><citerefentry><refentrytitle>xdg-utils-common</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+
<refsect1 id="examples">
<title>Examples</title>
<para>
diff --git a/scripts/desc/xdg-icon-resource.xml b/scripts/desc/xdg-icon-resource.xml
index 8dae3f6..0094174 100644
--- a/scripts/desc/xdg-icon-resource.xml
+++ b/scripts/desc/xdg-icon-resource.xml
@@ -83,8 +83,8 @@
The desktop icon system identifies icons by name. Depending on the
required size, the choice of icon theme and the context in which the
icon is used, the desktop icon system locates an appropriate
- icon resource to depict an icon. Icon resources can be XPM files or
- PNG files.
+ icon resource to depict an icon. Icon resources can be XPM files,
+ PNG files, or SVG files.
</para>
<para>
The desktop icon system works according to the
@@ -105,8 +105,8 @@
Icon names do not have an extension.
If <replaceable>icon-name</replaceable> is not provided the name is
derived from <replaceable>icon-file</replaceable>.
- The icon file must have
- <emphasis>.png</emphasis> or <emphasis>.xpm</emphasis>
+ The icon file must have <emphasis>.png</emphasis>,
+ <emphasis>.svg</emphasis>, or <emphasis>.xpm</emphasis>
as extension. If a corresponding <emphasis>.icon</emphasis>
file exists in the same location as <replaceable>icon-file</replaceable>
it will be installed as well.
@@ -349,6 +349,9 @@
<citerefentry><refentrytitle>xdg-mime</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
+ <citerefentry><refentrytitle>xdg-utils-common</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>,
<ulink url="http://www.freedesktop.org/wiki/Specifications/icon-theme-spec/">Icon theme specification</ulink>
</para>
</refsect1>
diff --git a/scripts/desc/xdg-mime.xml b/scripts/desc/xdg-mime.xml
index f3eba17..d2fdc44 100644
--- a/scripts/desc/xdg-mime.xml
+++ b/scripts/desc/xdg-mime.xml
@@ -83,7 +83,7 @@ and adding descriptions for new file types</refpurpose>
<title>Commands</title>
<variablelist>
<varlistentry>
- <term>query file</term>
+ <term>query filetype</term>
<listitem>
<simpara>
Returns the file type of <replaceable>FILE</replaceable> in the form of a MIME type.
@@ -96,8 +96,8 @@ and adding descriptions for new file types</refpurpose>
<listitem><para>Prefix known relative filepaths with a <quote>./</quote>. For example using <code>sed -E 's|^[^/]|./\0|'</code> as a preprocessor.</para></listitem>
</itemizedlist>
<simpara>
- The <emphasis>query file</emphasis> option is for use inside a desktop session only.
- It is not recommended to use xdg-mime query file as root.
+ The <emphasis>query filetype</emphasis> option is for use inside a desktop session only.
+ It is not recommended to use xdg-mime query filetype as root.
</simpara>
</listitem>
</varlistentry>
@@ -349,6 +349,9 @@ and adding descriptions for new file types</refpurpose>
<citerefentry><refentrytitle>xdg-desktop-menu</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
+ <citerefentry><refentrytitle>xdg-utils-common</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>,
<ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec/">Shared MIME database specification</ulink>,
<ulink url="http://www.freedesktop.org/wiki/Specifications/mime-apps-spec/">MIME applications associations specification</ulink>
</para>
diff --git a/scripts/desc/xdg-open.xml b/scripts/desc/xdg-open.xml
index 906d44f..aa2f05a 100644
--- a/scripts/desc/xdg-open.xml
+++ b/scripts/desc/xdg-open.xml
@@ -148,6 +148,24 @@
In case of success the process launched from the .desktop file will not be forked off and therefore may result in xdg-open running for a very long time. This behaviour intentionally differs from most desktop specific openers to allow terminal based applications to run using the same terminal xdg-open was called from.
</para>
</refsect1>
+
+ <refsect1>
+ <title>Environment</title>
+ <para>xdg-open honors the following environment variables:</para>
+ <variablelist>
+ <varlistentry>
+ <term><envar>BROWSER</envar></term>
+ <listitem>
+ <para>May contain a command that is used to open a filepath or URL when no other appropriate opener was found. The Path or URL will be appended as the last argument.</para>
+ <para>No parsing beyond splitting arguments on space characters should be assumed. Quoting is not supported. Be careful with ':' and '%' characters.</para>
+ <para>The following two features are supported in xdg-open only, but not by other applications that make use of the <envar>BROWSER</envar> variable. Using them is no longer recommended.</para>
+ <para>This environment variable may contain a colon separated list of commands if one command fails the command after it will be tried.</para>
+ <para>When using <code>%s</code> as a placeholder the first instance of it will be replaced with the filepath or URL to be opened instead of appending it as the last argument.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
<refsect1 id="reporting-issues">
<title>Reporting Issues</title>
<para>
@@ -174,6 +192,9 @@
<citerefentry><refentrytitle>xdg-settings</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
+ <citerefentry><refentrytitle>xdg-utils-common</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>,
<ulink url="http://www.freedesktop.org/wiki/Specifications/mime-apps-spec/">MIME applications associations specification</ulink>
</para>
</refsect1>
diff --git a/scripts/desc/xdg-realpath.xml b/scripts/desc/xdg-realpath.xml
index 60a5b22..99e444a 100644
--- a/scripts/desc/xdg-realpath.xml
+++ b/scripts/desc/xdg-realpath.xml
@@ -70,6 +70,12 @@
<para>
It is strongly recommended to call xdg-realpath using the <option>--</option> option.
</para>
+ <para>
+ When using xdg-realpath with multiple files and one of the given paths leads directly or indirectly to a missing file a message will be printed to stdout and xdg-realpath will continue resolving until it has finished with all given paths. If at least one path does not resolve, it will return an exit code 2.
+ </para>
+ <para>
+ Unlike <command>realpath</command> or <command>readlink -f</command> xdg-realpath will error if one attempts to resolve a non-existing file in an existing directory. If such behavior is added in the future it will be behind a command line flag.
+ </para>
</refsect1>
<refsect1 id="options">
<title>Options</title>
@@ -182,6 +188,7 @@
<title>See Also</title>
<para><citerefentry><refentrytitle>realpath</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>readlink</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>xdg-utils-common</refentrytitle><manvolnum>7</manvolnum></citerefentry>
</para>
</refsect1>
<refsect1 id="examples">
diff --git a/scripts/desc/xdg-screensaver.xml b/scripts/desc/xdg-screensaver.xml
index 0dadf04..6213581 100644
--- a/scripts/desc/xdg-screensaver.xml
+++ b/scripts/desc/xdg-screensaver.xml
@@ -213,6 +213,13 @@
</varlistentry>
</variablelist>
</refsect1>
+ <refsect1 id="seealso">
+ <title>See Also</title>
+ <para><citerefentry><refentrytitle>xdg-utils-common</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
<refsect1 id="examples">
<title>Examples</title>
<para>
diff --git a/scripts/desc/xdg-settings.xml b/scripts/desc/xdg-settings.xml
index 255d712..ddfbbe8 100644
--- a/scripts/desc/xdg-settings.xml
+++ b/scripts/desc/xdg-settings.xml
@@ -173,6 +173,9 @@
<citerefentry><refentrytitle>xdg-open</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
+ <citerefentry><refentrytitle>xdg-utils-common</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>,
<ulink url="http://www.freedesktop.org/wiki/Specifications/mime-apps-spec/">MIME applications associations specification</ulink>
</para>
</refsect1>
diff --git a/scripts/desc/xdg-su.xml b/scripts/desc/xdg-su.xml
index b4e1b7e..c0ac472 100644
--- a/scripts/desc/xdg-su.xml
+++ b/scripts/desc/xdg-su.xml
@@ -160,6 +160,9 @@
<title>See Also</title>
<para><citerefentry><refentrytitle>su</refentrytitle>
<manvolnum>1</manvolnum>
+ </citerefentry>,
+ <citerefentry><refentrytitle>xdg-utils-common</refentrytitle>
+ <manvolnum>7</manvolnum>
</citerefentry>
</para>
</refsect1>
diff --git a/scripts/desc/xdg-terminal.xml b/scripts/desc/xdg-terminal.xml
index 4ed4d90..c736a37 100644
--- a/scripts/desc/xdg-terminal.xml
+++ b/scripts/desc/xdg-terminal.xml
@@ -119,6 +119,15 @@
</varlistentry>
</variablelist>
</refsect1>
+
+ <refsect1 id="seealso">
+ <title>See Also</title>
+ <para><citerefentry><refentrytitle>xdg-utils-common</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+
<refsect1 id="examples">
<title>Examples</title>
<para>
diff --git a/scripts/desc/xdg-utils-common.xml b/scripts/desc/xdg-utils-common.xml
new file mode 100644
index 0000000..ed54879
--- /dev/null
+++ b/scripts/desc/xdg-utils-common.xml
@@ -0,0 +1,230 @@
+<?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl"
+ href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<refentry id="xdg-utils-common">
+ <refentryinfo>
+ <title>xdg-utils Common Manual</title>
+ <copyright>
+ <year>2024-04-27</year>
+ </copyright>
+ <author>
+ <firstname>Slatian</firstname>
+ <address>
+ <email>baschdel+xdg-utils@disroot.org</email>
+ </address>
+ </author>
+ <releaseinfo>xdg-utils 1.2</releaseinfo>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>xdg-utils-common</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>xdg-utils-common</refname>
+ <refpurpose>Shared functionality of the xdg-utils scripts.</refpurpose>
+ </refnamediv>
+
+ <refsect1 id="description">
+ <title>Description</title>
+ <para>
+ The xdg-utils package is a set of scripts that provide basic desktop integration functions for any Free Desktop on Linux, the BSDs and even partially on MacOS and WSL.
+ </para>
+ <para>
+ Available xdg-utils are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <citerefentry>
+ <refentrytitle>xdg-desktop-icon</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <citerefentry>
+ <refentrytitle>xdg-desktop-menu</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <citerefentry>
+ <refentrytitle>xdg-email</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <citerefentry>
+ <refentrytitle>xdg-icon-resource</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <citerefentry>
+ <refentrytitle>xdg-mime</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <citerefentry>
+ <refentrytitle>xdg-open</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <citerefentry>
+ <refentrytitle>xdg-realpath</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <citerefentry>
+ <refentrytitle>xdg-screensaver</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <citerefentry>
+ <refentrytitle>xdg-settings</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ <para>
+ This manual describes mechanisms that are shared across all or multiple of the xdg-utils.
+ </para>
+ </refsect1>
+
+ <refsect1 id="exitcodes">
+ <title>Exit Codes</title>
+ <para>All xdg-utils share a common set of exit codes.</para>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem><simpara>Success.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>1</term>
+ <listitem><simpara>CLI Syntax error, malformed or missing arguments/options.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>2</term>
+ <listitem><simpara>A file specified on the CLI is missing.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>3</term>
+ <listitem><simpara>An external tool needed to carry out the operation was not found.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>4</term>
+ <listitem><simpara>An external tool used by the xdg-utils failed.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>5</term>
+ <listitem><simpara>Permission problem: A file specified on the CLI couldn't be read.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>6</term>
+ <listitem><simpara>Permission problem: A file specified on the CLI couldn't be written.</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+ <para>For debugging have a look at the environment variables and the tool specific manual.</para>
+ <para>Exit codes not documented here or in a tool specific manual can be considered bugs.</para>
+ </refsect1>
+
+ <refsect1 id="mechanisms">
+ <title>Mechanisms</title>
+ <para>This chapter will explain different mechanisms under the hood of the xdg-utils.</para>
+ <refsect2 id="detectde">
+ <title>Desktop Environment Detection (detectDE)</title>
+ <para>The xdg-utils often try to delegate tasks to desktop specific tools to make things work, be consistent with the desktops native applications and a slight performance gain over the shell scripts.</para>
+ <para>To achieve this, they try to figure out which environment they are in by evaluating <envar>XDG_CURRENT_DESKTOP</envar>, the output of <code>uname</code> and the existence of specific files.</para>
+ <para>Currently recognized desktop environments are:</para>
+ <itemizedlist>
+ <listitem><para><code>cinnamon</code></para></listitem>
+ <listitem><para><code>dde</code> (Deepin)</para></listitem>
+ <listitem><para><code>enlightenment</code></para></listitem>
+ <listitem><para><code>gnome3</code></para></listitem>
+ <listitem><para><code>kde</code></para></listitem>
+ <listitem><para><code>lxde</code></para></listitem>
+ <listitem><para><code>lxqt</code></para></listitem>
+ <listitem><para><code>mate</code></para></listitem>
+ <listitem><para><code>xfce</code></para></listitem>
+ </itemizedlist>
+ <para>Recognized environments that aren't directly related to a desktop are:</para>
+ <itemizedlist>
+ <listitem><para><code>cygwin</code></para></listitem>
+ <listitem><para><code>wsl</code></para></listitem>
+ <listitem><para><code>darwin</code></para></listitem>
+ <listitem><para><code>flatpak</code></para></listitem>
+ <listitem><para><code>generic</code></para></listitem>
+ </itemizedlist>
+ </refsect2>
+ <refsect2 id="realpath">
+ <title>Realpath</title>
+ <para>Turning a relative path into an absolute one in a shellscript seems simple. Until one realizes that the safe way to call gnu realpath is not compatible with busybox realpath and sometimes <code>readlink -f</code> is the appropriate tool.</para>
+ <para>While this mechanism is used by most xdg-utils it is documented in <citerefentry><refentrytitle>xdg-realpath</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
+ </refsect2>
+ </refsect1>
+
+ <refsect1 id="environment">
+ <title>Environment</title>
+ <para>These environment variables work across all xdg-utils and are mostly intended for debugging purposes. If you have to set these to work around a problem please file a bug report.</para>
+ <variablelist>
+ <varlistentry>
+ <term><envar>XDG_UTILS_DEBUG_LEVEL</envar></term>
+ <listitem>
+ <simpara>Integer in the range 1 to 4 to make the xdg-utils output an increasing amount of debug information.</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><envar>XDG_UTILS_INSTALL_MODE</envar></term>
+ <listitem>
+ <simpara>For tools that install something this can be set to either <code>user</code> or <code>system</code>.</simpara>
+ <para>See <citerefentry><refentrytitle>xdg-desktop-icon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>xdg-icon-resource</refentrytitle><manvolnum>1</manvolnum></citerefentry> and <citerefentry><refentrytitle>xdg-desktop-menu</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><envar>XDG_UTILS_REALPATH_BACKEND</envar></term>
+ <listitem>
+ <para>Which tool the xdg-utils will use to convert relative paths to absolute ones. Documented in <citerefentry><refentrytitle>xdg-realpath</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><envar>XDG_CURRENT_DESKTOP</envar></term>
+ <listitem>
+ <para>Used for identifying desktop is currently in use. See the <ulink url="https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#recognized-keys">Desktop Entry Specification</ulink> for more details.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1 id="reporting-issues">
+ <title>Reporting Issues</title>
+ <para>The xdg-utils combine multiple other tools that have had bug in the past, before reporting a bug please check if the bug is caused by a tool used in the xdg-utils. (When unsure please report it anyway) The tool specific manuals may contain hints on how to find out.</para>
+ <para>In case an issue specific to xdg-utils please report it to <uri>https://gitlab.freedesktop.org/xdg/xdg-utils/-/issues</uri> .</para>
+ <para>Please help the developers with information on how to reproduce the issue, it will increase the chance of a timely fix.</para>
+ <para>Have a patch? Great, but please don't forget to include information on what behavior you are trying to fix. The xdg-utils have a bad habit of disguising one problem as a different one.</para>
+ </refsect1>
+</refentry>
+
diff --git a/scripts/man/.gitignore b/scripts/man/.gitignore
index 82d9456..b65b742 100644
--- a/scripts/man/.gitignore
+++ b/scripts/man/.gitignore
@@ -7,4 +7,4 @@ xdg-open.1
xdg-realpath.1
xdg-screensaver.1
xdg-settings.1
-
+xdg-utils-common.7
diff --git a/scripts/xdg-email.in b/scripts/xdg-email.in
index 73898a4..4e3a5e8 100644
--- a/scripts/xdg-email.in
+++ b/scripts/xdg-email.in
@@ -99,7 +99,7 @@ open_kde()
--group "PROFILE_$profile" \
--key EmailClient \
| cut -d ' ' -f 1)"
- if [ -z "${client%%*.desktop}" ] && ! command -v "$client" >/dev/null 2>&1; then
+ if [ -n "$client" ] && [ -z "${client%%*.desktop}" ] && ! command -v "$client" >/dev/null 2>&1; then
client="$(desktop_file_to_binary "$client")"
fi
diff --git a/scripts/xdg-icon-resource.in b/scripts/xdg-icon-resource.in
index a108143..414cc2b 100644
--- a/scripts/xdg-icon-resource.in
+++ b/scripts/xdg-icon-resource.in
@@ -148,8 +148,8 @@ while [ $# -gt 0 ] ; do
if [ -z "$1" ] ; then
exit_failure_syntax "size argument missing for --size"
fi
- if echo "$1" | grep '[^0-9]' > /dev/null 2> /dev/null; then
- exit_failure_syntax "size argument must be numeric"
+ if ! echo "$1" | grep '^\(scalable\|[0-9]\+\)$' > /dev/null 2> /dev/null; then
+ exit_failure_syntax "size argument must be numeric or the word 'scalable'"
fi
size="$1"
shift
@@ -275,7 +275,12 @@ extension=
if [ -z "$size" ] ; then
exit_failure_syntax "the icon size must be specified with --size"
fi
-xdg_size_name="${size}x${size}"
+
+if [ "$size" = "scalable" ]; then
+ xdg_size_name="$size"
+else
+ xdg_size_name="${size}x${size}"
+fi
if [ x"$action" = x"install" ] ; then
case "$icon_file" in
@@ -285,17 +290,33 @@ if [ x"$action" = x"install" ] ; then
*.png)
extension="png"
;;
+ *.svg)
+ extension="svg"
+ ;;
*)
- exit_failure_syntax "icon file to install must be a *.png or *.xpm file"
+ exit_failure_syntax "icon file to install must be a *.png, *.svg, or *.xpm file"
;;
esac
fi
+if [ "$xdg_size_name" = "scalable" ]; then
+ if [ "$extension" = "png" ]; then
+ exit_failure_syntax "png icons cannot be scalable"
+ fi
+
+ if [ "$extension" = "xpm" ]; then
+ exit_failure_syntax "xpm icons cannot be scalable"
+ fi
+fi
+
if [ -n "$icon_name" ] ; then
case "$icon_name" in
*.png)
exit_failure_syntax "icon name should not include an extension"
;;
+ *.svg)
+ exit_failure_syntax "icon name should not include an extension"
+ ;;
*.xpm)
exit_failure_syntax "icon name should not include an extension"
;;
@@ -426,15 +447,16 @@ case "$action" in
uninstall)
for icon_dir in "$xdg_dir" "$dot_icon_dir"; do
[ -z "$icon_dir" ] && continue
- rm -f "$icon_dir/$icon_name.xpm" "$icon_dir/$icon_name.png"
+ rm -f "$icon_dir/$icon_name.xpm" "$icon_dir/$icon_name.png" "$icon_dir/$icon_name.svg"
rm -f "$icon_dir/$icon_icon_name"
if [ -n "$need_gnome_mime" ] ; then
rm -f "$icon_dir/gnome-mime-$icon_name.xpm"
rm -f "$icon_dir/gnome-mime-$icon_name.png"
+ rm -f "$icon_dir/gnome-mime-$icon_name.svg"
fi
done
if [ -n "$kde_dir" ] ; then
- rm -f "$kde_dir/$icon_name.xpm" "$kde_dir/$icon_name.png"
+ rm -f "$kde_dir/$icon_name.xpm" "$kde_dir/$icon_name.png" "$kde_dir/$icon_name.svg"
fi
;;
diff --git a/scripts/xdg-mime.in b/scripts/xdg-mime.in
index f9c6bae..0af03f1 100644
--- a/scripts/xdg-mime.in
+++ b/scripts/xdg-mime.in
@@ -167,7 +167,7 @@ make_default_kde()
vendor="$1"
mimetype="$2"
if [ "${KDE_SESSION_VERSION:-0}" -gt 4 ] ; then
- default_dir="$(qtpaths --writable-path ConfigLocation)"
+ default_dir="$(get_xdg_config_home)"
default_file="$default_dir/mimeapps.list"
elif [ x"$KDE_SESSION_VERSION" = x"4" ]; then
default_dir="$(kde4-config --path xdgdata-apps 2> /dev/null | cut -d ':' -f 1)"
@@ -294,10 +294,7 @@ make_default_generic()
# $1 is vendor-name.desktop
# $2 is mime/type
# Add $2=$1 to XDG_CONFIG_HOME/mimeapps.list
- #shellcheck disable=SC2153 # not misspelled
- xdg_config_home="$XDG_CONFIG_HOME"
- [ -n "$xdg_config_home" ] || xdg_config_home="$HOME/.config"
- default_file="$xdg_config_home/mimeapps.list"
+ default_file="$(get_xdg_config_home)/mimeapps.list"
if [ -L "$default_file" ]; then
out_file="$(xdg_realpath "$default_file")"
else
@@ -459,8 +456,7 @@ check_mimeapps_list()
defapp_generic()
{
MIME="$1"
- xdg_config_home="$XDG_CONFIG_HOME"
- [ -n "$xdg_config_home" ] || xdg_config_home="$HOME/.config"
+ xdg_config_home="$(get_xdg_config_home)"
#shellcheck disable=SC2153 # not misspelled
xdg_config_dirs="$XDG_CONFIG_DIRS"
[ -n "$xdg_config_dirs" ] || xdg_config_dirs="/etc/xdg"
@@ -654,6 +650,13 @@ if [ "$action" = "makedefault" ]; then
detectDE
+ binary="$(desktop_file_to_binary "$filename")"
+ if [ -z "$binary" ] ; then
+ echo "The given .desktop file doesn't exist or doesn't have an Exec key that points to a program."
+ echo "To get more information run with: XDG_UTILS_DEBUG_LEVEL=4 xdg-mime makedefault …" >&2
+ exit_failure_file_missing
+ fi
+
while [ $# -gt 0 ] ; do
case $1 in
-*)
diff --git a/scripts/xdg-realpath.in b/scripts/xdg-realpath.in
index 39d8c6c..2fd7155 100644
--- a/scripts/xdg-realpath.in
+++ b/scripts/xdg-realpath.in
@@ -33,10 +33,18 @@ set -e
past_double_hyphen=""
exit_with_missing_status=""
+run_realpath() {
+ if [ -e "$1" ] ; then
+ xdg_realpath "$1"
+ else
+ echo "@NAME@: $1: No such file or directory" >&2
+ exit_with_missing_status=y
+ fi
+}
+
while [ $# -gt 0 ] ; do
if [ -n "$past_double_hyphen" ] ; then
- [ -e "$1" ] || echo "@NAME@: $1: No such file or directory" >&2
- xdg_realpath "$1"
+ run_realpath "$1"
else
case "$1" in
--)
@@ -50,7 +58,7 @@ while [ $# -gt 0 ] ; do
exit_failure_syntax "Unknown option: '$1'"
;;
*)
- xdg_realpath "$1"
+ run_realpath "$1"
;;
esac
fi
diff --git a/scripts/xdg-screensaver.in b/scripts/xdg-screensaver.in
index e70942f..1c25e57 100644
--- a/scripts/xdg-screensaver.in
+++ b/scripts/xdg-screensaver.in
@@ -363,7 +363,7 @@ screensaver_kde3()
xset_screensaver_timeout()
{
- xset q | sed '/^Screen Saver:/,/^[^ ]/ { s/.*timeout: *\([0-9]*\).*/\1/; t }; d'
+ xset q | sed '/^Screen Saver:/,/^[^ ]/ { s/.*timeout: *\([0-9]*\).*/\1/; t; }; d'
}
screensaver_xserver()
@@ -502,7 +502,9 @@ while (1) {
screensaver_gnome_screensaver()
{
# DBUS interface for gnome-screensaver
-# http://people.gnome.org/~mccann/gnome-screensaver/docs/gnome-screensaver.html
+# https://gitlab.gnome.org/Archive/gnome-screensaver/-/blob/master/doc/dbus-interface.xml
+# as well as gnome-shell
+# https://gitlab.gnome.org/GNOME/gnome-shell/-/blob/main/data/dbus-interfaces/org.gnome.ScreenSaver.xml
case "$1" in
suspend)
screensaver_dbus_process $window_id $screensaver_file "org.gnome.SessionManager" "/org/gnome/SessionManager"
@@ -541,8 +543,9 @@ screensaver_gnome_screensaver()
--dest=org.gnome.ScreenSaver \
--type=method_call \
/org/gnome/ScreenSaver \
- org.gnome.ScreenSaver.SimulateUserActivity \
- 2> /dev/null
+ org.gnome.ScreenSaver.SetActive \
+ boolean:false \
+ 2> /dev/null
result=$?
;;
diff --git a/scripts/xdg-settings.in b/scripts/xdg-settings.in
index 93ff352..78fdb9b 100755
--- a/scripts/xdg-settings.in
+++ b/scripts/xdg-settings.in
@@ -571,9 +571,15 @@ set_browser_xfce()
# }}} xfce
# {{{ generic
+# (Option<mimetype>)
get_browser_generic()
{
- if [ -n "$BROWSER" ]; then
+
+ if get_browser_mime "${1:-x-scheme-handler/http}"; then
+ return 0
+ fi
+
+ if [ -n "$BROWSER" ]; then
local browser=$(binary_to_desktop_file "${BROWSER%%:*}")
if [ -n "$browser" ]; then
basename "$browser"
@@ -581,10 +587,6 @@ get_browser_generic()
fi
fi
- if get_browser_mime x-scheme-handler/http; then
- return 0
- fi
-
# Debian and derivatives have x-www-browser
local browser=$(binary_to_desktop_file x-www-browser)
if [ -n "$browser" ]; then
@@ -621,15 +623,39 @@ check_browser_generic()
exit_success
}
-set_browser_generic()
+normalize_binary()
{
- if [ -n "$BROWSER" ]; then
- exit_failure_operation_failed \
- "\$BROWSER is set and can't be changed with xdg-settings"
+ xdg_realpath "$(command -v "$1")"
+}
+
+# The BROWSER variable is outside the control of xdg-settings,
+# the best we can do is to do our part and explain
+# that additional configurtion could be neccessary
+#
+# Takes as argument the value browser is suggested to be set to.
+
+explain_browser_variable()
+{
+ if [ "$(normalize_binary "$1")" != "$(normalize_binary "$BROWSER")" ] ; then
+ echo "\$BROWSER is set and can't be changed with xdg-settings." >&2
+ echo "This means that some applications won't adopt the new browser setting." >&2
+ echo "The \$BROWSER envoirnment variable is likely set in your ~/.profile or ~/.bashrc which you have to edit manually. If you don't find it there consult the documentation/wiki of your desktop envoirnment or distribution." >&2
+ echo "Depending on the applications not setting \$BROWSER at all might also help." >&2
+ echo "" >&2
+ echo "Your \$BROWSER is currently set to: $BROWSER" >&2
+ echo "It should be set to: $1" >&2
fi
+}
+
+set_browser_generic()
+{
+
+ binary="$(desktop_file_to_binary "$1")"
+ [ -n "$binary" ] || exit_failure_file_missing "Can't resolve this desktop file name to a command"
- binary=$(desktop_file_to_binary "$1")
- [ -n "$binary" ] || exit_failure_file_missing
+ if [ -n "$BROWSER" ] && [ "$binary" != "$BROWSER" ]; then
+ explain_browser_variable "$binary"
+ fi
set_browser_mime "$1" text/html || return
@@ -859,7 +885,7 @@ set_url_scheme_handler_xfce()
get_url_scheme_handler_generic()
{
if [ -n "$BROWSER" ] && ([ "$1" = http ] || [ "$1" = https ]); then
- get_browser_generic
+ get_browser_generic "x-scheme-handler/$1"
else
get_browser_mime "x-scheme-handler/$1"
fi
@@ -874,7 +900,7 @@ check_url_scheme_handler_generic()
exit_success
fi
- local browser=$(get_url_scheme_handler_generic "$scheme")
+ local browser="$(get_url_scheme_handler_generic "$scheme")"
if [ "$browser" != "$desktop" ]; then
echo no
exit_success
@@ -887,14 +913,15 @@ set_url_scheme_handler_generic()
{
local scheme="$1" desktop="$2"
- if [ -n "$BROWSER" ] && \
- ([ "$scheme" = http ] || [ "$scheme" = https ]); then
- exit_failure_operation_failed \
- "\$BROWSER is set and can't be changed with xdg-settings"
+ # needed by explain_browser_variable as global
+ binary="$(desktop_file_to_binary "$desktop")"
+
+ if [ -n "$BROWSER" ] && ([ "$scheme" = http ] || [ "$scheme" = https ]); then
+ explain_browser_variable "$binary"
fi
- if [ -z "$(desktop_file_to_binary "$desktop")" ]; then
- exit_failure_file_missing
+ if [ -z "$binary" ]; then
+ exit_failure_file_missing "Can't resolve a command for the given desktop file name"
fi
set_browser_mime "$desktop" "x-scheme-handler/$scheme"
diff --git a/scripts/xdg-utils-common.in b/scripts/xdg-utils-common.in
index adab368..1b99ef8 100644
--- a/scripts/xdg-utils-common.in
+++ b/scripts/xdg-utils-common.in
@@ -24,6 +24,10 @@ first_word()
# map a binary to a .desktop file
binary_to_desktop_file()
{
+ if [ -z "$1" ] ; then
+ DEBUG 2 "binary_to_desktop_file argument is empty"
+ return
+ fi
search="${XDG_DATA_HOME:-$HOME/.local/share}:${XDG_DATA_DIRS:-/usr/local/share:/usr/share}"
binary="$(command -v "$1")"
binary="$(xdg_realpath "$binary")"
@@ -58,6 +62,10 @@ binary_to_desktop_file()
desktop_file_to_binary()
{
DEBUG 1 "desktop_file_to_binary '$1'"
+ if [ -z "$1" ] ; then
+ DEBUG 2 "desktop_file_to_binary argument is empty"
+ return
+ fi
search="${XDG_DATA_HOME:-$HOME/.local/share}:${XDG_DATA_DIRS:-/usr/local/share:/usr/share}"
desktop="$(basename "$1")"
IFS=:
@@ -98,6 +106,10 @@ desktop_file_to_binary()
print substr($2,RSTART,RLENGTH)
}' \
< "$file_path" )"
+ if [ -z "$binary" ] ; then
+ DEBUG 2 "No or empty Exec key in .desktop file. Search failed."
+ return
+ fi
DEBUG 2 "Found command: $binary"
binary="$(xdg_which "$binary")"
DEBUG 2 "Resolved to command to file: '$binary'"
@@ -292,14 +304,17 @@ fi
#--------------------------------------
# Checks for known desktop environments
# set variable DE to the desktop environments name, lowercase
+# Don't forget to update the manpage!
detectDE()
{
# see https://bugs.freedesktop.org/show_bug.cgi?id=34164
unset GREP_OPTIONS
- if [ -n "${XDG_CURRENT_DESKTOP}" ]; then
- case "${XDG_CURRENT_DESKTOP}" in
+ IFS=:
+ for desktop in $XDG_CURRENT_DESKTOP ; do
+ unset IFS
+ case "$desktop" in
# only recently added to menu-spec, pre-spec X- still in use
Cinnamon|X-Cinnamon)
DE=cinnamon;
@@ -308,13 +323,13 @@ detectDE()
DE=enlightenment;
;;
# GNOME, GNOME-Classic:GNOME, or GNOME-Flashback:GNOME
- GNOME*)
+ GNOME)
DE=gnome;
;;
KDE)
DE=kde;
;;
- DEEPIN|Deepin|deepin)
+ DEEPIN|Deepin|deepin|DDE)
DE=deepin;
;;
LXDE)
@@ -333,7 +348,8 @@ detectDE()
DE=generic
;;
esac
- fi
+ [ -n "$DE" ] && break
+ done
# shellcheck disable=SC2153
if [ -z "$DE" ]; then
@@ -489,21 +505,42 @@ xdg_realpath()
# xdg_which <command>
xdg_which()
{
- if [ -z "$1" ] ; then
- return 1
- elif [ -x "$1" ] ; then
- printf "%s\n" "$1"
- else
- # this should be faster than the real thing because of shell builtins
- old_ifs="$IFS"
- IFS=:
- for p in $PATH ; do
- IFS="$old_ifs"
- if [ -x "$p/$1" ] ; then
- printf "%s\n" "$p/$1"
- return
+ case "$1" in
+ '') return 1 ;;
+ */*)
+ # We got a path containing slashes, test if it is executable
+ # and return its absolute path with symlinks resolved.
+ if [ -x "$1" ] ; then
+ xdg_realpath "$1"
+ return 0
fi
- done
- return 1
- fi
+ return 1
+ ;;
+ esac
+ # search PATH for command
+ old_ifs="$IFS"
+ IFS=:
+ for p in $PATH ; do
+ IFS="$old_ifs"
+ if [ -x "$p/$1" ] ; then
+ printf "%s\n" "$p/$1"
+ return
+ fi
+ done
+ return 1
+}
+
+#----------------------------------------------------------------------------
+# Helper function that returns the value for `$XDG_CONFIG_HOME`,
+# independent of it being explicitly set or simply a fallback.
+
+# get_xdg_config_home
+get_xdg_config_home()
+{
+ # Only use XDG_CONFIG_HOME if it is an absolute path
+ # shellcheck disable=SC2153 # not misspelled
+ case "$XDG_CONFIG_HOME" in
+ /*) printf "%s\n" "$XDG_CONFIG_HOME" ;;
+ *) printf "%s\n" "$HOME/.config" ;;
+ esac
}
generated by cgit v1.2.3 (git 2.39.1) at 2025-04-14 02:34:49 +0000