spec: Document a recommendation for IDNs in reversed domain names

D-Bus names are in an ASCII subset, so IDNs have to be in their ACE
encoding (Punycode). ACE-encoded labels contain hyphen/minus characters,
and like any other label containing a hyphen/minus, we recommend
replacing those with underscores, to improve interoperability with
contexts that allow underscores but not hyphen/minus, such as
D-Bus object paths and Flatpak app-IDs.

Prompted by <https://github.com/flatpak/flatpak/issues/4974>.

Signed-off-by: Simon McVittie <smcv@collabora.com>

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index e614af91a812aa149325f140b17ed7f78bdafa0f..a43b925609f99678ffea4b10f183c064663c2477 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -1975,6 +1975,21 @@
           plugins, it might be named <literal>org._7_zip.Plugin</literal>.
         </para>
 
+        <para>
+          If the author's DNS domain name is an internationalized domain
+          name (IDN) such as <literal>δοκιμή.example</literal>,
+          the ASCII encoding (known as ACE-encoding or Punycode) such as
+          <literal>xn--jxalpdlp.example</literal>
+          should be used as a basis for the reversed-domain-name form.
+          As with any other name, hyphen/minus characters should be
+          replaced by underscores in the reversed-domain-name form, for
+          example <literal>example.xn__jxalpdlp.ExampleService1</literal>.
+          For more information about internationalized domain names, see
+          <ulink url="https://datatracker.ietf.org/doc/html/rfc5890">RFC
+            5890 "Internationalized Domain Names for Applications (IDNA):
+            Definitions and Document Framework"</ulink>.
+        </para>
+
         <para>
           D-Bus does not distinguish between the concepts that would be
           called classes and interfaces in Java: either can be identified on
@@ -2049,12 +2064,18 @@
         </para>
 
         <para>
-          As with interface names, if the author's DNS domain name
+          As with <link linkend="message-protocol-names-interface">interface
+            names</link>, if the author's DNS domain name
           contains hyphen/minus characters they should be replaced by
-          underscores, and if it contains leading digits they should be
-          escaped by prepending an underscore. For example, if the owner
+          underscores, if it contains leading digits they should be
+          escaped by prepending an underscore, and internationalized
+          domain names (IDN) need to be encoded in their ASCII form
+          (ACE-encoding, Punycode) before replacing dashes with underscores.
+          For example, if the owner
           of 7-zip.org used a D-Bus name for an archiving application,
-          it might be named <literal>org._7_zip.Archiver</literal>.
+          it might be named <literal>org._7_zip.Archiver</literal>,
+          while the owner of <literal>δοκιμή.example</literal> might
+          use the name <literal>example.xn__jxalpdlp.ExampleService1</literal>.
         </para>
 
         <para>