spec: Deprecate hyphen/minus in well-known names

We don't really need two parallel forms of punctuation, and in
particular DNS domain names only have one (hyphens). If we choose one
representation and deprecate the other, it makes the recommendation
clearer for app authors.

This reflects a similar change to the Desktop Entry Specification,
which uses D-Bus well-known names as app IDs. While hyphens are not a
problem for D-Bus well-known names or for freedesktop.org app IDs,
they create problems for adjacent APIs and specifications that want to
use a well-known name in a context where hyphens are not allowed.
Hyphens are not allowed in D-Bus object paths and interface names,
are only conditionally allowed in Flatpak app IDs (they can only
appear in the last element), and have a special syntactic role in
Freedesktop icon names.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=103216
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=103914
Signed-off-by: Simon McVittie <smcv@collabora.com>
Reviewed-by: Philip Withnall <withnall@endlessm.com>
Reviewed-by: Alexander Larsson <alexl@redhat.com>

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index abafb819d441b4501ad17bf7b7e111a189a38f95..2cec36a6e1ae9713b7f5de5fd36d5f5942aabffc 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -1793,6 +1793,17 @@
           <literal>com.example.MusicPlayer1.Seekable</literal>.
         </para>
 
+        <para>
+          If the author's DNS domain name contains hyphen/minus characters
+          ('-'), which are not allowed in D-Bus interface names, they
+          should be replaced by underscores. If the DNS domain name
+          contains a digit immediately following a period ('.'), which
+          is also not allowed in interface names), the interface name
+          should add an underscore before that digit. For example, if
+          the owner of 7-zip.org defined an interface for out-of-process
+          plugins, it might be named <literal>org._7_zip.Plugin</literal>.
+        </para>
+
         <para>
           D-Bus does not distinguish between the concepts that would be
           called classes and interfaces in Java: either can be identified on
@@ -1822,7 +1833,8 @@
                 </para>
             </listitem>
             <listitem><para>Each element must only contain the ASCII characters
-                "[A-Z][a-z][0-9]_-". Only elements that are part of a unique
+                "[A-Z][a-z][0-9]_-", with "-" discouraged in new bus
+                names. Only elements that are part of a unique
                 connection name may begin with a digit, elements in
                 other bus names must not begin with a digit.
                 </para>
@@ -1837,8 +1849,20 @@
           </itemizedlist>
         </para>
         <para>
-          Note that the hyphen ('-') character is allowed in bus names but
-          not in interface names.
+          Note that the hyphen ('-') character is allowed in bus names
+          but not in interface names. It is also problematic or not
+          allowed in various specifications and APIs that refer to
+          D-Bus, such as <ulink
+            url="http://docs.flatpak.org/en/latest/introduction.html#identifiers"
+            >Flatpak application IDs</ulink>,
+          <ulink
+            url="https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus"
+            >the <literal>DBusActivatable</literal> interface in the
+            Desktop Entry Specification</ulink>, and the convention
+          that an application's "main" interface and object path
+          resemble its bus name. To avoid situations that require
+          special-case handling, it is recommended that new D-Bus names
+          consistently replace hyphens with underscores.
         </para>
 
         <para>
@@ -1853,6 +1877,15 @@
           simultaneously if backwards compatibility is required.
         </para>
 
+        <para>
+          As with interface names, 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
+          of 7-zip.org used a D-Bus name for an archiving application,
+          it might be named <literal>org._7_zip.Archiver</literal>.
+        </para>
+
         <para>
           If a well-known bus name implies the presence of a "main" interface,
           that "main" interface is often given the same name as