man: Clarify usage of /usr/share/factory/ in programs

As discussed in this thread:
https://github.com/redhat-performance/tuned/issues/798#issuecomment-3197697654

/usr/share/factory/ is not intended to be read from by programs,
but the wording in the FHS can be misread to think that programs
should be using /usr/share/factory/ as the vendor supplied configuration
directory rather than something like /usr/lib/foo/ or /usr/share/foo/.

This commit points developers to the UAPI configuration spec for how to
make their programs hermetic /usr/ compatible.

Signed-off-by: Ryan Brue <ryanbrue.dev@gmail.com>

diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml
index 1c4a33d59772a37aada05d5d1a7bb75a84ac375e..a61cada6958e9ea6ae4d0fb7ecf1df31d05a760b 100644 (file)
--- a/man/file-hierarchy.xml
+++ b/man/file-hierarchy.xml
@@ -230,7 +230,9 @@
         <listitem><para>Repository for vendor-supplied default configuration files. This directory should be
         populated with pristine vendor versions of all configuration files that may be placed in
         <filename>/etc/</filename>. This is useful to compare the local configuration of a system with vendor
-        defaults and to populate the local configuration with defaults.</para></listitem>
+        defaults and to populate the local configuration with defaults. Software should not read configuration
+        settings directly from <filename>/usr/share/factory/</filename>. Those files will be copied to
+        other locations if appropriate, and should only be read from there.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -239,7 +241,9 @@
         <listitem><para>Similar to
         <filename>/usr/share/factory/etc/</filename>, but for vendor
         versions of files in the variable, persistent data directory
-        <filename>/var/</filename>.</para></listitem>
+        <filename>/var/</filename>. The same recommendations as for
+        <filename>/usr/share/factory/etc/</filename> apply here.
+        </para></listitem>
       </varlistentry>
     </variablelist>
   </refsect1>