Merge pull request #34590 from poettering/file-hier-removals

man: remove some irrelevant dirs from file-hierarchy(7)

man/file-hierarchy.xml

@@ -24,17 +24,21 @@
     <title>Description</title>
 
     <para>Operating systems using the
-    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> system and service
-    manager are organized based on a file system hierarchy inspired by UNIX, more specifically the hierarchy described
-    in the <ulink url="http://refspecs.linuxfoundation.org/FHS_3.0/fhs-3.0.html">File System Hierarchy</ulink>
-    specification and <citerefentry
-    project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>, with various
-    extensions, partially documented in the <ulink
+    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> system and
+    service manager are organized based on a file system hierarchy inspired by UNIX, more specifically the
+    hierarchy described in the <ulink url="http://refspecs.linuxfoundation.org/FHS_3.0/fhs-3.0.html">File
+    System Hierarchy</ulink> specification and <citerefentry
+    project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>, with
+    various extensions, partially documented in the <ulink
     url="https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory
     Specification</ulink> and <ulink url="https://www.freedesktop.org/wiki/Software/xdg-user-dirs">XDG User
-    Directories</ulink>. This manual page describes a more generalized, though minimal and modernized subset of these
-    specifications that defines more strictly the suggestions and restrictions systemd makes on the file system
-    hierarchy.</para>
+    Directories</ulink>. This manual page describes a more generalized, though minimal and modernized subset
+    of these specifications that defines more strictly the suggestions and restrictions systemd makes on the
+    file system hierarchy. Note that this document makes no attempt to define the directory structure
+    comprehensively, it only documents a skeleton of a directory tree, that downstreams can extend. Because
+    of that traditional directories such as <filename>/usr/include/</filename> or
+    <filename>/var/spool/</filename> are not covered, even though it might (or might not) make a lot of sense
+    to include them in the structure of an actually deployed OS.</para>
 
     <para>Many of the paths described here can be queried
     with the
@@ -182,11 +186,6 @@
         subdirectory of <filename>/usr/lib/</filename> instead.</para></listitem>
       </varlistentry>
 
-      <varlistentry>
-        <term><filename>/usr/include/</filename></term>
-        <listitem><para>C and C++ API header files of system libraries.</para></listitem>
-      </varlistentry>
-
       <varlistentry>
         <term><filename>/usr/lib/</filename></term>
         <listitem><para>Static, private vendor data that is compatible with all architectures (though not
@@ -282,11 +281,6 @@
         calls.</para></listitem>
       </varlistentry>
 
-      <varlistentry>
-        <term><filename>/var/spool/</filename></term>
-        <listitem><para>Persistent system spool data, such as printer or mail queues.</para></listitem>
-      </varlistentry>
-
       <varlistentry>
         <term><filename>/var/tmp/</filename></term>
         <listitem><para>The place for larger and persistent temporary files. In contrast to
@@ -579,6 +573,9 @@
     Similarly, <filename>/run/</filename> shall be the only location to
     place sockets and FIFOs. Regular files, directories and symlinks
     may be used in all directories.</para>
+
+    <para>Applications should expect that a security policy might be enforced on a system that enforces these
+    rules.</para>
   </refsect1>
 
   <refsect1>
@@ -616,10 +613,6 @@
       <entry><filename>/usr/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable>/</filename></entry>
       <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures. Note that this generally does not include private executables since binaries of a specific architecture may be freely invoked from any other supported system architecture.</entry>
           </row>
-          <row>
-      <entry><filename>/usr/include/<replaceable>package</replaceable>/</filename></entry>
-      <entry>Public C/C++ APIs of public shared libraries of the package.</entry>
-          </row>
         </tbody>
       </tgroup>
     </table>
@@ -667,10 +660,6 @@
       <entry><filename>/var/log/<replaceable>package</replaceable>/</filename></entry>
       <entry>Persistent log data of the package. As above, the package should make sure to create this directory if necessary, possibly using <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> or <varname>LogsDirectory=</varname> (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>), as it might be missing.</entry>
           </row>
-          <row>
-      <entry><filename>/var/spool/<replaceable>package</replaceable>/</filename></entry>
-      <entry>Persistent spool/queue data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing.</entry>
-          </row>
         </tbody>
       </tgroup>
     </table>