From fa0e2f82ca6aca2baff6bb35df39a11001d0a74e Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@debian.org>
Date: Wed, 11 Oct 2017 10:38:28 +0100
Subject: [PATCH 1/4] desktop-entry-spec: New section "File naming"

This combines the notes on file naming that were previously part of
"Basic format of the file" with the former appendix "Desktop File ID".

Signed-off-by: Simon McVittie <smcv@debian.org>
---
 desktop-entry/desktop-entry-spec.xml | 78 +++++++++++++++++++-----------------
 1 file changed, 42 insertions(+), 36 deletions(-)

diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml
index c4d3299..9d0b5f5 100644
--- a/desktop-entry/desktop-entry-spec.xml
+++ b/desktop-entry/desktop-entry-spec.xml
@@ -85,8 +85,8 @@
       the specification, becomes simpler.
     </para>
   </sect1>
-  <sect1 id="basic-format">
-    <title>Basic format of the file</title>
+  <sect1 id="file-naming">
+    <title>File naming</title>
     <para>
       Desktop entry files should have the <filename>.desktop</filename>
       extension, except for files of <varname>Type</varname>
@@ -103,6 +103,46 @@
       <literal>[A-Z][a-z][0-9]</literal> along with dash ('<literal>-</literal>') and underscore
       ('<literal>_</literal>').  Components may not begin with a digit.
     </para>
+
+    <sect2 id="desktop-file-id">
+      <title>Desktop File ID</title>
+      <para>
+        Each desktop entry representing an application is identified by
+        its <firstterm>desktop file ID</firstterm>, which is based on its
+        filename.
+      </para>
+      <para>
+          To determine the ID of a desktop file, make its full path relative to
+          the <literal>$XDG_DATA_DIRS</literal> component in which the desktop file is installed, remove the "applications/"
+          prefix, and turn '/' into '-'.
+       </para>
+       <para>
+          For example <filename>/usr/share/applications/foo/bar.desktop</filename> has
+          the desktop file ID <literal>foo-bar.desktop</literal>.
+       </para>
+       <para>
+          If multiple files have the same desktop file ID, the first one in the
+          $XDG_DATA_DIRS precedence order is used.
+       </para>
+       <para>
+          For example, if <literal>$XDG_DATA_DIRS</literal> contains the default paths /usr/local/share:/usr/share, then
+          <filename>/usr/local/share/applications/org.foo.bar.desktop</filename> and
+          <filename>/usr/share/applications/org.foo.bar.desktop</filename> both have
+          the same desktop file ID <literal>org.foo.bar.desktop</literal>, but only the first
+          one will be used.
+       </para>
+       <para>
+          If both <filename>foo-bar.desktop</filename> and <filename>foo/bar.desktop</filename> exist,
+          it is undefined which is selected.
+       </para>
+       <para>
+          If the desktop file is not installed in an <literal>applications</literal> subdirectory of one
+          of the $XDG_DATA_DIRS components, it does not have an ID.
+       </para>
+    </sect2>
+  </sect1>
+  <sect1 id="basic-format">
+    <title>Basic format of the file</title>
     <para>
       Desktop entry files are encoded in UTF-8. A file is interpreted as a
       series of lines that are separated by linefeed characters. Case is
@@ -1554,40 +1594,6 @@ Icon=fooview-new
       the name as it appears in the "Encoding" column above.
     </para>
   </appendix>
-  <appendix id="desktop-file-id">
-    <title>Desktop File ID</title>
-    <para>
-        The desktop file ID is the identifier of an installed desktop entry file.
-    </para>
-    <para>
-        To determine the ID of a desktop file, make its full path relative to
-        the <literal>$XDG_DATA_DIRS</literal> component in which the desktop file is installed, remove the "applications/"
-        prefix, and turn '/' into '-'.
-     </para>
-     <para>
-        For example <filename>/usr/share/applications/foo/bar.desktop</filename> has
-        the desktop file ID <literal>foo-bar.desktop</literal>.
-     </para>
-     <para>
-        If multiple files have the same desktop file ID, the first one in the
-        $XDG_DATA_DIRS precedence order is used.
-     </para>
-     <para>
-        For example, if <literal>$XDG_DATA_DIRS</literal> contains the default paths /usr/local/share:/usr/share, then
-        <filename>/usr/local/share/applications/org.foo.bar.desktop</filename> and
-        <filename>/usr/share/applications/org.foo.bar.desktop</filename> both have
-        the same desktop file ID <literal>org.foo.bar.desktop</literal>, but only the first
-        one will be used.
-     </para>
-     <para>
-        If both <filename>foo-bar.desktop</filename> and <filename>foo/bar.desktop</filename> exist,
-        it is undefined which is selected.
-     </para>
-     <para>
-        If the desktop file is not installed in an <literal>applications</literal> subdirectory of one
-        of the $XDG_DATA_DIRS components, it does not have an ID.
-     </para>
-  </appendix>
   <appendix>
     <title>Changes to this Specification</title>
     <section>
-- 
2.15.0.rc0