Document quirks with xdg-mime for query file and query default

1 files changed, 25 insertions, 11 deletions

diff --git a/scripts/desc/xdg-mime.xml b/scripts/desc/xdg-mime.xml
index 7ac0b76..54b0922 100644
--- a/scripts/desc/xdg-mime.xml
+++ b/scripts/desc/xdg-mime.xml
@@ -1,8 +1,8 @@
 <?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.1.2//EN"
-    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
 ]>
 <refentry id="xdg-mime">
   <refentryinfo>
@@ -83,26 +83,40 @@ and adding descriptions for new file types</refpurpose>
     <title>Commands</title>
     <variablelist>
       <varlistentry>
-	<term>query</term>
+	<term>query file</term>
 	<listitem>
 	  <simpara>
-	    Returns information related to file types.
+	    Returns the file type of <replaceable>FILE</replaceable> in the form of a MIME type.
 	  </simpara>
 	  <simpara>
-            The <emphasis>query</emphasis> option is for use inside a desktop session only.
-            It is not recommended to use xdg-mime query as root.
+		Please note that <replaceable>FILE</replaceable> names starting with a <code>-</code> will be rejected, this can be mitigated:
 	  </simpara>
+      <itemizedlist>
+        <listitem><para>Pass absolute paths, i.e. by using <command>realpath</command> as a preprocessor.</para></listitem>
+		<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 following queries are supported:
-	  </simpara>
-	  <simpara>query filetype <replaceable>FILE</replaceable>:
-	    Returns the file type of <replaceable>FILE</replaceable> in the form of a MIME type.
+            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.
 	  </simpara>
-	  <simpara>query default <replaceable>mimetype</replaceable>:
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>query default</term>
+	<listitem>
+	  <simpara>
 	    Returns the default application that the desktop environment uses for opening
 	    files of type <replaceable>mimetype</replaceable>. The default application is
             identified by its *.desktop file.
 	  </simpara>
+	  <simpara>
+        The value returned by this command may or may not match the application launched by <command>xdg-open</command> as <command>xdg-open</command> hands over to desktop specific openers most of the time which may implement their own logic.
+	  </simpara>
+	  <simpara>
+            The <emphasis>query default</emphasis> option is for use inside a desktop session only.
+            It is not recommended to use xdg-mime query default as root.
+	  </simpara>
 	</listitem>
       </varlistentry>